@sous-io/sous 0.1.0 → 0.2.0

package/docs/markdown/config-discovery.md

@@ -0,0 +1,74 @@
+# Discovery and Overrides
+
+How sous locates a project's configuration, and every way to override it. Discovery runs on
+every command; there is no opt-out.
+
+## Locating the primary config
+
+Precedence, highest first. Flags beat env vars; both beat walk-up discovery:
+
+1. `--config <path>` (`-c`), or its verbose alias `--sous-config <path>`
+2. `SOUS_CONFIG` environment variable
+3. `--sous-dir <path>` flag
+4. `SOUS_DIR` environment variable
+5. Walk UP from the working directory to the filesystem root, taking the first `.sous/`
+   directory that holds a primary config. A `.sous/` without one does not stop the walk.
+
+A primary config is named `sous.config.js`, `sous.config.mjs`, `sous.config.json`,
+`sous.config.jsonc` or `sous.config.yaml`. The `.jsonc` form is JSON with comments: line comments,
+block comments and trailing commas are all allowed in it.
+
+Every flag or env value resolves with the same rules. It may point at:
+
+- a config file directly,
+- a directory holding one of the primary config names, or
+- a directory whose `.sous/` child holds one (so `--config .` works from a project root).
+
+A leading `~` expands to your home directory. An empty or whitespace-only value (for example a
+bare `export SOUS_CONFIG=`) is treated as unset and falls through to the next tier; it never
+hijacks resolution. Error messages name the source that was actually set (`--sous-dir`,
+`SOUS_CONFIG`, and so on), not a generic flag.
+
+## Locating the conf.d layer directory
+
+Precedence: `--sous-confd <path>` flag, then `SOUS_CONFD` env var, then the default
+`<sousDir>/conf.d`. An override flows everywhere the default would: layer enumeration, the
+duplicate-baseName check, and watch-mode reload.
+
+## Env file layering
+
+After discovery, sous loads two optional files from the discovered `.sous/` into the process
+environment:
+
+- `.env.local`: gitignored; machine-specific values and secrets
+- `.env`: committed; team-shared defaults
+
+Load order is `.env.local` first, then `.env`, and no load ever overwrites a value that is
+already set. Effective precedence is therefore: real shell environment, then `.env.local`, then
+`.env`. The syntax is deliberately small (not a shell): `KEY=value` lines, `#` comments, an
+optional `export ` prefix, single or double quoted values (`\n` and `\t` expand inside double
+quotes), and inline `# comment` stripped from unquoted values. Lines without `=` are ignored.
+
+!> The location vars (`SOUS_CONFIG`, `SOUS_DIR`, `SOUS_CONFD`) are read from the real shell
+environment only, never from the env files. Finding `.env.local` requires knowing `sousDir`
+first, so setting a location var inside `.env.local` has no effect on discovery.
+
+## Discovery errors
+
+All are hard `ConfigError`s; sous never guesses:
+
+- **No config found**: the error lists every directory checked during the walk and shows a
+  minimal starter config.
+- **Multiple primary configs**: two or more of `sous.config.js|mjs|json|jsonc|yaml` in the same
+  `.sous/` is an error naming every candidate.
+- **Duplicate layer baseNames**: any two loaded files (primary or conf.d) whose names differ
+  only by extension is an error naming both files, because their merge order would otherwise
+  depend on extension. `500-repos.json` and `500-repos.jsonc` collide for the same reason, which
+  is what keeps a layer sous is migrating to `.jsonc` from being loaded twice.
+
+## Interaction with `sous launch` pass-through
+
+`sous launch` forwards unrecognized arguments to the launched tool. The `--sous-config`,
+`--sous-dir` and `--sous-confd` flags are declared on every command, so launch consumes them
+rather than forwarding. To pass a literally-named flag through to the tool, put it after a bare
+`--`, which forwards everything following it verbatim.

package/docs/markdown/config-inspection.md

@@ -0,0 +1,69 @@
+# Inspecting and Validating
+
+## The validation pipeline
+
+Every command validates the config on load, in this order:
+
+1. The kernel merges all layers (any layer failure names the file).
+2. The legacy-schema guard rejects the removed multi-project keys (`projects`,
+   `defaultProject`) with a migration message.
+3. A strict schema validates the merged result: unknown keys at ANY level are rejected with the
+   full path and a typo hint; a target must have exactly one of `entryPoint` / `entryGlob`;
+   `version`, when present, must be `1` (anything else fails as unsupported by this sous
+   version).
+4. Variable resolution and substitution run as values are used; `sous config validate` runs them
+   eagerly (below).
+
+Validation applies to the MERGED config only. A `conf.d/` fragment on its own does not need to
+be a complete config; it only needs to use schema-known keys.
+
+## The JSON Schema artifact
+
+Sous ships `sous.config.schema.json` at the package root (generated from the same schema that
+validates at load time). A JSON config can bind it for editor autocompletion and external
+tooling:
+
+```json
+{ "$schema": "./path/to/sous.config.schema.json" }
+```
+
+The `$schema` key is accepted at the top level and ignored by sous itself.
+
+## sous config show
+
+Prints the full merged config as pretty JSON: the config as written, after layer merging but
+BEFORE variable resolution. Output is machine-readable by contract: the decorative header and
+any error text go to stderr, so `sous config show | jq .` always receives either valid JSON or
+nothing. Colorized only when stdout is a TTY.
+
+## sous config get
+
+Prints one value by dot-path, with `[n]` for array indices:
+
+```bash
+sous config get name
+sous config get compilation.targets[0].entryPoint
+```
+
+Scalars print raw (no quotes); objects and arrays print as pretty JSON. A missing path exits
+non-zero with a message on stderr.
+
+`--layers` adds provenance: for each loaded layer whose cumulative merge CHANGED the value at
+that path, one line prints the layer file and the old and new values, starting from `(unset)`.
+This answers "which file set this?" directly:
+
+```bash
+sous config get tools.claude.command --layers
+```
+
+## sous config validate
+
+Runs the whole pipeline eagerly: discovery, kernel merge, legacy guard, schema, then FULL
+variable resolution including compilation, tools and watch config. This surfaces the errors
+schema validation alone cannot: variable cycles, undefined `${refs}`, and bad substitutions in
+entry points and destinations. On success it prints a short summary (config file, layer count,
+target count, tools) and exits 0; on failure it prints the `ConfigError` and exits non-zero.
+
+All three commands honor the same config-locating flags and env vars as every other command
+(`--config`/`-c`/`--sous-config`, `--sous-dir`, `--sous-confd`, `SOUS_CONFIG`, `SOUS_DIR`,
+`SOUS_CONFD`); see [Discovery and overrides](config-discovery.md).

package/docs/markdown/config-layers.md

@@ -0,0 +1,92 @@
+# Layers and Merging
+
+Every config source (the primary file plus each `conf.d/` layer) is loaded by one subprocess,
+the config kernel, which merges everything into a single cumulative config and returns it as
+plain JSON.
+
+## Load order
+
+1. The primary `sous.config.*` file.
+2. Every `*.js|mjs|json|jsonc|yaml` file directly inside `conf.d/` (non-recursive), sorted BYTEWISE
+   by filename. The sort is locale-independent and per-machine stable, but it is not numeric:
+   `10-a.json` sorts before `2-b.json` because the character `1` precedes `2`. Zero-pad numeric
+   prefixes (`02-`, `10-`) when ordering matters.
+
+A `.jsonc` layer is JSON with comments: line comments, block comments and trailing commas are all
+allowed in it, and it merges exactly like a `.json` one. The layers sous manages for you are
+written that way, so each can say in the file itself what it holds.
+
+## JSON forcing
+
+Each layer's contribution passes through a JSON round-trip BEFORE merging:
+
+- Functions and `undefined` values are dropped.
+- `RegExp` becomes `{}`; `Date` becomes its ISO string.
+- The final merged config is round-tripped once more on the way out.
+
+Write configs as plain data; behavior belongs in `configure()` (below), which runs inside the
+kernel before serialization.
+
+## Deep merge semantics
+
+Applied key by key when a later layer meets the cumulative config:
+
+- plain object + plain object: recurse
+- array + array: CONCATENATE, cumulative first, layer second. No dedupe; loading the same
+  fragment twice duplicates its array entries. There is no declarative way to remove or replace
+  an array entry; use `configure()` and mutate directly when you need that.
+- anything else (scalar, mixed types, null): the later layer replaces
+- an own `__proto__`, `constructor`, or `prototype` key in layer data is skipped
+  (prototype-pollution guard)
+
+## The JS/MJS layer contract
+
+A `.js` or `.mjs` layer may export a config object, a configure function, or both:
+
+- **Object**: `export const config = {...}`, or a default export that is a non-function object.
+  Merged first.
+- **Function**: `export function configure(currentConfig, builder)`, or a default export that is
+  a function. Runs AFTER the object (if any) merges. It may be async and is awaited. It may
+  mutate `currentConfig` by reference freely. A returned object is merged after it resolves,
+  UNLESS the return value IS `currentConfig` itself (the mutate-and-return-for-chaining idiom),
+  which is skipped so arrays are not duplicated by a self-merge.
+
+## The builder
+
+`configure` receives a builder with:
+
+- `builder.config`: the live cumulative config (same object as `currentConfig`)
+- `builder.sousDir`, `builder.confDir`: resolved directories
+- `builder.currentFile`: absolute path of the layer being loaded
+- `builder.env(name, fallback)`: read an environment variable (env files are already loaded at
+  this point)
+- `builder.merge(obj)`: JSON-force `obj` and deep-merge it into the cumulative config
+- `builder.loadConfig(path)`: load another file (any supported extension) under the full layer
+  contract, including its own nested `configure`. Async.
+- `builder.loadConfigs(globPattern)`: glob, sort matches bytewise, and load each. Async.
+
+Builder path arguments resolve BEFORE variable resolution, so user `_vars` do not exist yet.
+Only the auto-vars may appear in them: `${sousDir}`, `${sousConfDir}`, `${sousRootPath}`,
+`${sousVersion}`. Any other `${name}` in a builder path is a hard error listing the allowed
+names. Relative paths resolve against the directory of `builder.currentFile`. Load cycles (a
+file loading itself, directly or indirectly) are detected and reported.
+
+## Failure behavior
+
+Any layer failure (a JSON/YAML parse error, an import error, a `configure` throw, a load cycle,
+the legacy multi-project schema) halts the whole load with an error naming the layer file. There
+is no warn-and-skip; a broken layer never silently drops out of the merge.
+
+## The managed 5xx layer band
+
+`conf.d/500-*` through `conf.d/599-*` is reserved for layers the sous CLI writes on your behalf.
+They are `.jsonc`, and each one opens with a header comment saying what it holds.
+
+**Sous edits these files by key; you may edit them too.** A write rewrites only the bytes of the
+entry that changes, so your comments, your key order and your formatting survive it, and repeated
+edits produce minimal version-control diffs. Sous never edits a hand-written primary config or a
+layer outside the 5xx band. To override a managed value rather than change it in place, add a
+higher-sorting layer (for example `conf.d/600-overrides.json`).
+
+Where a comment is impossible because a format really is strict JSON, the convention is a `//`
+key, which sous ignores wherever it appears.

package/docs/markdown/config-variables.md

@@ -0,0 +1,79 @@
+# Variables
+
+How `${var}` references resolve inside a sous config.
+
+?> Template files use LiquidJS double-brace syntax instead; that is a different stage entirely.
+This page is about the config side only.
+
+## The scope chain
+
+Later scopes override earlier ones:
+
+```
+auto-vars  ->  _env scope  ->  _vars  ->  compilation._vars  ->  target._vars  ->  output._vars
+```
+
+Nested `_vars` blocks (on `compilation`, on a target, on an output) resolve with their parent
+scope inherited, so a target var may reference a top-level var, and an output var may override
+both for that output only.
+
+## Auto-vars
+
+Always injected first, before `_env` and `_vars`:
+
+| Variable | Value |
+|----------|-------|
+| `sousDir` | the discovered `.sous/` directory holding the active config |
+| `sousConfDir` | the `conf.d/` drop-in directory for the active config |
+| `sousConfigPath` | absolute path of the active primary config file |
+| `sousRootPath` | absolute path of the sous CLI install directory |
+| `sousVersion` | the sous CLI version string |
+| `sousTemplatePath` | absolute path of the `.tpl.` file being rendered (render time only) |
+| `sousTemplateDir` | directory of the `.tpl.` file being rendered (render time only) |
+
+The `sous*` namespace is reserved: defining any var whose name starts with `sous` earns a
+warning and risks colliding with a future auto-var.
+
+## _env
+
+The top-level-only `_env` block maps config var names to environment variable names:
+`_env: { userHome: "HOME" }` makes `${userHome}` available everywhere. Values come from the real
+shell environment, `.sous/.env.local`, or `.sous/.env` (first writer wins, in that order). A
+mapped env var that is not set anywhere is a hard `ConfigError` telling you which file to define
+it in.
+
+## Fixpoint resolution
+
+Each `_vars` block resolves by a fixpoint loop, not top-to-bottom: every round re-scans the
+still-unresolved entries and finalizes any whose `${refs}` all resolve, repeating until a round
+finalizes nothing. Declaration order therefore never matters; `{ file: "${root}/x", root:
+"/data" }` resolves as readily as the reverse.
+
+If entries remain unresolved when progress stops, that is a hard `ConfigError`. The message
+separates:
+
+- **Cycles**: entries that reference each other (members are named), and
+- **Undefined references**: `${names}` defined nowhere (each is named along with the entries
+  that need it),
+
+and then lists the variables that ARE in scope. There is no silent fallthrough: an unresolved
+`${var}` never survives into a value sous acts on. Entry points, destinations, prompt files and
+similar action values additionally pass a strict substitution that fails on any leftover
+reference.
+
+## Path normalization
+
+Absolute `entryPoint`, `entryGlob`, `globBase`, `destinationFile` and `destinationDir` values
+are normalized after substitution, so the common `${sousDir}/..` idiom collapses to the real
+parent directory. This matters: prune compares tracked outputs against `destinationDir` by
+string prefix, and watch mode matches event paths against watched entries; both need the
+normalized form.
+
+## Special variables sous reads
+
+Two ordinary `_vars` entries change sous's own behavior when present:
+
+- `stateFilePath`: overrides where the build state file is written (default
+  `<sousDir>/sous.state.json`)
+- `pidFilePath`: overrides where the watch-mode PID file is written (default
+  `<sousDir>/sous.pid`)

package/docs/markdown/configuration.md

@@ -0,0 +1,71 @@
+# Configuration
+
+Sous reads one configuration per project from the project's `.sous/` directory. One config
+describes one project: every setting lives at the top level of a single flat object. There is no
+user-level config (nothing is read from `~/.sous`) and no multi-project map.
+
+## The config file
+
+Exactly one primary config lives inside `.sous/`: `sous.config.js`, `sous.config.mjs`,
+`sous.config.json`, `sous.config.jsonc`, or `sous.config.yaml`. Two or more candidates is an
+error, never a silent first-match. A typical config:
+
+```js
+export const config = {
+  version: 1,                          // optional; must be 1 when present
+  name: "My Project",                  // optional display name
+  _env: { userHome: "HOME" },          // map config vars from env vars (top-level only)
+  _vars: {
+    projectRoot: "${sousDir}/..",      // ${sousDir} is the discovered .sous/ dir
+    docsDir: "${projectRoot}/docs",    // declaration order never matters
+  },
+  _aliases: { myDocs: "${docsDir}" },  // extra @include bases (optional)
+  compilation: {
+    targets: [
+      {
+        entryPoint: "${projectRoot}/prompts/AGENTS.md",
+        outputs: [{ destinationFile: "${projectRoot}/AGENTS.md" }],
+      },
+      {
+        entryGlob: "${projectRoot}/prompts/skills/**/*.md",
+        outputs: [{ destinationDir: "${projectRoot}/.claude/skills" }],
+      },
+    ],
+  },
+  tools: {
+    claude: { command: "claude", promptFile: "${projectRoot}/CLAUDE.md" },
+  },
+};
+```
+
+A JSON config may set `"$schema"` to bind the `sous.config.schema.json` artifact shipped with
+sous for editor autocompletion; sous accepts and ignores the key.
+
+?> Configs use `${var}` syntax. Template files use LiquidJS double-brace syntax instead; the two
+are resolved at different stages and never mix.
+
+## Composition
+
+The primary config is optionally extended by drop-in layers: every `*.js|mjs|json|jsonc|yaml` file
+directly inside `.sous/conf.d/` is loaded after the primary config and deep-merged over it. A
+`.js`/`.mjs` config or layer can also compose programmatically through a `configure()` function.
+[Layers and merging](config-layers.md) covers the full semantics.
+
+## Where to go next
+
+- [Discovery and overrides](config-discovery.md): how sous finds the config, and the flags and
+  environment variables that override it
+- [Layers and merging](config-layers.md): `conf.d/` ordering, merge semantics, the JS
+  `configure()` contract
+- [Variables](config-variables.md): the `${var}` scope chain, auto-vars, fixpoint resolution
+- [Inspecting and validating](config-inspection.md): the `sous config` commands and the
+  validation pipeline
+
+## Rules of the road
+
+- Hand-written config belongs in the primary file or your own `conf.d/` layers. The
+  `conf.d/500-*` through `conf.d/599-*` band is reserved for layers the sous CLI itself writes.
+  Sous edits those by key, so you may edit them too and your comments, key order and formatting
+  survive; put a layer of your own outside the band.
+- Any config problem halts sous with a `ConfigError` naming the offending file; there is no
+  warn-and-continue.

package/docs/markdown/design-principles.md

@@ -0,0 +1,59 @@
+# Design Principles
+
+These principles govern every feature sous ships. They are constraints on design, not
+aspirations; when a proposal violates one, the proposal changes.
+
+## 1. Augment, don't compete
+
+When a coding tool can do something natively, do it natively; sous exists for what the tool
+cannot do. Sous never wraps, replaces, or re-implements a capability an agent harness already
+provides well.
+
+*Example: sous compiles `CLAUDE.md` and skill files because no harness composes them from
+shared, templated sources; it does not try to replace how the harness loads them.*
+
+## 2. Fill the collective gaps
+
+Sous actively tries to avoid competing with any tool, and especially with any class of tools.
+Instead it fills the gaps that most or all tools either cannot or will not fill, because those
+problems span every provider at once.
+
+*Example: keeping one instruction source current across Claude, Codex, and whatever comes next
+is nobody's product; it is sous's whole job.*
+
+## 3. Be a tool, not a framework
+
+Sous avoids forcing opinions; that is different from having none. Beyond the few core skills
+that teach agents how to work with sous itself, every built-in is opt-in only, and even the
+core is opt-out-able.
+
+*Example: the core skills arrive by default because agents need them to avoid editing
+generated files, but a single explicit setting removes them entirely.*
+
+## 4. Be easy to enter
+
+Sous copies plain files just as readily as it renders templates, so adopting it does not
+require converting anything. Existing marketplaces and installers keep working, pointed at a
+sous-managed directory.
+
+*Example: drop an existing skill directory into a sous target unchanged; it compiles verbatim
+on the next build.*
+
+## 5. Be easy to exit
+
+Leaving sous must never cost more than a commit. The generated output is complete and ordinary;
+commit it and delete `.sous`, and the project keeps working exactly as it did.
+
+*Example: every file sous writes is a normal file in its final location; nothing references
+sous at runtime.*
+
+## 6. Maximum user control
+
+Everything gets an escape hatch, within practicality. The happy path stays maximally simple;
+the escape hatches are advanced usage and may require the docs, but they must exist and they
+still get thoughtful ergonomics. Projects control everything granularly, and an individual
+user can override every project decision through their own configuration layers.
+
+*Example: subscribing to a recipe is one line and pulls in everything the recipe provides;
+excluding one skill from that subscription may take a documented setting, but the setting is
+there.*