@sous-io/sous 0.1.0

package/src/commands/build.ts

@@ -0,0 +1,196 @@
+import path from "node:path";
+import { Flags } from "@oclif/core";
+import { BaseCommand } from "../base-command.js";
+import { BuildService } from "../lib/build-service.js";
+import { PidService } from "../lib/pid-service.js";
+import { CLI_ROOT, loadSettings, resolveRootScope, resolveScope, resolveWatchConfig } from "../lib/settings.js";
+import type { WatchHandle } from "../lib/watch-service.js";
+import { WatchService } from "../lib/watch-service.js";
+import { footer, heading, log, showCommandVars } from "../utils/formatting.js";
+
+export default class Build extends BaseCommand {
+  static description = "Compile outputs and prune stale files (compile + prune)";
+
+  static examples = [
+    "<%= config.bin %> build",
+    "<%= config.bin %> build --no-prune",
+    "<%= config.bin %> build --rebuild",
+    "<%= config.bin %> build --dry-run",
+  ];
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    "no-prune": Flags.boolean({
+      description: "Skip the prune step",
+      default: false,
+    }),
+    "no-compile": Flags.boolean({
+      description: "Skip the compile step (prune only)",
+      default: false,
+    }),
+    rebuild: Flags.boolean({
+      description: "Ignore cached hashes and reprocess all outputs",
+      default: false,
+    }),
+    "dry-run": Flags.boolean({
+      description: "Print what would be written/pruned without making changes",
+      default: false,
+    }),
+    strict: Flags.boolean({
+      description: "Fail on any compilation error",
+      default: false,
+    }),
+    watch: Flags.boolean({
+      char: "w",
+      description: "Watch source files and rebuild on changes",
+      default: false,
+    }),
+  };
+
+  async run(): Promise<void> {
+    const { flags } = await this.parse(Build);
+
+    const project = this.resolveProject(flags.project);
+
+    showCommandVars({
+      Project: project.name,
+      Config: this.configContext.configPath,
+      Rebuild: flags.rebuild,
+      "Dry Run": flags["dry-run"],
+      "No Compile": flags["no-compile"],
+      "No Prune": flags["no-prune"],
+    });
+
+    heading("Building");
+
+    const buildOptions = {
+      strict: flags.strict,
+      rebuild: flags.rebuild,
+      dryRun: flags["dry-run"],
+      noCompile: flags["no-compile"],
+      noPrune: flags["no-prune"],
+      configContext: this.configContext,
+    };
+
+    const buildService = new BuildService();
+    const success = await buildService.build(project.key, this.settings, buildOptions);
+
+    footer();
+
+    if (!success && !flags.watch) {
+      this.exit(1);
+    }
+
+    if (flags.watch) {
+      const configPath = this.configContext.configPath;
+
+      const rootScope = resolveRootScope(this.settings, this.configContext);
+      const projectScope = resolveScope(project._vars ?? {}, rootScope);
+
+      // --- PID file enforcement ---
+      const pidService = new PidService();
+      const pidFilePath = pidService.getFilePath(project.key, projectScope, this.projectCount);
+      await pidService.acquire(pidFilePath, project.key);
+
+      let isRebuilding = false;
+
+      const cleanup = async (watchHandle?: WatchHandle) => {
+        if (process.stdin.isTTY) {
+          process.stdin.setRawMode(false);
+        }
+        process.stdin.pause();
+        if (watchHandle) await watchHandle.stop();
+        await pidService.release(pidFilePath);
+      };
+
+      process.on("SIGINT", () => { void cleanup().then(() => process.exit(0)); });
+      process.on("SIGTERM", () => { void cleanup().then(() => process.exit(0)); });
+
+      const watchService = new WatchService();
+
+      /**
+       * Builds a WatchConfig from current settings, injecting the config file path
+       * and the templating directory into fullRebuildPaths.
+       */
+      const buildWatchConfig = () => {
+        const currentRootScope = resolveRootScope(this.settings, this.configContext);
+        const config = resolveWatchConfig(project, currentRootScope, project.key);
+        config.fullRebuildPaths = [
+          ...(config.fullRebuildPaths ?? []),
+          configPath,
+          path.join(CLI_ROOT, "src", "templating"),
+        ];
+        return config;
+      };
+
+      /** Starts a new watcher and updates the shared handle reference. */
+      const startWatcher = (handle: { current: WatchHandle | null }) => {
+        const watchConfig = buildWatchConfig();
+        handle.current = watchService.watch(watchConfig, async (event) => {
+          if (event.type === "partial") {
+            if (isRebuilding) return;
+            isRebuilding = true;
+            log(`\nChange detected: ${event.filePath}`);
+            heading("Rebuilding");
+            await buildService.build(project.key, this.settings, {
+              ...buildOptions,
+              // --rebuild means full clean build on every trigger; skip partial optimisation
+              changedFile: buildOptions.rebuild ? undefined : event.filePath,
+            });
+            footer();
+            isRebuilding = false;
+          } else {
+            // Full rebuild: stop current watcher, reload settings, restart
+            if (isRebuilding) return;
+            isRebuilding = true;
+            log(`\nConfig changed (${event.filePath}), reloading settings and restarting watcher...`);
+            await handle.current!.stop();
+
+            this.settings = await loadSettings(configPath);
+
+            heading("Rebuilding");
+            await buildService.build(project.key, this.settings, buildOptions);
+            footer();
+            isRebuilding = false;
+
+            startWatcher(handle);
+          }
+        });
+      };
+
+      const handle: { current: WatchHandle | null } = { current: null };
+      startWatcher(handle);
+
+      const triggerFullRebuild = async (reason: string) => {
+        if (isRebuilding) return;
+        isRebuilding = true;
+        log(`\n${reason}`);
+        heading("Rebuilding");
+        await buildService.build(project.key, this.settings, buildOptions);
+        footer();
+        isRebuilding = false;
+      };
+
+      // Display the interactive prompt
+      log("[ Press Q to quit  |  any other key: rebuild ]");
+
+      if (process.stdin.isTTY) {
+        process.stdin.setRawMode(true);
+        process.stdin.resume();
+        process.stdin.setEncoding("utf8");
+
+        process.stdin.on("data", (key: string) => {
+          // q, Q, or Ctrl+C → clean exit
+          if (key === "q" || key === "Q" || key === "\u0003") {
+            void cleanup(handle.current ?? undefined).then(() => process.exit(0));
+            return;
+          }
+          // Any other key → trigger a full rebuild immediately (bypass debounce)
+          void triggerFullRebuild("Manual rebuild triggered.");
+        });
+      }
+
+      await new Promise(() => {}); // keep process alive
+    }
+  }
+}

package/src/commands/clear.ts

@@ -0,0 +1,71 @@
+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 { displayError, footer, heading, log, showCommandVars } from "../utils/formatting.js";
+
+export default class Clear extends BaseCommand {
+  static description = "Delete all files and directories written by Sous for a project";
+
+  static examples = [
+    "<%= config.bin %> clear",
+    "<%= config.bin %> clear --force",
+  ];
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    force: Flags.boolean({
+      char: "f",
+      description: "Skip confirmation prompt",
+      default: false,
+    }),
+  };
+
+  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 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.`
+      );
+      this.exit(1);
+    }
+
+    showCommandVars({ Project: project.name, Config: this.configContext.configPath });
+
+    const fileCount = state!.files.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}'?`,
+        default: false,
+      });
+      if (!confirmed) {
+        log("Aborted.");
+        return;
+      }
+    }
+
+    heading("Clearing");
+
+    stateService.deleteTrackedFiles(state!.files, state!.dirs);
+    for (const entry of state!.files) log(`  ✗ ${entry.dest}`);
+
+    // Delete state file itself
+    if (fs.existsSync(stateFilePath)) {
+      fs.rmSync(stateFilePath);
+      log(`  ✗ ${stateFilePath} (state file)`);
+    }
+
+    footer();
+  }
+}

package/src/commands/compile.ts

@@ -0,0 +1,95 @@
+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 { WatchService } from "../lib/watch-service.js";
+import { displayError, footer, heading, log, showCommandVars } 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",
+  ];
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    strict: Flags.boolean({
+      description: "Fail immediately on any error",
+      default: false,
+    }),
+    rebuild: Flags.boolean({
+      description: "Ignore cached hashes and reprocess all outputs",
+      default: false,
+    }),
+    "dry-run": Flags.boolean({
+      description: "Print what would be written without making changes",
+      default: false,
+    }),
+    watch: Flags.boolean({
+      char: "w",
+      description: "Watch source files and recompile on changes",
+      default: false,
+    }),
+  };
+
+  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);
+
+    if (!config) {
+      displayError(`Project '${project.key}' has no compilation config`);
+      this.exit(1);
+    }
+
+    const stateFilePath = resolveStateFilePath(project.key, this.settings, this.configContext);
+
+    showCommandVars({
+      Project: project.name,
+      Config: this.configContext.configPath,
+      Strict: flags.strict,
+      Rebuild: flags.rebuild,
+      "Dry Run": flags["dry-run"],
+    });
+
+    heading("Compiling");
+
+    const compilerOptions = {
+      strict: flags.strict,
+      rebuild: flags.rebuild,
+      dryRun: flags["dry-run"],
+    };
+
+    const compiler = new CompilationService(compilerOptions);
+    const success = await compiler.compile(config!, stateFilePath);
+
+    footer();
+
+    if (!success && flags.strict && !flags.watch) {
+      this.exit(1);
+    }
+
+    if (flags.watch) {
+      const watchConfig = resolveWatchConfig(project, rootScope, project.key);
+      const watchService = new WatchService();
+
+      watchService.watch(watchConfig, async (changedFile) => {
+        log(`\nChange detected: ${changedFile}`);
+        heading("Recompiling");
+        const recompiler = new CompilationService(compilerOptions);
+        await recompiler.compile(config!, stateFilePath);
+        footer();
+      });
+
+      await new Promise(() => {}); // keep process alive
+    }
+  }
+}

package/src/commands/launch.ts

@@ -0,0 +1,111 @@
+import { Args, Flags } from "@oclif/core";
+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 { 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 examples = [
+    "<%= config.bin %> launch claude",
+    "<%= config.bin %> launch codex --no-build",
+    "<%= config.bin %> launch claude --continuous",
+    "<%= config.bin %> launch codex --project myproject",
+  ];
+
+  static args = {
+    tool: Args.string({
+      description: "Tool to launch (e.g. claude, codex)",
+      required: true,
+    }),
+  };
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    "no-build": Flags.boolean({
+      description: "Skip xcv build before launching",
+      default: false,
+    }),
+    continuous: Flags.boolean({
+      description: "Restart the agent automatically on exit",
+      default: false,
+    }),
+  };
+
+  async run(): Promise<void> {
+    const { args, flags } = await this.parse(Launch);
+
+    const project = this.resolveProject(flags.project);
+    const rootScope = resolveRootScope(this.settings, this.configContext);
+    const tools = resolveProjectTools(project, rootScope, project.key);
+    const toolConfig = tools[args.tool];
+
+    if (!toolConfig) {
+      displayError(
+        `Tool '${args.tool}' not found in project '${project.key}'. ` +
+          `Available tools: ${Object.keys(tools).join(", ") || "(none)"}`
+      );
+      this.exit(1);
+    }
+
+    const projectScope = resolveScope(project._vars ?? {}, rootScope);
+    const projectRoot = projectScope.projectRoot ?? process.cwd();
+
+    showCommandVars({
+      Project: project.name,
+      Config: this.configContext.configPath,
+      Tool: args.tool,
+      "Project Root": projectRoot,
+      "No Build": flags["no-build"],
+      Continuous: flags.continuous,
+    });
+
+    const buildService = new BuildService();
+
+    do {
+      // Build step (unless --no-build)
+      if (!flags["no-build"]) {
+        heading("Building");
+        await buildService.build(project.key, this.settings, {
+          configContext: this.configContext,
+        });
+        footer();
+      }
+
+      // Resolve promptFile content
+      const launchArgs = [...(toolConfig.args ?? [])];
+      if (toolConfig.promptFile) {
+        if (!fs.existsSync(toolConfig.promptFile)) {
+          displayError(`promptFile not found: ${toolConfig.promptFile}`);
+          this.exit(1);
+        }
+        const promptContent = fs.readFileSync(toolConfig.promptFile, "utf8");
+        launchArgs.push(promptContent);
+      }
+
+      heading(`Launching ${args.tool}`);
+
+      // Run the tool with inherited stdio (interactive)
+      const result = spawnSync(toolConfig.command, launchArgs, {
+        cwd: projectRoot,
+        stdio: "inherit",
+        shell: false,
+      });
+
+      if (result.error) {
+        displayError(`Failed to launch '${args.tool}': ${result.error.message}`);
+        this.exit(1);
+      }
+
+      if (flags.continuous) {
+        // Small delay to avoid tight spin on immediate crash
+        await new Promise(resolve => setTimeout(resolve, 150));
+      }
+    } while (flags.continuous);
+
+    footer();
+  }
+}

package/src/commands/prune.ts

@@ -0,0 +1,48 @@
+import { Flags } from "@oclif/core";
+import { BaseCommand } from "../base-command.js";
+import { BuildService, resolveStateFilePath } from "../lib/build-service.js";
+import { footer, heading, showCommandVars } from "../utils/formatting.js";
+
+export default class Prune extends BaseCommand {
+  static description = "Remove output files that are no longer in the current config";
+
+  static examples = [
+    "<%= config.bin %> prune",
+    "<%= config.bin %> prune --dry-run",
+    "<%= config.bin %> prune --project myproject",
+  ];
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    "dry-run": Flags.boolean({
+      description: "Print what would be pruned without deleting",
+      default: false,
+    }),
+  };
+
+  async run(): Promise<void> {
+    const { flags } = await this.parse(Prune);
+
+    const project = this.resolveProject(flags.project);
+    const stateFilePath = resolveStateFilePath(project.key, this.settings, this.configContext);
+
+    showCommandVars({
+      Project: project.name,
+      Config: this.configContext.configPath,
+      "Dry Run": flags["dry-run"],
+    });
+
+    heading("Pruning");
+
+    const buildService = new BuildService();
+    await buildService.prune(
+      project.key,
+      this.settings,
+      stateFilePath,
+      flags["dry-run"],
+      this.configContext
+    );
+
+    footer();
+  }
+}