@sous-io/sous 0.1.1 → 0.2.0

package/src/commands/clear.ts

@@ -1,9 +1,10 @@
-import { Flags } from "@oclif/core";
 import { confirm } from "@inquirer/prompts";
 import fs from "node:fs";
 import { BaseCommand } from "../base-command.js";
 import { resolveStateFilePath } from "../lib/build-service.js";
-import { StateService } from "../lib/state.js";
+import { isProtectedPath, StateService } from "../lib/state.js";
+import { protectedRepoPaths } from "../lib/repos/links.js";
+import { confirmationFlag } from "../utils/flags.js";
 import { displayError, footer, heading, log, showCommandVars } from "../utils/formatting.js";
 
 export default class Clear extends BaseCommand {
@@ -12,41 +13,48 @@ export default class Clear extends BaseCommand {
   static examples = [
     "<%= config.bin %> clear",
     "<%= config.bin %> clear --force",
+    "<%= config.bin %> clear -y",
   ];
 
   static flags = {
     ...BaseCommand.baseFlags,
-    force: Flags.boolean({
-      char: "f",
-      description: "Skip confirmation prompt",
-      default: false,
-    }),
+    // `--force` is this command's original spelling, so it stays the primary
+    // one; `--yes` and `-y` are aliases of it, and the confirmation therefore
+    // answers the same way here as it does on every other command.
+    force: confirmationFlag({ primary: "force" }),
   };
 
   async run(): Promise<void> {
     const { flags } = await this.parse(Clear);
 
-    const project = this.resolveProject(flags.project);
-    const stateFilePath = resolveStateFilePath(project.key, this.settings, this.configContext);
+    const stateFilePath = resolveStateFilePath(this.settings, this.configContext);
 
     const stateService = new StateService();
     const state = await stateService.load(stateFilePath);
 
     if (!state) {
       displayError(
-        `No state file found at ${stateFilePath}. Run 'xcv build' first, then 'xcv clear' to recover.`
+        `No state file found at ${stateFilePath}. Run 'sous build' first, then 'sous clear' to recover.`
       );
       this.exit(1);
     }
 
-    showCommandVars({ Project: project.name, Config: this.configContext.configPath });
+    showCommandVars({ Project: this.projectLabel, Config: this.configContext.configPath });
 
-    const fileCount = state!.files.length;
+    // A linked checkout holds somebody's unpushed edits and the recipe store is
+    // shared by every project on this machine, so neither is ever clearable,
+    // whatever a stale state entry claims.
+    const protectedPaths = protectedRepoPaths(this.configContext.sousDir);
+    const clearable = state!.files.filter(
+      (entry) => !isProtectedPath(entry.dest, protectedPaths)
+    );
+
+    const fileCount = clearable.length;
     const dirCount = state!.dirs.length;
 
     if (!flags.force) {
       const confirmed = await confirm({
-        message: `Delete ${fileCount} file(s) and ${dirCount} director(ies) for project '${project.key}'?`,
+        message: `Delete ${fileCount} file(s) and ${dirCount} director(ies) for '${this.projectLabel}'?`,
         default: false,
       });
       if (!confirmed) {
@@ -57,8 +65,8 @@ export default class Clear extends BaseCommand {
 
     heading("Clearing");
 
-    stateService.deleteTrackedFiles(state!.files, state!.dirs);
-    for (const entry of state!.files) log(`  ✗ ${entry.dest}`);
+    stateService.deleteTrackedFiles(clearable, state!.dirs, protectedPaths);
+    for (const entry of clearable) log(`  ✗ ${entry.dest}`);
 
     // Delete state file itself
     if (fs.existsSync(stateFilePath)) {

package/src/commands/compile.ts

@@ -1,17 +1,30 @@
 import { Flags } from "@oclif/core";
 import { BaseCommand } from "../base-command.js";
 import { CompilationService } from "../lib/markdown-compiler.js";
-import { resolveProjectCompilation, resolveRootScope, resolveWatchConfig } from "../lib/settings.js";
-import { resolveStateFilePath } from "../lib/build-service.js";
+import { resolveCompilation, resolveRootScope } from "../lib/settings.js";
+import {
+  resolveRecipeTargets,
+  resolveStateFilePath,
+  withRecipeTargets,
+} from "../lib/build-service.js";
+import { createProjectNamespaceResolver } from "../lib/repos/locked-namespace-resolver.js";
+import { describeLinkedRepos } from "../lib/repos/links.js";
+import { buildReloadWatchConfig, startConfigReloadWatch } from "../lib/watch-loop.js";
 import { WatchService } from "../lib/watch-service.js";
-import { displayError, footer, heading, log, showCommandVars } from "../utils/formatting.js";
+import {
+  displayError,
+  footer,
+  heading,
+  log,
+  showCommandVars,
+  warning,
+} from "../utils/formatting.js";
 
 export default class Compile extends BaseCommand {
   static description = "Compile markdown templates into output files";
 
   static examples = [
     "<%= config.bin %> compile",
-    "<%= config.bin %> compile --project myproject",
     "<%= config.bin %> compile --rebuild",
     "<%= config.bin %> compile --dry-run",
     "<%= config.bin %> compile --strict",
@@ -41,19 +54,33 @@ export default class Compile extends BaseCommand {
   async run(): Promise<void> {
     const { flags } = await this.parse(Compile);
 
-    const project = this.resolveProject(flags.project);
-    const rootScope = resolveRootScope(this.settings, this.configContext);
-    const config = resolveProjectCompilation(project, rootScope, this.settings, project.key);
+    // The recipes this project subscribes to contribute compile targets
+    // alongside its own; both go through the same compiler.
+    const withRecipes = () => {
+      const scope = resolveRootScope(this.settings, this.configContext);
+      const recipes = resolveRecipeTargets(this.settings, scope, this.configContext);
+      for (const notice of recipes.warnings) warning(notice);
+      return withRecipeTargets(
+        resolveCompilation(this.settings, scope),
+        recipes,
+        this.settings,
+        scope
+      );
+    };
+
+    for (const line of describeLinkedRepos(this.configContext.sousDir)) log(line);
+
+    const config = withRecipes();
 
     if (!config) {
-      displayError(`Project '${project.key}' has no compilation config`);
+      displayError(`No compilation config found in ${this.configContext.configPath}`);
       this.exit(1);
     }
 
-    const stateFilePath = resolveStateFilePath(project.key, this.settings, this.configContext);
+    const stateFilePath = resolveStateFilePath(this.settings, this.configContext);
 
     showCommandVars({
-      Project: project.name,
+      Project: this.projectLabel,
       Config: this.configContext.configPath,
       Strict: flags.strict,
       Rebuild: flags.rebuild,
@@ -62,13 +89,24 @@ export default class Compile extends BaseCommand {
 
     heading("Compiling");
 
+    // Rebuilt on every compile rather than captured once: a watch-mode reload
+    // may follow a subscribe, and the lockfile is what this reads.
+    const namespaceResolver = () =>
+      createProjectNamespaceResolver({
+        sousDir: this.configContext.sousDir,
+        settings: this.settings,
+      });
+
     const compilerOptions = {
       strict: flags.strict,
       rebuild: flags.rebuild,
       dryRun: flags["dry-run"],
     };
 
-    const compiler = new CompilationService(compilerOptions);
+    const compiler = new CompilationService({
+      ...compilerOptions,
+      namespaceResolver: namespaceResolver(),
+    });
     const success = await compiler.compile(config!, stateFilePath);
 
     footer();
@@ -78,15 +116,35 @@ export default class Compile extends BaseCommand {
     }
 
     if (flags.watch) {
-      const watchConfig = resolveWatchConfig(project, rootScope, project.key);
       const watchService = new WatchService();
 
-      watchService.watch(watchConfig, async (changedFile) => {
-        log(`\nChange detected: ${changedFile}`);
+      // Recompiles using the command's CURRENT settings. Called for partial
+      // rebuilds (a changed source) and, after a clean reload, for full
+      // rebuilds. The compilation config and state-file path are re-resolved
+      // each time so a config reload takes effect. Owns the "Recompiling"
+      // heading/footer. (`changedFile` is accepted for parity with build and
+      // logged by the watch loop; compile always does a full recompile.)
+      const rebuild = async (_changedFile?: string) => {
+        const currentConfig = withRecipes();
+        if (!currentConfig) {
+          displayError(`No compilation config found in ${this.configContext.configPath}`);
+          return;
+        }
+        const currentStateFilePath = resolveStateFilePath(this.settings, this.configContext);
         heading("Recompiling");
-        const recompiler = new CompilationService(compilerOptions);
-        await recompiler.compile(config!, stateFilePath);
+        const recompiler = new CompilationService({
+          ...compilerOptions,
+          namespaceResolver: namespaceResolver(),
+        });
+        await recompiler.compile(currentConfig, currentStateFilePath);
         footer();
+      };
+
+      startConfigReloadWatch({
+        watchService,
+        buildWatchConfig: () => buildReloadWatchConfig(this.settings, this.configContext),
+        rebuild,
+        reloadConfig: () => this.reloadDiscoveredConfig(),
       });
 
       await new Promise(() => {}); // keep process alive

package/src/commands/config/get.ts

@@ -0,0 +1,110 @@
+import path from "node:path";
+import { Args, Flags } from "@oclif/core";
+import { ConfigCommand } from "../../config-command.js";
+import { ConfigError, loadSettingsWithLayers } from "../../lib/settings.js";
+import {
+  isScalar,
+  lookupPath,
+  NOT_FOUND,
+  parsePath,
+  renderJson,
+  truncateJson,
+} from "../../lib/config-inspect.js";
+
+export default class ConfigGet extends ConfigCommand {
+  static description =
+    "Print one value from the merged config by dot-path (e.g. compilation.targets[0].entryPoint)";
+
+  /**
+   * The other spelling of the topic. It lives under a hidden topic, so it is
+   * typable everywhere without ever reaching the top-level listing.
+   */
+  static aliases = ["configs:get"];
+
+  static examples = [
+    "<%= config.bin %> config get name",
+    "<%= config.bin %> config get compilation.targets[0].entryPoint",
+    "<%= config.bin %> config get compilation --layers",
+  ];
+
+  static args = {
+    path: Args.string({
+      description: "Dot-path into the config, with [n] for array indices",
+      required: true,
+    }),
+  };
+
+  static flags = {
+    ...ConfigCommand.baseFlags,
+    layers: Flags.boolean({
+      description: "Show which config layer set the value (per-layer provenance)",
+      default: false,
+    }),
+  };
+
+  async run(): Promise<void> {
+    const { args, flags } = await this.parse(ConfigGet);
+    const segments = parsePath(args.path);
+
+    if (flags.layers) {
+      await this.showLayers(args.path, segments);
+      return;
+    }
+
+    const value = lookupPath(this.settings, segments);
+    if (value === NOT_FOUND) {
+      throw new ConfigError(
+        `No value at config path '${args.path}'.\n` +
+          `  It is not present in the merged config (${this.configContext.configPath}).\n` +
+          `  Run 'sous config show' to see the whole config.`
+      );
+    }
+
+    // Scalars print raw (no quotes) so the output is directly usable; objects and
+    // arrays print as pretty JSON, colorized only for a TTY.
+    if (isScalar(value)) {
+      process.stdout.write(`${String(value)}\n`);
+    } else {
+      process.stdout.write(`${renderJson(value, Boolean(process.stdout.isTTY))}\n`);
+    }
+  }
+
+  /**
+   * Prints one line per config layer whose cumulative snapshot CHANGED the value
+   * at `pathStr`, showing old -> new (JSON-encoded, truncated). The first layer
+   * counts as a change from (unset).
+   */
+  private async showLayers(pathStr: string, segments: (string | number)[]): Promise<void> {
+    const { layers } = await loadSettingsWithLayers(this.discovered, { trace: true });
+    const sousDir = this.configContext.sousDir;
+
+    let previous: unknown = NOT_FOUND;
+    let printedAny = false;
+
+    for (const layer of layers) {
+      const current = lookupPath(layer.config, segments);
+      // JSON round-trip so structurally-equal values compare equal.
+      const unchanged =
+        current !== NOT_FOUND
+          ? previous !== NOT_FOUND && JSON.stringify(current) === JSON.stringify(previous)
+          : previous === NOT_FOUND;
+      if (unchanged) continue;
+
+      const rel = path.relative(sousDir, layer.path);
+      const label = rel && !rel.startsWith("..") ? rel : layer.path;
+      const oldStr = previous === NOT_FOUND ? "(unset)" : truncateJson(previous);
+      const newStr = current === NOT_FOUND ? "(unset)" : truncateJson(current);
+      process.stdout.write(`${label}: ${oldStr} -> ${newStr}\n`);
+
+      previous = current;
+      printedAny = true;
+    }
+
+    if (!printedAny) {
+      throw new ConfigError(
+        `No value at config path '${pathStr}' in any config layer.\n` +
+          `  Run 'sous config show' to see the whole merged config.`
+      );
+    }
+  }
+}

package/src/commands/config/show.ts

@@ -0,0 +1,32 @@
+import { ConfigCommand } from "../../config-command.js";
+import { renderJson } from "../../lib/config-inspect.js";
+
+export default class ConfigShow extends ConfigCommand {
+  static description =
+    "Print the merged config (all conf.d layers merged, before variable resolution) as JSON";
+
+  /**
+   * The other spelling of the topic. It lives under a hidden topic, so it is
+   * typable everywhere without ever reaching the top-level listing.
+   */
+  static aliases = ["configs:show"];
+
+  static examples = [
+    "<%= config.bin %> config show",
+    "<%= config.bin %> config show | jq .compilation",
+  ];
+
+  static flags = {
+    ...ConfigCommand.baseFlags,
+  };
+
+  async run(): Promise<void> {
+    await this.parse(ConfigShow);
+
+    // this.settings is the merged config as written: every conf.d layer has been
+    // deep-merged and the whole thing schema-validated, but no ${var} has been
+    // resolved yet. Colorize only for a TTY so piped output stays valid JSON.
+    const useColor = Boolean(process.stdout.isTTY);
+    process.stdout.write(`${renderJson(this.settings, useColor)}\n`);
+  }
+}

package/src/commands/config/validate.ts

@@ -0,0 +1,53 @@
+import { BaseCommand } from "../../base-command.js";
+import {
+  resolveCompilation,
+  resolveRootScope,
+  resolveTools,
+  resolveWatchConfig,
+} from "../../lib/settings.js";
+import { footer, heading, showVariables } from "../../utils/formatting.js";
+
+export default class ConfigValidate extends BaseCommand {
+  static description =
+    "Validate the merged config: schema, then full variable resolution (fixpoint + substitution)";
+
+  /**
+   * The other spelling of the topic. It lives under a hidden topic, so it is
+   * typable everywhere without ever reaching the top-level listing.
+   */
+  static aliases = ["configs:validate"];
+
+  static examples = ["<%= config.bin %> config validate"];
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+  };
+
+  async run(): Promise<void> {
+    await this.parse(ConfigValidate);
+
+    // Discovery, the config kernel, assertFlatConfig and zod validation have all
+    // already run in BaseCommand.init(); a failure there exits before we get here.
+    // Running the resolvers now surfaces the errors validation alone cannot:
+    // fixpoint cycles, undefined ${vars}, and unresolved substitutions. Any
+    // ConfigError they throw is rendered by BaseCommand.catch (non-zero exit).
+    const rootScope = resolveRootScope(this.settings, this.configContext);
+    resolveCompilation(this.settings, rootScope);
+    const tools = resolveTools(this.settings, rootScope);
+    resolveWatchConfig(this.settings, rootScope);
+
+    const layerCount = this.configContext.layerPaths?.length ?? 1;
+    const targetCount = this.settings.compilation?.targets.length ?? 0;
+    const toolNames = Object.keys(tools);
+
+    heading("Config is valid");
+    showVariables({
+      "Config File": this.configContext.configPath,
+      Layers: layerCount,
+      Targets: targetCount,
+      Tools: toolNames.length > 0 ? toolNames.join(", ") : "(none)",
+    });
+
+    footer();
+  }
+}

package/src/commands/help.ts

@@ -0,0 +1,46 @@
+/**
+ * `sous help`, `sous help <command>`, `sous help <topic>`, `sous help <topic> <command>`.
+ *
+ * The word form of `--help`, and deliberately the same screen: it hands the
+ * arguments straight to the help class oclif itself uses for `--help`, so there
+ * is exactly one help renderer and no second copy to fall out of date.
+ *
+ * This exists because `sous help build` is what people type, and without a
+ * command by that name oclif answers "command help not found", which reads like
+ * sous has no help at all. Adding it here rather than installing
+ * `@oclif/plugin-help` keeps the dependency list as it is.
+ *
+ * It does not extend `BaseCommand`: reading the help must work from anywhere,
+ * including a directory with no `.sous/` above it, and `BaseCommand` requires a
+ * discoverable config.
+ */
+
+import { Args, Command, loadHelpClass } from "@oclif/core";
+
+export default class Help extends Command {
+  static description = "Print the help for sous, or for one command or topic";
+
+  static examples = [
+    "<%= config.bin %> help",
+    "<%= config.bin %> help build",
+    "<%= config.bin %> help repo",
+    "<%= config.bin %> help repo add",
+  ];
+
+  /** A command id is one or more words, so the argument list is open-ended. */
+  static strict = false;
+
+  static args = {
+    command: Args.string({
+      description: "The command or topic to describe, such as 'build' or 'repo add'",
+      required: false,
+    }),
+  };
+
+  async run(): Promise<void> {
+    const { argv } = await this.parse(Help);
+    const HelpClass = await loadHelpClass(this.config);
+    const help = new HelpClass(this.config, this.config.pjson.oclif.helpOptions);
+    await help.showHelp(argv as string[]);
+  }
+}

package/src/commands/launch.ts

@@ -3,17 +3,19 @@ import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import { BaseCommand } from "../base-command.js";
 import { BuildService } from "../lib/build-service.js";
-import { resolveProjectTools, resolveRootScope, resolveScope } from "../lib/settings.js";
+import { resolveRootScope, resolveTools } from "../lib/settings.js";
 import { displayError, footer, heading, showCommandVars } from "../utils/formatting.js";
 
 export default class Launch extends BaseCommand {
-  static description = "Build and launch a coding agent for a project";
+  static description =
+    "Build this project's outputs, then start a coding agent configured in its config";
 
   static examples = [
     "<%= config.bin %> launch claude",
     "<%= config.bin %> launch codex --no-build",
     "<%= config.bin %> launch claude --continuous",
-    "<%= config.bin %> launch codex --project myproject",
+    "<%= config.bin %> launch claude --resume",
+    "<%= config.bin %> launch claude -- -c",
   ];
 
   static args = {
@@ -26,7 +28,7 @@ export default class Launch extends BaseCommand {
   static flags = {
     ...BaseCommand.baseFlags,
     "no-build": Flags.boolean({
-      description: "Skip xcv build before launching",
+      description: "Skip sous build before launching",
       default: false,
     }),
     continuous: Flags.boolean({
@@ -35,32 +37,52 @@ export default class Launch extends BaseCommand {
     }),
   };
 
+  // Any argument launch does not recognize is forwarded to the tool, after the
+  // config-defined tool args. Flags that collide with sous's own (e.g. claude's
+  // -c / --continue vs sous's -c / --config) can be forced through with `--`:
+  // everything after it is forwarded verbatim.
+  //
+  // strict=false lets extra positionals through; "--"=false is what routes
+  // unknown flags into argv instead of a NonExistentFlagsError (oclif rejects
+  // them even in non-strict mode otherwise). Disabling oclif's `--` handling
+  // means it would keep parsing sous flags past the separator, so run() splits
+  // argv at the first `--` itself, before oclif ever sees the tail.
+  static strict = false;
+  static "--" = false;
+
   async run(): Promise<void> {
-    const { args, flags } = await this.parse(Launch);
+    const sepIndex = this.argv.indexOf("--");
+    const ownArgv = sepIndex === -1 ? this.argv : this.argv.slice(0, sepIndex);
+    const verbatimArgs = sepIndex === -1 ? [] : this.argv.slice(sepIndex + 1);
+
+    const { args, argv, flags } = await this.parse(Launch, ownArgv);
+
+    // argv holds every token oclif did not claim, in original order; the first
+    // is the tool name itself.
+    const passThroughArgs = [...argv.slice(1).map(String), ...verbatimArgs];
 
-    const project = this.resolveProject(flags.project);
     const rootScope = resolveRootScope(this.settings, this.configContext);
-    const tools = resolveProjectTools(project, rootScope, project.key);
+    const tools = resolveTools(this.settings, rootScope);
     const toolConfig = tools[args.tool];
 
     if (!toolConfig) {
       displayError(
-        `Tool '${args.tool}' not found in project '${project.key}'. ` +
+        `Tool '${args.tool}' not found in ${this.configContext.configPath}. ` +
           `Available tools: ${Object.keys(tools).join(", ") || "(none)"}`
       );
       this.exit(1);
     }
 
-    const projectScope = resolveScope(project._vars ?? {}, rootScope);
-    const projectRoot = projectScope.projectRoot ?? process.cwd();
+    const projectRoot = rootScope.projectRoot ?? process.cwd();
 
     showCommandVars({
-      Project: project.name,
+      Project: this.projectLabel,
       Config: this.configContext.configPath,
       Tool: args.tool,
       "Project Root": projectRoot,
       "No Build": flags["no-build"],
       Continuous: flags.continuous,
+      ...(passThroughArgs.length > 0 && { "Tool Args": passThroughArgs.join(" ") }),
     });
 
     const buildService = new BuildService();
@@ -69,14 +91,14 @@ export default class Launch extends BaseCommand {
       // Build step (unless --no-build)
       if (!flags["no-build"]) {
         heading("Building");
-        await buildService.build(project.key, this.settings, {
+        await buildService.build(this.settings, {
           configContext: this.configContext,
         });
         footer();
       }
 
-      // Resolve promptFile content
-      const launchArgs = [...(toolConfig.args ?? [])];
+      // Config-defined args first, then pass-through, then promptFile content
+      const launchArgs = [...(toolConfig.args ?? []), ...passThroughArgs];
       if (toolConfig.promptFile) {
         if (!fs.existsSync(toolConfig.promptFile)) {
           displayError(`promptFile not found: ${toolConfig.promptFile}`);