@sous-io/sous 0.2.3 → 0.2.6

package/README.md

@@ -26,12 +26,19 @@ formats agents actually read: `.claude/` plus `CLAUDE.md` for Claude Code, `.cod
 
 ## Quickstart
 
-Install the CLI:
+Install the CLI globally, or add it to a project, or both:
 
 ```bash
-npm install -g @sous-io/sous
+npm install -g @sous-io/sous     # one sous for every project on the machine
+npm install -D @sous-io/sous     # the version this project's templates were written against
 ```
 
+A project install pins the sous version a project builds with, and it always does the
+building: a global `sous` run anywhere inside a project that holds `node_modules/@sous-io/sous`
+hands the command to that copy, so `sous`, `npx sous` and a package script all produce the same
+output. When the two versions differ, one line on standard error says which copy ran. Set
+`SOUS_NO_DELEGATE=1` to run the copy you invoked instead.
+
 Or run it from a clone (useful when developing sous itself):
 
 ```bash
@@ -41,16 +48,22 @@ npm install
 npm link
 ```
 
-Then set up a project. A project needs a `.sous/` directory holding a config file, named
-`sous.config.js`, `sous.config.mjs`, `sous.config.json`, or `sous.config.yaml`:
+Then set up a project:
 
 ```bash
 cd /path/to/your/project
-mkdir .sous
-$EDITOR .sous/sous.config.js
+sous init
 ```
 
-A config that compiles one file:
+`sous init` writes the project's `.sous/` directory and runs the first build. It creates a
+commented `sous.config.js` (pass `--format json` for a JSON config bound to the shipped
+schema), a starter prompt at `.sous/prompts/AGENTS.md` that the config compiles to `AGENTS.md`
+at the project root, the two env files described below, and a `.sous/.gitignore` covering the
+files sous keeps local to one machine. The first build compiles the starter prompt and the
+`core` skills every project gets, and pins them in `.sous/sous.lock.json`. A project that
+already holds a config is left untouched.
+
+The config it writes compiles one file:
 
 ```js
 export const config = {
@@ -59,17 +72,19 @@ export const config = {
   compilation: {
     targets: [
       {
-        entryPoint: "${sousDir}/AGENTS.md",
-        outputs: [{ destinationFile: "${projectRoot}/CLAUDE.md" }],
+        entryPoint: "${sousDir}/prompts/AGENTS.md",
+        outputs: [{ destinationFile: "${projectRoot}/AGENTS.md" }],
       },
     ],
   },
+  recipeOutputs: { skills: ["${projectRoot}/.claude/skills"] },
 };
 ```
 
 `${sousDir}` is the `.sous/` directory sous found, so a config can name paths relative to
-itself without hardcoding anything machine-specific. One config describes one project. Then
-build:
+itself without hardcoding anything machine-specific. One config describes one project. A
+`.sous/` may hold one config file, named `sous.config.js`, `sous.config.mjs`,
+`sous.config.json`, `sous.config.jsonc` or `sous.config.yaml`. After editing, build:
 
 ```bash
 sous build
@@ -95,6 +110,7 @@ Useful commands:
 
 | Command | What it does |
 |---|---|
+| `sous init` | Set a project up: write `.sous/`, then run the first build |
 | `sous build` | Compile, then prune stale outputs |
 | `sous build --watch` | Rebuild on source changes |
 | `sous compile` | Compile only |

package/bin/run.js

@@ -1,26 +1,38 @@
 #!/usr/bin/env node
-import { register } from "tsx/esm/api";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { handOffToProjectInstall, isEnvFlagOn } from "../src/lib/project-install.mjs";
 
-// The CLI runs from TypeScript source; register tsx before oclif dynamically
-// imports any command module. Resolving "tsx" from this file (rather than a
-// $PKG_ROOT/node_modules path) works in every install layout: repo clone,
-// global install (nested deps), and local/npx installs (hoisted deps).
-register();
+// A project that installs @sous-io/sous itself has pinned the version its
+// templates and lockfile were written against, so that copy does the work.
+// This runs before anything else is loaded: when a project copy is found, its
+// own bin is imported into this process and this one loads nothing further
+// (see src/lib/project-install.mjs for the rules, and SOUS_NO_DELEGATE to
+// keep the invoked copy running).
+const ownRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const handedOff = await handOffToProjectInstall({ ownRoot });
 
-const { execute, settings } = await import("@oclif/core");
+if (!handedOff) {
+  // The CLI runs from TypeScript source; register tsx before oclif dynamically
+  // imports any command module. Resolving "tsx" from this file (rather than a
+  // $PKG_ROOT/node_modules path) works in every install layout: repo clone,
+  // global install (nested deps), and local/npx installs (hoisted deps).
+  const { register } = await import("tsx/esm/api");
+  register();
 
-// tsx (above) already makes .ts imports work, so oclif's own auto-transpile
-// machinery is redundant; leaving it on makes every downstream run warn that
-// the (unshipped) typescript devDependency is missing.
-settings.enableAutoTranspile = false;
+  const { execute, settings } = await import("@oclif/core");
 
-// oclif's development mode turns on its debug setting, which makes every error
-// it prints a raw stack trace. Sous reports its own errors as sentences (see
-// src/utils/command-errors.ts), so development mode is switched on only when
-// SOUS_DEBUG asks for the traces; anything that gets past a command's own
-// reporting then prints its stack too.
-const debugRequested = !["", "0", "false", "no", "off"].includes(
-  (process.env.SOUS_DEBUG ?? "").trim().toLowerCase()
-);
+  // tsx (above) already makes .ts imports work, so oclif's own auto-transpile
+  // machinery is redundant; leaving it on makes every downstream run warn that
+  // the (unshipped) typescript devDependency is missing.
+  settings.enableAutoTranspile = false;
 
-await execute({ development: debugRequested, dir: import.meta.url });
+  // oclif's development mode turns on its debug setting, which makes every error
+  // it prints a raw stack trace. Sous reports its own errors as sentences (see
+  // src/utils/command-errors.ts), so development mode is switched on only when
+  // SOUS_DEBUG asks for the traces; anything that gets past a command's own
+  // reporting then prints its stack too.
+  const debugRequested = isEnvFlagOn(process.env.SOUS_DEBUG);
+
+  await execute({ development: debugRequested, dir: import.meta.url });
+}

package/docs/markdown/README.md

@@ -17,6 +17,37 @@ compiled 4 targets, pruned 1 stale file
 ?> These docs are young. **Configuration** and **Repositories** are the reference material so
 far; more will follow.
 
+## Installing
+
+Sous installs three ways, and they work together:
+
+- **Globally** (`npm install -g @sous-io/sous`): one `sous` on the path for every project on the
+  machine, and the one to reach for first.
+- **In a project** (`npm install -D @sous-io/sous`): the project pins the version its templates
+  and its lockfile were written against, and `npx sous` or a package script runs it. This is the
+  right choice for a team, because the implicit `core` subscription asks for exactly the running
+  version and a project built by two versions in turn rewrites its committed lockfile back and
+  forth.
+- **Both**: a global `sous` run anywhere inside a project that holds `node_modules/@sous-io/sous`
+  hands the whole command to that copy before loading any of its own code, so the project's
+  version always does the building however it was invoked. The lookup walks up from the working
+  directory the way Node resolves a package, so a copy hoisted to a monorepo root is found from
+  any package inside it.
+
+When the two versions differ, one sentence on standard error names the copy that ran and the
+one you invoked; standard output is untouched, so a piped command prints exactly what it always
+did. Set `SOUS_DEBUG` and the sentence prints on every hand-off. Set `SOUS_NO_DELEGATE` to
+anything but `0`, `false`, `no` or `off` to run the copy you invoked instead, for debugging a
+broken project install or for deliberately using the global one:
+
+```term
+$ sous --version
+Running the project's own sous 0.2.4 from /work/app/node_modules/@sous-io/sous instead of the sous 0.3.0 you invoked; set SOUS_NO_DELEGATE=1 to run the one you invoked.
+@sous-io/sous/0.2.4 linux-x64 node-v22.21.0
+$ SOUS_NO_DELEGATE=1 sous --version
+@sous-io/sous/0.3.0 linux-x64 node-v22.21.0
+```
+
 ## Where to look
 
 - Watch the [animated introduction](../) for the full pitch

package/docs/markdown/_sidebar.md

@@ -20,3 +20,5 @@
 - **ADRs**
   - [0001: Repositories](adrs/0001-repositories.md)
   - [0002: Recipe answers in the template scope](adrs/0002-recipe-answers-in-templates.md)
+  - [0003: Project setup with sous init](adrs/0003-project-init.md)
+  - [0004: A global sous defers to the project's install](adrs/0004-project-install-handoff.md)

package/docs/markdown/commands.md

@@ -46,6 +46,27 @@ Every topic answers to both spellings of its name: `repo` and `repos`, `subscrip
 
 ## Top-level commands
 
+### `sous init [DIRECTORY]`
+Sets a project up for sous: writes its `.sous/` directory, then runs the first build. It is the one command that
+runs before a config exists, and the starting point for a project that has never used sous. It writes a commented
+primary config, a starter prompt at `.sous/prompts/AGENTS.md` that the config compiles to `AGENTS.md` at the
+project root, `.sous/.env` and `.sous/.env.local.example`, and the sous-managed block in `.sous/.gitignore`. The
+first build compiles the starter prompt and the `core` skills, and pins them in `.sous/sous.lock.json`.
+
+A project whose `.sous/` already holds a primary config is refused, and nothing is written. Setting up a directory
+inside a project that is already set up is a question rather than an error, since a subproject may want its own
+instructions; `-y, --yes` answers it ahead of time, and a run with no terminal fails naming that flag.
+
+- `DIRECTORY`: the project directory to set up; the current one by default. `--sous-dir` and `SOUS_DIR` also say
+  where, when no directory is given.
+- `--format <js|json>`: which config to write, `js` by default. The JSON config carries `$schema`, bound to the
+  schema artifact published for the running sous version.
+- `--name <name>`: the display name written into the config; the directory's own name by default.
+- `--no-build`: write the setup without running the first build.
+- `--dry-run`: print the files that would be written without writing them.
+
+Example: `sous init --format json`
+
 ### `sous build`
 Compiles this project's outputs, then removes the ones its config no longer produces. It is compile plus prune,
 and the command you want almost always. Takes `--dry-run`.
@@ -317,7 +338,12 @@ $ sous subscription add workflow --non-interactive
 No expected failure prints a stack trace. A failure sous did not expect prints the message and one more sentence
 asking you to set `SOUS_DEBUG=1` and run the command again. Set `SOUS_DEBUG` to anything but `0`, `false`, `no`
 or `off` and every reported failure prints its stack to standard error underneath the message:
-`SOUS_DEBUG=1 sous build`. Nothing else changes when it is set.
+`SOUS_DEBUG=1 sous build`. The one other thing it changes is that every hand-off to a project's own install
+announces itself, not only one between different versions.
+
+`SOUS_NO_DELEGATE` is the other environment variable every command reads. Set it the same way and the copy of
+sous you invoked runs the command, even inside a project that installs its own `@sous-io/sous`; see
+[Installing](README.md#installing) for the hand-off it switches off.
 
 Every listing fits itself to the terminal it runs in: columns shrink, descriptions wrap, and a path or URL is
 cut in the middle so the host and the last segment both survive. On a terminal too narrow, the least important

package/docs/markdown/config-discovery.md

@@ -57,8 +57,9 @@ first, so setting a location var inside `.env.local` has no effect on discovery.
 
 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.
+- **No config found**: the error lists every directory checked during the walk and names the two
+  fixes: run `sous init` in the project's root directory, which writes the config and everything
+  else a first build needs, or pass `--config <path>`.
 - **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

package/docs/markdown/config-inspection.md

@@ -27,7 +27,10 @@ tooling:
 { "$schema": "./path/to/sous.config.schema.json" }
 ```
 
-The `$schema` key is accepted at the top level and ignored by sous itself.
+The `$schema` key is accepted at the top level and ignored by sous itself. A config written by
+`sous init --format json` binds it to the same artifact as published on GitHub for the running
+version, so an editor resolves it without a path into the installed package; point it at the
+package-local copy instead when the editor should work offline.
 
 ## sous config show
 

package/docs/markdown/configuration.md

@@ -39,7 +39,8 @@ export const config = {
 ```
 
 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.
+sous for editor autocompletion; sous accepts and ignores the key. `sous init --format json`
+writes one already bound to the copy of that artifact published for the running version.
 
 ?> Configs use `${var}` syntax. Template files use LiquidJS double-brace syntax instead; the two
 are resolved at different stages and never mix.

package/docs/markdown/repositories-quickstart.md

@@ -24,7 +24,10 @@ echo 'name: my-project' > .sous/sous.config.yaml
 ```
 
 Everything else has a default: skills compile into `<project root>/.claude/skills`, and the
-lockfile, the state file and the config layers sous writes land under `.sous/`. `SOUS_HOME` puts
+lockfile, the state file and the config layers sous writes land under `.sous/`. Outside a
+walkthrough, `sous init` writes a fuller starting point (a commented config, a starter prompt,
+the env files and the ignore block) and runs the first build for you; the one-line config is
+used here so that each step shows one thing. `SOUS_HOME` puts
 the machine-wide store somewhere throwaway, so this walkthrough leaves your real one alone. See
 [The config file](configuration.md) for the keys you will want later.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sous-io/sous",
-  "version": "0.2.3",
+  "version": "0.2.6",
   "description": "Compiles AI coding agent configuration (CLAUDE.md, skills, memories) from LiquidJS templates",
   "type": "module",
   "license": "Apache-2.0",

package/recipes/core/sous-skills/sous.recipe.yaml

@@ -11,7 +11,7 @@ formatVersion: 1
 
 namespace: core
 name: sous-skills
-version: 0.2.3
+version: 0.2.6
 
 description: >-
   The skills that teach an agent what sous is and how it works: which files sous

package/src/base-command.ts

@@ -40,6 +40,23 @@ import { reportCommandError } from "./utils/command-errors.js";
  * lives in `lib/interactive.ts`, which also treats a truthy `CI` and a
  * non-terminal stdin or stdout the same way.
  */
+/**
+ * What the config-locating flags and environment said on this run, resolved to
+ * absolute paths but not yet turned into a config.
+ */
+export type ConfigLocator = {
+  /** The working directory discovery started from. */
+  cwd: string;
+  /**
+   * The explicit config location, when one was given: the resolved path and
+   * the flag or environment variable that supplied it (`--config`,
+   * `--sous-config`, `SOUS_CONFIG`, `--sous-dir` or `SOUS_DIR`).
+   */
+  primary?: { value: string; source: string };
+  /** The conf.d directory override, when `--sous-confd` or `SOUS_CONFD` gave one. */
+  confDirOverride?: string;
+};
+
 export abstract class BaseCommand extends Command {
   static baseFlags = {
     config: Flags.string({
@@ -60,11 +77,29 @@ export abstract class BaseCommand extends Command {
     "non-interactive": nonInteractiveFlag(),
   };
 
+  /**
+   * Whether a run of this command needs a project config to exist. Every
+   * command that works on a project leaves this true, and a run that finds no
+   * config fails before `run()` with the "No sous config found" block. The one
+   * command whose job is to CREATE the config sets it false: discovery still
+   * runs, so the config-locating flags still say where the project is, but
+   * finding nothing is the expected case rather than an error, and `settings`
+   * stays unset until `adoptConfig` is given the config that was written.
+   */
+  static requiresConfig = true;
+
   protected settings!: Settings;
 
   /** Where the active config was found. */
   protected configContext!: ConfigContext;
 
+  /**
+   * What the config-locating flags and environment said, before discovery
+   * turned it into a config. A command that runs without a config reads the
+   * project's location from here.
+   */
+  protected configLocator!: ConfigLocator;
+
   /** The full discovery result, including how the config was located. */
   protected discovered!: DiscoveredConfig;
 
@@ -142,6 +177,16 @@ export abstract class BaseCommand extends Command {
       [sousDirEnv, "SOUS_DIR"],
     ];
     const primary = primaryCandidates.find(([value]) => value !== undefined);
+    const requiresConfig = (this.constructor as typeof BaseCommand).requiresConfig;
+
+    this.configLocator = {
+      cwd,
+      primary:
+        primary !== undefined
+          ? { value: path.resolve(cwd, expandHome(primary[0] as string)), source: primary[1] }
+          : undefined,
+      confDirOverride,
+    };
 
     let discovered: DiscoveredConfig | null;
 
@@ -150,6 +195,9 @@ export abstract class BaseCommand extends Command {
       try {
         discovered = resolveConfigFlag(primarySource, cwd, confDirOverride, sourceLabel);
       } catch (error) {
+        // A command that creates the config is pointed at a place with none in
+        // it by design; the flag still says where, so this is not a failure.
+        if (!requiresConfig) return;
         displayError(error instanceof Error ? error.message : String(error), this.errorSink);
         return this.exit(1);
       }
@@ -158,10 +206,29 @@ export abstract class BaseCommand extends Command {
     }
 
     if (!discovered) {
+      if (!requiresConfig) return;
       displayErrorBlock(formatNotFoundMessage(), this.errorSink);
       return this.exit(1);
     }
 
+    await this.adoptConfig(discovered);
+  }
+
+  /** True once a config has been discovered or adopted and its settings loaded. */
+  protected get hasConfig(): boolean {
+    return this.discovered !== undefined;
+  }
+
+  /**
+   * Makes a discovered config THE config for the rest of the run: loads its
+   * env files, enumerates its layers again now that `SOUS_HOME` may have
+   * changed, and loads the settings. `init()` calls it for the config discovery
+   * found; a command that creates a config calls it for the one it wrote, so
+   * both go through the same steps in the same order.
+   *
+   * @param discovered - The config to adopt.
+   */
+  protected async adoptConfig(discovered: DiscoveredConfig): Promise<void> {
     // Inject .sous/.env.local and .sous/.env before anything resolves variables,
     // keeping a copy of what the shell itself set so the variables layer can
     // still tell the two apart.
@@ -172,27 +239,28 @@ export abstract class BaseCommand extends Command {
     // file-settable, and it decides where the store holding a subscribed
     // recipe's config layers is. A first pass already ran during discovery, when
     // only the real environment was known.
+    let refreshed: DiscoveredConfig;
     try {
-      discovered = refreshDiscoveredConfig(discovered);
+      refreshed = refreshDiscoveredConfig(discovered);
     } catch (error) {
       displayErrorBlock(error instanceof Error ? error.message : String(error), this.errorSink);
       return this.exit(1);
     }
 
-    this.discovered = discovered;
+    this.discovered = refreshed;
     this.configContext = {
-      sousDir: discovered.sousDir,
-      configPath: discovered.configPath,
-      confDir: discovered.confDir,
-      layerPaths: discovered.layerPaths,
+      sousDir: refreshed.sousDir,
+      configPath: refreshed.configPath,
+      confDir: refreshed.confDir,
+      layerPaths: refreshed.layerPaths,
     };
 
     // Routed through the command's error sink, not stdout: a recipe layer
     // warning must not land in the middle of `sous config show | jq`.
-    for (const notice of discovered.recipeLayerWarnings) warning(notice, this.errorSink);
+    for (const notice of refreshed.recipeLayerWarnings) warning(notice, this.errorSink);
 
     try {
-      this.settings = await loadSettings(discovered);
+      this.settings = await loadSettings(refreshed);
     } catch (error) {
       displayErrorBlock(error instanceof Error ? error.message : String(error), this.errorSink);
       return this.exit(1);

package/src/commands/build.ts

@@ -5,15 +5,12 @@ import { PidService } from "../lib/pid-service.js";
 import { resolveRootScope } from "../lib/settings.js";
 import { describeLinkedRepos } from "../lib/repos/links.js";
 import { resolveStoreSettings } from "../lib/repos/store/settings.js";
-import {
-  subscriptionServiceFor,
-  type SubscriptionService,
-} from "../lib/repos/subscription-service.js";
+import { prepareRepositoriesForBuild } from "../lib/build-preparation.js";
+import { subscriptionServiceFor } from "../lib/repos/subscription-service.js";
 import { buildReloadWatchConfig, startConfigReloadWatch } from "../lib/watch-loop.js";
 import type { WatchHandle } from "../lib/watch-service.js";
 import { WatchService } from "../lib/watch-service.js";
 import {
-  blankLine,
   footer,
   heading,
   log,
@@ -87,7 +84,7 @@ export default class Build extends BaseCommand {
     });
 
     if (!flags["dry-run"] && !flags["no-compile"]) {
-      await this.prepareRepositories(repositories);
+      await prepareRepositoriesForBuild(repositories);
     }
 
     heading("Building");
@@ -196,78 +193,4 @@ export default class Build extends BaseCommand {
       await new Promise(() => {}); // keep process alive
     }
   }
-
-  /**
-   * Gets this project's recipes ready to compile: restores whatever the store is
-   * missing (a fresh clone, or a collected store) and then asks upstream for the
-   * repositories that prefer a newer in-range version.
-   *
-   * Restoring asks nothing and decides nothing; it fetches exactly what the
-   * lockfile pins. An upstream check that fails is reported and then ignored,
-   * because a build must not depend on the network being up.
-   *
-   * @param repositories - The subscription service for this project.
-   */
-  private async prepareRepositories(repositories: SubscriptionService): Promise<void> {
-    const needsRestore = repositories.needsRestore();
-    if (needsRestore) {
-      heading("Restoring recipes");
-      blankLine();
-      paragraph(
-        "This project's lockfile pins recipes that are not in the store on this " +
-          "machine, so they are being fetched at exactly the versions it records."
-      );
-    }
-
-    const { seed, subscriptions, restored, upstream } =
-      await repositories.prepareForBuild();
-
-    // Seeding the packaged core recipe is silent when it works, which is almost
-    // always; it is only worth a word when it could not be done at all.
-    if (seed.skippedBecause !== undefined) warning(seed.skippedBecause);
-
-    // A subscription the lockfile did not pin yet has just been pinned. That is
-    // a change to a committed file, so it is always announced.
-    if (subscriptions.added.length > 0 || subscriptions.moved.length > 0) {
-      heading("Locking subscribed recipes");
-      blankLine();
-      for (const entry of subscriptions.added) {
-        paragraph(`  pinned: ${entry.key} at version ${entry.version}.`);
-      }
-      for (const change of subscriptions.moved) {
-        paragraph(`  ${change.key} moved from version ${change.from} to version ${change.to}.`);
-      }
-      blankLine();
-      paragraph(
-        "The lockfile has been updated. Commit it, so everyone building this project " +
-          "gets exactly these versions."
-      );
-      footer();
-    }
-
-    for (const failure of subscriptions.failed) {
-      warning(
-        `Sous could not work out which version of '${failure.key}' to use, so nothing ` +
-          `from it was compiled.\n${failure.reason}`
-      );
-    }
-
-    if (restored !== undefined && restored.restored.length > 0) {
-      blankLine();
-      for (const key of restored.restored) paragraph(`  restored: ${key}`);
-    }
-
-    for (const change of upstream.updated) {
-      paragraph(`  ${change.key} moved from ${change.from} to ${change.to}.`);
-    }
-
-    for (const failure of upstream.failed) {
-      warning(
-        `Sous could not check the repository '${failure.repo}' for a newer version, so ` +
-          `this build uses the versions it already had.\n${failure.reason}`
-      );
-    }
-
-    if (needsRestore) footer();
-  }
 }