README
¶
DevLore
New machine to productive developer in minutes. DevLore sets up real developer machines — pick a role like "Azure Cloud developer" or "Apple Mobile App developer" and the tools arrive installed, configured, and verified the way your team actually uses them. It works on the physical machine (macOS, Linux, and Windows natively), which is exactly where devcontainers, cloud IDEs, and VM-based tooling stop.
Software installation is the visible tip. The value is everything under the waterline: the post-install steps nobody wrote down. Deploying Docker on a fresh Linux box, for example, means removing conflicting packages, adding the vendor repository, installing five packages in order, configuring group membership, setting up rootless mode, generating shell completions, and verifying with a hello-world run — DevLore captures that whole sequence as an executable, verifiable package, not a wiki page.
The tools
| Binary | Purpose |
|---|---|
lore |
Deploys software with its tribal knowledge: prepare → install → provision → verify, with receipts recording what actually happened |
writ |
Manages your environment: dotfiles, configuration layers, drift detection, and reconciliation as role definitions evolve |
Both are single native binaries with man pages and completions for bash, zsh,
fish, and PowerShell. The CLI surface is being unified under the devlore
name; lore and writ are the current entry points.
Install
# From source
go install github.com/NobleFactor/devlore-cli/cmd/lore@latest
go install github.com/NobleFactor/devlore-cli/cmd/writ@latest
# Or use the install scripts
./install.sh # macOS, Linux
./install.ps1 # Windows
# Then let the tools finish their own setup (completions, man pages)
lore self install
writ self install
Homebrew and MacPorts packaging are staged in packaging/ and
will ship with the first tagged release.
Cross-platform, genuinely
macOS, Linux, and Windows are first-class targets — including a native PowerShell provider on Windows, not a WSL shim. One manifest describes a role; each platform deploys it with its native package managers (Homebrew, MacPorts, apt, dnf, winget, and more) plus the provisioning steps those managers don't do.
The registry
Packages live in devlore-registry — the curated catalog of deployment knowledge: lifecycle manifests, per-platform phase scripts, and the knowledge assets that let AI assistants author and validate packages. Content is served from GitHub today; OCI distribution (point DevLore at the registry you already run) is the planned path.
Building
Prerequisites: Go 1.26+ and GNU make 3.82+.
macOS ships GNU make 3.81 — the last GPLv2 release, so it will never advance — and the build uses
.ONESHELL:, which 3.82 introduced. Older make ignores that directive silently and fails with
syntax error: unexpected end of file, so the Makefile refuses to run on it and says why:
brew install make
export PATH="$(brew --prefix)/opt/make/libexec/gnubin:$PATH" # or invoke gmake
make build # Build binaries to bin/
make test # Run the test suite
All paths follow the XDG Base Directory Specification; see docs/ for architecture and guides.
Contributing
Contributions arrive under Apache-2.0 §5 with a
Developer Certificate of Origin sign-off
(git commit -s). See CONTRIBUTING.md.
License
Apache License 2.0. See LICENSE and NOTICE.
DevLore is a Noble Factor project. Project home: devlore.org.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
devlore-docs
command
Command docgen generates Docker-style CLI reference documentation for the writ and lore commands.
|
Command docgen generates Docker-style CLI reference documentation for the writ and lore commands. |
|
devlore-index
command
Command gen-index generates index.yaml manifests for knowledge domains in the devlore-registry.
|
Command gen-index generates index.yaml manifests for knowledge domains in the devlore-registry. |
|
devlore-inventory
command
New-OpInventory scans Go package trees for calls to op.AnnounceReceiver() and op.AnnounceResource(), then generates a blank-import file that ensures all self-registering packages are linked into the binary.
|
New-OpInventory scans Go package trees for calls to op.AnnounceReceiver() and op.AnnounceResource(), then generates a blank-import file that ensures all self-registering packages are linked into the binary. |
|
devlore-test
command
Command devlore-test is the graph test harness for Starlark plan + execute + verify.
|
Command devlore-test is the graph test harness for Starlark plan + execute + verify. |
|
devlore-test/devloretest
Package devloretest implements the devlore-test CLI commands.
|
Package devloretest implements the devlore-test CLI commands. |
|
internal/cli
Package cli provides shared CLI infrastructure for writ and lore commands.
|
Package cli provides shared CLI infrastructure for writ and lore commands. |
|
internal/config
Package config provides centralized configuration for the devlore ecosystem.
|
Package config provides centralized configuration for the devlore ecosystem. |
|
internal/devlore
Package devlore names the locations the devlore tools share, beneath the XDG base directories.
|
Package devlore names the locations the devlore tools share, beneath the XDG base directories. |
|
internal/e2e
Package e2e provides end-to-end testing infrastructure for LLM-based operations.
|
Package e2e provides end-to-end testing infrastructure for LLM-based operations. |
|
internal/lorepackage
Package lorepackage provides the client interface for accessing the devlore registry.
|
Package lorepackage provides the client interface for accessing the devlore registry. |
|
internal/model
Package model provides LLM provider configuration and client implementations.
|
Package model provides LLM provider configuration and client implementations. |
|
lore
command
Command lore is the tribal knowledge package deployer.
|
Command lore is the tribal knowledge package deployer. |
|
lore/lore
Package lore provides the runtime types and execution engine for the lore CLI.
|
Package lore provides the runtime types and execution engine for the lore CLI. |
|
lore/lore/onboard
Package onboard implements the multi-phase onboarding pipeline for lore.
|
Package onboard implements the multi-phase onboarding pipeline for lore. |
|
scenario
Package scenario holds end-to-end scenarios that belong to no single command.
|
Package scenario holds end-to-end scenarios that belong to no single command. |
|
star
command
star is the Starlark-powered operations tool for NobleFactor projects.
|
star is the Starlark-powered operations tool for NobleFactor projects. |
|
star/cli
Package cli provides CLI utilities for output formatting and user interaction.
|
Package cli provides CLI utilities for output formatting and user interaction. |
|
star/config
Package config provides unified configuration for star commands.
|
Package config provides unified configuration for star commands. |
|
star/provider/commands
Package commands provides command tree navigation and execution for the star runtime.
|
Package commands provides command tree navigation and execution for the star runtime. |
|
star/provider/config
Package config provides configuration management operations for the star runtime.
|
Package config provides configuration management operations for the star runtime. |
|
star/provider/goast
Package goast provides Go AST operations as a Starlark receiver.
|
Package goast provides Go AST operations as a Starlark receiver. |
|
star/provider/goast/doctaxonomy
Package doctaxonomy defines the documentation schema the goast provider enforces.
|
Package doctaxonomy defines the documentation schema the goast provider enforces. |
|
star/provider/lint
Package lint provides static analysis operations for Go, shell, and markdown files.
|
Package lint provides static analysis operations for Go, shell, and markdown files. |
|
star/provider/setup
Package setup provides repository setup operations: tool checks, pre-commit hooks, config initialization, and native git hook management.
|
Package setup provides repository setup operations: tool checks, pre-commit hooks, config initialization, and native git hook management. |
|
star/provider/shellcheck
Package shellcheck provides shell script analysis operations for the operation graph.
|
Package shellcheck provides shell script analysis operations for the operation graph. |
|
star/provider/staranalysis
Package staranalysis provides combined analysis of Starlark source files, combining stats, complexity scoring, indexing, and hotspot detection.
|
Package staranalysis provides combined analysis of Starlark source files, combining stats, complexity scoring, indexing, and hotspot detection. |
|
star/provider/starcode
Package starcode provides Starlark source file capture with glob pattern matching, .gitignore awareness.
|
Package starcode provides Starlark source file capture with glob pattern matching, .gitignore awareness. |
|
star/provider/starcomplexity
Package starcomplexity computes cyclomatic and cognitive complexity metrics for Starlark source files.
|
Package starcomplexity computes cyclomatic and cognitive complexity metrics for Starlark source files. |
|
star/provider/starindex
Package starindex provides AST-based indexing of Starlark source files, extracting functions, loads, globals, and line statistics.
|
Package starindex provides AST-based indexing of Starlark source files, extracting functions, loads, globals, and line statistics. |
|
star/provider/starstats
Package starstats computes line and byte statistics for Starlark source files.
|
Package starstats computes line and byte statistics for Starlark source files. |
|
star/star
Package star provides the runtime types and execution engine for the star CLI.
|
Package star provides the runtime types and execution engine for the star CLI. |
|
writ
command
Command writ is the portable environment orchestrator.
|
Command writ is the portable environment orchestrator. |
|
writ/writ
Package writ implements the writ CLI commands.
|
Package writ implements the writ CLI commands. |
|
writ/writ/adopt
Package adopt plans the `writ adopt` batch graph.
|
Package adopt plans the `writ adopt` batch graph. |
|
writ/writ/decommission
Package decommission removes deployed files through the sealed graph model (phase-8 step 47 slice 2).
|
Package decommission removes deployed files through the sealed graph model (phase-8 step 47 slice 2). |
|
writ/writ/deploy
Package deploy plans and executes writ deployments on the sealed graph model (phase-8 step 47 slice 1).
|
Package deploy plans and executes writ deployments on the sealed graph model (phase-8 step 47 slice 1). |
|
writ/writ/identity
Package identity provides age identity loading for writ.
|
Package identity provides age identity loading for writ. |
|
writ/writ/migrate
Package migrate implements dotfile migration analysis and execution.
|
Package migrate implements dotfile migration analysis and execution. |
|
writ/writ/readback
Package readback derives "what has writ deployed" from the store's graph and trace documents (phase-8 step 47 slice 1).
|
Package readback derives "what has writ deployed" from the store's graph and trace documents (phase-8 step 47 slice 1). |
|
writ/writ/secret
Package secret implements the writ secret family: SOPS lifecycle operations scoped to registered layers.
|
Package secret implements the writ secret family: SOPS lifecycle operations scoped to registered layers. |
|
writ/writ/segment
Package segment provides segment-based directory matching for writ.
|
Package segment provides segment-based directory matching for writ. |
|
writ/writ/snapshot
Package snapshot provides git worktree-based snapshots for hermetic planning.
|
Package snapshot provides git worktree-based snapshots for hermetic planning. |
|
writ/writ/status
Package status reports what should be present, where it should have come from, and what's missing or different (phase-8 step 47 slice 3 — `writ status` replaces `writ reconcile`).
|
Package status reports what should be present, where it should have come from, and what's missing or different (phase-8 step 47 slice 3 — `writ status` replaces `writ reconcile`). |
|
writ/writ/tree
Package tree builds deployment trees from source and target specifications.
|
Package tree builds deployment trees from source and target specifications. |
|
writ/writ/upgrade
Package upgrade regenerates deployed copied files (templates, secrets, copies) from their current sources (phase-8 step 47 slice 2).
|
Package upgrade regenerates deployed copied files (templates, secrets, copies) from their current sources (phase-8 step 47 slice 2). |
|
writ/writ/verify
Package verify implements `writ verify` — publisher-signature verification for graph and trace documents (phase-8 step 46).
|
Package verify implements `writ verify` — publisher-signature verification for graph and trace documents (phase-8 step 46). |
|
internal
|
|
|
console
Package console provides an interactive terminal UI for guided workflows.
|
Package console provides an interactive terminal UI for guided workflows. |
|
credentials
Package credentials provides secure credential storage using native OS keychains (macOS Keychain, Linux libsecret, Windows Credential Manager) with file-based fallback.
|
Package credentials provides secure credential storage using native OS keychains (macOS Keychain, Linux libsecret, Windows Credential Manager) with file-based fallback. |
|
document
Package document provides structured document I/O for YAML and JSON files.
|
Package document provides structured document I/O for YAML and JSON files. |
|
manifest
Package manifest provides loading and validation for packages-manifest files.
|
Package manifest provides loading and validation for packages-manifest files. |
|
registry
Package registry provides the transport abstraction for devlore registry access.
|
Package registry provides the transport abstraction for devlore registry access. |
|
pkg
|
|
|
application
Package application defines the per-tool Application handle the workflow framework carries on its runtime environment.
|
Package application defines the per-tool Application handle the workflow framework carries on its runtime environment. |
|
assert
Package assert provides uniform vocabulary for invariant checks.
|
Package assert provides uniform vocabulary for invariant checks. |
|
devconfig
Package devconfig is the domain-free foundation for devlore's unified configuration model.
|
Package devconfig is the domain-free foundation for devlore's unified configuration model. |
|
fsroot
Package fsroot provides scoped filesystem roots.
|
Package fsroot provides scoped filesystem roots. |
|
gitignore
Package gitignore provides gitignore-aware file filtering using go-git's gitignore package.
|
Package gitignore provides gitignore-aware file filtering using go-git's gitignore package. |
|
iox
Package iox provides standalone I/O utilities independent of the op framework.
|
Package iox provides standalone I/O utilities independent of the op framework. |
|
op
Package op owns the concrete graph data model shared by the execution engine, Starlark layer, and CLI tools.
|
Package op owns the concrete graph data model shared by the execution engine, Starlark layer, and CLI tools. |
|
op/provider
Package provider holds the shared provider-registration surface.
|
Package provider holds the shared provider-registration surface. |
|
op/provider/appnet
Package appnet provides network actions for the operation graph.
|
Package appnet provides network actions for the operation graph. |
|
op/provider/archive
Package archive provides archive extraction actions for the operation graph.
|
Package archive provides archive extraction actions for the operation graph. |
|
op/provider/elevator
Package elevator is a STUB / PLACEHOLDER for the privilege-elevation provider — the mechanism that fulfills the elevation policy ([6.1-privilege-elevation.md]).
|
Package elevator is a STUB / PLACEHOLDER for the privilege-elevation provider — the mechanism that fulfills the elevation policy ([6.1-privilege-elevation.md]). |
|
op/provider/encryption
Package encryption provides encryption and decryption actions for the operation graph.
|
Package encryption provides encryption and decryption actions for the operation graph. |
|
op/provider/file
Package file provides file system actions for the operation graph.
|
Package file provides file system actions for the operation graph. |
|
op/provider/flow
Package flow implements flow-control methods for execution graphs.
|
Package flow implements flow-control methods for execution graphs. |
|
op/provider/function
Package function is the function provider: session-scoped Starlark function resources.
|
Package function is the function provider: session-scoped Starlark function resources. |
|
op/provider/json
Package json provides JSON encoding and decoding for the operation graph.
|
Package json provides JSON encoding and decoding for the operation graph. |
|
op/provider/mem
Package mem is the in-memory resource provider.
|
Package mem is the in-memory resource provider. |
|
op/provider/pkg
Package pkg provides package management actions for the operation graph.
|
Package pkg provides package management actions for the operation graph. |
|
op/provider/plan
Package plan provides graph-construction actions for the plan namespace.
|
Package plan provides graph-construction actions for the plan namespace. |
|
op/provider/platform
Package platform provides access to platform information by graph actions and executing receivers.
|
Package platform provides access to platform information by graph actions and executing receivers. |
|
op/provider/powershell
Package powershell provides PowerShell 7+ command execution actions for the operation graph.
|
Package powershell provides PowerShell 7+ command execution actions for the operation graph. |
|
op/provider/regex
Package regex provides regular expression operations for the operation graph.
|
Package regex provides regular expression operations for the operation graph. |
|
op/provider/service
Package service provides platform-agnostic service management actions.
|
Package service provides platform-agnostic service management actions. |
|
op/provider/shell
Package shell provides POSIX shell command execution actions for the operation graph.
|
Package shell provides POSIX shell command execution actions for the operation graph. |
|
op/provider/template
Package template provides template expansion actions for the operation graph.
|
Package template provides template expansion actions for the operation graph. |
|
op/provider/ui
Package ui exposes the runtime environment's [status.Narrator] capability to starlark.
|
Package ui exposes the runtime environment's [status.Narrator] capability to starlark. |
|
op/provider/yaml
Package yaml provides YAML encoding and decoding for the operation graph.
|
Package yaml provides YAML encoding and decoding for the operation graph. |
|
op/server
Package server is the HTTP/2 wire listener for op runs (architecture 2.7) — it bridges a remote consumer to a run's in-process op.ControlPlane over REST commands and Server-Sent Events, so the whole bidirectional channel is drivable with curl.
|
Package server is the HTTP/2 wire listener for op runs (architecture 2.7) — it bridges a remote consumer to a run's in-process op.ControlPlane over REST commands and Server-Sent Events, so the whole bidirectional channel is drivable with curl. |
|
op/starlarkbridge
Package starlarkbridge bridges the Go framework and Starlark scripts.
|
Package starlarkbridge bridges the Go framework and Starlark scripts. |
|
platform
Package platform models a target platform as a standalone, op-free capability.
|
Package platform models a target platform as a standalone, op-free capability. |
|
process
Package process is the single bridge between os/exec and the runtime environment's status (narration) and result (typed payload) channels.
|
Package process is the single bridge between os/exec and the runtime environment's status (narration) and result (typed payload) channels. |
|
result
Package result owns the primary output channel — the structured-data stream the framework emits to the user (or to downstream tooling, when piped).
|
Package result owns the primary output channel — the structured-data stream the framework emits to the user (or to downstream tooling, when piped). |
|
signing
Package signing signs and verifies the two signable op artifacts — graphs and execution traces — per the settled signing design (docs/plans/extract-starlark-from-op/phase-8/signing-options.md and graph-signing.md; phase-8 step 46).
|
Package signing signs and verifies the two signable op artifacts — graphs and execution traces — per the settled signing design (docs/plans/extract-starlark-from-op/phase-8/signing-options.md and graph-signing.md; phase-8 step 46). |
|
sink
Package sink defines the byte-out endpoint contract used by pkg/status (categorized narration) and pkg/result (structured result emission).
|
Package sink defines the byte-out endpoint contract used by pkg/status (categorized narration) and pkg/result (structured result emission). |
|
sops
Package sops provides SOPS decryption and encryption detection over the getsops library.
|
Package sops provides SOPS decryption and encryption detection over the getsops library. |
|
status
Package status owns the side-channel for human-facing user-interface output.
|
Package status owns the side-channel for human-facing user-interface output. |
|
xdg
Package xdg resolves the XDG base directories, rooted at the user's home directory on every platform.
|
Package xdg resolves the XDG base directories, rooted at the user's home directory on every platform. |
|
Package schema provides embedded JSON schemas and default configs for the devlore ecosystem.
|
Package schema provides embedded JSON schemas and default configs for the devlore ecosystem. |
Click to show internal directories.
Click to hide internal directories.