@kitsy/cnos-cli 1.4.0 → 1.5.1

package/dist/index.js

@@ -203,9 +203,6 @@ function parseArgs(argv) {
   };
 }
 
-// src/commands/define.ts
-import path3 from "path";
-
 // src/cli/commandOptions.ts
 function consumeFlag(args, flag) {
   const index = args.indexOf(flag);
@@ -253,17 +250,9 @@ function printJson(value) {
   return JSON.stringify(value, null, 2);
 }
 
-// src/services/writes.ts
-import { mkdir, readFile, writeFile } from "fs/promises";
+// src/services/envMaterialization.ts
+import { mkdir, writeFile } from "fs/promises";
 import path2 from "path";
-import {
-  getNamespaceDefinition,
-  createSecretVaultProvider,
-  parseYaml,
-  resolveConfigDocumentPath,
-  resolveVaultAuth,
-  stringifyYaml
-} from "@kitsy/cnos/internal";
 
 // src/services/runtime.ts
 import { createCnos } from "@kitsy/cnos/configure";
@@ -279,7 +268,92 @@ async function createRuntimeService(options = {}) {
   });
 }
 
+// src/services/envMaterialization.ts
+function resolveEnvFromRuntime(runtime, cliArgs = []) {
+  const args = [...cliArgs];
+  const isPublic = consumeFlag(args, "--public");
+  const framework = consumeOption(args, "--framework");
+  const prefix = consumeOption(args, "--prefix");
+  return isPublic ? runtime.toPublicEnv({
+    ...framework ? { framework } : {},
+    ...prefix ? { prefix } : {}
+  }) : runtime.toEnv();
+}
+function formatEnvOutput(env) {
+  return Object.entries(env).sort(([left], [right]) => left.localeCompare(right)).map(([key, value]) => `${key}=${value}`).join("\n");
+}
+async function resolveMaterializedEnv(options = {}) {
+  const runtime = await createRuntimeService({
+    ...options,
+    cliArgs: [...options.cliArgs ?? []]
+  });
+  const env = resolveEnvFromRuntime(runtime, options.cliArgs ?? []);
+  return {
+    runtime,
+    env,
+    output: formatEnvOutput(env)
+  };
+}
+function resolveMaterializedEnvTarget(to, root = process.cwd()) {
+  return path2.resolve(root, to);
+}
+async function writeMaterializedEnvFile(to, output, root = process.cwd()) {
+  const targetPath = resolveMaterializedEnvTarget(to, root);
+  await mkdir(path2.dirname(targetPath), { recursive: true });
+  await writeFile(targetPath, output, "utf8");
+  return targetPath;
+}
+async function materializeEnvToFile(to, options = {}) {
+  const result = await resolveMaterializedEnv(options);
+  const targetPath = await writeMaterializedEnvFile(to, result.output, options.root ?? process.cwd());
+  return {
+    ...result,
+    targetPath
+  };
+}
+
+// src/commands/build.ts
+async function runBuild(subcommand, options = {}) {
+  if (subcommand !== "env") {
+    throw new Error(`Unsupported build target: ${subcommand ?? "(missing)"}`);
+  }
+  const infoArgs = [...options.cliArgs ?? []];
+  const isPublic = consumeFlag(infoArgs, "--public");
+  const framework = consumeOption(infoArgs, "--framework");
+  consumeOption(infoArgs, "--prefix");
+  const to = consumeOption(infoArgs, "--to");
+  if (!to) {
+    throw new Error("build env requires --to <path>");
+  }
+  const result = await materializeEnvToFile(to, {
+    ...options,
+    cliArgs: [...options.cliArgs ?? []]
+  });
+  if (options.json) {
+    return printJson({
+      to: result.targetPath,
+      count: Object.keys(result.env).length,
+      public: isPublic,
+      ...framework ? { framework } : {}
+    });
+  }
+  return `built env artifact at ${displayPath(result.targetPath, options.root ?? process.cwd())}`;
+}
+
+// src/commands/define.ts
+import path4 from "path";
+
 // src/services/writes.ts
+import { mkdir as mkdir2, readFile, writeFile as writeFile2 } from "fs/promises";
+import path3 from "path";
+import {
+  getNamespaceDefinition,
+  createSecretVaultProvider,
+  parseYaml,
+  resolveConfigDocumentPath,
+  resolveVaultAuth,
+  stringifyYaml
+} from "@kitsy/cnos/internal";
 function setNestedValue(target, pathSegments, value) {
   const [head, ...tail] = pathSegments;
   if (!head) {
@@ -379,8 +453,8 @@ async function defineValue(namespace, configPath, rawValue, options = {}) {
   const document = await readYamlDocument(filePath);
   const parsedValue = parseScalarValue(rawValue);
   setNestedValue(document, configPath.split("."), parsedValue);
-  await mkdir(path2.dirname(filePath), { recursive: true });
-  await writeFile(filePath, stringifyYaml(document), "utf8");
+  await mkdir2(path3.dirname(filePath), { recursive: true });
+  await writeFile2(filePath, stringifyYaml(document), "utf8");
   return {
     filePath,
     value: parsedValue
@@ -417,8 +491,8 @@ async function setSecret(configPath, rawValue, options = {}) {
     };
   }
   setNestedValue(document, configPath.split("."), reference);
-  await mkdir(path2.dirname(filePath), { recursive: true });
-  await writeFile(filePath, stringifyYaml(document), "utf8");
+  await mkdir2(path3.dirname(filePath), { recursive: true });
+  await writeFile2(filePath, stringifyYaml(document), "utf8");
   return {
     filePath,
     provider: reference.provider,
@@ -440,7 +514,7 @@ async function deleteSecret(configPath, options = {}) {
       deleted: false
     };
   }
-  await writeFile(filePath, stringifyYaml(document), "utf8");
+  await writeFile2(filePath, stringifyYaml(document), "utf8");
   const secretRef = metadata?.secretRef;
   if (isSecretReference(secretRef) && secretRef.provider === "local") {
     const definition = runtime.manifest.vaults[secretRef.vault ?? "default"];
@@ -485,7 +559,7 @@ async function deleteValue(namespace, configPath, options = {}) {
       deleted: false
     };
   }
-  await writeFile(filePath, stringifyYaml(document), "utf8");
+  await writeFile2(filePath, stringifyYaml(document), "utf8");
   return {
     filePath,
     deleted: true
@@ -495,7 +569,7 @@ async function deleteValue(namespace, configPath, options = {}) {
 // src/commands/define.ts
 async function runDefine(namespace, configPath, rawValue, options = {}) {
   const cliArgs = [...options.cliArgs ?? []];
-  const root = path3.resolve(options.root ?? process.cwd());
+  const root = path4.resolve(options.root ?? process.cwd());
   const target = consumeOption(cliArgs, "--target") ?? "local";
   const local = consumeFlag(cliArgs, "--local");
   const remote = consumeFlag(cliArgs, "--remote");
@@ -524,6 +598,193 @@ async function runDefine(namespace, configPath, rawValue, options = {}) {
   return `defined ${namespace}.${configPath} in ${displayPath(result.filePath, root)}`;
 }
 
+// src/services/spawn.ts
+import { spawn } from "child_process";
+function shouldUseShellForCommand(command) {
+  if (process.platform !== "win32") {
+    return false;
+  }
+  return !/[\\/]/.test(command);
+}
+function spawnCommand(command, options) {
+  const executable = command[0];
+  if (!executable) {
+    throw new Error("A command is required.");
+  }
+  return spawn(executable, command.slice(1), {
+    cwd: options.cwd,
+    env: options.env,
+    stdio: options.stdio ?? "inherit",
+    shell: shouldUseShellForCommand(executable)
+  });
+}
+
+// src/services/watchLoop.ts
+import { watch } from "fs";
+import { diffGraphs, watchFiles } from "@kitsy/cnos/internal";
+async function startGraphWatchLoop(options) {
+  const debounceMs = options.debounceMs ?? 300;
+  let current = await createRuntimeService(options);
+  const watcherMap = /* @__PURE__ */ new Map();
+  let timer;
+  let closed = false;
+  const attachWatcher = (targetPath, recursive = false) => {
+    if (watcherMap.has(targetPath)) {
+      return;
+    }
+    try {
+      const watcher = watch(
+        targetPath,
+        recursive ? {
+          recursive: true
+        } : void 0,
+        () => {
+          if (timer) {
+            clearTimeout(timer);
+          }
+          timer = setTimeout(() => {
+            void handleChange();
+          }, debounceMs);
+        }
+      );
+      watcherMap.set(targetPath, watcher);
+    } catch {
+      if (recursive) {
+        attachWatcher(targetPath, false);
+      }
+    }
+  };
+  const refreshWatchers = async () => {
+    const nextTargets = await watchFiles(current, options.root);
+    attachWatcher(nextTargets.manifestPath, false);
+    for (const workspaceRoot of nextTargets.roots) {
+      attachWatcher(workspaceRoot, true);
+    }
+    for (const filePath of nextTargets.files) {
+      attachWatcher(filePath, false);
+    }
+  };
+  const handleChange = async () => {
+    if (closed) {
+      return;
+    }
+    const next = await createRuntimeService(options);
+    const changedKeys = diffGraphs(current.graph, next.graph);
+    current = next;
+    await refreshWatchers();
+    if (changedKeys.length === 0) {
+      return;
+    }
+    await options.onChange?.({
+      runtime: next,
+      changedKeys
+    });
+  };
+  await refreshWatchers();
+  return {
+    async close() {
+      closed = true;
+      if (timer) {
+        clearTimeout(timer);
+      }
+      for (const watcher of watcherMap.values()) {
+        watcher.close();
+      }
+      watcherMap.clear();
+    }
+  };
+}
+
+// src/commands/dev.ts
+async function startDevEnvLoop(command, options = {}) {
+  if (command.length === 0) {
+    throw new Error("dev env requires a command after --");
+  }
+  const cliArgs = [...options.cliArgs ?? []];
+  const to = consumeOption(cliArgs, "--to");
+  const isSignal = consumeFlag(cliArgs, "--signal");
+  const debounceMs = Number(consumeOption(cliArgs, "--debounce") ?? "300");
+  if (!to) {
+    throw new Error("dev env requires --to <path>");
+  }
+  const root = options.root ?? process.cwd();
+  let child;
+  const writeCurrent = async () => {
+    await materializeEnvToFile(to, {
+      ...options,
+      cliArgs: [...cliArgs]
+    });
+  };
+  await writeCurrent();
+  if (!isSignal) {
+    child = spawnCommand(command, {
+      cwd: root,
+      env: process.env,
+      stdio: "inherit"
+    });
+  }
+  const watcher = await startGraphWatchLoop({
+    ...options,
+    cliArgs,
+    debounceMs,
+    async onChange(payload) {
+      await writeCurrent();
+      if (isSignal) {
+        process.stdout.write(`${printJson({ changedKeys: payload.changedKeys })}
+`);
+        return;
+      }
+      if (child && !child.killed) {
+        await new Promise((resolve) => {
+          child?.once("close", () => resolve());
+          child?.kill();
+        });
+      }
+      child = spawnCommand(command, {
+        cwd: root,
+        env: process.env,
+        stdio: "inherit"
+      });
+    }
+  });
+  return {
+    async close() {
+      await watcher.close();
+      if (child && !child.killed) {
+        await new Promise((resolve) => {
+          child?.once("close", () => resolve());
+          child?.kill();
+        });
+      }
+    }
+  };
+}
+async function runDev(subcommand, command, options = {}) {
+  if (subcommand !== "env") {
+    throw new Error(`Unsupported dev target: ${subcommand ?? "(missing)"}`);
+  }
+  const cliArgs = [...options.cliArgs ?? []];
+  const to = consumeOption(cliArgs, "--to");
+  const isSignal = consumeFlag(cliArgs, "--signal");
+  if (!to) {
+    throw new Error("dev env requires --to <path>");
+  }
+  if (command.length === 0) {
+    throw new Error("dev env requires a command after --");
+  }
+  const handle = await startDevEnvLoop(command, {
+    ...options,
+    cliArgs
+  });
+  const closeLoop = () => {
+    void handle.close();
+  };
+  process.once("SIGINT", closeLoop);
+  process.once("SIGTERM", closeLoop);
+  const targetPath = displayPath(to, options.root ?? process.cwd());
+  return isSignal ? `watching config changes and rewriting ${targetPath} in signal mode` : `watching config changes, rewriting ${targetPath}, and restarting the child process`;
+}
+
 // src/commands/drift.ts
 import { compareSchemaToGraph, formatDriftReport } from "@kitsy/cnos/internal";
 async function runDrift(options = {}) {
@@ -574,7 +835,7 @@ async function runDiff(leftProfile, rightProfile, options = {}) {
 
 // src/services/doctor.ts
 import { readdir, readFile as readFile2 } from "fs/promises";
-import path4 from "path";
+import path5 from "path";
 import {
   detectLegacyVaultFormat,
   isSecretReference as isSecretReference2,
@@ -596,7 +857,7 @@ async function createValidationSummary(options = {}) {
 
 // src/services/doctor.ts
 async function checkGitignore(root) {
-  const gitignorePath = path4.join(root, ".gitignore");
+  const gitignorePath = path5.join(root, ".gitignore");
   const expected = [
     ".cnos/env/.env",
     ".cnos/env/.env.*",
@@ -631,12 +892,12 @@ async function collectYamlFiles(root) {
     const entries = await readdir(root, { withFileTypes: true });
     const results = [];
     for (const entry of entries) {
-      const target = path4.join(root, entry.name);
+      const target = path5.join(root, entry.name);
       if (entry.isDirectory()) {
         results.push(...await collectYamlFiles(target));
         continue;
       }
-      if (entry.isFile() && [".yml", ".yaml"].includes(path4.extname(entry.name).toLowerCase())) {
+      if (entry.isFile() && [".yml", ".yaml"].includes(path5.extname(entry.name).toLowerCase())) {
         results.push(target);
       }
     }
@@ -661,7 +922,7 @@ async function checkSecretSecurity(options, runtime) {
   );
   const legacyDetected = legacyPaths.filter((entry) => Boolean(entry.path));
   const secretFiles = await Promise.all(
-    runtime.graph.workspace.workspaceRoots.filter((root) => root.scope === "local").map((root) => collectYamlFiles(path4.join(root.path, "secrets")))
+    runtime.graph.workspace.workspaceRoots.filter((root) => root.scope === "local").map((root) => collectYamlFiles(path5.join(root.path, "secrets")))
   );
   const plaintextFiles = [];
   for (const file of secretFiles.flat()) {
@@ -691,7 +952,7 @@ async function checkSecretSecurity(options, runtime) {
   };
 }
 async function evaluateDoctor(options = {}) {
-  const root = path4.resolve(options.root ?? process.cwd());
+  const root = path5.resolve(options.root ?? process.cwd());
   const { runtime, summary } = await createValidationSummary(options);
   const localRoot = runtime.graph.workspace.workspaceRoots.find((entry) => entry.scope === "local");
   const globalRoot = runtime.graph.workspace.workspaceRoots.find((entry) => entry.scope === "global");
@@ -811,44 +1072,33 @@ async function runCodegen(options = {}) {
 }
 
 // src/commands/exportEnv.ts
-import { mkdir as mkdir2, writeFile as writeFile2 } from "fs/promises";
-import path5 from "path";
-function formatEnvOutput(env) {
-  return Object.entries(env).sort(([left], [right]) => left.localeCompare(right)).map(([key, value]) => `${key}=${value}`).join("\n");
-}
 async function runExportEnv(options = {}) {
-  const cliArgs = [...options.cliArgs ?? []];
-  const isPublic = consumeFlag(cliArgs, "--public");
-  const framework = consumeOption(cliArgs, "--framework");
-  const prefix = consumeOption(cliArgs, "--prefix");
-  const to = consumeOption(cliArgs, "--to");
-  const runtime = await createRuntimeService({
+  const infoArgs = [...options.cliArgs ?? []];
+  const isPublic = consumeFlag(infoArgs, "--public");
+  const framework = consumeOption(infoArgs, "--framework");
+  consumeOption(infoArgs, "--prefix");
+  const to = consumeOption(infoArgs, "--to");
+  const baseOptions = {
     ...options,
-    cliArgs
-  });
-  const env = isPublic ? runtime.toPublicEnv({
-    ...framework ? { framework } : {},
-    ...prefix ? { prefix } : {}
-  }) : runtime.toEnv();
-  const output = formatEnvOutput(env);
+    cliArgs: [...options.cliArgs ?? []]
+  };
   if (to) {
-    const targetPath = path5.resolve(options.root ?? process.cwd(), to);
-    await mkdir2(path5.dirname(targetPath), { recursive: true });
-    await writeFile2(targetPath, output, "utf8");
+    const result2 = await materializeEnvToFile(to, baseOptions);
     if (options.json) {
       return printJson({
-        to: targetPath,
-        count: Object.keys(env).length,
+        to: result2.targetPath,
+        count: Object.keys(result2.env).length,
         public: isPublic,
         ...framework ? { framework } : {}
       });
     }
-    return `Wrote ${Object.keys(env).length} env vars to ${targetPath}`;
+    return `Wrote ${Object.keys(result2.env).length} env vars to ${displayPath(result2.targetPath, options.root ?? process.cwd())}`;
   }
+  const result = await resolveMaterializedEnv(baseOptions);
   if (options.json) {
-    return printJson(env);
+    return printJson(result.env);
   }
-  return output;
+  return result.output;
 }
 
 // src/commands/export.ts
@@ -1309,6 +1559,52 @@ var COMMANDS = [
       "cnos export env --public --framework next --workspace webapp"
     ]
   },
+  {
+    id: "build",
+    summary: "Build derived configuration artifacts from CNOS.",
+    usage: "cnos build <subcommand> [options] [global-options]",
+    description: "Builds deterministic derived outputs from the selected workspace. Currently supports env artifact generation.",
+    arguments: [
+      {
+        name: "subcommand",
+        description: "Supported value: env.",
+        required: true
+      }
+    ],
+    examples: [
+      "cnos build env --profile local --to .env.local",
+      "cnos build env --public --framework vite --profile prod --to .env.production"
+    ]
+  },
+  {
+    id: "build env",
+    summary: "Build a flat env-file artifact from CNOS.",
+    usage: "cnos build env --to <path> [--public] [--framework <name>] [--prefix <prefix>] [global-options]",
+    description: "Builds a deterministic KEY=VALUE artifact for legacy build and runtime workflows. The target file is derived output, not the CNOS source of truth.",
+    options: [
+      {
+        flag: "--to <path>",
+        description: "Write the rendered KEY=VALUE output to a file. Required."
+      },
+      {
+        flag: "--public",
+        description: "Build only public values based on manifest promotion rules."
+      },
+      {
+        flag: "--framework <name>",
+        description: "Apply framework-specific public env conventions such as vite or next."
+      },
+      {
+        flag: "--prefix <prefix>",
+        description: "Override the generated public env prefix."
+      }
+    ],
+    examples: [
+      "cnos build env --profile local --to .env.local",
+      "cnos build env --profile stage --to .env.stage",
+      "cnos build env --public --framework vite --to .env.local"
+    ]
+  },
   {
     id: "export env",
     summary: "Render environment variables for the selected workspace.",
@@ -1338,6 +1634,60 @@ var COMMANDS = [
       "cnos export env --public --framework vite --to .env.local --workspace api"
     ]
   },
+  {
+    id: "dev",
+    summary: "Run watched CNOS-driven development workflows.",
+    usage: "cnos dev <subcommand> [options] [global-options] -- <command...>",
+    description: "Runs higher-level development workflows that derive config artifacts from CNOS and keep them up to date while a child process is running.",
+    arguments: [
+      {
+        name: "subcommand",
+        description: "Supported value: env.",
+        required: true
+      }
+    ],
+    examples: [
+      "cnos dev env --profile local --to .env.local -- pnpm dev",
+      "cnos dev env --public --framework vite --to .env.local -- pnpm dev"
+    ]
+  },
+  {
+    id: "dev env",
+    summary: "Watch CNOS config, rewrite an env file, and restart a child process.",
+    usage: "cnos dev env --to <path> [--public] [--framework <name>] [--prefix <prefix>] [--debounce <ms>] [--signal] [global-options] -- <command...>",
+    description: "Writes a derived env file before first launch, watches CNOS inputs, rewrites the file on change, and restarts the child process by default.",
+    options: [
+      {
+        flag: "--to <path>",
+        description: "Write the rendered KEY=VALUE output to a file. Required."
+      },
+      {
+        flag: "--public",
+        description: "Build only public values based on manifest promotion rules."
+      },
+      {
+        flag: "--framework <name>",
+        description: "Apply framework-specific public env conventions such as vite or next."
+      },
+      {
+        flag: "--prefix <prefix>",
+        description: "Override the generated public env prefix."
+      },
+      {
+        flag: "--debounce <ms>",
+        description: "Debounce config changes before rebuilding the env artifact. Defaults to 300ms."
+      },
+      {
+        flag: "--signal",
+        description: "Rewrite the env artifact and emit changed keys as JSON instead of restarting the child process."
+      }
+    ],
+    examples: [
+      "cnos dev env --profile local --to .env.local -- pnpm dev",
+      "cnos dev env --profile stage --to .env.stage -- node server.js",
+      "cnos dev env --public --framework vite --to .env.local --signal -- pnpm dev"
+    ]
+  },
   {
     id: "dump",
     summary: "Materialize the selected workspace into files.",
@@ -1542,6 +1892,8 @@ var HELP_DOCUMENT = {
   examples: [
     "cnos use --profile stage",
     "cnos doctor --workspace api",
+    "cnos build env --profile stage --to .env.stage",
+    "cnos dev env --profile local --to .env.local -- pnpm dev",
     "cnos export env --public --framework vite",
     "cnos export env --public --framework next",
     "cnos help-ai --format json"
@@ -2443,7 +2795,6 @@ async function runRead(key, options = {}) {
 }
 
 // src/commands/run.ts
-import { spawn } from "child_process";
 import {
   CNOS_GRAPH_ENV_VAR,
   CNOS_SECRET_PAYLOAD_ENV_VAR,
@@ -2517,11 +2868,10 @@ async function runCommand(command, options = {}) {
       reject(new Error("run requires a command after --"));
       return;
     }
-    const child = spawn(executable, command.slice(1), {
+    const child = spawnCommand(command, {
       cwd: options.root ?? process.cwd(),
       env,
-      stdio: options.stdio === "pipe" ? "pipe" : "inherit",
-      shell: false
+      stdio: options.stdio === "pipe" ? "pipe" : "inherit"
     });
     let stdout = "";
     let stderr = "";
@@ -2993,7 +3343,7 @@ async function runValidate(options = {}) {
 // package.json
 var package_default = {
   name: "@kitsy/cnos-cli",
-  version: "1.4.0",
+  version: "1.5.1",
   description: "CLI entry point and developer tooling for CNOS.",
   type: "module",
   main: "./dist/index.js",
@@ -3133,16 +3483,12 @@ async function runValue(argsOrPath, options = {}) {
 }
 
 // src/commands/watch.ts
-import { watch } from "fs";
-import { spawn as spawn2 } from "child_process";
 import {
   CNOS_GRAPH_ENV_VAR as CNOS_GRAPH_ENV_VAR2,
   CNOS_SECRET_PAYLOAD_ENV_VAR as CNOS_SECRET_PAYLOAD_ENV_VAR2,
   CNOS_SESSION_KEY_ENV_VAR as CNOS_SESSION_KEY_ENV_VAR2,
-  diffGraphs,
   serializeRuntimeGraph as serializeRuntimeGraph2,
-  serializeSecretPayload as serializeSecretPayload2,
-  watchFiles
+  serializeSecretPayload as serializeSecretPayload2
 } from "@kitsy/cnos/internal";
 async function buildRunEnvironment(options) {
   const cliArgs = [...options.cliArgs ?? []];
@@ -3179,11 +3525,10 @@ function spawnWatchedChild(command, cwd, env) {
   if (!executable) {
     throw new Error("watch requires a command after -- unless --signal is used");
   }
-  return spawn2(executable, command.slice(1), {
+  return spawnCommand(command, {
     cwd,
     env,
-    stdio: "inherit",
-    shell: false
+    stdio: "inherit"
   });
 }
 async function startWatchLoop(options) {
@@ -3197,85 +3542,39 @@ async function startWatchLoop(options) {
     cliArgs
   });
   let child = !isSignal ? spawnWatchedChild(command, root, current.env) : void 0;
-  const watcherMap = /* @__PURE__ */ new Map();
-  let timer;
   let closed = false;
-  const attachWatcher = (targetPath, recursive = false) => {
-    if (watcherMap.has(targetPath)) {
-      return;
-    }
-    try {
-      const watcher = watch(
-        targetPath,
-        recursive ? {
-          recursive: true
-        } : void 0,
-        () => {
-          if (timer) {
-            clearTimeout(timer);
-          }
-          timer = setTimeout(() => {
-            void handleChange();
-          }, debounceMs);
-        }
-      );
-      watcherMap.set(targetPath, watcher);
-    } catch {
-      if (recursive) {
-        attachWatcher(targetPath, false);
+  const watcher = await startGraphWatchLoop({
+    ...options,
+    cliArgs,
+    debounceMs,
+    async onChange(payload) {
+      if (closed) {
+        return;
       }
-    }
-  };
-  const refreshWatchers = async () => {
-    const nextTargets = await watchFiles(current.runtime, options.root);
-    attachWatcher(nextTargets.manifestPath, false);
-    for (const workspaceRoot of nextTargets.roots) {
-      attachWatcher(workspaceRoot, true);
-    }
-    for (const filePath of nextTargets.files) {
-      attachWatcher(filePath, false);
-    }
-  };
-  const handleChange = async () => {
-    if (closed) {
-      return;
-    }
-    const next = await buildRunEnvironment({
-      ...options,
-      cliArgs
-    });
-    const changedKeys = diffGraphs(current.runtime.graph, next.runtime.graph);
-    current = next;
-    await refreshWatchers();
-    if (changedKeys.length === 0) {
-      return;
-    }
-    if (isSignal) {
-      await options.onSignal?.({ changedKeys });
-      process.stdout.write(`${printJson({ changedKeys })}
-`);
-      return;
-    }
-    if (child && !child.killed) {
-      await new Promise((resolve) => {
-        child?.once("close", () => resolve());
-        child?.kill();
+      current = await buildRunEnvironment({
+        ...options,
+        cliArgs
       });
+      if (isSignal) {
+        await options.onSignal?.({ changedKeys: payload.changedKeys });
+        process.stdout.write(`${printJson({ changedKeys: payload.changedKeys })}
+`);
+        return;
+      }
+      if (child && !child.killed) {
+        await new Promise((resolve) => {
+          child?.once("close", () => resolve());
+          child?.kill();
+        });
+      }
+      child = spawnWatchedChild(command, root, current.env);
+      await options.onRestart?.({ changedKeys: payload.changedKeys });
     }
-    child = spawnWatchedChild(command, root, current.env);
-    await options.onRestart?.({ changedKeys });
-  };
-  await refreshWatchers();
+  });
   return {
     async close() {
       closed = true;
-      if (timer) {
-        clearTimeout(timer);
-      }
-      for (const watcher of watcherMap.values()) {
-        watcher.close();
-      }
-      watcherMap.clear();
+      await watcher.close();
       if (child && !child.killed) {
         await new Promise((resolve) => {
           child?.once("close", () => resolve());
@@ -3314,6 +3613,12 @@ function resolveHelpTopic(command, args) {
   if (command === "export" && args[0] === "env") {
     return normalizeHelpTopic([command, args[0]]);
   }
+  if (command === "build" && args[0] === "env") {
+    return normalizeHelpTopic([command, args[0]]);
+  }
+  if (command === "dev" && args[0] === "env") {
+    return normalizeHelpTopic([command, args[0]]);
+  }
   if (command === "vault" && args[0] && ["create", "add", "list", "delete", "remove"].includes(args[0])) {
     return normalizeHelpTopic([command, args[0] === "delete" ? "remove" : args[0] === "add" ? "create" : args[0]]);
   }
@@ -3444,6 +3749,14 @@ async function main(argv) {
       return;
     case "export":
       process.stdout.write(`${await runExport(args[0], runtimeOptions)}
+`);
+      return;
+    case "build":
+      process.stdout.write(`${await runBuild(args[0], runtimeOptions)}
+`);
+      return;
+    case "dev":
+      process.stdout.write(`${await runDev(args[0], passthrough.length > 0 ? passthrough : args.slice(1), runtimeOptions)}
 `);
       return;
     case "dump":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kitsy/cnos-cli",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "description": "CLI entry point and developer tooling for CNOS.",
   "type": "module",
   "main": "./dist/index.js",
@@ -36,7 +36,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@kitsy/cnos": "1.4.0"
+    "@kitsy/cnos": "1.5.1"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm --dts",