@kitsy/cnos-cli 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kitsy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,3 @@
+# @kitsy/cnos-cli
+
+Developer CLI for CNOS. The package exposes the `cnos` executable and keeps command routing, output formatting, and future developer workflows outside of the runtime packages.

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+declare function main(argv: string[]): Promise<void>;
+
+export { main };

package/dist/index.js

@@ -0,0 +1,1209 @@
+#!/usr/bin/env node
+
+// src/cli/parseArgs.ts
+var OPTION_KEYS = {
+  "--root": "root",
+  "--workspace": "workspace",
+  "--profile": "profile",
+  "--global-root": "globalRoot"
+};
+var COMMAND_OPTION_KEYS_WITH_VALUE = /* @__PURE__ */ new Set(["--format", "--framework", "--prefix", "--target", "--to"]);
+var COMMAND_FLAG_KEYS = /* @__PURE__ */ new Set(["--flatten", "--public"]);
+function setOption(options, key, value) {
+  options[key] = value;
+}
+function parseArgs(argv) {
+  if (argv[0] === "--help" || argv[0] === "-h") {
+    return {
+      command: "help",
+      args: [],
+      options: {
+        cliArgs: []
+      },
+      passthrough: []
+    };
+  }
+  const [command = "doctor", ...rest] = argv;
+  const options = {};
+  const args = [];
+  const cliArgs = [];
+  const passthrough = [];
+  let passthroughMode = false;
+  for (let index = 0; index < rest.length; index += 1) {
+    const token = rest[index];
+    if (!token) {
+      continue;
+    }
+    if (token === "--") {
+      passthroughMode = true;
+      continue;
+    }
+    if (passthroughMode) {
+      passthrough.push(token);
+      continue;
+    }
+    if (token === "--json") {
+      options.json = true;
+      continue;
+    }
+    if (token === "--help" || token === "-h") {
+      options.help = true;
+      continue;
+    }
+    const optionKey = Object.keys(OPTION_KEYS).find(
+      (candidate) => token === candidate || token.startsWith(`${candidate}=`)
+    );
+    if (optionKey) {
+      const inlineValue = token.includes("=") ? token.slice(token.indexOf("=") + 1) : void 0;
+      const nextValue = inlineValue ?? rest[index + 1];
+      if (!nextValue) {
+        throw new Error(`Missing value for ${optionKey}`);
+      }
+      setOption(options, OPTION_KEYS[optionKey], nextValue);
+      if (!inlineValue) {
+        index += 1;
+      }
+      continue;
+    }
+    if (token.startsWith("--")) {
+      cliArgs.push(token);
+      const rawKey = token.includes("=") ? token.slice(0, token.indexOf("=")) : token;
+      if (!token.includes("=") && COMMAND_OPTION_KEYS_WITH_VALUE.has(rawKey)) {
+        const nextValue = rest[index + 1];
+        if (!nextValue || nextValue.startsWith("--")) {
+          throw new Error(`Missing value for ${rawKey}`);
+        }
+        cliArgs.push(nextValue);
+        index += 1;
+        continue;
+      }
+      if (COMMAND_FLAG_KEYS.has(rawKey)) {
+        continue;
+      }
+      continue;
+    }
+    args.push(token);
+  }
+  return {
+    command,
+    args,
+    options: {
+      ...options,
+      cliArgs
+    },
+    passthrough
+  };
+}
+
+// src/cli/commandOptions.ts
+function consumeFlag(args, flag) {
+  const index = args.indexOf(flag);
+  if (index >= 0) {
+    args.splice(index, 1);
+    return true;
+  }
+  return false;
+}
+function consumeOption(args, flag) {
+  const inline = args.find((entry) => entry.startsWith(`${flag}=`));
+  if (inline) {
+    args.splice(args.indexOf(inline), 1);
+    return inline.slice(flag.length + 1);
+  }
+  const index = args.indexOf(flag);
+  if (index >= 0) {
+    const value = args[index + 1];
+    if (!value) {
+      throw new Error(`Missing value for ${flag}`);
+    }
+    args.splice(index, 2);
+    return value;
+  }
+  return void 0;
+}
+
+// src/format/printJson.ts
+function printJson(value) {
+  return JSON.stringify(value, null, 2);
+}
+
+// src/services/writes.ts
+import { mkdir, readFile, writeFile } from "fs/promises";
+import path from "path";
+import { parseYaml, resolveWorkspaceScopedPath, stringifyYaml } from "@kitsy/cnos-core";
+
+// src/services/runtime.ts
+import { createCnos } from "@kitsy/cnos";
+async function createRuntimeService(options = {}) {
+  const createOptions = {
+    root: options.root ?? process.cwd(),
+    ...options.workspace ? {
+      workspace: options.workspace
+    } : {},
+    ...options.profile ? {
+      profile: options.profile
+    } : {},
+    ...options.globalRoot ? {
+      globalRoot: options.globalRoot
+    } : {},
+    ...options.cliArgs && options.cliArgs.length > 0 ? {
+      cliArgs: options.cliArgs
+    } : {},
+    ...options.processEnv ? {
+      processEnv: options.processEnv
+    } : {
+      processEnv: process.env
+    }
+  };
+  return createCnos({
+    ...createOptions
+  });
+}
+
+// src/services/writes.ts
+function setNestedValue(target, pathSegments, value) {
+  const [head, ...tail] = pathSegments;
+  if (!head) {
+    return;
+  }
+  if (tail.length === 0) {
+    target[head] = value;
+    return;
+  }
+  const nextTarget = target[head] && typeof target[head] === "object" && !Array.isArray(target[head]) ? target[head] : {};
+  target[head] = nextTarget;
+  setNestedValue(nextTarget, tail, value);
+}
+function parseScalarValue(rawValue) {
+  try {
+    return parseYaml(rawValue);
+  } catch {
+    return rawValue;
+  }
+}
+async function defineValue(namespace, configPath, rawValue, options = {}) {
+  const runtime = await createRuntimeService(options);
+  const target = options.target ?? "local";
+  const workspaceRoot = runtime.graph.workspace.workspaceRoots.find(
+    (entry) => entry.scope === target && entry.workspaceId === runtime.graph.workspace.workspaceId
+  );
+  if (!workspaceRoot) {
+    throw new Error(`No ${target} workspace root is available for ${runtime.graph.workspace.workspaceId}`);
+  }
+  if (target === "global" && !runtime.manifest.workspaces.global.allowWrite) {
+    throw new Error("Global writes require workspaces.global.allowWrite: true");
+  }
+  const profile = options.profile ?? runtime.manifest.writePolicy.define.defaultProfile;
+  const template = runtime.manifest.writePolicy.define.targets[namespace];
+  const filePath = resolveWorkspaceScopedPath(workspaceRoot.path, template, {
+    workspace: runtime.graph.workspace.workspaceId,
+    profile
+  });
+  let document = {};
+  try {
+    document = parseYaml(await readFile(filePath, "utf8")) ?? {};
+  } catch {
+    document = {};
+  }
+  const parsedValue = parseScalarValue(rawValue);
+  setNestedValue(document, configPath.split("."), parsedValue);
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, stringifyYaml(document), "utf8");
+  return {
+    filePath,
+    value: parsedValue
+  };
+}
+
+// src/commands/define.ts
+async function runDefine(namespace, configPath, rawValue, options = {}) {
+  const cliArgs = [...options.cliArgs ?? []];
+  const target = consumeOption(cliArgs, "--target") ?? "local";
+  const result = await defineValue(namespace, configPath, rawValue, {
+    ...options,
+    cliArgs,
+    target
+  });
+  if (options.json) {
+    return printJson({
+      namespace,
+      path: configPath,
+      target,
+      filePath: result.filePath,
+      value: result.value
+    });
+  }
+  return `defined ${namespace}.${configPath} in ${result.filePath}`;
+}
+
+// src/commands/diff.ts
+import { flattenObject } from "@kitsy/cnos-core";
+function flattenRuntime(runtime) {
+  return {
+    ...Object.fromEntries(
+      Object.entries(flattenObject(runtime.toNamespace("value"))).map(([key, value]) => [`value.${key}`, value])
+    ),
+    ...Object.fromEntries(
+      Object.entries(flattenObject(runtime.toNamespace("secret"))).map(([key, value]) => [`secret.${key}`, value])
+    )
+  };
+}
+async function runDiff(leftProfile, rightProfile, options = {}) {
+  const leftRuntime = await createRuntimeService({
+    ...options,
+    profile: leftProfile
+  });
+  const rightRuntime = await createRuntimeService({
+    ...options,
+    profile: rightProfile
+  });
+  const left = flattenRuntime(leftRuntime);
+  const right = flattenRuntime(rightRuntime);
+  const keys = Array.from(/* @__PURE__ */ new Set([...Object.keys(left), ...Object.keys(right)])).sort(
+    (a, b) => a.localeCompare(b)
+  );
+  const rows = keys.filter((key) => JSON.stringify(left[key]) !== JSON.stringify(right[key])).map((key) => ({
+    key,
+    left: left[key] ?? null,
+    right: right[key] ?? null
+  }));
+  if (options.json) {
+    return printJson(rows);
+  }
+  return rows.map((row) => `${row.key}: ${JSON.stringify(row.left)} -> ${JSON.stringify(row.right)}`).join("\n");
+}
+
+// src/services/doctor.ts
+import { readFile as readFile2 } from "fs/promises";
+import path2 from "path";
+
+// src/services/validation.ts
+import { validateRuntime } from "@kitsy/cnos-core";
+async function createValidationSummary(options = {}) {
+  const runtime = await createRuntimeService(options);
+  const summary = await validateRuntime(runtime);
+  return {
+    summary,
+    runtime
+  };
+}
+
+// src/services/doctor.ts
+async function checkGitignore(root) {
+  const gitignorePath = path2.join(root, ".gitignore");
+  const expected = [
+    "cnos/workspaces/*/secrets/",
+    "cnos/workspaces/*/env/.env",
+    "cnos/workspaces/*/env/.env.*",
+    "!cnos/workspaces/*/env/.env.example",
+    "!cnos/workspaces/*/env/.env.*.example"
+  ];
+  try {
+    const content = await readFile2(gitignorePath, "utf8");
+    const missing = expected.filter((entry) => !content.includes(entry));
+    return {
+      name: "gitignore",
+      ok: missing.length === 0,
+      details: missing.length === 0 ? "workspace secrets and live env files are ignored while example env files stay trackable" : `missing: ${missing.join(", ")}`
+    };
+  } catch {
+    return {
+      name: "gitignore",
+      ok: false,
+      details: "missing .gitignore"
+    };
+  }
+}
+function issueSummary(issues) {
+  return issues.length === 0 ? "no issues" : issues.map((issue) => issue.message).join("; ");
+}
+async function evaluateDoctor(options = {}) {
+  const root = path2.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");
+  return [
+    {
+      name: "manifest",
+      ok: true,
+      details: `project=${runtime.manifest.project.name}`
+    },
+    {
+      name: "workspace",
+      ok: true,
+      details: `${runtime.graph.workspace.workspaceId} via ${runtime.graph.workspace.workspaceSource}`
+    },
+    {
+      name: "source-roots",
+      ok: Boolean(localRoot),
+      details: [localRoot?.path, globalRoot?.path].filter(Boolean).join(" | ")
+    },
+    {
+      name: "validation",
+      ok: summary.valid,
+      details: issueSummary(summary.issues)
+    },
+    {
+      name: "global-policy",
+      ok: !runtime.manifest.workspaces.global.enabled || Boolean(runtime.graph.workspace.globalRoot),
+      details: runtime.manifest.workspaces.global.enabled ? runtime.graph.workspace.globalRoot ? `enabled at ${runtime.graph.workspace.globalRoot}` : "enabled but no global root resolved" : "disabled"
+    },
+    await checkGitignore(root)
+  ];
+}
+
+// src/commands/doctor.ts
+async function runDoctor(options = {}) {
+  const checks = await evaluateDoctor(options);
+  const hasFailures = checks.some((check) => !check.ok);
+  if (hasFailures) {
+    process.exitCode = 1;
+  }
+  if (options.json) {
+    return printJson(checks);
+  }
+  return checks.map((check) => `${check.ok ? "OK" : "FAIL"} ${check.name}: ${check.details}`).join("\n");
+}
+
+// src/commands/dump.ts
+import { writeDump } from "@kitsy/cnos";
+async function runDump(options = {}) {
+  const cliArgs = [...options.cliArgs ?? []];
+  const flatten = consumeFlag(cliArgs, "--flatten");
+  const to = consumeOption(cliArgs, "--to");
+  if (!to) {
+    throw new Error("dump requires --to <path>");
+  }
+  const runtime = await createRuntimeService({
+    ...options,
+    cliArgs
+  });
+  const result = await writeDump(runtime.graph, {
+    to,
+    flatten
+  });
+  if (options.json) {
+    return printJson(result);
+  }
+  return `dumped ${result.files.length} files to ${result.root}`;
+}
+
+// src/commands/exportEnv.ts
+async function runExportEnv(options = {}) {
+  const cliArgs = [...options.cliArgs ?? []];
+  const isPublic = consumeFlag(cliArgs, "--public");
+  const framework = consumeOption(cliArgs, "--framework");
+  const prefix = consumeOption(cliArgs, "--prefix");
+  const runtime = await createRuntimeService({
+    ...options,
+    cliArgs
+  });
+  const env = isPublic ? runtime.toPublicEnv({
+    ...framework ? { framework } : {},
+    ...prefix ? { prefix } : {}
+  }) : runtime.toEnv();
+  if (options.json) {
+    return printJson(env);
+  }
+  return Object.entries(env).sort(([left], [right]) => left.localeCompare(right)).map(([key, value]) => `${key}=${value}`).join("\n");
+}
+
+// src/commands/export.ts
+async function runExport(subcommand, options = {}) {
+  if ((subcommand ?? "env") !== "env") {
+    throw new Error(`Unsupported export target: ${subcommand}`);
+  }
+  return runExportEnv(options);
+}
+
+// src/cli/helpRegistry.ts
+var GLOBAL_OPTIONS = [
+  {
+    flag: "--root <path>",
+    description: "Resolve the CNOS project from a specific filesystem root."
+  },
+  {
+    flag: "--workspace <id>",
+    description: "Select the active workspace for this invocation."
+  },
+  {
+    flag: "--profile <name>",
+    description: "Override the active profile for reads, export, diff, and run."
+  },
+  {
+    flag: "--global-root <path>",
+    description: "Override the configured global CNOS root used for workspace layering."
+  },
+  {
+    flag: "--json",
+    description: "Emit JSON output for commands that support structured responses."
+  },
+  {
+    flag: "--help, -h",
+    description: "Show command help."
+  }
+];
+var COMMANDS = [
+  {
+    id: "init",
+    summary: "Scaffold a workspace-aware CNOS tree in the current project.",
+    usage: "cnos init [--workspace <id>] [--root <path>] [--json]",
+    description: "Creates cnos/cnos.yml, .cnos-workspace.yml, workspace folders, and .gitignore entries without overwriting existing files.",
+    examples: ["cnos init", "cnos init --workspace api", "cnos init --root ./apps/api --workspace api --json"]
+  },
+  {
+    id: "onboard",
+    summary: "Onboard an existing repo into CNOS and import root dotenv files.",
+    usage: "cnos onboard [--workspace <id>] [--root <path>] [--move] [--json]",
+    description: "Scaffolds the CNOS workspace tree and imports root-level .env, .env.<profile>, and .env.*.example files into cnos/workspaces/<workspace>/env.",
+    options: [
+      {
+        flag: "--move",
+        description: "Move the root env files into CNOS instead of leaving the originals in place."
+      }
+    ],
+    examples: ["cnos onboard", "cnos onboard --workspace webapp", "cnos onboard --root ../my-app --workspace app --move"]
+  },
+  {
+    id: "read",
+    summary: "Read any fully-qualified CNOS key.",
+    usage: "cnos read <key> [global-options]",
+    description: "Reads a fully-qualified key such as value.app.name or secret.app.token.",
+    arguments: [
+      {
+        name: "key",
+        description: "Fully-qualified key to read.",
+        required: true
+      }
+    ],
+    examples: ["cnos read value.app.name", "cnos read secret.app.token --workspace api"]
+  },
+  {
+    id: "value",
+    summary: "Read a value namespace key without the value. prefix.",
+    usage: "cnos value <path> [global-options]",
+    description: "Reads value.<path> from the selected workspace and profile.",
+    arguments: [
+      {
+        name: "path",
+        description: "Value path without the value. namespace prefix.",
+        required: true
+      }
+    ],
+    examples: ["cnos value app.name", "cnos value server.port --profile stage --workspace api"]
+  },
+  {
+    id: "secret",
+    summary: "Read a secret namespace key without the secret. prefix.",
+    usage: "cnos secret <path> [global-options]",
+    description: "Reads secret.<path> from the selected workspace and profile.",
+    arguments: [
+      {
+        name: "path",
+        description: "Secret path without the secret. namespace prefix.",
+        required: true
+      }
+    ],
+    examples: ["cnos secret app.token", "cnos secret service.apiKey --workspace agents"]
+  },
+  {
+    id: "define",
+    summary: "Write a value or secret into the selected workspace.",
+    usage: "cnos define <value|secret> <path> <rawValue> [--target <local|global>] [global-options]",
+    description: "Writes deterministic YAML into the selected workspace. Global writes require allowWrite and an explicit --target global flag.",
+    arguments: [
+      {
+        name: "namespace",
+        description: "Either value or secret.",
+        required: true
+      },
+      {
+        name: "path",
+        description: "Path without the namespace prefix.",
+        required: true
+      },
+      {
+        name: "rawValue",
+        description: "Literal value to write.",
+        required: true
+      }
+    ],
+    options: [
+      {
+        flag: "--target <local|global>",
+        description: "Choose whether the write lands in the local project workspace or the configured global root."
+      }
+    ],
+    examples: [
+      "cnos define value server.port 3000 --workspace api",
+      "cnos define secret app.token super-secret --workspace api --target global"
+    ]
+  },
+  {
+    id: "inspect",
+    summary: "Inspect the winning value and provenance for a key.",
+    usage: "cnos inspect <key> [global-options]",
+    description: "Shows the resolved value, namespace, active profile, workspace context, and the loader/origin that won precedence.",
+    arguments: [
+      {
+        name: "key",
+        description: "Fully-qualified key to inspect.",
+        required: true
+      }
+    ],
+    examples: ["cnos inspect value.server.port", "cnos inspect secret.app.token --workspace api --json"]
+  },
+  {
+    id: "validate",
+    summary: "Validate schema, public promotion, and workspace safety rules.",
+    usage: "cnos validate [global-options]",
+    description: "Runs the CNOS validation pipeline and exits non-zero when validation issues are found.",
+    examples: ["cnos validate", "cnos validate --workspace api --profile stage --json"]
+  },
+  {
+    id: "export",
+    summary: "Export data from the selected workspace.",
+    usage: "cnos export <subcommand> [options] [global-options]",
+    description: "Currently supports env export for runtime and public environment projections.",
+    arguments: [
+      {
+        name: "subcommand",
+        description: "Supported value: env.",
+        required: true
+      }
+    ],
+    examples: ["cnos export env", "cnos export env --public --framework vite --workspace api"]
+  },
+  {
+    id: "export env",
+    summary: "Render environment variables for the selected workspace.",
+    usage: "cnos export env [--public] [--framework <name>] [--prefix <prefix>] [global-options]",
+    description: "Exports the effective environment as KEY=VALUE lines, or only promoted public values when --public is set.",
+    options: [
+      {
+        flag: "--public",
+        description: "Export only public values based on manifest promotion rules."
+      },
+      {
+        flag: "--framework <name>",
+        description: "Apply framework-specific public env conventions such as vite or nextjs."
+      },
+      {
+        flag: "--prefix <prefix>",
+        description: "Override the generated public env prefix."
+      }
+    ],
+    examples: ["cnos export env", "cnos export env --public --framework vite --workspace api"]
+  },
+  {
+    id: "dump",
+    summary: "Materialize the selected workspace into files.",
+    usage: "cnos dump --to <path> [--flatten] [global-options]",
+    description: "Writes the effective workspace snapshot to disk. Use --flatten to emit a standalone values/secrets tree instead of preserving workspace layout.",
+    options: [
+      {
+        flag: "--to <path>",
+        description: "Destination directory for the materialized snapshot."
+      },
+      {
+        flag: "--flatten",
+        description: "Write a flattened values/secrets tree instead of workspace-preserving output."
+      }
+    ],
+    examples: ["cnos dump --to ./out", "cnos dump --to ./snapshot --flatten --workspace api"]
+  },
+  {
+    id: "run",
+    summary: "Run a child process with CNOS env injected.",
+    usage: "cnos run [global-options] -- <command...>",
+    description: "Resolves the active workspace and profile, injects runtime env variables, and executes the command after --.",
+    examples: ["cnos run -- node server.js", "cnos run --workspace api -- pnpm dev"]
+  },
+  {
+    id: "diff",
+    summary: "Diff two profiles for the same workspace.",
+    usage: "cnos diff <leftProfile> <rightProfile> [global-options]",
+    description: "Compares effective value and secret graphs between two profiles in the selected workspace.",
+    arguments: [
+      {
+        name: "leftProfile",
+        description: "Baseline profile name.",
+        required: true
+      },
+      {
+        name: "rightProfile",
+        description: "Comparison profile name.",
+        required: true
+      }
+    ],
+    examples: ["cnos diff local stage --workspace api", "cnos diff stage prod --workspace api --json"]
+  },
+  {
+    id: "doctor",
+    summary: "Run repository and workspace diagnostics.",
+    usage: "cnos doctor [global-options]",
+    description: "Checks manifest/workspace setup, gitignore coverage, and related diagnostics for the selected workspace.",
+    examples: ["cnos doctor", "cnos doctor --workspace api --json"]
+  },
+  {
+    id: "help",
+    summary: "Show human-readable CLI help.",
+    usage: "cnos help [command]",
+    description: "Prints either the root command list or detailed help for a specific command.",
+    arguments: [
+      {
+        name: "command",
+        description: "Optional command or subcommand, for example export env."
+      }
+    ],
+    examples: ["cnos help", "cnos help define", "cnos help export env"]
+  },
+  {
+    id: "help-ai",
+    summary: "Show machine-readable CLI help for agents.",
+    usage: "cnos help-ai [command] [--format <json|text>]",
+    description: "Prints structured CLI help intended for automation and agents. JSON is the default format.",
+    arguments: [
+      {
+        name: "command",
+        description: "Optional command or subcommand, for example export env."
+      }
+    ],
+    options: [
+      {
+        flag: "--format <json|text>",
+        description: "Select output format. Defaults to json."
+      }
+    ],
+    examples: ["cnos help-ai --format json", "cnos help-ai export env --format json"]
+  }
+];
+var HELP_DOCUMENT = {
+  name: "cnos",
+  summary: "Workspace-aware configuration runtime and CLI for local, global, and promoted environment data.",
+  usage: "cnos <command> [args] [options]",
+  description: "CNOS resolves one active workspace per invocation, layers local and optional global config roots, and exposes read, write, export, dump, validation, and diagnostics commands.",
+  globalOptions: GLOBAL_OPTIONS,
+  commands: COMMANDS,
+  examples: ["cnos doctor --workspace api", "cnos export env --public --framework vite", "cnos help-ai --format json"]
+};
+function normalizeHelpTopic(parts) {
+  const cleaned = parts.filter((part) => part.length > 0);
+  if (cleaned.length === 0) {
+    return void 0;
+  }
+  const candidate = cleaned.join(" ");
+  if (COMMANDS.some((command) => command.id === candidate)) {
+    return candidate;
+  }
+  throw new Error(`Unknown help topic: ${candidate}`);
+}
+function findHelpCommand(topic) {
+  if (!topic) {
+    return void 0;
+  }
+  return COMMANDS.find((command) => command.id === topic);
+}
+
+// src/commands/help.ts
+function formatOptions(title, options) {
+  if (!options || options.length === 0) {
+    return [];
+  }
+  return [title, ...options.map((option) => `  ${option.flag.padEnd(24, " ")} ${option.description}`)];
+}
+function formatCommandHelp(command) {
+  const lines = [`Usage: ${command.usage}`, "", command.summary, "", command.description];
+  if (command.arguments && command.arguments.length > 0) {
+    lines.push("", "Arguments");
+    lines.push(
+      ...command.arguments.map((argument) => {
+        const suffix = argument.required ? " (required)" : "";
+        return `  ${argument.name}${suffix}: ${argument.description}`;
+      })
+    );
+  }
+  lines.push(...command.options && command.options.length > 0 ? ["", ...formatOptions("Options", command.options)] : []);
+  lines.push("", ...formatOptions("Global options", HELP_DOCUMENT.globalOptions));
+  if (command.examples && command.examples.length > 0) {
+    lines.push("", "Examples", ...command.examples.map((example) => `  ${example}`));
+  }
+  return lines.join("\n");
+}
+function formatRootHelp() {
+  const lines = [
+    HELP_DOCUMENT.summary,
+    "",
+    `Usage: ${HELP_DOCUMENT.usage}`,
+    "",
+    "Commands",
+    ...HELP_DOCUMENT.commands.filter((command) => !command.id.includes(" ")).map((command) => `  ${command.id.padEnd(12, " ")} ${command.summary}`),
+    "",
+    ...formatOptions("Global options", HELP_DOCUMENT.globalOptions),
+    "",
+    "Examples",
+    ...HELP_DOCUMENT.examples.map((example) => `  ${example}`)
+  ];
+  return lines.join("\n");
+}
+function runHelp(topic) {
+  const command = findHelpCommand(topic);
+  if (!command) {
+    return formatRootHelp();
+  }
+  return formatCommandHelp(command);
+}
+
+// src/commands/helpAi.ts
+function runHelpAi(topic, cliArgs = []) {
+  const helpArgs = [...cliArgs];
+  const format = consumeOption(helpArgs, "--format") ?? "json";
+  const command = topic ? findHelpCommand(topic) : void 0;
+  if (helpArgs.length > 0) {
+    throw new Error(`Unsupported help-ai arguments: ${helpArgs.join(" ")}`);
+  }
+  const payload = topic ? {
+    cli: HELP_DOCUMENT.name,
+    summary: HELP_DOCUMENT.summary,
+    globalOptions: HELP_DOCUMENT.globalOptions,
+    command
+  } : {
+    cli: HELP_DOCUMENT.name,
+    summary: HELP_DOCUMENT.summary,
+    usage: HELP_DOCUMENT.usage,
+    description: HELP_DOCUMENT.description,
+    globalOptions: HELP_DOCUMENT.globalOptions,
+    commands: HELP_DOCUMENT.commands
+  };
+  if (topic && !command) {
+    throw new Error(`Unknown help topic: ${topic}`);
+  }
+  if (format === "text") {
+    return topic ? `cnos help-ai ${topic} emits JSON by default. Re-run with --format json for structured output.` : "cnos help-ai emits JSON by default. Re-run with --format json for structured output.";
+  }
+  if (format !== "json") {
+    throw new Error(`Unsupported help-ai format: ${format}`);
+  }
+  return printJson(payload);
+}
+
+// src/commands/init.ts
+import path4 from "path";
+
+// src/services/scaffold.ts
+import { mkdir as mkdir2, readFile as readFile3, writeFile as writeFile2 } from "fs/promises";
+import path3 from "path";
+function scaffoldManifest(projectName, workspace) {
+  return [
+    "version: 1",
+    "project:",
+    `  name: ${projectName}`,
+    "workspaces:",
+    `  default: ${workspace}`,
+    "  global:",
+    "    enabled: false",
+    "    allowWrite: false",
+    "  items:",
+    `    ${workspace}: {}`,
+    "profiles:",
+    "  default: local",
+    "envMapping:",
+    "  convention: SCREAMING_SNAKE",
+    "public:",
+    "  promote: []",
+    ""
+  ].join("\n");
+}
+async function ensureFile(filePath, content) {
+  try {
+    await readFile3(filePath, "utf8");
+    return false;
+  } catch {
+    await writeFile2(filePath, content, "utf8");
+    return true;
+  }
+}
+async function ensureGitignore(root) {
+  const gitignorePath = path3.join(root, ".gitignore");
+  const requiredEntries = [
+    "cnos/workspaces/*/secrets/",
+    "cnos/workspaces/*/env/.env",
+    "cnos/workspaces/*/env/.env.*",
+    "!cnos/workspaces/*/env/.env.example",
+    "!cnos/workspaces/*/env/.env.*.example"
+  ];
+  let current = "";
+  try {
+    current = await readFile3(gitignorePath, "utf8");
+  } catch {
+    current = "";
+  }
+  const missingEntries = requiredEntries.filter((entry) => !current.includes(entry));
+  if (missingEntries.length === 0) {
+    return false;
+  }
+  const prefix = current.trim().length > 0 ? `${current.trimEnd()}
+` : "";
+  await writeFile2(gitignorePath, `${prefix}${missingEntries.join("\n")}
+`, "utf8");
+  return true;
+}
+async function scaffoldWorkspace(root, workspace) {
+  const cnosRoot = path3.join(root, "cnos");
+  const workspaceRoot = path3.join(cnosRoot, "workspaces", workspace);
+  const createdPaths = [];
+  await mkdir2(path3.join(workspaceRoot, "profiles"), { recursive: true });
+  await mkdir2(path3.join(workspaceRoot, "values", "local"), { recursive: true });
+  await mkdir2(path3.join(workspaceRoot, "secrets", "local"), { recursive: true });
+  await mkdir2(path3.join(workspaceRoot, "env"), { recursive: true });
+  for (const relativePath of [
+    ["workspaces", workspace, "profiles", ".gitkeep"],
+    ["workspaces", workspace, "values", "local", ".gitkeep"],
+    ["workspaces", workspace, "secrets", "local", ".gitkeep"],
+    ["workspaces", workspace, "env", ".gitkeep"]
+  ]) {
+    const filePath = path3.join(cnosRoot, ...relativePath);
+    if (await ensureFile(filePath, "")) {
+      createdPaths.push(path3.relative(root, filePath).replace(/\\/g, "/"));
+    }
+  }
+  if (await ensureFile(path3.join(cnosRoot, "cnos.yml"), scaffoldManifest(path3.basename(root), workspace))) {
+    createdPaths.push("cnos/cnos.yml");
+  }
+  if (await ensureFile(path3.join(root, ".cnos-workspace.yml"), `workspace: ${workspace}
+globalRoot: ~/.cnos
+`)) {
+    createdPaths.push(".cnos-workspace.yml");
+  }
+  if (await ensureGitignore(root)) {
+    createdPaths.push(".gitignore");
+  }
+  return {
+    root,
+    workspace,
+    created: createdPaths
+  };
+}
+
+// src/commands/init.ts
+async function runInit(options = {}) {
+  const root = path4.resolve(options.root ?? process.cwd());
+  const workspace = options.workspace ?? path4.basename(root);
+  const result = await scaffoldWorkspace(root, workspace);
+  if (options.json) {
+    return printJson(result);
+  }
+  return `initialized CNOS workspace ${workspace} at ${root}`;
+}
+
+// src/format/printInspect.ts
+function printInspect(record) {
+  const lines = [
+    `key: ${record.key}`,
+    `value: ${String(record.value)}`,
+    `namespace: ${record.namespace}`,
+    `profile: ${record.profile} (${record.profileSource})`,
+    `workspace: ${record.workspace.id} (${record.workspace.source})`,
+    `workspaceChain: ${record.workspace.chain.join(" -> ")}`,
+    `winner: ${record.winner.sourceId} via ${record.winner.pluginId} @ ${record.winner.workspaceId}`
+  ];
+  if (record.winner.origin?.file) {
+    lines.push(`winnerOrigin: ${record.winner.origin.file}`);
+  }
+  if (record.overridden.length > 0) {
+    lines.push(
+      `overridden: ${record.overridden.map((entry) => `${entry.sourceId}@${entry.workspaceId}=${String(entry.value)}`).join(", ")}`
+    );
+  }
+  return lines.join("\n");
+}
+
+// src/commands/inspect.ts
+async function runInspect(key, options = {}) {
+  const runtime = await createRuntimeService(options);
+  const inspectResult = runtime.inspect(key);
+  if (options.json) {
+    return printJson(inspectResult);
+  }
+  return printInspect(inspectResult);
+}
+
+// src/commands/onboard.ts
+import { copyFile, readdir, rm } from "fs/promises";
+import path5 from "path";
+var ROOT_ENV_FILE_PATTERN = /^\.env(?:\.[A-Za-z0-9_-]+)*(?:\.example)?$/;
+async function listRootEnvFiles(root) {
+  const entries = await readdir(root, { withFileTypes: true });
+  return entries.filter((entry) => entry.isFile() && ROOT_ENV_FILE_PATTERN.test(entry.name)).map((entry) => entry.name).sort((left, right) => left.localeCompare(right));
+}
+async function runOnboard(options = {}) {
+  const root = path5.resolve(options.root ?? process.cwd());
+  const workspace = options.workspace ?? path5.basename(root);
+  const cliArgs = [...options.cliArgs ?? []];
+  const move = consumeFlag(cliArgs, "--move");
+  if (cliArgs.length > 0) {
+    throw new Error(`Unsupported onboard arguments: ${cliArgs.join(" ")}`);
+  }
+  const scaffold = await scaffoldWorkspace(root, workspace);
+  const envRoot = path5.join(root, "cnos", "workspaces", workspace, "env");
+  const rootFiles = await listRootEnvFiles(root);
+  const imported = [];
+  const skipped = [];
+  for (const fileName of rootFiles) {
+    const sourcePath = path5.join(root, fileName);
+    const targetPath = path5.join(envRoot, fileName);
+    try {
+      await copyFile(sourcePath, targetPath);
+      imported.push(path5.relative(root, targetPath).replace(/\\/g, "/"));
+      if (move) {
+        await rm(sourcePath);
+      }
+    } catch {
+      skipped.push(fileName);
+    }
+  }
+  const result = {
+    root,
+    workspace,
+    scaffolded: scaffold.created,
+    imported,
+    skipped,
+    mode: move ? "move" : "copy"
+  };
+  if (options.json) {
+    return printJson(result);
+  }
+  const importedCount = imported.length;
+  const skippedSuffix = skipped.length > 0 ? ` (${skipped.length} skipped)` : "";
+  return `onboarded ${workspace} at ${root}; imported ${importedCount} root env files into cnos/workspaces/${workspace}/env using ${result.mode}${skippedSuffix}`;
+}
+
+// src/format/printValue.ts
+function printValue(value, json = false) {
+  if (json) {
+    return printJson(value);
+  }
+  if (typeof value === "string") {
+    return value;
+  }
+  if (value === void 0 || value === null || typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+    return String(value);
+  }
+  return printJson(value);
+}
+
+// src/commands/read.ts
+async function runRead(key, options = {}) {
+  const runtime = await createRuntimeService(options);
+  const value = runtime.read(key);
+  if (value === void 0) {
+    throw new Error(`Missing CNOS config key: ${key}`);
+  }
+  if (options.json) {
+    return printJson({ key, value });
+  }
+  return printValue(value);
+}
+
+// src/commands/run.ts
+import { spawn } from "child_process";
+async function runCommand(command, options = {}) {
+  if (command.length === 0) {
+    throw new Error("run requires a command after --");
+  }
+  const runtime = await createRuntimeService(options);
+  const env = {
+    ...process.env,
+    ...runtime.toEnv()
+  };
+  return new Promise((resolve, reject) => {
+    const executable = command[0];
+    if (!executable) {
+      reject(new Error("run requires a command after --"));
+      return;
+    }
+    const child = spawn(executable, command.slice(1), {
+      cwd: options.root ?? process.cwd(),
+      env,
+      stdio: options.stdio === "pipe" ? "pipe" : "inherit",
+      shell: false
+    });
+    let stdout = "";
+    let stderr = "";
+    if (options.stdio === "pipe") {
+      child.stdout?.on("data", (chunk) => {
+        stdout += chunk.toString();
+      });
+      child.stderr?.on("data", (chunk) => {
+        stderr += chunk.toString();
+      });
+    }
+    child.on("error", reject);
+    child.on("close", (code) => {
+      resolve({
+        exitCode: code ?? 1,
+        stdout,
+        stderr
+      });
+    });
+  });
+}
+
+// src/commands/secret.ts
+async function runSecret(path6, options = {}) {
+  const runtime = await createRuntimeService(options);
+  const value = runtime.secret(path6);
+  if (value === void 0) {
+    throw new Error(`Missing CNOS secret path: ${path6}`);
+  }
+  if (options.json) {
+    return printJson({
+      key: `secret.${path6}`,
+      value
+    });
+  }
+  return printValue(value);
+}
+
+// src/commands/validate.ts
+async function runValidate(options = {}) {
+  const { summary } = await createValidationSummary(options);
+  if (!summary.valid) {
+    process.exitCode = 1;
+  }
+  if (options.json) {
+    return printJson(summary);
+  }
+  return summary.valid ? "validation passed" : summary.issues.map((issue) => `${issue.code}: ${issue.message}`).join("\n");
+}
+
+// src/commands/value.ts
+async function runValue(path6, options = {}) {
+  const runtime = await createRuntimeService(options);
+  const value = runtime.value(path6);
+  if (value === void 0) {
+    throw new Error(`Missing CNOS value path: ${path6}`);
+  }
+  if (options.json) {
+    return printJson({
+      key: `value.${path6}`,
+      value
+    });
+  }
+  return printValue(value);
+}
+
+// src/index.ts
+function resolveHelpTopic(command, args) {
+  if (command === "help" || command === "help-ai") {
+    return normalizeHelpTopic(args);
+  }
+  if (command === "export" && args[0] === "env") {
+    return normalizeHelpTopic([command, args[0]]);
+  }
+  return normalizeHelpTopic([command]);
+}
+async function main(argv) {
+  const { command, args, options, passthrough } = parseArgs(argv);
+  if (options.help) {
+    process.stdout.write(`${runHelp(resolveHelpTopic(command, args))}
+`);
+    return;
+  }
+  const runtimeOptions = {
+    ...options.root ? {
+      root: options.root
+    } : {},
+    ...options.workspace ? {
+      workspace: options.workspace
+    } : {},
+    ...options.profile ? {
+      profile: options.profile
+    } : {},
+    ...options.globalRoot ? {
+      globalRoot: options.globalRoot
+    } : {},
+    ...options.json ? {
+      json: true
+    } : {},
+    ...options.cliArgs.length > 0 ? {
+      cliArgs: options.cliArgs
+    } : {}
+  };
+  switch (command) {
+    case "help":
+      process.stdout.write(`${runHelp(resolveHelpTopic(command, args))}
+`);
+      return;
+    case "help-ai":
+      process.stdout.write(`${runHelpAi(resolveHelpTopic(command, args), options.cliArgs)}
+`);
+      return;
+    case "init":
+      process.stdout.write(`${await runInit(runtimeOptions)}
+`);
+      return;
+    case "onboard":
+      process.stdout.write(`${await runOnboard(runtimeOptions)}
+`);
+      return;
+    case "read":
+      process.stdout.write(`${await runRead(args[0] ?? "value.app.name", runtimeOptions)}
+`);
+      return;
+    case "value":
+      process.stdout.write(`${await runValue(args[0] ?? "app.name", runtimeOptions)}
+`);
+      return;
+    case "secret":
+      process.stdout.write(`${await runSecret(args[0] ?? "app.token", runtimeOptions)}
+`);
+      return;
+    case "define":
+      process.stdout.write(
+        `${await runDefine(args[0] ?? "value", args[1] ?? "app.name", args[2] ?? "", runtimeOptions)}
+`
+      );
+      return;
+    case "inspect":
+      process.stdout.write(`${await runInspect(args[0] ?? "meta.profile", runtimeOptions)}
+`);
+      return;
+    case "validate":
+      process.stdout.write(`${await runValidate(runtimeOptions)}
+`);
+      return;
+    case "export":
+      process.stdout.write(`${await runExport(args[0], runtimeOptions)}
+`);
+      return;
+    case "dump":
+      process.stdout.write(`${await runDump(runtimeOptions)}
+`);
+      return;
+    case "run": {
+      const result = await runCommand(passthrough.length > 0 ? passthrough : args, {
+        ...runtimeOptions,
+        stdio: "inherit"
+      });
+      process.exitCode = result.exitCode;
+      return;
+    }
+    case "diff":
+      process.stdout.write(`${await runDiff(args[0] ?? "local", args[1] ?? "stage", runtimeOptions)}
+`);
+      return;
+    case "doctor":
+      process.stdout.write(`${await runDoctor(runtimeOptions)}
+`);
+      return;
+    default:
+      process.stderr.write(`Unknown command: ${command}
+`);
+      process.exitCode = 1;
+  }
+}
+void main(process.argv.slice(2));
+export {
+  main
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@kitsy/cnos-cli",
+  "version": "0.0.1",
+  "description": "CLI entry point and developer tooling for CNOS.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "cnos": "./dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kitsyai/cnos.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/kitsyai/cnos/tree/main/packages/cli",
+  "bugs": {
+    "url": "https://github.com/kitsyai/cnos/issues"
+  },
+  "keywords": [
+    "cnos",
+    "cli",
+    "config"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@kitsy/cnos": "0.0.1",
+    "@kitsy/cnos-core": "0.0.1"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "clean": "rimraf dist",
+    "dev": "tsup src/index.ts --watch --format esm --dts",
+    "lint": "eslint src test",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}