code-workspace-zhuiyi 0.1.0-beta.1

package/src/cli/commands/update.js

@@ -0,0 +1,146 @@
+const path = require("node:path");
+
+const { cleanupObsoleteAssets, planObsoleteAssets } = require("../../core/assets");
+const {
+  configPath,
+  loadConfig,
+  loadState,
+  saveConfig,
+  statePath,
+} = require("../../core/config");
+const { WorkspaceError } = require("../../core/errors");
+const { commitUpdateState, loadInitManifest } = require("../../core/init");
+const { workspaceGuide } = require("../../core/language");
+const { inspectManagedFiles, installManagedFiles, planManagedFiles } = require("../../core/managed-files");
+const { planWorkspaceMaintenance } = require("../../core/migration");
+const { inspectProjectPermissions } = require("../../core/permissions");
+const { resolveWorkspaceTools } = require("../../core/tools");
+const { createFileTransaction } = require("../../core/transaction");
+const { success } = require("../result");
+const { migrationData } = require("./init");
+
+function verifyUpdatedManagedFiles(root, manifest, tools, capabilities, variables) {
+  const inspection = inspectManagedFiles(root, manifest, tools, capabilities, variables);
+  const incomplete = [
+    ...inspection.managedOld.map((target) => ({ target, state: "managed-old" })),
+    ...inspection.replaceable.map((target) => ({ target, state: "replaceable" })),
+    ...inspection.missing.map((target) => ({ target, state: "missing" })),
+    ...inspection.unknown.map((target) => ({ target, state: "unknown" })),
+  ];
+  if (incomplete.length > 0) {
+    throw new WorkspaceError(
+      "UPDATE_POSTCONDITION_FAILED",
+      `Updated managed files failed verification: ${incomplete.map((entry) => `${entry.target} (${entry.state})`).join(", ")}`,
+      { files: incomplete, remediation: "Run code-w doctor --json, review the reported files, and retry update." }
+    );
+  }
+  return inspection;
+}
+
+function updateWorkspace(root, options = {}) {
+  const manifest = loadInitManifest();
+  const initialState = loadState(root);
+  if (!initialState) {
+    throw new WorkspaceError(
+      "UPDATE_STATE_MISSING",
+      "Local initialization state is missing; update can only run on an initialized workspace.",
+      { file: statePath(root), remediation: "Re-run code-w init . --yes before updating this workspace." }
+    );
+  }
+  const toolSelection = resolveWorkspaceTools({
+    explicit: options.tools,
+    state: initialState,
+    manifestTools: manifest.tools,
+  });
+  const tools = toolSelection.tools;
+  const migration = planWorkspaceMaintenance(root, {
+    language: options.language,
+    allowLegacy: true,
+    defaultLanguage: false,
+  });
+  const language = migration.language.value;
+  const config = loadConfig(root, { defaultLanguage: language });
+  const nextConfig = { ...config, workspace: { ...config.workspace, language } };
+  const capabilities = nextConfig.monitor.enable ? ["monitor"] : [];
+  const variables = { WORKSPACE_LANGUAGE: language, WORKSPACE_USER_GUIDE: workspaceGuide(language) };
+  let managedPlan;
+  let obsoletePlan;
+  try {
+    managedPlan = planManagedFiles(root, manifest, tools, {
+      force: options.force === true,
+      capabilities,
+      variables,
+    });
+    obsoletePlan = planObsoleteAssets(root, tools, { force: options.force === true });
+  } catch (error) {
+    if (options.language && /unknown changes/.test(error.message)) {
+      throw new WorkspaceError("MANAGED_FILE_UNKNOWN", `${error.message}. No configuration or artifacts were changed.`, {
+        remediation: `Review the file or re-run code-w update --language ${language} --force.`,
+      });
+    }
+    throw error;
+  }
+  const transaction = createFileTransaction([
+    configPath(root),
+    statePath(root),
+    ...managedPlan.plans.map((plan) => plan.target),
+    ...obsoletePlan.map((plan) => path.join(root, plan.target)),
+  ]);
+  try {
+    const obsoleteFiles = cleanupObsoleteAssets(root, tools, { force: options.force === true });
+    options.injectFailure?.("after-obsolete-cleanup", obsoleteFiles);
+    const managedFiles = installManagedFiles(root, manifest, tools, {
+      force: options.force === true,
+      capabilities,
+      variables,
+    });
+    options.injectFailure?.("after-managed-install", managedFiles);
+    saveConfig(root, nextConfig);
+    options.injectFailure?.("after-config-save", nextConfig);
+    verifyUpdatedManagedFiles(root, manifest, tools, capabilities, variables);
+    const result = {
+      language,
+      tools: toolSelection,
+      migration: migrationData(migration),
+      obsoleteFiles,
+      managedFiles,
+      forcedUnknown: managedPlan.plans.filter((plan) => plan.reason === "unknown").map((plan) => plan.entry.target),
+      diagnostics: [],
+    };
+    const previousTools = new Set(initialState.tools || []);
+    const addedTools = tools.filter((tool) => !previousTools.has(tool));
+    if (addedTools.length > 0 && nextConfig.projects.length > 0) {
+      for (const inspection of inspectProjectPermissions({ root, tools: addedTools, projects: nextConfig.projects })) {
+        if (inspection.missing.length === 0) continue;
+        result.diagnostics.push({
+          code: "WORKSPACE_PERMISSION_APPLY_REQUIRED",
+          severity: "warning",
+          message: `${inspection.tool} is selected but lacks authorization for ${inspection.missing.length} registered project director${inspection.missing.length === 1 ? "y" : "ies"}.`,
+          tool: inspection.tool,
+          directories: inspection.missing,
+          file: inspection.target,
+          remediation: "Review and run code-w permissions apply --yes.",
+        });
+      }
+    }
+    options.injectFailure?.("after-verify", result);
+    const state = commitUpdateState(root, manifest, {
+      tools,
+      removeLegacyWorkspaceLanguage: true,
+    });
+    options.injectFailure?.("after-state-save", state);
+    transaction.commit();
+    return result;
+  } catch (error) {
+    transaction.rollback(error);
+    throw error;
+  }
+}
+
+function executeUpdate(invocation) {
+  const result = updateWorkspace(invocation.root, invocation.options);
+  const written = result.managedFiles.filter((entry) => entry.action === "write").length;
+  return success("update", result, `Updated Code Workspace assets (${written} written). Tools: ${result.tools.tools.join(", ") || "none"} (${result.tools.source}).`, result.diagnostics);
+}
+
+module.exports = { executeUpdate, updateWorkspace };

package/src/cli/commands/workspace.js

@@ -0,0 +1,24 @@
+const { loadInitManifest } = require("../../core/init");
+const { doctorWorkspace } = require("../../core/doctor");
+const { getLocale } = require("../../i18n");
+const { fromDiagnostics, success } = require("../result");
+
+function executeLanguage(invocation) {
+  const language = invocation.config.workspace.language;
+  const locale = getLocale(language);
+  return success("language", { language, label: locale.label, projectContext: locale.projectContext }, language);
+}
+
+function executeDoctor(invocation) {
+  const output = doctorWorkspace(invocation.root, loadInitManifest());
+  return fromDiagnostics("doctor", output, {
+    projects: output.config.projects.length,
+    tools: output.toolSelection,
+    capabilities: output.capabilities,
+  }, `Code Workspace is healthy (${output.config.projects.length} local projects).`);
+}
+
+module.exports = {
+  executeDoctor,
+  executeLanguage,
+};

package/src/cli/confirmation.js

@@ -0,0 +1,22 @@
+const readline = require("node:readline/promises");
+
+const { WorkspaceError } = require("../core/errors");
+
+async function confirm(message, options = {}) {
+  if (options.yes === true) return true;
+  if (options.json || !process.stdin.isTTY) {
+    throw new WorkspaceError(
+      "CLI_CONFIRMATION_REQUIRED",
+      `${message} Re-run with --yes to confirm non-interactively.`,
+      { remediation: "Re-run the command with --yes." }
+    );
+  }
+  const input = readline.createInterface({ input: options.input || process.stdin, output: options.output || process.stdout });
+  try {
+    return /^y(?:es)?$/i.test((await input.question(`${message} [y/N] `)).trim());
+  } finally {
+    input.close();
+  }
+}
+
+module.exports = { confirm };

package/src/cli/parser.js

@@ -0,0 +1,108 @@
+const { WorkspaceError } = require("../core/errors");
+const { COMMANDS, GLOBAL_OPTIONS, getCommand } = require("./registry");
+
+const aliasEntries = Object.entries(GLOBAL_OPTIONS).flatMap(([name, definition]) =>
+  (definition.aliases || []).map((alias) => [alias, name])
+);
+
+function optionName(token) {
+  if (token === "-p") return "p";
+  if (!token.startsWith("--") || token === "--") return null;
+  return token.slice(2).split("=", 1)[0];
+}
+
+function commandCandidates(first) {
+  return COMMANDS.filter((command) => command.path[0] === first).sort((left, right) => right.path.length - left.path.length);
+}
+
+function resolveCommand(tokens) {
+  let index = 0;
+  const leadingOptions = {};
+  while (index < tokens.length && optionName(tokens[index])) {
+    const token = tokens[index];
+    const rawName = optionName(token);
+    const name = new Map(aliasEntries).get(rawName) || rawName;
+    const definition = GLOBAL_OPTIONS[name];
+    if (!definition) throw new WorkspaceError("CLI_UNKNOWN_OPTION", `Unknown global option: ${token.split("=")[0]}`, { option: rawName });
+    if (token.includes("=")) throw new WorkspaceError("CLI_INVALID_OPTION_VALUE", `Boolean option --${name} does not accept a value`, { option: name });
+    leadingOptions[name] = true;
+    index += 1;
+  }
+  if (index >= tokens.length) return { command: null, index, leadingOptions };
+  const candidates = commandCandidates(tokens[index]);
+  const command = candidates.find((candidate) => candidate.path.every((part, offset) => tokens[index + offset] === part));
+  if (!command) throw new WorkspaceError("CLI_UNKNOWN_COMMAND", `Unknown command: ${tokens[index]}`, { command: tokens[index] });
+  return { command, index: index + command.path.length, leadingOptions };
+}
+
+function parseOption(token, definitions, tokens, index) {
+  const rawName = optionName(token);
+  const aliases = Object.entries(definitions).flatMap(([name, definition]) => (definition.aliases || []).map((alias) => [alias, name]));
+  const name = new Map(aliases).get(rawName) || rawName;
+  const definition = definitions[name];
+  if (!definition) throw new WorkspaceError("CLI_UNKNOWN_OPTION", `Unknown option for this command: ${token.split("=")[0]}`, { option: rawName });
+  const equal = token.indexOf("=");
+  if (definition.type === "boolean") {
+    if (equal >= 0) throw new WorkspaceError("CLI_INVALID_OPTION_VALUE", `Boolean option --${name} does not accept a value`, { option: name });
+    return { name, value: true, next: index + 1 };
+  }
+  const value = equal >= 0 ? token.slice(equal + 1) : tokens[index + 1];
+  if (!value || (equal < 0 && value.startsWith("-"))) {
+    throw new WorkspaceError("CLI_OPTION_VALUE_REQUIRED", `--${name} requires a value`, { option: name });
+  }
+  return { name, value, next: equal >= 0 ? index + 1 : index + 2 };
+}
+
+function parse(argv) {
+  const tokens = argv.slice(2);
+  const resolved = resolveCommand(tokens);
+  if (!resolved.command) return { command: null, positionals: [], args: [], options: resolved.leadingOptions };
+  try {
+    const definitions = { ...GLOBAL_OPTIONS, ...resolved.command.options };
+    const options = { ...resolved.leadingOptions };
+    const args = [];
+    let positionalOnly = false;
+    for (let index = resolved.index; index < tokens.length;) {
+      const token = tokens[index];
+      if (token === "--") {
+        positionalOnly = true;
+        index += 1;
+        continue;
+      }
+      if (!positionalOnly && token.startsWith("-")) {
+        const parsed = parseOption(token, definitions, tokens, index);
+        if (Object.prototype.hasOwnProperty.call(options, parsed.name)) {
+          throw new WorkspaceError("CLI_DUPLICATE_OPTION", `Option provided more than once: --${parsed.name}`, { option: parsed.name });
+        }
+        options[parsed.name] = parsed.value;
+        index = parsed.next;
+        continue;
+      }
+      args.push(token);
+      index += 1;
+    }
+    const required = resolved.command.args.filter((argument) => argument.required).length;
+    if (!options.help && args.length < required) {
+      const missing = resolved.command.args[args.length]?.name || "argument";
+      throw new WorkspaceError("CLI_ARGUMENT_REQUIRED", `${resolved.command.path.join(" ")} requires <${missing}>`, { argument: missing });
+    }
+    const variadic = resolved.command.args.at(-1)?.variadic === true;
+    if (!options.help && !variadic && args.length > resolved.command.args.length) {
+      throw new WorkspaceError("CLI_EXTRA_ARGUMENT", `Unexpected argument for ${resolved.command.path.join(" ")}: ${args[resolved.command.args.length]}`, { argument: args[resolved.command.args.length] });
+    }
+    return {
+      command: resolved.command,
+      args,
+      options,
+      positionals: [...resolved.command.path, ...args],
+    };
+  } catch (error) {
+    error.details = {
+      ...(error.details || {}),
+      command: resolved.command.path.join("."),
+    };
+    throw error;
+  }
+}
+
+module.exports = { parse, resolveCommand };

package/src/cli/registry.js

@@ -0,0 +1,108 @@
+const GLOBAL_OPTIONS = {
+  help: { type: "boolean" },
+  version: { type: "boolean" },
+  json: { type: "boolean" },
+};
+
+const COMMAND_SUMMARIES = {
+  init: "Initialize workspace (path defaults to current directory)",
+  monitor: "Run the global multi-workspace Agent monitor",
+  update: "Update Workspace-owned managed assets",
+  language: "Print the workspace language",
+  "project inspect": "Inspect a Git project without writing files",
+  "project add": "Register a project (low-level skill command)",
+  "project remove": "Remove a local project",
+  "project branch inspect": "Inspect selected projects' registered and actual branches",
+  "project branch verify": "Verify selected projects' registered and actual branches match",
+  "project branch accept-actual": "Update selected registered branches from actual branches",
+  "project branch use-registered": "Switch selected project worktrees to registered branches",
+  "project branch update-latest": "Update selected enabled project branches to their latest upstream commits",
+  "project list": "List local projects",
+  "project show": "Show one local project",
+  "project verify": "Validate all local projects or selected projects",
+  "permissions apply": "Apply registered project directory authorization",
+  "extension install": "Install one or more built-in extensions into the Workspace",
+  "extension uninstall": "Uninstall one built-in extension from the Workspace",
+  doctor: "Report workspace health",
+  completion: "Print shell completion script",
+};
+
+const COMMANDS = [
+  { path: ["init"], args: [{ name: "path", required: false }], workspace: "target", config: [], interaction: "optional", effects: "planned-write", options: {
+    tools: { type: "string" }, extensions: { type: "string" }, "workspace-name": { type: "string" }, language: { type: "string" },
+    monitor: { type: "boolean" }, "no-monitor": { type: "boolean" }, "monitor-url": { type: "string" }, yes: { type: "boolean" }, force: { type: "boolean" },
+  } },
+  { path: ["monitor"], args: [], workspace: "none", config: [], interaction: "never", effects: "external", options: { port: { type: "string", aliases: ["p"] } } },
+  { path: ["monitor", "report"], args: [], workspace: "optional", config: ["identity", "monitor"], interaction: "never", effects: "external", options: {} },
+  { path: ["update"], args: [], workspace: "required", config: [], interaction: "optional", effects: "planned-write", options: {
+    tools: { type: "string" }, language: { type: "string" }, force: { type: "boolean" },
+  } },
+  { path: ["language"], args: [], workspace: "required", config: ["language"], interaction: "never", effects: "read-only", options: {} },
+  { path: ["project", "inspect"], args: [{ name: "path", required: true }], workspace: "none", config: [], interaction: "never", effects: "read-only", options: {} },
+  { path: ["project", "add"], args: [{ name: "path", required: false }], workspace: "required", config: ["complete"], interaction: "required", effects: "planned-write", options: {
+    "project-file": { type: "string" }, "projects-file": { type: "string" }, name: { type: "string" }, type: { type: "string" },
+    context: { type: "string" }, "context-file": { type: "string" }, yes: { type: "boolean" },
+  } },
+  { path: ["project", "remove"], args: [{ name: "name", required: true }], workspace: "required", config: ["complete"], interaction: "required", effects: "planned-write", options: { yes: { type: "boolean" } } },
+  { path: ["project", "branch", "inspect"], args: [{ name: "name", required: true, variadic: true }], workspace: "required", config: ["projects"], interaction: "never", effects: "read-only", options: {} },
+  { path: ["project", "branch", "verify"], args: [{ name: "name", required: true, variadic: true }], workspace: "required", config: ["projects"], interaction: "never", effects: "read-only", options: {} },
+  { path: ["project", "branch", "accept-actual"], args: [{ name: "name", required: true, variadic: true }], workspace: "required", config: ["projects"], interaction: "required", effects: "planned-write", options: { yes: { type: "boolean" } } },
+  { path: ["project", "branch", "use-registered"], args: [{ name: "name", required: true, variadic: true }], workspace: "required", config: ["projects"], interaction: "required", effects: "external", options: { yes: { type: "boolean" }, "allow-remote": { type: "boolean" }, remote: { type: "string" } } },
+  { path: ["project", "branch", "update-latest"], args: [{ name: "name", required: true, variadic: true }], workspace: "required", config: ["projects"], interaction: "never", effects: "external", options: {} },
+  { path: ["project", "list"], args: [], workspace: "required", config: ["projects"], interaction: "never", effects: "read-only", options: {} },
+  { path: ["project", "show"], args: [{ name: "name", required: false }], workspace: "required", config: ["projects"], interaction: "never", effects: "read-only", options: { name: { type: "string" } } },
+  { path: ["project", "verify"], args: [{ name: "name", required: false, variadic: true }], workspace: "required", config: ["projects"], interaction: "never", effects: "read-only", options: {} },
+  { path: ["permissions", "apply"], args: [], workspace: "required", config: ["projects"], interaction: "required", effects: "planned-write", options: {
+    tools: { type: "string" }, yes: { type: "boolean" },
+  } },
+  { path: ["extension", "install"], args: [{ name: "name", required: false, variadic: true }], workspace: "required", config: ["identity", "language"], interaction: "required", effects: "planned-write", options: { yes: { type: "boolean" } } },
+  { path: ["extension", "uninstall"], args: [{ name: "name", required: true }], workspace: "required", config: [], interaction: "required", effects: "planned-write", options: { yes: { type: "boolean" } } },
+  { path: ["doctor"], args: [], workspace: "required", config: ["complete"], interaction: "never", effects: "read-only", options: {} },
+  { path: ["completion"], args: [], workspace: "none", config: [], interaction: "never", effects: "read-only", options: { shell: { type: "string" } } },
+  { path: ["help"], args: [], workspace: "none", config: [], interaction: "never", effects: "read-only", options: {} },
+  { path: ["version"], args: [], workspace: "none", config: [], interaction: "never", effects: "read-only", options: {} },
+];
+
+const byPath = new Map(COMMANDS.map((command) => [command.path.join(" "), Object.freeze(command)]));
+
+function getCommand(path) {
+  return byPath.get(Array.isArray(path) ? path.join(" ") : String(path || "")) || null;
+}
+
+function commandHelpRows() {
+  return COMMANDS
+    .filter((command) => COMMAND_SUMMARIES[command.path.join(" ")])
+    .map((command) => ({
+      usage: [
+        ...command.path,
+        ...command.args.map((argument) => {
+          const name = `${argument.name}${argument.variadic ? "..." : ""}`;
+          return argument.required ? `<${name}>` : `[${name}]`;
+        }),
+      ].join(" "),
+      summary: COMMAND_SUMMARIES[command.path.join(" ")],
+      command,
+    }));
+}
+
+function validateCommandReference(reference) {
+  const tokens = [];
+  const input = String(reference || "").trim();
+  const pattern = /"([^"\\]*(?:\\.[^"\\]*)*)"|'([^'\\]*(?:\\.[^'\\]*)*)'|([^\s]+)/g;
+  for (const match of input.matchAll(pattern)) tokens.push(match[1] ?? match[2] ?? match[3]);
+  if (tokens.length === 0) return { valid: false, reason: "empty command reference" };
+  const normalized = tokens.map((token) => /^<[^>]+>$/.test(token) ? "placeholder" : token);
+  try {
+    const parsed = require("./parser").parse([process.execPath, "code-workspace", ...normalized]);
+    return {
+      valid: true,
+      command: parsed.command,
+      options: Object.keys(parsed.options),
+      args: parsed.args,
+    };
+  } catch (error) {
+    return { valid: false, reason: `${error.code || "CLI_ERROR"}: ${error.message}` };
+  }
+}
+
+module.exports = { COMMANDS: Object.freeze(COMMANDS), GLOBAL_OPTIONS: Object.freeze(GLOBAL_OPTIONS), commandHelpRows, getCommand, validateCommandReference };

package/src/cli/renderer.js

@@ -0,0 +1,20 @@
+const { jsonEnvelope } = require("./result");
+
+function renderResult(result, options = {}) {
+  const stdout = options.stdout || process.stdout;
+  const stderr = options.stderr || process.stderr;
+  if (options.json) {
+    stdout.write(`${JSON.stringify(jsonEnvelope(result), null, 2)}\n`);
+  } else {
+    for (const diagnostic of result.diagnostics) {
+      const stream = diagnostic.severity === "warning" ? stderr : diagnostic.severity === "error" ? stderr : stdout;
+      stream.write(`${diagnostic.severity === "warning" ? "WARN" : diagnostic.severity === "error" ? "ERROR" : "INFO"} ${diagnostic.message}\n`);
+      if (diagnostic.remediation) stream.write(`REMEDIATION ${diagnostic.remediation}\n`);
+    }
+    if (result.text && (result.ok || result.renderTextOnError)) stdout.write(result.text.endsWith("\n") ? result.text : `${result.text}\n`);
+  }
+  if (!result.ok) process.exitCode = 1;
+  return result;
+}
+
+module.exports = { renderResult };

package/src/cli/result.js

@@ -0,0 +1,118 @@
+const { WorkspaceError } = require("../core/errors");
+
+const RESULT_SCHEMA_VERSION = 1;
+
+function commandName(command) {
+  if (Array.isArray(command)) return command.join(".");
+  return command ? String(command) : null;
+}
+
+function normalizeDiagnostic(entry) {
+  if (!entry || typeof entry !== "object") {
+    return { code: "CLI_DIAGNOSTIC_INVALID", severity: "error", message: String(entry) };
+  }
+  const { code, severity, message, details, ...rest } = entry;
+  return {
+    code: code || "CLI_ERROR",
+    severity: severity || "error",
+    message: message || "Unknown command diagnostic",
+    ...rest,
+    ...(details && typeof details === "object" ? details : {}),
+  };
+}
+
+function commandResult(command, data = null, options = {}) {
+  const diagnostics = (options.diagnostics || []).map(normalizeDiagnostic);
+  const ok = options.ok ?? !diagnostics.some((entry) => entry.severity === "error");
+  return {
+    schemaVersion: RESULT_SCHEMA_VERSION,
+    ok,
+    command: commandName(command),
+    data: data ?? null,
+    diagnostics,
+    text: options.text || "",
+    renderTextOnError: options.renderTextOnError === true,
+  };
+}
+
+function success(command, data = null, text = "", diagnostics = []) {
+  return commandResult(command, data, { ok: true, text, diagnostics });
+}
+
+function fromDiagnostics(command, output, data = null, text = "") {
+  return commandResult(command, data, {
+    ok: !output.diagnostics.some((entry) => entry.severity === "error"),
+    diagnostics: output.diagnostics,
+    text,
+  });
+}
+
+function failure(error, command = null) {
+  const source = error instanceof Error ? error : new WorkspaceError("CLI_ERROR", String(error));
+  return commandResult(command, null, {
+    ok: false,
+    diagnostics: [{
+      code: source.code || "CLI_ERROR",
+      severity: "error",
+      message: source.message,
+      details: source.details,
+    }],
+  });
+}
+
+function diagnosticFromError(error, details = {}) {
+  const source = error instanceof Error ? error : new WorkspaceError("CLI_ERROR", String(error));
+  return normalizeDiagnostic({
+    code: source.code || "CLI_ERROR",
+    severity: "error",
+    message: source.message,
+    details: {
+      ...details,
+      ...(source.details || {}),
+    },
+  });
+}
+
+function selectionResult(command, requested, results, options = {}) {
+  const diagnostics = options.diagnostics || [];
+  const summary = {
+    total: results.length,
+    succeeded: results.filter((entry) => entry.ok && entry.action !== "skip").length,
+    skipped: results.filter((entry) => entry.ok && entry.action === "skip").length,
+    failed: results.filter((entry) => !entry.ok).length,
+  };
+  return commandResult(command, {
+    scope: "selection",
+    requested,
+    results,
+    summary,
+  }, {
+    ok: summary.failed === 0 && !diagnostics.some((entry) => (entry.severity || "error") === "error"),
+    diagnostics,
+    text: options.text || "",
+    renderTextOnError: true,
+  });
+}
+
+function jsonEnvelope(result) {
+  return {
+    schemaVersion: result.schemaVersion,
+    ok: result.ok,
+    command: result.command,
+    data: result.data,
+    diagnostics: result.diagnostics,
+  };
+}
+
+module.exports = {
+  RESULT_SCHEMA_VERSION,
+  commandName,
+  commandResult,
+  diagnosticFromError,
+  failure,
+  fromDiagnostics,
+  jsonEnvelope,
+  normalizeDiagnostic,
+  selectionResult,
+  success,
+};

package/src/cli.js

@@ -0,0 +1,76 @@
+const { loadConfigProjection, requireWorkspaceRoot } = require("./core/config");
+const { normalizeTools } = require("./core/tools");
+const { WorkspaceError } = require("./core/errors");
+const { parse } = require("./cli/parser");
+const { failure } = require("./cli/result");
+const { executeCompletion } = require("./cli/commands/completion");
+const { executeHelp, executeVersion } = require("./cli/commands/help");
+const { executeInit } = require("./cli/commands/init");
+const { executeExtension } = require("./cli/commands/extension");
+const { executeMonitor, readStdinJson } = require("./cli/commands/monitor");
+const { executePermissions } = require("./cli/commands/permissions");
+const { executeProject } = require("./cli/commands/project");
+const { executeProjectBranch } = require("./cli/commands/project-branch");
+const { executeProjectBranchUpdateLatest } = require("./cli/commands/project-branch-update");
+const { executeUpdate, updateWorkspace } = require("./cli/commands/update");
+const {
+  executeDoctor,
+  executeLanguage,
+} = require("./cli/commands/workspace");
+
+async function dispatch(invocation) {
+  const key = invocation.definition.path.join(" ");
+  if (key === "init") return executeInit(invocation);
+  if (key.startsWith("extension ")) return executeExtension(invocation);
+  if (key === "monitor" || key === "monitor report") return executeMonitor(invocation);
+  if (key === "project branch update-latest") return executeProjectBranchUpdateLatest(invocation);
+  if (key.startsWith("project branch ")) return executeProjectBranch(invocation);
+  if (key.startsWith("project ")) return executeProject(invocation);
+  if (key === "update") return executeUpdate(invocation);
+  if (key === "language") return executeLanguage(invocation);
+  if (key === "permissions apply") return executePermissions(invocation);
+  if (key === "doctor") return executeDoctor(invocation);
+  if (key === "completion") return executeCompletion(invocation);
+  if (key === "help") return executeHelp();
+  if (key === "version") return executeVersion();
+  throw Object.assign(new Error(`No handler is registered for command: ${key}`), { code: "CLI_HANDLER_MISSING" });
+}
+
+async function main(argv) {
+  let command = null;
+  try {
+    const parsed = parse(argv);
+    command = parsed.command?.path || null;
+    if (parsed.options.version || parsed.command?.path[0] === "version") return executeVersion();
+    if (parsed.options.help || !parsed.command || parsed.command.path[0] === "help") return executeHelp();
+    const root = parsed.command.workspace === "required" ? requireWorkspaceRoot(process.cwd()) : process.cwd();
+    const config = parsed.command.config.length > 0 && parsed.command.path[0] !== "doctor"
+      ? loadConfigProjection(root, parsed.command.config)
+      : null;
+    return await dispatch({
+      definition: parsed.command,
+      args: parsed.args,
+      options: parsed.options,
+      root,
+      config,
+    });
+  } catch (error) {
+    if (error.code !== "CLI_UNKNOWN_COMMAND") command ||= error.details?.command || null;
+    if (!error.code && command) {
+      const commandText = Array.isArray(command) ? command.join("_") : String(command).replace(/\./g, "_");
+      const code = `${commandText.replace(/[^a-z0-9_]/gi, "_").toUpperCase()}_FAILED`;
+      error = new WorkspaceError(code, error.message, { cause: error.name });
+    }
+    return failure(error, command);
+  }
+}
+
+function toolsOption(value) {
+  return value === undefined ? ["claude", "codex"] : normalizeTools(value, "cli");
+}
+
+async function monitorCommand(action, options = {}) {
+  return executeMonitor({ definition: { path: action ? ["monitor", action] : ["monitor"] }, options });
+}
+
+module.exports = { dispatch, main, monitorCommand, parse, readStdinJson, toolsOption, updateWorkspace };