code-workspace-zhuiyi 0.1.0-beta.1

package/schemas/extension-manifest-v3.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://icebearx.ai/code-workspace/extension-manifest-v3.json",
+  "title": "Code Workspace Extension Spec v1 manifest schema v3",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "extensionSpecVersion", "experimental", "id", "name", "version", "entry", "entrySha256", "timeoutMs", "outputs"],
+  "properties": {
+    "schemaVersion": { "const": 3 },
+    "extensionSpecVersion": { "const": 1 },
+    "experimental": { "const": true },
+    "id": { "$ref": "#/$defs/id" },
+    "name": { "type": "string", "minLength": 1, "maxLength": 100 },
+    "version": { "type": "string" },
+    "entry": { "const": "init.js" },
+    "entrySha256": { "$ref": "#/$defs/sha256" },
+    "timeoutMs": { "type": "integer", "minimum": 1, "maximum": 300000 },
+    "capabilities": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "networkHosts": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "$ref": "#/$defs/hostname" }
+        }
+      }
+    },
+    "outputs": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "kind", "ownership", "target"],
+        "properties": {
+          "id": { "$ref": "#/$defs/id" },
+          "kind": { "enum": ["file", "directory", "text-block", "json-member"] },
+          "ownership": { "enum": ["exclusive", "shared"] },
+          "target": { "$ref": "#/$defs/relativePath" },
+          "selector": { "type": "string", "pattern": "^/(?:[^~/]|~[01])+(?:/(?:[^~/]|~[01])+)*$" },
+          "format": { "enum": ["text", "toml"] },
+          "tools": {
+            "type": "array",
+            "minItems": 1,
+            "uniqueItems": true,
+            "items": { "enum": ["claude", "codex"] }
+          }
+        },
+        "allOf": [
+          {
+            "if": { "properties": { "kind": { "enum": ["file", "directory"] } } },
+            "then": { "properties": { "ownership": { "const": "exclusive" } } }
+          },
+          {
+            "if": { "properties": { "kind": { "enum": ["text-block", "json-member"] } } },
+            "then": { "properties": { "ownership": { "const": "shared" } } }
+          },
+          {
+            "if": { "properties": { "kind": { "const": "json-member" } } },
+            "then": { "required": ["selector"] },
+            "else": { "properties": { "selector": false } }
+          },
+          {
+            "if": { "properties": { "kind": { "const": "text-block" } } },
+            "then": { "properties": { "format": { "enum": ["text", "toml"] } } },
+            "else": { "properties": { "format": false } }
+          }
+        ]
+      }
+    }
+  },
+  "$defs": {
+    "id": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
+    "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "hostname": { "type": "string", "pattern": "^(?=.{1,253}$)[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$" },
+    "relativePath": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?!/)(?!.*\\\\)(?!.*(?:^|/)\\.{1,2}(?:/|$))(?!.*//).+$"
+    }
+  }
+}

package/spec/extension/v1/specification.en-US.md

@@ -0,0 +1,171 @@
+# Code Workspace Extension Spec v1
+
+[简体中文](./specification.zh-CN.md) | [English](./specification.en-US.md)
+
+> Status: Normative translation  
+> Extension Spec version: 1  
+> Language: English  
+> Interpretation baseline: `specification.zh-CN.md`  
+> Published at: `spec/extension/v1/specification.en-US.md`
+
+This document and the JSON Schemas it references together constitute Code Workspace Extension Spec v1. Compatibility between an extension and a Host is determined only by `extensionSpecVersion`; it does not depend on the Code Workspace product version or the extension version.
+
+## 0. Document Status and Conformance
+
+### 0.1 Normative Keywords
+
+The terms MUST and MUST NOT express conformance requirements. SHOULD means that a requirement is expected unless there is a specific, explainable reason not to follow it. MAY indicates permitted but optional behavior.
+
+### 0.2 Normative Components
+
+The normative artifacts of Extension Spec v1 are:
+
+- the entry, capability, output, staging, installation, upgrade, verification, and uninstall semantics defined by this document;
+- manifest schema v3: `schemas/extension-manifest-v3.json`;
+- init context schema v1: `schemas/extension-init-context-v1.json`;
+- init result schema v1: `schemas/extension-init-result-v1.json`.
+
+The JSON Schemas define document structure. This document defines cross-document and lifecycle semantics. A conflict between them is a specification defect; Hosts and extensions MUST NOT infer compatibility from such a conflict.
+
+The Chinese and English specifications MUST express the same conformance requirements and preserve corresponding section structures. If the two languages produce different interpretations, the difference is a specification defect. Until corrected, the Chinese specification is the interpretation baseline, and a translation difference MUST NOT be treated as a compatibility capability.
+
+### 0.3 Conforming Parties
+
+A conforming Spec v1 Host MUST implement every Host requirement in this document and MUST execute only extensions that pass the Spec v1 schema and lifecycle validations. A conforming Spec v1 extension MUST declare `extensionSpecVersion: 1`, follow the corresponding schemas, and MUST NOT bypass the Host when managing artifacts in the real Workspace.
+
+All JSON, command, and directory-layout examples in this document are non-normative. They illustrate the rules but do not expand or narrow the requirements.
+
+## 1. Versioning and Compatibility
+
+Extension Spec versions are discrete positive integers. A Host MUST explicitly list the versions it implements. An extension MUST declare exactly one version.
+
+```text
+compatible ⇔ extension.extensionSpecVersion ∈ host.supportedExtensionSpecVersions
+```
+
+A component `schemaVersion` describes the format of one JSON document. `extensionSpecVersion` describes the complete development and execution contract between a Host and an extension.
+
+A product release, a private implementation change, or an extension SemVer change does not automatically create a new Extension Spec. A new specification version is required only when the manifest, context/result, output, or lifecycle contract has a non-backward-compatible, machine-observable change.
+
+## 2. Stable Discovery Envelope
+
+Every manifest in every specification version MUST retain the following fields so that an older Host can identify, but not execute, an unknown specification:
+
+```json
+{
+  "extensionSpecVersion": 1,
+  "id": "example-extension",
+  "name": "Example Extension",
+  "version": "1.0.0"
+}
+```
+
+For an unknown `extensionSpecVersion`, the Host MUST read only these fields and MUST NOT interpret the entry, capabilities, or outputs. When an extension contains multiple versions, the Host selects the highest extension SemVer implemented against a specification version that the Host supports.
+
+## 3. Manifest
+
+A Spec v1 manifest uses manifest schema v3. The manifest is the static declaration of installation permissions and maximum output scope; it is not a post-execution report.
+
+```json
+{
+  "schemaVersion": 3,
+  "extensionSpecVersion": 1,
+  "experimental": true,
+  "id": "example-extension",
+  "name": "Example Extension",
+  "version": "1.0.0",
+  "entry": "init.js",
+  "entrySha256": "<sha256>",
+  "timeoutMs": 30000,
+  "capabilities": {
+    "networkHosts": ["example.com"]
+  },
+  "outputs": [
+    {
+      "id": "runtime",
+      "kind": "directory",
+      "ownership": "exclusive",
+      "target": ".code-workspace/extensions/example-extension/1.0.0"
+    }
+  ]
+}
+```
+
+The `codeWorkspace` product-version range is not part of Extension Spec and MUST NOT appear in a Spec v1 manifest.
+
+Before confirmation, the Host MUST freeze the manifest, entry, and complete extension-version directory digest. The Host MUST verify them again before execution. An extension MUST NOT use a dynamic result to expand the declarations in its manifest.
+
+## 4. Execution Entry
+
+The entry MUST be `init.js` inside the extension-version directory. The Host executes it with the current Node.js runtime:
+
+```text
+node init.js --context <context.json> --output <staging-directory> --result <result.json>
+```
+
+The Host MUST pass only the environment-variable allowlist required for execution. Process isolation is not a security sandbox; Spec v1 executes trusted bundled extensions only.
+
+The entry MUST exit within the timeout declared by the manifest. A failure, timeout, missing result, or invalid result MUST NOT produce writes to the real Workspace.
+
+## 5. Context and Result
+
+The context and result MUST both echo `extensionSpecVersion: 1`. The value MUST match the frozen plan.
+
+The context contains only extension identity, non-sensitive Workspace display metadata, and the selected tools. It MUST NOT contain the real Workspace root or credentials.
+
+The result contains only the extension identity and a list of `{id, source}` entries. It MUST NOT declare targets, kinds, ownership, selectors, digests, or network capabilities.
+
+## 6. Capability Declarations
+
+Spec v1 defines only `capabilities.networkHosts`. The field is used in planning, confirmation, and diagnostics to describe the HTTPS hosts that the extension expects to access.
+
+Without operating-system-level enforcement, the Host MUST NOT claim that it can prevent a trusted extension from accessing other network or user resources.
+
+## 7. Output Kinds
+
+Spec v1 supports four output kinds:
+
+| kind | ownership | Lifecycle semantics |
+|---|---|---|
+| `file` | `exclusive` | The Host exclusively writes, digests, drift-checks, and removes one regular file |
+| `directory` | `exclusive` | The Host exclusively replaces, canonically digests, drift-checks, and recursively removes a directory |
+| `text-block` | `shared` | The Host manages a marked text contribution using the extension id and output id |
+| `json-member` | `shared` | The Host manages one member selected by JSON Pointer while preserving other content |
+
+Public output kinds MUST NOT encode private business concepts such as Jira, MCP, npm, archive formats, or individual Agent products.
+
+## 8. Staging Verification
+
+An extension MUST generate candidate content only inside the staging directory supplied by the Host. The Host MUST:
+
+- normalize result sources and reject path traversal;
+- require the result to return exactly every output id applicable to the current execution;
+- reject unknown, duplicate, missing, overlapping, or extra outputs;
+- reject symbolic links, devices, sockets, FIFOs, and other special files;
+- compute file and directory digests from the actual staging content.
+
+A digest reported by the extension MUST NOT be accepted as an installed fact.
+
+## 9. Installation, Upgrade, and Uninstall
+
+Each extension uses an independent transaction to commit its exclusive outputs, shared contributions, and installed state. The transaction MUST NOT commit until every postcondition passes.
+
+A new installation MUST record:
+
+- the installed-record version;
+- `extensionSpecVersion`;
+- the extension version;
+- the manifest and complete extension-package digests;
+- output ownership and the installed facts computed by the Host.
+
+Idempotency MUST verify both installed state and the real Workspace. A failed upgrade MUST restore the previous artifacts and previous installed state.
+
+Uninstall depends only on installed state. It MUST NOT read the current extension package or execute extension code. Even when the Host no longer supports the execution specification of an installed extension, it MUST safely verify and uninstall the artifacts whenever it can still read the corresponding installed record.
+
+## 10. Specification Evolution
+
+A new extension that fully reuses Spec v1 capabilities MUST NOT require changes to Host core or the public schemas.
+
+A new public capability can enter a later specification version only when it has cross-extension semantics and a complete Host-managed installation, verification, upgrade, rollback, and uninstall lifecycle. A Host MUST fail safely on an unknown specification version and MUST NOT infer compatibility from numeric ranges.
+
+After Spec v1 is published, its machine-observable semantics remain unchanged. Text-only clarifications that do not alter conformance outcomes MAY continue to be published in this directory. Any breaking change MUST use a new `spec/extension/<version>/` directory and a new `extensionSpecVersion`.

package/spec/extension/v1/specification.zh-CN.md

@@ -0,0 +1,170 @@
+# Code Workspace Extension Spec v1
+
+[简体中文](./specification.zh-CN.md) | [English](./specification.en-US.md)
+
+> 状态：规范性（Normative）  
+> Extension Spec 版本：1  
+> 语言：简体中文（解释基准）  
+> 规范发布路径：`spec/extension/v1/specification.zh-CN.md`
+
+本文档与其引用的 JSON Schema 共同构成 Code Workspace Extension Spec v1。扩展与 Host 的兼容性只由 `extensionSpecVersion` 判断，不依赖 Code Workspace 产品版本或扩展版本。
+
+## 0. 文档地位与一致性
+
+### 0.1 规范关键字
+
+本文中的“必须”“不得”表示一致性要求；“应当”表示除非存在明确且可说明的理由，否则需要遵守；“可以”表示允许但不强制。
+
+### 0.2 规范组成
+
+Extension Spec v1 的规范性制品包括：
+
+- 本文定义的入口、能力、输出、staging、安装、升级、验证和卸载语义；
+- manifest schema v3：`schemas/extension-manifest-v3.json`；
+- init context schema v1：`schemas/extension-init-context-v1.json`；
+- init result schema v1：`schemas/extension-init-result-v1.json`。
+
+JSON Schema 规定文档结构，本文规定跨文档和生命周期语义。二者出现冲突时属于规范缺陷，Host 和扩展不得自行猜测兼容性。
+
+中文与英文规范必须表达相同的一致性要求并保持对应章节结构。两种语言产生不同解释时，差异属于规范缺陷；修正前以中文版本为解释基准，不得将翻译差异当作兼容能力。
+
+### 0.3 一致性主体
+
+符合 Spec v1 的 Host 必须实现本文对 Host 的全部要求，并且只执行通过 Spec v1 schema 和生命周期校验的扩展。符合 Spec v1 的扩展必须声明 `extensionSpecVersion: 1`，遵守对应 schema，并且不得绕过 Host 管理真实 Workspace 制品。
+
+本文中的 JSON、命令和目录结构示例均为非规范性示例；它们用于说明规则，不能扩大或缩小规范要求。
+
+## 1. 版本与兼容性
+
+Extension Spec 使用离散正整数版本。Host 必须明确列出自己实现的版本集合；扩展必须声明一个版本。
+
+```text
+兼容 ⇔ extension.extensionSpecVersion ∈ host.supportedExtensionSpecVersions
+```
+
+组件的 `schemaVersion` 只描述单个 JSON 文档格式；`extensionSpecVersion` 描述 Host 与扩展之间的完整开发和执行契约。
+
+产品发布、扩展私有实现或扩展 SemVer 变化不会自动产生新的 Extension Spec。只有 manifest、context/result、输出或生命周期出现不向后兼容的机器可观察变化时，才发布新的规范版本。
+
+## 2. 稳定发现 Envelope
+
+所有规范版本的 manifest 必须保留以下字段，使旧 Host 可以识别但不执行未知规范：
+
+```json
+{
+  "extensionSpecVersion": 1,
+  "id": "example-extension",
+  "name": "Example Extension",
+  "version": "1.0.0"
+}
+```
+
+Host 对未知 `extensionSpecVersion` 只能读取上述字段，不得解释入口、能力或输出。一个扩展包含多个版本时，Host 从自己支持的规范实现中选择最高扩展 SemVer。
+
+## 3. Manifest
+
+Spec v1 manifest 使用 schema v3。manifest 是安装权限和最大输出范围的静态声明，不是扩展执行后的报告。
+
+```json
+{
+  "schemaVersion": 3,
+  "extensionSpecVersion": 1,
+  "experimental": true,
+  "id": "example-extension",
+  "name": "Example Extension",
+  "version": "1.0.0",
+  "entry": "init.js",
+  "entrySha256": "<sha256>",
+  "timeoutMs": 30000,
+  "capabilities": {
+    "networkHosts": ["example.com"]
+  },
+  "outputs": [
+    {
+      "id": "runtime",
+      "kind": "directory",
+      "ownership": "exclusive",
+      "target": ".code-workspace/extensions/example-extension/1.0.0"
+    }
+  ]
+}
+```
+
+`codeWorkspace` 产品版本范围不属于 Extension Spec，不得出现在 Spec v1 manifest 中。
+
+Host 在确认前冻结 manifest、入口及完整扩展版本目录摘要，在执行前重新验证。扩展不得通过动态 result 扩大 manifest 声明。
+
+## 4. 执行入口
+
+入口必须是扩展版本目录中的 `init.js`，由 Host 使用当前 Node 运行时执行：
+
+```text
+node init.js --context <context.json> --output <staging-directory> --result <result.json>
+```
+
+Host 只传递运行所需的环境变量白名单。子进程隔离不是安全沙箱；Spec v1 只执行可信内置扩展。
+
+入口必须在 manifest 声明的超时内退出。失败、超时、缺少 result 或非法 result 均不得产生真实 Workspace 写入。
+
+## 5. Context 与 Result
+
+context 和 result 必须同时回显 `extensionSpecVersion: 1`。该值必须与冻结计划一致。
+
+context 只包含扩展身份、非敏感 Workspace 元数据和工具选择，不包含真实 Workspace 根目录或凭证。
+
+result 只包含扩展身份和 `{id, source}` 列表。它不得声明 target、kind、ownership、selector、摘要或网络能力。
+
+## 6. 能力声明
+
+Spec v1 只定义 `capabilities.networkHosts`。该字段用于安装计划、确认和诊断，表达扩展预期访问的 HTTPS host。
+
+在没有 OS 级 enforcement 时，Host 不得声称它能阻止可信扩展访问其他网络或用户资源。
+
+## 7. 输出类型
+
+Spec v1 支持四种输出：
+
+| kind | ownership | 生命周期语义 |
+|---|---|---|
+| `file` | `exclusive` | Host 独占写入、摘要、漂移检查和删除单个普通文件 |
+| `directory` | `exclusive` | Host 独占替换、规范目录摘要、漂移检查和递归删除目录 |
+| `text-block` | `shared` | Host 以扩展 id/output id 标记并管理文本片段 |
+| `json-member` | `shared` | Host 以 JSON Pointer selector 管理单个成员并保留其他内容 |
+
+公共输出不得包含 Jira、MCP、npm、归档或特定 Agent 产品的业务类型。
+
+## 8. Staging 验证
+
+扩展只能在 Host 提供的 staging 目录生成候选内容。Host 必须：
+
+- 规范化 result source 并拒绝路径逃逸；
+- 要求 result 恰好返回本次适用的全部 output id；
+- 拒绝未知、重复、缺失、重叠或额外输出；
+- 拒绝符号链接、设备、socket、FIFO 和其他特殊文件；
+- 根据真实 staging 内容计算文件或目录摘要。
+
+扩展报告的摘要不能作为 installed 事实。
+
+## 9. 安装、升级与卸载
+
+每个扩展使用独立事务提交其独占输出、共享 contribution 和 installed 状态。完整后置条件通过前不得提交。
+
+新安装必须记录：
+
+- installed record 版本；
+- `extensionSpecVersion`；
+- 扩展版本；
+- manifest 和完整扩展包摘要；
+- 输出所有权以及 Host 计算的 installed 事实。
+
+幂等判断必须同时验证 installed 状态和真实 Workspace。升级失败必须恢复旧制品和旧 installed 状态。
+
+卸载只依据 installed 状态，不读取当前扩展包，也不执行扩展代码。Host 即使不再支持某个扩展的执行规范，只要仍能读取对应 installed record，就必须能够安全验证和卸载其制品。
+
+## 10. 规范演进
+
+新扩展完全复用 Spec v1 能力时，不得修改 Host 核心或公共 schema。
+
+新公共能力只有同时具备跨扩展语义以及安装、验证、升级、回滚和卸载闭环时，才可以进入后续规范版本。Host 对未知规范版本必须安全失败，不得按数字范围猜测兼容。
+
+Spec v1 发布后，其机器可观察语义保持不变。仅文字澄清且不改变一致性结果的修订可以继续发布在本目录；任何破坏性变化必须使用新的 `spec/extension/<version>/` 目录和新的 `extensionSpecVersion`。

package/src/cli/commands/completion.js

@@ -0,0 +1,203 @@
+const { WorkspaceError } = require("../../core/errors");
+const { COMMANDS, GLOBAL_OPTIONS } = require("../registry");
+const { success } = require("../result");
+
+const SUPPORTED_SHELLS = ["bash", "zsh"];
+
+function optionToken(name) {
+  return `--${name}`;
+}
+
+function aliasToken(alias) {
+  return alias.length === 1 ? `-${alias}` : `--${alias}`;
+}
+
+function optionTokens(definitions) {
+  return Object.entries(definitions).flatMap(([name, definition]) => [
+    optionToken(name),
+    ...(definition.aliases || []).map(aliasToken),
+  ]);
+}
+
+function buildCompletionSpec(commands = COMMANDS, globalOptions = GLOBAL_OPTIONS) {
+  const children = new Map();
+  const addChild = (prefix, child) => {
+    const key = prefix.join(" ");
+    const values = children.get(key) || [];
+    if (!values.includes(child)) values.push(child);
+    children.set(key, values);
+  };
+  for (const command of commands) {
+    for (let index = 0; index < command.path.length; index += 1) {
+      addChild(command.path.slice(0, index), command.path[index]);
+    }
+  }
+  const globals = optionTokens(globalOptions);
+  return {
+    globals,
+    children: [...children.entries()].map(([key, values]) => ({
+      path: key ? key.split(" ") : [],
+      values,
+    })),
+    commands: commands.map((command) => ({
+      path: [...command.path],
+      options: [...new Set([...globals, ...optionTokens(command.options)])],
+    })),
+  };
+}
+
+function bashWords(values) {
+  return values.join(" ").replace(/(["\\$`])/g, "\\$1");
+}
+
+function bashPathCondition(path) {
+  return path.map((part, index) => `[[ "\${COMP_WORDS[$((command_index + ${index}))]}" == "${part}" ]]`).join(" && ");
+}
+
+function renderBashCompletion(spec) {
+  const root = spec.children.find((entry) => entry.path.length === 0)?.values || [];
+  const childBlocks = spec.children
+    .filter((entry) => entry.path.length > 0)
+    .map((entry) => [
+      `  if (( depth == ${entry.path.length} )) && ${bashPathCondition(entry.path)} && [[ "$current" != -* ]]; then`,
+      `    COMPREPLY=( $(compgen -W "${bashWords(entry.values)}" -- "$current") )`,
+      "    return",
+      "  fi",
+    ].join("\n"))
+    .join("\n");
+  const optionBlocks = [...spec.commands]
+    .sort((left, right) => right.path.length - left.path.length)
+    .map((entry) => [
+      `  if ${bashPathCondition(entry.path)}; then`,
+      `    COMPREPLY=( $(compgen -W "${bashWords(entry.options)}" -- "$current") )`,
+      "    return",
+      "  fi",
+    ].join("\n"))
+    .join("\n");
+  return [
+    "_code_workspace() {",
+    "  local current=\"${COMP_WORDS[COMP_CWORD]}\"",
+    "  local command_index=1",
+    "  local depth",
+    "  COMPREPLY=()",
+    "  while (( command_index < COMP_CWORD )); do",
+    "    case \"${COMP_WORDS[command_index]}\" in",
+    `      ${spec.globals.join("|")}) ((command_index += 1)) ;;`,
+    "      *) break ;;",
+    "    esac",
+    "  done",
+    "  depth=$((COMP_CWORD - command_index))",
+    "  if [[ \"${COMP_WORDS[COMP_CWORD-1]}\" == \"--shell\" ]]; then",
+    `    COMPREPLY=( $(compgen -W "${SUPPORTED_SHELLS.join(" ")}" -- "$current") )`,
+    "    return",
+    "  fi",
+    "  if (( depth == 0 )); then",
+    "    if [[ \"$current\" == -* ]]; then",
+    `      COMPREPLY=( $(compgen -W "${bashWords(spec.globals)}" -- "$current") )`,
+    "    else",
+    `      COMPREPLY=( $(compgen -W "${bashWords(root)}" -- "$current") )`,
+    "    fi",
+    "    return",
+    "  fi",
+    childBlocks,
+    "  if [[ \"$current\" != -* ]]; then return; fi",
+    optionBlocks,
+    "}",
+    "complete -F _code_workspace code-workspace code-w",
+  ].filter(Boolean).join("\n");
+}
+
+function zshQuote(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+function zshArray(values) {
+  return values.map(zshQuote).join(" ");
+}
+
+function zshPathCondition(path) {
+  return path.map((part, index) => `[[ "\${words[$((command_index + ${index}))]}" == ${zshQuote(part)} ]]`).join(" && ");
+}
+
+function renderZshCompletion(spec) {
+  const root = spec.children.find((entry) => entry.path.length === 0)?.values || [];
+  const childBlocks = spec.children
+    .filter((entry) => entry.path.length > 0)
+    .map((entry) => [
+      `  if (( depth == ${entry.path.length} )) && ${zshPathCondition(entry.path)} && [[ "$current" != -* ]]; then`,
+      `    candidates=( ${zshArray(entry.values)} )`,
+      "    compadd -- \"${candidates[@]}\"",
+      "    return",
+      "  fi",
+    ].join("\n"))
+    .join("\n");
+  const optionBlocks = [...spec.commands]
+    .sort((left, right) => right.path.length - left.path.length)
+    .map((entry) => [
+      `  if ${zshPathCondition(entry.path)}; then`,
+      `    candidates=( ${zshArray(entry.options)} )`,
+      "    compadd -- \"${candidates[@]}\"",
+      "    return",
+      "  fi",
+    ].join("\n"))
+    .join("\n");
+  return [
+    "#compdef code-workspace code-w",
+    "_code_workspace() {",
+    "  local current=\"${words[CURRENT]}\"",
+    "  local command_index=2",
+    "  local depth",
+    "  local -a candidates",
+    "  while (( command_index < CURRENT )); do",
+    "    case \"${words[command_index]}\" in",
+    `      ${spec.globals.join("|")}) ((command_index += 1)) ;;`,
+    "      *) break ;;",
+    "    esac",
+    "  done",
+    "  depth=$((CURRENT - command_index))",
+    "  if [[ \"${words[CURRENT-1]}\" == \"--shell\" ]]; then",
+    `    candidates=( ${zshArray(SUPPORTED_SHELLS)} )`,
+    "    compadd -- \"${candidates[@]}\"",
+    "    return",
+    "  fi",
+    "  if (( depth == 0 )); then",
+    "    if [[ \"$current\" == -* ]]; then",
+    `      candidates=( ${zshArray(spec.globals)} )`,
+    "    else",
+    `      candidates=( ${zshArray(root)} )`,
+    "    fi",
+    "    compadd -- \"${candidates[@]}\"",
+    "    return",
+    "  fi",
+    childBlocks,
+    "  if [[ \"$current\" != -* ]]; then return; fi",
+    optionBlocks,
+    "}",
+    "compdef _code_workspace code-workspace code-w",
+  ].filter(Boolean).join("\n");
+}
+
+function executeCompletion(invocation) {
+  const shell = invocation.options.shell || "zsh";
+  const spec = buildCompletionSpec();
+  const script = shell === "bash"
+    ? renderBashCompletion(spec)
+    : shell === "zsh"
+      ? renderZshCompletion(spec)
+      : null;
+  if (!script) {
+    throw new WorkspaceError("CLI_COMPLETION_SHELL_UNSUPPORTED", `Unsupported completion shell: ${shell}`, {
+      actual: shell,
+      supported: SUPPORTED_SHELLS,
+    });
+  }
+  return success("completion", { shell, script }, script);
+}
+
+module.exports = {
+  SUPPORTED_SHELLS,
+  buildCompletionSpec,
+  executeCompletion,
+  renderBashCompletion,
+  renderZshCompletion,
+};