code-workspace-zhuiyi 0.1.0-beta.1

package/src/cli/commands/extension.js

@@ -0,0 +1,193 @@
+const { loadState } = require("../../core/config");
+const { WorkspaceError } = require("../../core/errors");
+const {
+  applyExtensionUninstall,
+  discoverExtensions,
+  inspectExtensionState,
+  normalizeExtensionNames,
+  planExtensionUninstall,
+  prepareExtensionPlans,
+  runExtensionBatch,
+} = require("../../core/extensions");
+const { loadInitManifest } = require("../../core/init");
+const { acquireInitLock } = require("../../core/init-lock");
+const { resolveWorkspaceTools } = require("../../core/tools");
+const { createInteractiveUi } = require("../../init/ui");
+const { confirm } = require("../confirmation");
+const { selectionResult, success } = require("../result");
+
+function formatUninstallPlan(plan) {
+  if (plan.action === "skip") return `Extension ${plan.id} is not installed.`;
+  return [
+    `Uninstall extension ${plan.id}@${plan.version}:`,
+    ...plan.targets.map((target) => `  REMOVE ${target}`),
+    "  REMOVE .code-workspace/ext-manifest.json entry",
+  ].join("\n");
+}
+
+function formatInstallPlan(plans) {
+  return [
+    `Install ${plans.length} extension${plans.length === 1 ? "" : "s"}:`,
+    ...plans.flatMap((plan) => [
+      `  ${plan.id}@${plan.version} [Extension Spec ${plan.extensionSpecVersion}] (manifest ${plan.manifestSha256})`,
+      ...(plan.capabilities.networkHosts || []).map((host) => `    NETWORK https://${host}`),
+      ...plan.artifacts.map((artifact) => `    WRITE ${artifact.target} (${artifact.kind})`),
+    ]),
+  ].join("\n");
+}
+
+async function collectExtensionInstallSelection(catalog, state, options = {}) {
+  const ui = options.ui || await createInteractiveUi({
+    ...options,
+    cancelCode: "EXTENSION_INSTALL_CANCELLED",
+    cancelMessage: "Extension installation cancelled. No changes were made.",
+  });
+  const installed = new Set(Object.entries(state.extensions || {}).filter(([, value]) => value.installed).map(([id]) => id));
+  const choices = catalog.map((entry) => ({
+    value: entry.id,
+    label: `${entry.id} · ${entry.name} · ${entry.latestSupported ? `latest supported: ${entry.latestSupported.version} · Extension Spec ${entry.latestSupported.extensionSpecVersion}` : "no supported Extension Spec"}${installed.has(entry.id) ? " · installed" : ""}`,
+    ...(entry.latestSupported ? {} : { disabled: true }),
+  }));
+  ui.intro("Code Workspace extensions");
+  if (choices.length === 0) {
+    ui.close("No built-in extensions are available.");
+    return [];
+  }
+  const selected = await ui.multiselect("Extensions (select any)", choices, []);
+  ui.close(selected.length > 0 ? "Extension selection ready." : "No extensions selected.");
+  return normalizeExtensionNames(selected);
+}
+
+function installResultEntry(entry) {
+  const failed = entry.status === "failed";
+  return {
+    name: entry.id,
+    ok: !failed,
+    action: entry.status === "skipped" ? "skip" : "install",
+    status: entry.status,
+    version: entry.version,
+    extensionSpecVersion: entry.extensionSpecVersion,
+    ...(entry.reason ? { reason: entry.reason } : {}),
+    ...(entry.artifacts ? { artifacts: entry.artifacts } : {}),
+    ...(entry.code ? { code: entry.code } : {}),
+    ...(entry.message ? { message: entry.message } : {}),
+    ...(entry.statePersisted !== undefined ? { statePersisted: entry.statePersisted } : {}),
+  };
+}
+
+function installResultText(results) {
+  const lines = results.map((entry) => entry.status === "installed"
+    ? `Installed ${entry.id}@${entry.version}.`
+    : entry.status === "skipped"
+      ? `Skipped ${entry.id}@${entry.version}: already current.`
+      : `Failed ${entry.id}${entry.version ? `@${entry.version}` : ""}: ${entry.message}`);
+  const installed = results.filter((entry) => entry.status === "installed").length;
+  const skipped = results.filter((entry) => entry.status === "skipped").length;
+  const failed = results.filter((entry) => entry.status === "failed").length;
+  lines.push(`Extensions: ${installed} installed, ${skipped} skipped, ${failed} failed.`);
+  return lines.join("\n");
+}
+
+async function executeExtensionInstall(invocation) {
+  const command = "extension.install";
+  const dependencies = invocation.dependencies || {};
+  const interactive = dependencies.interactive ?? (!invocation.options.json && invocation.options.yes !== true && process.stdin.isTTY && process.stdout.isTTY);
+  let requested = invocation.args.length > 0 ? normalizeExtensionNames(invocation.args) : null;
+  if (requested === null && !interactive) {
+    throw new WorkspaceError("EXTENSION_SELECTION_REQUIRED", "Extension installation requires one or more extension names outside interactive mode.", {
+      remediation: "Pass one or more names, for example: code-w extension install openspec-workspace --yes",
+    });
+  }
+
+  const catalogResult = discoverExtensions({ tolerant: true, ...(dependencies.extensionsRoot ? { extensionsRoot: dependencies.extensionsRoot } : {}) });
+  const stateInspection = inspectExtensionState(invocation.root);
+  if (requested === null) {
+    try {
+      requested = await (dependencies.collectExtensionInstallSelection || collectExtensionInstallSelection)(catalogResult.catalog, stateInspection.state, dependencies);
+    } catch (error) {
+      if (error.code === "EXTENSION_INSTALL_CANCELLED") {
+        return success(command, { action: "cancel", scope: "selection", requested: [], results: [], summary: { total: 0, succeeded: 0, skipped: 0, failed: 0 } }, "Extension installation cancelled. No changes were made.");
+      }
+      throw error;
+    }
+  }
+  if (requested.length === 0) {
+    return success(command, { action: "skip", scope: "selection", requested: [], results: [], summary: { total: 0, succeeded: 0, skipped: 0, failed: 0 } }, "No extensions selected. No changes were made.");
+  }
+
+  const tools = resolveWorkspaceTools({ state: loadState(invocation.root), manifestTools: loadInitManifest().tools }).tools;
+  const preparation = prepareExtensionPlans(catalogResult, requested, {
+    tools,
+    state: stateInspection.state,
+    stateError: stateInspection.error,
+  });
+  if (preparation.plans.length > 0) {
+    const planText = formatInstallPlan(preparation.plans);
+    if (!(await (dependencies.confirm || confirm)(`${planText}\nContinue?`, invocation.options))) {
+      throw new WorkspaceError("CLI_CANCELLED", "Extension installation cancelled.");
+    }
+  }
+  const workspace = invocation.config.workspace;
+  const batch = runExtensionBatch(invocation.root, preparation.plans, (extension) => ({
+    schemaVersion: 1,
+    extensionSpecVersion: extension.extensionSpecVersion,
+    extension: { id: extension.id, version: extension.version },
+    workspace: { name: workspace.name, uuid: workspace.uuid, language: workspace.language },
+    tools,
+  }), { requested, preFailures: preparation.failures });
+  const failedIds = new Set(batch.results.filter((entry) => entry.status === "failed").map((entry) => entry.id));
+  const diagnostics = [
+    ...preparation.diagnostics.filter((entry) => !entry.extension || !failedIds.has(entry.extension)),
+    ...batch.results.filter((entry) => entry.status === "failed").map((entry) => ({
+      code: entry.code || "EXTENSION_INSTALL_FAILED",
+      severity: "error",
+      message: entry.message || `Extension ${entry.id} failed to install.`,
+      extension: entry.id,
+      version: entry.version,
+    })),
+    ...batch.results.flatMap((entry) => (entry.warnings || []).map((warning) => ({
+      code: warning.code,
+      severity: "warning",
+      message: warning.message,
+      extension: entry.id,
+      version: entry.version,
+    }))),
+  ];
+  return selectionResult(command, requested, batch.results.map(installResultEntry), {
+    diagnostics,
+    text: installResultText(batch.results),
+  });
+}
+
+async function executeExtensionUninstall(invocation) {
+  const command = "extension.uninstall";
+  const plan = planExtensionUninstall(invocation.root, invocation.args[0]);
+  const planText = formatUninstallPlan(plan);
+  if (plan.action === "remove" && !(await confirm(`${planText}\nContinue?`, invocation.options))) {
+    throw new WorkspaceError("CLI_CANCELLED", "Extension uninstall cancelled.");
+  }
+  const result = applyExtensionUninstall(plan, invocation.dependencies);
+  const text = result.status === "skipped" ? planText : `${planText}\nExtension uninstalled and verified.`;
+  return success(command, { ...result, targets: plan.targets }, text);
+}
+
+async function executeExtension(invocation) {
+  const command = invocation.definition.path.join(".");
+  const releaseLock = await (invocation.dependencies?.acquireInitLock || acquireInitLock)(invocation.root);
+  try {
+    if (command === "extension.install") return await executeExtensionInstall(invocation);
+    if (command === "extension.uninstall") return await executeExtensionUninstall(invocation);
+    throw new WorkspaceError("CLI_HANDLER_MISSING", `Unsupported extension action: ${command}`);
+  } finally {
+    await releaseLock();
+  }
+}
+
+module.exports = {
+  collectExtensionInstallSelection,
+  executeExtension,
+  executeExtensionInstall,
+  executeExtensionUninstall,
+  formatInstallPlan,
+  formatUninstallPlan,
+};

package/src/cli/commands/help.js

@@ -0,0 +1,36 @@
+const packageJson = require("../../../package.json");
+const { SUPPORTED_LANGUAGES } = require("../../core/language");
+const { commandHelpRows, GLOBAL_OPTIONS } = require("../registry");
+const { success } = require("../result");
+
+function optionUsage(name, definition) {
+  const aliases = (definition.aliases || []).map((alias) => `-${alias}`).join(", ");
+  const long = `--${name}${definition.type === "string" ? ` <${name}>` : ""}`;
+  return aliases ? `${aliases}, ${long}` : long;
+}
+
+function helpText() {
+  const rows = commandHelpRows();
+  const commands = rows.map(({ usage, summary }) => `  ${usage.padEnd(36)}${summary}`).join("\n");
+  const commandOptions = rows
+    .filter(({ command }) => Object.keys(command.options).length > 0)
+    .map(({ command }) => {
+      const label = command.path.join(" ");
+      const options = Object.entries(command.options).map(([name, definition]) => `    ${optionUsage(name, definition)}`).join("\n");
+      return `  ${label}:\n${options}`;
+    })
+    .join("\n");
+  const globalOptions = Object.entries(GLOBAL_OPTIONS).map(([name, definition]) => optionUsage(name, definition)).join(", ");
+  const languages = SUPPORTED_LANGUAGES.map((entry) => entry.value).join("|");
+  return `Code Workspace ${packageJson.version}\n\nUsage: code-workspace [command] [options]\n\nCommands:\n${commands}\n\nCommand options:\n${commandOptions}\n\nWorkspace languages: ${languages}\nGlobal options: ${globalOptions}`;
+}
+
+function executeHelp() {
+  return success("help", { version: packageJson.version, commands: commandHelpRows().map(({ usage, summary }) => ({ usage, summary })) }, helpText());
+}
+
+function executeVersion() {
+  return success("version", { version: packageJson.version }, packageJson.version);
+}
+
+module.exports = { executeHelp, executeVersion, helpText, optionUsage };

package/src/cli/commands/init.js

@@ -0,0 +1,200 @@
+const path = require("node:path");
+
+const { loadState } = require("../../core/config");
+const { WorkspaceError } = require("../../core/errors");
+const { acquireInitLock } = require("../../core/init-lock");
+const {
+  discoverExtensions,
+  emptyExtensionState,
+  hasWorkspaceConfiguration,
+  inspectExtensionState,
+  installedExtensionNames,
+  parseExtensionSelection,
+  prepareExtensionPlans,
+  runExtensionBatch,
+} = require("../../core/extensions");
+const { compareVersions, loadInitManifest, minimumFromRange, runCommand } = require("../../core/init");
+const { initializeWorkspace } = require("../../core/initializer");
+const { resolveWorkspaceTools } = require("../../core/tools");
+const { collectInitPlan } = require("../../init/wizard");
+const { success } = require("../result");
+
+function migrationData(plan) {
+  if (!plan) return null;
+  return {
+    fromVersion: plan.schema.fromVersion,
+    toVersion: plan.schema.toVersion,
+    changed: plan.changed,
+    steps: plan.steps,
+    schemaSteps: plan.schema.steps,
+    language: plan.language,
+    writeTargets: plan.writeTargets,
+  };
+}
+
+async function executeInit(invocation) {
+  const root = path.resolve(invocation.args[0] || ".");
+  const releaseInitLock = await acquireInitLock(root);
+  try {
+    return await executeInitUnlocked(invocation, root);
+  } finally {
+    await releaseInitLock();
+  }
+}
+
+async function executeInitUnlocked(invocation, root) {
+  const { options } = invocation;
+  if (options.json && options.yes !== true) {
+    throw new WorkspaceError("CLI_CONFIRMATION_REQUIRED", "Workspace initialization requires explicit confirmation in JSON mode.", {
+      remediation: "Re-run with --yes.",
+    });
+  }
+  const run = options.json
+    ? (command, commandArgs, runOptions = {}) => runCommand(command, commandArgs, { ...runOptions, capture: true })
+    : runCommand;
+  const manifest = loadInitManifest();
+  const minimumNode = minimumFromRange(manifest.requirements.node);
+  if (compareVersions(process.versions.node, minimumNode) < 0) {
+    throw new WorkspaceError("NODE_VERSION_UNSUPPORTED", `Node ${minimumNode} or newer is required; found ${process.versions.node}`, {
+      actual: process.versions.node,
+      required: minimumNode,
+    });
+  }
+  const existingState = loadState(root);
+  const explicitExtensions = parseExtensionSelection(options.extensions);
+  const resolvedTools = resolveWorkspaceTools({
+    explicit: options.tools,
+    state: existingState,
+    manifestTools: manifest.tools,
+  });
+  const interactive = !options.json && !options.yes && process.stdin.isTTY && process.stdout.isTTY;
+  const existingWorkspace = hasWorkspaceConfiguration(root);
+  const inspectExtensions = interactive || explicitExtensions?.length > 0 || (explicitExtensions === null && existingWorkspace);
+  const extensionStateInspection = inspectExtensions ? inspectExtensionState(root) : { state: emptyExtensionState(), error: null };
+  const extensionState = extensionStateInspection.state;
+  const defaultExtensions = existingWorkspace && !extensionStateInspection.error ? installedExtensionNames(extensionState) : [];
+  const extensionCatalogResult = inspectExtensions ? discoverExtensions({ tolerant: true }) : { catalog: [], invalid: [] };
+  const extensionCatalog = extensionStateInspection.error && interactive ? [] : extensionCatalogResult.catalog;
+  if (interactive && explicitExtensions !== null) {
+    prepareExtensionPlans(extensionCatalogResult, explicitExtensions, { tools: resolvedTools.tools, state: extensionState, stateError: extensionStateInspection.error });
+  }
+  const interactiveExplicitExtensions = explicitExtensions === null
+    ? undefined
+    : explicitExtensions.filter((id) => extensionCatalog.some((entry) => entry.id === id && entry.latestSupported));
+  let plan = null;
+  if (interactive) {
+    try {
+      plan = await collectInitPlan(root, manifest, {
+        run,
+        tools: options.tools !== undefined ? resolvedTools.tools : undefined,
+        initialTools: resolvedTools.tools,
+        workspaceName: options["workspace-name"],
+        monitor: options.monitor === true ? true : options["no-monitor"] === true ? false : undefined,
+        monitorUrl: options["monitor-url"],
+        language: options.language,
+        extensionCatalog,
+        extensionState,
+        extensions: interactiveExplicitExtensions,
+        initialExtensions: explicitExtensions === null ? defaultExtensions : interactiveExplicitExtensions,
+      });
+    } catch (error) {
+      if (error.code === "INIT_CANCELLED") {
+        return success("init", { action: "cancel" }, "Initialization cancelled. No changes were made.");
+      }
+      throw error;
+    }
+  }
+  const tools = plan?.tools || resolvedTools.tools;
+  const requestedExtensions = explicitExtensions !== null
+    ? explicitExtensions
+    : plan ? plan.extensions.map((entry) => entry.id) : defaultExtensions;
+  const extensionPreparation = prepareExtensionPlans(extensionCatalogResult, requestedExtensions, { tools, state: extensionState, stateError: extensionStateInspection.error });
+  const extensionPlans = extensionPreparation.plans;
+  const toolSelection = { tools, source: plan ? (options.tools !== undefined ? "cli" : "interactive") : resolvedTools.source };
+  const result = await initializeWorkspace(root, {
+    run,
+    tools,
+    force: options.force === true,
+    yes: plan ? true : options.yes === true,
+    workspaceName: plan?.workspace.name || options["workspace-name"],
+    workspaceUuid: plan?.workspace.uuid,
+    monitor: plan?.monitor.enable ?? (options.monitor === true ? true : options["no-monitor"] === true ? false : undefined),
+    monitorUrl: plan?.monitor.url || options["monitor-url"],
+    language: plan?.language || options.language,
+    interactive: false,
+    initPlan: plan,
+    onStage: null,
+  });
+  const extensionResult = runExtensionBatch(root, extensionPlans, (extension) => ({
+    schemaVersion: 1,
+    extensionSpecVersion: extension.extensionSpecVersion,
+    extension: { id: extension.id, version: extension.version },
+    workspace: {
+      name: result.workspaceConfig.workspace.name,
+      uuid: result.workspaceConfig.workspace.uuid,
+      language: result.language,
+    },
+    tools,
+  }), { requested: requestedExtensions, preFailures: extensionPreparation.failures });
+  const extensionDiagnostics = [
+    ...extensionPreparation.diagnostics,
+    ...extensionResult.results
+    .filter((entry) => entry.status === "failed")
+    .map((entry) => ({
+      code: "EXTENSION_INIT_FAILED",
+      severity: "warning",
+      message: `Extension ${entry.id}@${entry.version} failed: ${entry.message}`,
+      extension: entry.id,
+      version: entry.version,
+      causeCode: entry.code,
+    })),
+  ];
+  for (const entry of extensionResult.results) {
+    for (const warning of entry.warnings || []) {
+      extensionDiagnostics.push({
+        code: warning.code,
+        severity: "warning",
+        message: warning.message,
+        extension: entry.id,
+        version: entry.version,
+      });
+    }
+  }
+  const data = {
+    root: result.root,
+    releaseVersion: result.manifest.releaseVersion,
+    nodeVersion: result.nodeVersion,
+    dependencies: result.dependencies,
+    obsoleteFiles: result.obsoleteFiles,
+    managedFiles: result.managedFiles,
+    localConfig: result.localConfig,
+    workspace: result.workspaceConfig.workspace,
+    monitor: result.workspaceConfig.monitor,
+    language: result.language,
+    tools: toolSelection,
+    migration: migrationData(result.migration),
+    permissions: result.permissions,
+    verification: result.verification,
+    plan: result.initPlan,
+    stages: result.stages.map((stage) => stage.name),
+    extensions: extensionResult,
+  };
+  const lines = [
+    "Code Workspace is ready.",
+    `Workspace: ${result.workspaceConfig.workspace.name} (${result.workspaceConfig.workspace.uuid})`,
+    `Language: ${result.language}`,
+    `Tools: ${tools.length ? tools.join(", ") : "none"} (${toolSelection.source})`,
+    `Extensions: ${extensionResult.summary.installed} installed, ${extensionResult.summary.skipped} skipped, ${extensionResult.summary.failed} failed`,
+  ];
+  if (result.workspaceConfig.monitor.enable) {
+    lines.push(`Codex monitoring reports to ${result.workspaceConfig.monitor.url}. Review and trust the project hooks with \`/hooks\` in Codex.`);
+  }
+  if (result.localConfig.action === "write" || result.permissions.action === "skip") {
+    lines.push(tools.length > 0
+      ? "Add local projects with the `code-workspace-add-projects` skill."
+      : "Add local projects with `code-workspace project inspect`, then register a complete project record.");
+  }
+  return success("init", data, lines.join("\n"), extensionDiagnostics);
+}
+
+module.exports = { executeInit, migrationData };

package/src/cli/commands/monitor.js

@@ -0,0 +1,62 @@
+const { loadConfigProjection, requireWorkspaceRoot } = require("../../core/config");
+const { WorkspaceError } = require("../../core/errors");
+const { reportHookEvent, startMonitor, validatePort } = require("../../monitor");
+const { success } = require("../result");
+
+async function readStdinJson(input = process.stdin) {
+  const chunks = [];
+  for await (const chunk of input) chunks.push(chunk);
+  try {
+    return JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}");
+  } catch (error) {
+    throw new WorkspaceError("MONITOR_EVENT_INVALID", `Cannot parse monitor event JSON: ${error.message}`);
+  }
+}
+
+async function executeMonitor(invocation) {
+  const action = invocation.definition.path[1];
+  if (action === "report") {
+    try {
+      const root = requireWorkspaceRoot(process.cwd());
+      const report = await reportHookEvent(await readStdinJson(), loadConfigProjection(root, ["identity", "monitor"]));
+      return success("monitor.report", report);
+    } catch (error) {
+      return success("monitor.report", { action: "skip", reason: "reporting failed open", errorCode: error.code || "MONITOR_REPORT_FAILED" });
+    }
+  }
+  if (invocation.options.json) {
+    throw new WorkspaceError("CLI_JSON_UNSUPPORTED", "The long-running monitor command does not support --json; use the dashboard API for machine-readable state.");
+  }
+  const port = validatePort(invocation.options.port);
+  let monitor;
+  try {
+    monitor = await startMonitor({ port });
+  } catch (error) {
+    if (error.code === "EADDRINUSE") {
+      throw new WorkspaceError("MONITOR_PORT_IN_USE", `Monitor port 127.0.0.1:${port} is already in use.`, {
+        port,
+        remediation: `Start another port with code-w monitor -p 8080, then update monitor.url.`,
+      });
+    }
+    throw error;
+  }
+  const text = [
+    `Code Workspace Monitor listening on http://${monitor.host}:${monitor.port}`,
+    `Dashboard: http://${monitor.host}:${monitor.port}/`,
+    `Workspaces report to http://${monitor.host}:${monitor.port}/api/v1/events`,
+  ].join("\n");
+  process.stdout.write(`${text}\n`);
+  await new Promise((resolve) => {
+    let closing = false;
+    const close = () => {
+      if (closing) return;
+      closing = true;
+      monitor.server.close(resolve);
+    };
+    process.once("SIGINT", close);
+    process.once("SIGTERM", close);
+  });
+  return success("monitor", { host: monitor.host, port: monitor.port });
+}
+
+module.exports = { executeMonitor, readStdinJson };

package/src/cli/commands/permissions.js

@@ -0,0 +1,33 @@
+const { loadState } = require("../../core/config");
+const { loadInitManifest } = require("../../core/init");
+const { applyPermissionPlan, formatPermissionPlan, planPermissionChanges } = require("../../core/permissions");
+const { resolveWorkspaceTools } = require("../../core/tools");
+const { validateProjects } = require("../../core/validation");
+const { confirm } = require("../confirmation");
+const { fromDiagnostics, success } = require("../result");
+
+async function executePermissions(invocation) {
+  const command = "permissions.apply";
+  const validation = validateProjects(invocation.root, invocation.config);
+  if (validation.errors.length > 0) return fromDiagnostics(command, validation);
+  const toolSelection = resolveWorkspaceTools({
+    explicit: invocation.options.tools,
+    state: loadState(invocation.root),
+    manifestTools: loadInitManifest().tools,
+  });
+  const plan = planPermissionChanges({
+    root: invocation.root,
+    tools: toolSelection.tools,
+    grants: invocation.config.projects.map((project) => project.location),
+  });
+  const planText = formatPermissionPlan(plan);
+  if (plan.action === "write" && !(await confirm(`${planText}\nApply these Agent authorization changes?`, invocation.options))) {
+    const error = new Error("Agent authorization changes cancelled.");
+    error.code = "CLI_CANCELLED";
+    throw error;
+  }
+  const result = applyPermissionPlan(plan, invocation.options.dependencies);
+  return success(command, { ...result, toolSelection }, plan.action === "skip" ? planText : `${planText}\nAgent authorization changes applied and verified.`, validation.diagnostics);
+}
+
+module.exports = { executePermissions };

package/src/cli/commands/project-branch-update.js

@@ -0,0 +1,107 @@
+const { WorkspaceError } = require("../../core/errors");
+const {
+  applyLatestBranchUpdate,
+  planLatestBranchUpdate,
+} = require("../../core/project-branch-update");
+const {
+  diagnosticFromError,
+  selectionResult,
+  success,
+} = require("../result");
+
+function updateError(code, message, details = {}) {
+  return new WorkspaceError(code, message, details);
+}
+
+function uniqueProjectSelection(args) {
+  const requested = [...args];
+  const names = [];
+  const diagnostics = [];
+  const seen = new Set();
+  for (const name of requested) {
+    if (!seen.has(name)) {
+      seen.add(name);
+      names.push(name);
+      continue;
+    }
+    diagnostics.push({
+      code: "CLI_DUPLICATE_ARGUMENT",
+      severity: "warning",
+      message: `Project ${name} was provided more than once; later occurrences were ignored.`,
+      project: name,
+      argument: "name",
+    });
+  }
+  return { requested, names, diagnostics };
+}
+
+function batchEntry(project, ok, action, data, message) {
+  return { project, ok, action, data: data || null, message };
+}
+
+function batchText(results) {
+  const lines = results.map((entry) => `${entry.ok ? (entry.action === "skip" ? "SKIP" : "OK") : "FAILED"}\t${entry.project}\t${entry.message}`);
+  const succeeded = results.filter((entry) => entry.ok && entry.action !== "skip").length;
+  const skipped = results.filter((entry) => entry.ok && entry.action === "skip").length;
+  const failed = results.filter((entry) => !entry.ok).length;
+  return [...lines, `Summary\ttotal=${results.length}\tsucceeded=${succeeded}\tskipped=${skipped}\tfailed=${failed}`].join("\n");
+}
+
+function recordFailure(slot, error, diagnostics) {
+  diagnostics.push(diagnosticFromError(error, { project: slot.name }));
+  slot.result = batchEntry(slot.name, false, "failed", null, error.message);
+}
+
+function resultMessage(data) {
+  if (data.action === "skip" && data.reason === "disabled") return "latest-branch update disabled";
+  if (data.action === "skip" && data.reason === "already-latest") return `already latest: ${data.afterHead || data.targetHead}`;
+  return `fast-forwarded ${data.project?.name || "project"}: ${data.beforeHead} -> ${data.afterHead}`;
+}
+
+function executeSingle(invocation, dependencies) {
+  const { config, root, args } = invocation;
+  const plan = (dependencies.planLatestBranchUpdate || planLatestBranchUpdate)(config, args[0], dependencies);
+  const applied = (dependencies.applyLatestBranchUpdate || applyLatestBranchUpdate)(root, plan, dependencies);
+  return success("project.branch.update-latest", applied, resultMessage(applied));
+}
+
+function executeBatch(invocation, dependencies) {
+  const { config, root } = invocation;
+  const selection = uniqueProjectSelection(invocation.args);
+  const diagnostics = [...selection.diagnostics];
+  const slots = selection.names.map((name) => ({ name }));
+  for (const slot of slots) {
+    try {
+      slot.plan = (dependencies.planLatestBranchUpdate || planLatestBranchUpdate)(config, slot.name, dependencies);
+    } catch (error) {
+      recordFailure(slot, error, diagnostics);
+    }
+  }
+  for (const slot of slots.filter((entry) => entry.plan && !entry.result)) {
+    try {
+      const applied = (dependencies.applyLatestBranchUpdate || applyLatestBranchUpdate)(root, slot.plan, dependencies);
+      slot.result = batchEntry(slot.name, true, applied.action, applied, resultMessage(applied));
+    } catch (error) {
+      recordFailure(slot, error, diagnostics);
+    }
+  }
+  return selectionResult("project.branch.update-latest", selection.requested, slots.map((slot) => slot.result), {
+    diagnostics,
+    text: batchText(slots.map((slot) => slot.result)),
+  });
+}
+
+function executeProjectBranchUpdateLatest(invocation) {
+  const dependencies = invocation.options.dependencies || {};
+  if (invocation.args.length > 1) return executeBatch(invocation, dependencies);
+  if (invocation.args.length !== 1) throw updateError("CLI_ARGUMENT_REQUIRED", "project branch update-latest requires <name>", { argument: "name" });
+  return executeSingle(invocation, dependencies);
+}
+
+module.exports = {
+  batchText,
+  executeProjectBranchUpdateLatest,
+  executeBatch,
+  executeSingle,
+  uniqueProjectSelection,
+};