code-workspace-zhuiyi 1.0.0-beta.4 → 1.0.0

package/README.md

@@ -1,5 +1,7 @@
 # Code Workspace
 
+[English](README.md) | [简体中文](README.zh-CN.md)
+
 Code Workspace is a local multi-project registry and safety layer for Claude Code and Codex. It manages workspace identity, project locations and branches, agent instructions, writable-root permissions, validation, and optional monitoring.
 
 ## Requirements
@@ -13,11 +15,8 @@ Code Workspace is a local multi-project registry and safety layer for Claude Cod
 npm install -g code-workspace-zhuiyi@latest
 ```
 
-The package provides the `code-workspace` command and the shorter `codew` alias. The legacy `code-w` alias remains available for compatibility.
-
 ## Initialize
 
-
 Interactive initialization:
 
 ```bash
@@ -226,16 +225,7 @@ codew language --json
 
 `update` refreshes only Workspace-owned managed assets and never changes Agent directory authorization. Unknown local edits stop the batch before writes; review them or pass `--force` explicitly.
 
-## Monitor
-
-Monitor is an ordinary Nexus extension. Install it into a workspace and run its dashboard through the generic extension runtime:
-
-```bash
-codew extension install monitor --yes
-codew ext monitor serve --port 3211
-```
-
-The monitor binds to loopback, combines events from multiple initialized workspaces, and keeps hook reporting (`codew ext monitor report`) failure-open. Review and trust project hooks in Codex before relying on reports.
+## Completion
 
 ```bash
 codew completion --shell zsh

package/README.zh-CN.md

@@ -1,5 +1,7 @@
 # Code Workspace
 
+[English](README.md) | [简体中文](README.zh-CN.md)
+
 Code Workspace 是面向 Claude Code 与 Codex 的本地多项目注册表和安全边界层，负责工作区身份、项目路径与分支、Agent 指令、可写目录权限、校验以及可选监控。
 
 ## 环境要求
@@ -13,8 +15,6 @@ Code Workspace 是面向 Claude Code 与 Codex 的本地多项目注册表和安
 npm install -g code-workspace-zhuiyi@latest
 ```
 
-软件包提供 `code-workspace` 命令及短别名 `codew`。为保持兼容，旧别名 `code-w` 仍然可用。
-
 ## 初始化
 
 交互式初始化：
@@ -223,17 +223,6 @@ codew language --json
 
 `update` 只刷新 Workspace 自有托管资产，绝不会修改 Agent 目录授权。遇到未知本地修改时，会在任何写入前终止批次；请先审查修改，或显式传入 `--force`。
 
-## 监控
-
-监控以 Nexus 中的 `monitor` 扩展提供。先在 Workspace 中安装扩展，再通过通用扩展运行时启动面板：
-
-```bash
-codew extension install monitor --yes
-codew ext monitor serve --port 3211
-```
-
-监控服务仅绑定 loopback，可汇总多个已初始化工作区的事件；hook 上报（`codew ext monitor report`）失败不会阻断 Agent。依赖监控前，请在 Codex 中检查并信任项目 hook。
-
 ## 命令补全
 
 ```bash

package/artifacts/manifest.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 2,
-  "releaseVersion": "1.0.0-beta.4",
+  "releaseVersion": "1.0.0",
   "requirements": {
     "node": ">=20.19.0"
   },

package/artifacts/templates/extension-init/extension/init.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+"use strict";
+
+// TODO: implement the extension init protocol.

package/artifacts/templates/extension-init/gitignore

@@ -0,0 +1 @@
+/dist

package/docs/extension-development/extension-development-guide.zh-CN.md

@@ -35,7 +35,27 @@ Host 负责确认、校验、事务提交、状态记录、升级和卸载。
 
 ## 2. 包目录
 
-系统扩展使用固定版本目录；普通扩展在独立仓库中维护并发布到 Nexus：
+系统扩展使用固定版本目录；普通扩展建议使用 `extension init` 创建最小 package 空壳，再按 Extension Spec 添加能力并发布到 Nexus：
+
+```bash
+codew extension init ./example-extension --yes
+```
+
+开发 package 的目录结构为：
+
+```text
+example-extension/
+├── .gitignore
+├── README.md
+├── extension/
+│   ├── manifest.json
+│   └── init.js
+└── package.json
+```
+
+初始化产物中的静态文件模板位于仓库的 `artifacts/templates/extension-init/`。后续调整 README、`.gitignore` 或 `extension/` 下的默认文件时，直接修改该模板目录即可；其中 `gitignore` 会在生成时映射为 `.gitignore`，以避免 npm 发布包排除点文件。`extension init` 只负责注入元数据、生成摘要并写入 package envelope。
+
+系统扩展仍使用固定版本目录：
 
 ```text
 extensions/<extension-id>/<version>/
@@ -45,7 +65,7 @@ extensions/<extension-id>/<version>/
     └── SKILL.md
 ```
 
-外部扩展仓库可以使用任意仓库根目录，但交给 `extension pack` 的 `<source>` 必须直接指向包含 `manifest.json` 和 `init.js` 的版本目录。
+公开 CLI 的 `extension pack <source>` 要求 `<source>` 直接指向包含 `package.json` 和 `extension/` 的 package 根目录。空壳尚未声明 `outputs`、`hooks` 或 `runtime` 时不能打包。
 
 命名要求：
 
@@ -53,11 +73,18 @@ extensions/<extension-id>/<version>/
 - `version` 必须是完整 SemVer，例如 `1.0.0`；
 - 已发布版本目录不可修改；新实现创建新的版本目录。
 
-不要在扩展目录中添加运输用 `package.json`。npm 包装由 `extension pack` 生成；真实扩展目录的 `packageSha256` 是 Extension 身份的一部分。
+根目录 `package.json` 是固定格式的 transport envelope，不要添加 `dependencies`、`scripts` 或其他 npm lifecycle 字段。`extension pack` 只校验并打包这个 envelope，不会自动生成或修改它。
+
+`extension init` 只询问扩展 id、显示名称、描述和版本，不预设扩展是 Skill、MCP、Hook 还是 Runtime。完成 manifest 能力声明后，再运行：
+
+```bash
+codew extension digest update ./example-extension --yes
+codew extension pack ./example-extension --output ./dist/extensions --json
+```
 
 ## 3. manifest
 
-Spec v1 使用 manifest schema v3。最小示例：
+Spec v1 使用 manifest schema v3。下面是声明了一个 file output 的最小完整示例；`extension init` 生成的空壳会在用户添加能力前缺少 `outputs`、`hooks` 或 `runtime`：
 
 ```json
 {
@@ -89,7 +116,13 @@ Spec v1 使用 manifest schema v3。最小示例：
 node -e "process.stdout.write(require('node:crypto').createHash('sha256').update(require('node:fs').readFileSync('extensions/example-extension/1.0.0/init.js')).digest('hex'))"
 ```
 
-每次修改 `init.js` 后都必须更新 `entrySha256`。其他文件不需要手工写摘要；Host 和打包器会计算完整目录摘要。
+每次修改 `init.js` 或 `extension/` 下其他文件后，使用 CLI 同步摘要：
+
+```bash
+codew extension digest update ./example-extension --yes
+```
+
+该命令会先更新 `extension/manifest.json.entrySha256`，再更新 `package.json.codeWorkspace.packageSha256`。
 
 ### 3.1 身份与展示
 
@@ -296,10 +329,10 @@ codew extension upgrade example-extension --yes
 
 ## 6. npm/Nexus 打包
 
-打包单个版本目录：
+打包单个 package 根目录：
 
 ```bash
-code-workspace extension pack extensions/example-extension/1.0.0 --output dist/extensions --json
+code-workspace extension pack ./example-extension --output dist/extensions --json
 ```
 
 输出目录缺失时会递归创建。目标文件已存在时命令拒绝覆盖；重复打包前使用新的输出目录，或清理上一次构建产物。
@@ -331,14 +364,16 @@ npm 身份固定映射为：
 
 打包器会：
 
-- 校验 manifest、入口摘要、目录类型和 Extension Spec；
-- 生成不含 dependencies、bundled dependencies 和 scripts 的 envelope；
+- 校验 package envelope、manifest、入口摘要、目录类型和 Extension Spec；
+- 原样保留已验证的 `package.json`，不生成或修改 envelope；
 - 只归档普通文件；
 - 拒绝符号链接、硬链接、特殊文件、路径逃逸和重复路径；
 - 限制最多 1024 个文件、单文件 2 MiB、载荷总计 16 MiB、envelope 64 KiB；
 - 重新读取 tarball 并验证 envelope、manifest、入口和 package digest；
 - 使用同目录临时文件并原子提交输出。
 
+开发 package 的 README 和其他根目录文件不会进入 tarball；最终内容严格由 `package.json.files` 中的 `extension` 决定。
+
 成功 JSON 返回 npm name、扩展身份、tarball 绝对路径、tarball integrity、manifest/entry/package digest 和文件清单。
 
 ## 7. 发布边界

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "code-workspace-zhuiyi",
-  "version": "1.0.0-beta.4",
+  "version": "1.0.0",
   "description": "Local multi-project registry and safety layer for AI coding workspaces",
   "author": "icebearx-ai",
   "license": "MIT",

package/src/cli/commands/extension.js

@@ -1,3 +1,4 @@
+const path = require("node:path");
 const { LOCAL_DIRECTORY, loadState } = require("../../core/config");
 const { WorkspaceError } = require("../../core/errors");
 const {
@@ -13,7 +14,8 @@ const {
 const { loadInitManifest } = require("../../core/init");
 const { acquireInitLock } = require("../../core/init-lock");
 const { defaultExtensionStoreRoot } = require("../../core/extension-store");
-const { packExtensionToDirectory } = require("../../core/extension-package");
+const { packExtensionSourceToDirectory } = require("../../core/extension-package");
+const { digestUpdate, scaffoldExtensionPackage } = require("../../core/extension-scaffold");
 const { resolveExtensionSettings } = require("../../core/extension-settings");
 const { DEFAULT_NEXUS_REGISTRY } = require("../../core/nexus-extension-provider");
 const {
@@ -159,6 +161,24 @@ function uninstallResultEntry(entry) {
   };
 }
 
+function sameUninstallTarget(expected, current) {
+  return expected.id === current.id
+    && expected.version === current.version
+    && (expected.packageSha256 || null) === (current.packageSha256 || null)
+    && JSON.stringify(expected.targets || []) === JSON.stringify(current.targets || []);
+}
+
+function refreshUninstallPlan(root, frozenPlan) {
+  const currentPlan = planExtensionUninstall(root, frozenPlan.id);
+  if (currentPlan.action !== frozenPlan.action || !sameUninstallTarget(frozenPlan, currentPlan)) {
+    throw new WorkspaceError("EXTENSION_STATE_CONFLICT", `Extension ${frozenPlan.id} changed after confirmation.`, {
+      extension: frozenPlan.id,
+      remediation: "Re-run extension search and review the current extension selection.",
+    });
+  }
+  return currentPlan;
+}
+
 function validateInstallOptions(invocation) {
   if (invocation.options.version) {
     if (invocation.args.length !== 1) {
@@ -382,7 +402,8 @@ async function executeExtensionSearch(invocation) {
   const uninstallResults = [];
   for (const plan of effectiveUninstallPlans) {
     try {
-      uninstallResults.push({ ...applyExtensionUninstall(plan, {
+      const currentPlan = refreshUninstallPlan(invocation.root, plan);
+      uninstallResults.push({ ...applyExtensionUninstall(currentPlan, {
         ...(dependencies || {}),
         extensionStoreRoot: dependencies.extensionStoreRoot || defaultExtensionStoreRoot(),
       }), action: "uninstall" });
@@ -539,7 +560,7 @@ async function executeExtensionPack(invocation) {
   const command = "extension.pack";
   const dependencies = invocation.dependencies || {};
   const settings = resolveExtensionSettings(dependencies);
-  const result = await packExtensionToDirectory(invocation.args[0], invocation.options.output, {
+  const result = await packExtensionSourceToDirectory(invocation.args[0], invocation.options.output, {
     ...dependencies,
     scope: dependencies.scope || settings.values.scope,
   });
@@ -550,9 +571,56 @@ async function executeExtensionPack(invocation) {
   );
 }
 
+async function collectExtensionInitOptions(invocation, target) {
+  const options = { ...invocation.options };
+  const interactive = !options.json && options.yes !== true && process.stdin.isTTY && process.stdout.isTTY;
+  if (!interactive) return options;
+  const ui = await createInteractiveUi({
+    cancelCode: "EXTENSION_INIT_CANCELLED",
+    cancelMessage: "Extension initialization cancelled. No changes were made.",
+  });
+  const defaultId = path.basename(path.resolve(target)).toLowerCase();
+  ui.intro("Create Code Workspace extension package");
+  if (options.id === undefined) options.id = await ui.text("Extension id", defaultId);
+  const defaultName = String(options.id || defaultId).split("-").map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
+  if (options.name === undefined) options.name = await ui.text("Extension name", defaultName);
+  if (options.description === undefined) options.description = await ui.text("Description", "Code Workspace extension.");
+  if (options.version === undefined) options.version = await ui.text("Version", "0.1.0");
+  ui.close("Extension metadata ready.");
+  return options;
+}
+
+async function executeExtensionInit(invocation) {
+  const command = "extension.init";
+  const target = invocation.args[0] || ".";
+  const options = await collectExtensionInitOptions(invocation, target);
+  const pathText = path.resolve(target);
+  const planText = `Create extension package shell in ${pathText}:\n  CREATE package.json\n  CREATE extension/manifest.json\n  CREATE extension/init.js\nContinue?`;
+  if (!(await confirm(planText, options))) throw new WorkspaceError("CLI_CANCELLED", "Extension package initialization cancelled.");
+  const result = scaffoldExtensionPackage(target, options);
+  const text = result.action === "skip"
+    ? `Extension package is already current: ${result.path}.`
+    : `Created extension package shell in ${result.path}.\nNext: add outputs, hooks, or runtime to extension/manifest.json.`;
+  return success(command, result, text);
+}
+
+async function executeExtensionDigestUpdate(invocation) {
+  const command = "extension.digest.update";
+  const target = invocation.args[0] || ".";
+  if (!(await confirm(`Update extension digests in ${path.resolve(target)}?`, invocation.options))) {
+    throw new WorkspaceError("CLI_CANCELLED", "Extension digest update cancelled.");
+  }
+  const result = digestUpdate(target);
+  return success(command, result, result.action === "skip"
+    ? `Extension digests are already current: ${result.path}.`
+    : `Updated extension digests in ${result.path}.`);
+}
+
 async function executeExtension(invocation) {
   const command = invocation.definition.path.join(".");
   if (command === "extension.pack") return await executeExtensionPack(invocation);
+  if (command === "extension.init") return await executeExtensionInit(invocation);
+  if (command === "extension.digest.update") return await executeExtensionDigestUpdate(invocation);
   if (command === "extension.search") {
     const dependencies = invocation.dependencies || {};
     const interactive = dependencies.interactive ?? (!invocation.options.json && invocation.options.yes !== true && process.stdin.isTTY && process.stdout.isTTY);
@@ -581,6 +649,8 @@ module.exports = {
   executeExtension,
   executeExtensionInstall,
   executeExtensionPack,
+  executeExtensionInit,
+  executeExtensionDigestUpdate,
   executeExtensionSearch,
   executeExtensionInfo,
   executeExtensionUninstall,

package/src/cli/commands/init.js

@@ -44,6 +44,24 @@ function stateWithPlans(state, plans) {
   return next;
 }
 
+function sameUninstallTarget(expected, current) {
+  return expected.id === current.id
+    && expected.version === current.version
+    && (expected.packageSha256 || null) === (current.packageSha256 || null)
+    && JSON.stringify(expected.targets || []) === JSON.stringify(current.targets || []);
+}
+
+function refreshUninstallPlan(root, frozenPlan) {
+  const currentPlan = planExtensionUninstall(root, frozenPlan.id);
+  if (currentPlan.action !== frozenPlan.action || !sameUninstallTarget(frozenPlan, currentPlan)) {
+    throw new WorkspaceError("EXTENSION_STATE_CONFLICT", `Extension ${frozenPlan.id} changed after confirmation.`, {
+      extension: frozenPlan.id,
+      remediation: "Re-run init and review the current extension selection.",
+    });
+  }
+  return currentPlan;
+}
+
 function migrationData(plan) {
   if (!plan) return null;
   return {
@@ -258,8 +276,9 @@ async function executeInitUnlocked(invocation, root) {
   const ordinaryRemovalResults = [];
   const ordinaryRemovalDiagnostics = [];
   for (const removalPlan of ordinaryRemovalPlans) {
-    const planToApply = typeof removalPlan === "string" ? planExtensionUninstall(root, removalPlan) : removalPlan;
+    const frozenPlan = typeof removalPlan === "string" ? planExtensionUninstall(root, removalPlan) : removalPlan;
     try {
+      const planToApply = refreshUninstallPlan(root, frozenPlan);
       const removal = applyExtensionUninstall(planToApply, {
         extensionStoreRoot: options.extensionStoreRoot || dependencies.extensionStoreRoot || defaultExtensionStoreRoot(),
       });

package/src/cli/registry.js

@@ -23,6 +23,8 @@ const COMMAND_SUMMARIES = {
   "extension install": "Install one or more extensions into the Workspace",
   "extension uninstall": "Uninstall one ordinary extension from the Workspace",
   "extension pack": "Create a verified npm tarball from an extension package",
+  "extension init": "Create an extension package shell",
+  "extension digest update": "Update extension entry and package digests",
   "extension search": "Search, install, or update extensions (TTY); read-only results in JSON/non-TTY",
   "extension info": "Show extension metadata from the configured Registry",
   "extension upgrade": "Upgrade installed ordinary extensions",
@@ -70,6 +72,10 @@ const COMMANDS = [
   } },
   { path: ["extension", "uninstall"], args: [{ name: "name", required: true }], workspace: "required", config: [], interaction: "required", effects: "planned-write", options: { yes: { type: "boolean" } } },
   { path: ["extension", "pack"], args: [{ name: "source", required: true }], workspace: "none", config: [], interaction: "never", effects: "planned-write", options: { output: { type: "string", required: true } } },
+  { path: ["extension", "init"], args: [{ name: "path", required: false }], workspace: "none", config: [], interaction: "optional", effects: "planned-write", options: {
+    id: { type: "string" }, name: { type: "string" }, description: { type: "string" }, version: { type: "string" }, yes: { type: "boolean" },
+  } },
+  { path: ["extension", "digest", "update"], args: [{ name: "path", required: false }], workspace: "none", config: [], interaction: "optional", effects: "planned-write", options: { yes: { type: "boolean" } } },
   { path: ["extension", "search"], args: [{ name: "query", required: false }], workspace: "required", config: ["identity", "language"], interaction: "required", effects: "planned-write", options: { yes: { type: "boolean" } } },
   { path: ["extension", "info"], args: [{ name: "name", required: true }], workspace: "none", config: [], interaction: "never", effects: "external", options: {} },
   { path: ["extension", "upgrade"], args: [{ name: "name", required: true, variadic: true }], workspace: "required", config: ["identity", "language"], interaction: "required", effects: "planned-write", options: { yes: { type: "boolean" }, offline: { type: "boolean" } } },

package/src/core/extension-package.js

@@ -590,6 +590,209 @@ async function hashFile(file, algorithm, encoding) {
   return hash.digest(encoding);
 }
 
+function readPackageJson(file) {
+  let value;
+  try {
+    value = JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch (error) {
+    throw packageError("EXTENSION_PACKAGE_JSON_INVALID", `Cannot parse package.json: ${error.message}`, { path: file });
+  }
+  return value;
+}
+
+function inspectExtensionSourcePackage(source, options = {}) {
+  const packageRoot = path.resolve(source);
+  let stat;
+  try {
+    stat = fs.lstatSync(packageRoot);
+  } catch (error) {
+    throw packageError("EXTENSION_PACKAGE_MISSING", `Extension package directory is missing: ${packageRoot}`, {
+      path: packageRoot,
+      cause: error.code,
+    });
+  }
+  if (!stat.isDirectory() || stat.isSymbolicLink()) {
+    throw packageError("EXTENSION_PACKAGE_INVALID", `Extension package must be a regular directory: ${packageRoot}`, { path: packageRoot });
+  }
+  const packageJsonFile = path.join(packageRoot, "package.json");
+  const extensionRoot = path.join(packageRoot, EXTENSION_PACKAGE_ROOT);
+  let packageJsonStat;
+  try { packageJsonStat = fs.lstatSync(packageJsonFile); } catch (error) {
+    throw packageError("EXTENSION_NPM_ENVELOPE_MISSING", `Extension package is missing package.json: ${packageJsonFile}`, { path: packageJsonFile, cause: error.code });
+  }
+  if (!packageJsonStat.isFile() || packageJsonStat.isSymbolicLink()) {
+    throw packageError("EXTENSION_NPM_ENVELOPE_INVALID", `package.json must be a regular file: ${packageJsonFile}`, { path: packageJsonFile });
+  }
+  let extensionStat;
+  try { extensionStat = fs.lstatSync(extensionRoot); } catch (error) {
+    throw packageError("EXTENSION_PACKAGE_LAYOUT_INVALID", `Extension package is missing extension/: ${extensionRoot}`, { path: extensionRoot, cause: error.code });
+  }
+  if (!extensionStat.isDirectory() || extensionStat.isSymbolicLink()) {
+    throw packageError("EXTENSION_PACKAGE_LAYOUT_INVALID", `Extension package root must be a regular directory: ${extensionRoot}`, { path: extensionRoot });
+  }
+  const packageJsonBytes = fs.readFileSync(packageJsonFile);
+  const rawEnvelope = readPackageJson(packageJsonFile);
+  const envelope = validateExtensionTransportEnvelope(rawEnvelope, {
+    ...(options.scope ? { expectedScope: options.scope } : {}),
+  });
+  const inspected = inspectExtensionPackageDirectory(extensionRoot, {
+    expectedId: envelope.codeWorkspace.extensionId,
+    expectedVersion: envelope.version,
+    expectedExtensionSpecVersion: envelope.codeWorkspace.extensionSpecVersion,
+    ...(options.supportedExtensionSpecVersions ? { supportedExtensionSpecVersions: options.supportedExtensionSpecVersions } : {}),
+    ...(options.protectedTargets ? { protectedTargets: options.protectedTargets } : {}),
+  });
+  try {
+    validateExtensionTransportEnvelope(rawEnvelope, {
+      expectedId: inspected.id,
+      expectedVersion: inspected.version,
+      expectedExtensionSpecVersion: inspected.extensionSpecVersion,
+      expectedPackageSha256: inspected.packageSha256,
+      ...(options.scope ? { expectedScope: options.scope } : {}),
+    });
+  } catch (error) {
+    if (error.code === "EXTENSION_NPM_PACKAGE_DIGEST_MISMATCH") {
+      error.details = { ...(error.details || {}), remediation: "Run codew extension digest update <package-path> before packing." };
+    }
+    throw error;
+  }
+  if (envelope.description !== inspected.manifest.description) {
+    throw packageError("EXTENSION_NPM_IDENTITY_MISMATCH", "npm transport description does not match the Extension manifest", {
+      field: "description",
+      expected: inspected.manifest.description,
+      actual: envelope.description,
+    });
+  }
+  return Object.freeze({
+    ...inspected,
+    packageRoot,
+    extensionRoot,
+    packageJsonFile,
+    packageJsonBytes,
+    envelope,
+  });
+}
+
+function assertSourcePackageUnchanged(source, inspected, files, options = {}) {
+  let current;
+  try {
+    current = inspectExtensionSourcePackage(source, options);
+  } catch (error) {
+    throw packageError("EXTENSION_PACKAGE_CHANGED", `Extension package changed while packing: ${inspected.id}@${inspected.version}`, {
+      extension: inspected.id,
+      version: inspected.version,
+      cause: error.code,
+    });
+  }
+  const currentFiles = collectPackageFiles(current.extensionRoot, options.limits);
+  const digestMatches = current.packageJsonBytes.equals(inspected.packageJsonBytes)
+    && current.packageSha256 === inspected.packageSha256
+    && current.manifestSha256 === inspected.manifestSha256
+    && current.entrySha256 === inspected.entrySha256;
+  const filesMatch = currentFiles.length === files.length && currentFiles.every((file, index) =>
+    file.relative === files[index].relative && file.size === files[index].size && file.mode === files[index].mode && file.sha256 === files[index].sha256
+  );
+  if (!digestMatches || !filesMatch) {
+    throw packageError("EXTENSION_PACKAGE_CHANGED", `Extension package changed while packing: ${inspected.id}@${inspected.version}`, {
+      extension: inspected.id,
+      version: inspected.version,
+    });
+  }
+}
+
+async function packExtensionSourceToDirectory(source, outputDirectory, options = {}) {
+  // Keep the repository's built-in legacy extension layout packable while the
+  // public authoring workflow uses a package-root envelope.
+  if (!fs.existsSync(path.join(path.resolve(source), "package.json"))) {
+    return packExtensionToDirectory(source, outputDirectory, options);
+  }
+  const limits = normalizeLimits(options.limits);
+  const outputRoot = path.resolve(outputDirectory);
+  const inspected = inspectExtensionSourcePackage(source, {
+    ...(options.scope ? { scope: options.scope } : {}),
+    ...(options.supportedExtensionSpecVersions ? { supportedExtensionSpecVersions: options.supportedExtensionSpecVersions } : {}),
+    ...(options.protectedTargets ? { protectedTargets: options.protectedTargets } : {}),
+  });
+  const files = collectPackageFiles(inspected.extensionRoot, limits);
+  try {
+    fs.mkdirSync(outputRoot, { recursive: true });
+  } catch (error) {
+    throw packageError("EXTENSION_PACK_OUTPUT_CREATE_FAILED", `Cannot create output directory: ${outputRoot}`, { path: outputRoot, cause: error.code });
+  }
+  const outputStat = fs.lstatSync(outputRoot);
+  if (!outputStat.isDirectory() || outputStat.isSymbolicLink()) {
+    throw packageError("EXTENSION_PACK_OUTPUT_INVALID", `Output must be a regular directory: ${outputRoot}`, { path: outputRoot });
+  }
+  const filename = extensionNpmTarballFilename(inspected.id, inspected.version, options.scope);
+  const target = path.join(outputRoot, filename);
+  if (fs.existsSync(target)) {
+    throw packageError("EXTENSION_PACK_OUTPUT_EXISTS", `Extension package output already exists: ${target}`, {
+      path: target,
+      remediation: "Move or remove the existing tarball, or choose another output directory.",
+    });
+  }
+  const temporaryTarget = path.join(outputRoot, `.${filename}.${process.pid}.${crypto.randomUUID()}.tmp`);
+  const fd = fs.openSync(temporaryTarget, "wx", 0o600);
+  fs.closeSync(fd);
+  let targetReserved = false;
+  try {
+    try {
+      await writeTransportTarball({
+        sourceRoot: inspected.extensionRoot,
+        files,
+        envelopeBytes: inspected.packageJsonBytes,
+        target: temporaryTarget,
+        limits,
+      });
+    } catch (error) {
+      if (error instanceof WorkspaceError) throw error;
+      throw packageError("EXTENSION_TARBALL_CREATE_FAILED", `Cannot create extension npm tarball: ${error.message}`, { path: target, cause: error.code });
+    }
+    assertSourcePackageUnchanged(source, inspected, files, { ...options, limits });
+    let verified;
+    try {
+      verified = await inspectExtensionTransportTarball(temporaryTarget, {
+        expectedId: inspected.id,
+        expectedVersion: inspected.version,
+        expectedExtensionSpecVersion: inspected.extensionSpecVersion,
+        expectedPackageSha256: inspected.packageSha256,
+        ...(options.scope ? { expectedScope: options.scope } : {}),
+        expectedFiles: files,
+        limits,
+      });
+    } catch (error) {
+      if (error instanceof WorkspaceError) throw error;
+      throw packageError("EXTENSION_TARBALL_VERIFY_FAILED", `Cannot verify extension npm tarball: ${error.message}`, { path: target, cause: error.code });
+    }
+    if (!verified || verified.packageSha256 !== inspected.packageSha256 || verified.manifestSha256 !== inspected.manifestSha256 || verified.entrySha256 !== inspected.entrySha256) {
+      throw packageError("EXTENSION_TARBALL_VERIFY_FAILED", `Extension npm tarball verification failed: ${inspected.id}@${inspected.version}`, { extension: inspected.id, version: inspected.version });
+    }
+    const tarballBytes = fs.statSync(temporaryTarget).size;
+    const integrity = `sha512-${await hashFile(temporaryTarget, "sha512", "base64")}`;
+    const targetFd = fs.openSync(target, "wx", 0o600);
+    fs.closeSync(targetFd);
+    targetReserved = true;
+    fs.renameSync(temporaryTarget, target);
+    targetReserved = false;
+    return Object.freeze({
+      schemaVersion: 1,
+      extensionId: inspected.id,
+      version: inspected.version,
+      extensionSpecVersion: inspected.extensionSpecVersion,
+      npmName: inspected.envelope.name,
+      tarball: Object.freeze({ path: target, filename, bytes: tarballBytes, integrity, files: verified.files }),
+      manifestSha256: inspected.manifestSha256,
+      entrySha256: inspected.entrySha256,
+      packageSha256: inspected.packageSha256,
+    });
+  } finally {
+    try { fs.unlinkSync(temporaryTarget); } catch { /* cleanup is best-effort */ }
+    if (targetReserved) {
+      try { fs.unlinkSync(target); } catch { /* cleanup is best-effort */ }
+    }
+  }
+}
+
 async function packExtensionToDirectory(source, outputDirectory, options = {}) {
   const limits = normalizeLimits(options.limits);
   const outputRoot = path.resolve(outputDirectory);
@@ -733,6 +936,8 @@ module.exports = {
   normalizeNpmScope,
   extractExtensionTransportTarball,
   inspectExtensionTransportTarball,
+  inspectExtensionSourcePackage,
+  packExtensionSourceToDirectory,
   packExtensionToDirectory,
   validateExtensionTransportEnvelope,
 };

package/src/core/extension-scaffold.js

@@ -0,0 +1,212 @@
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const { atomicWrite, sha256 } = require("./fs");
+const { createFileTransaction } = require("./transaction");
+const { directoryDigest } = require("./directory-digest");
+const { EXTENSION_NAME_PATTERN, parseSemver, validateManifestEnvelope } = require("./extensions");
+const { validateExtensionTransportEnvelope } = require("./extension-package");
+const { WorkspaceError } = require("./errors");
+
+function scaffoldError(code, message, details = {}) {
+  return new WorkspaceError(code, message, details);
+}
+
+function titleFromId(id) {
+  return id.split("-").map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
+}
+
+function readJson(file, code) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch (error) {
+    throw scaffoldError(code, `Cannot parse JSON file: ${file}`, { path: file, cause: error.message });
+  }
+}
+
+function validateScaffoldMetadata(options = {}, targetRoot) {
+  const derivedId = path.basename(targetRoot).toLowerCase();
+  const id = String(options.id || derivedId).trim();
+  if (!EXTENSION_NAME_PATTERN.test(id)) throw scaffoldError("EXTENSION_NAME_INVALID", `Invalid extension name: ${id || "<missing>"}`, { extension: id || null });
+  const name = String(options.name || titleFromId(id)).trim();
+  const description = String(options.description || "Code Workspace extension.").trim();
+  const version = parseSemver(options.version || "0.1.0").raw;
+  if (!name || [...name].length > 100) throw scaffoldError("EXTENSION_MANIFEST_INVALID", `Extension display name is invalid: ${id}`, { extension: id });
+  if (!description || [...description].length > 60 || /[\r\n]/.test(description)) throw scaffoldError("EXTENSION_MANIFEST_INVALID", `Extension description is invalid: ${id}`, { extension: id });
+  return Object.freeze({ id, name, description, version });
+}
+
+const SCAFFOLD_TEMPLATE_ROOT = path.join(__dirname, "..", "..", "artifacts", "templates", "extension-init");
+
+function readTemplateFiles(root = SCAFFOLD_TEMPLATE_ROOT, current = root, result = {}) {
+  let entries;
+  try {
+    entries = fs.readdirSync(current, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name));
+  } catch (error) {
+    throw scaffoldError("EXTENSION_TEMPLATE_INVALID", `Cannot read extension init template: ${root}`, { path: root, cause: error.code || error.message });
+  }
+  for (const entry of entries) {
+    const file = path.join(current, entry.name);
+    const relative = path.relative(root, file).split(path.sep).join("/");
+    const stat = fs.lstatSync(file);
+    if (stat.isSymbolicLink()) throw scaffoldError("EXTENSION_TEMPLATE_INVALID", `Extension init template contains a symbolic link: ${relative}`, { path: relative });
+    if (stat.isDirectory()) readTemplateFiles(root, file, result);
+    else if (stat.isFile()) result[relative === "gitignore" ? ".gitignore" : relative] = fs.readFileSync(file);
+    else throw scaffoldError("EXTENSION_TEMPLATE_INVALID", `Extension init template contains a special file: ${relative}`, { path: relative });
+  }
+  return result;
+}
+
+function validateShellManifest(raw) {
+  const envelope = validateManifestEnvelope(raw);
+  if (raw.schemaVersion !== 3 || raw.experimental !== true || raw.entry !== "init.js") {
+    throw scaffoldError("EXTENSION_MANIFEST_INVALID", "Extension shell manifest must use schemaVersion 3, experimental true, and entry init.js", { extension: envelope.id });
+  }
+  if (!/^[a-f0-9]{64}$/.test(raw.entrySha256 || "")) throw scaffoldError("EXTENSION_MANIFEST_INVALID", `Extension ${envelope.id} entrySha256 is invalid`, { extension: envelope.id });
+  if (!Number.isInteger(raw.timeoutMs) || raw.timeoutMs < 1 || raw.timeoutMs > 300000) throw scaffoldError("EXTENSION_MANIFEST_INVALID", `Extension ${envelope.id} timeoutMs is invalid`, { extension: envelope.id });
+  return envelope;
+}
+
+function readRelativeFiles(root, current = root, result = []) {
+  for (const entry of fs.readdirSync(current, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name))) {
+    const file = path.join(current, entry.name);
+    const relative = path.relative(root, file).split(path.sep).join("/");
+    const stat = fs.lstatSync(file);
+    if (stat.isSymbolicLink()) throw scaffoldError("EXTENSION_INIT_TARGET_EXISTS", `Scaffold target contains a symbolic link: ${relative}`, { path: relative });
+    if (stat.isDirectory()) readRelativeFiles(root, file, result);
+    else if (stat.isFile()) result.push(relative);
+    else throw scaffoldError("EXTENSION_INIT_TARGET_EXISTS", `Scaffold target contains a special file: ${relative}`, { path: relative });
+  }
+  return result;
+}
+
+function filesMatch(root, files) {
+  let actual;
+  try { actual = readRelativeFiles(root); } catch { return false; }
+  const expected = Object.keys(files).sort();
+  if (actual.length !== expected.length || actual.some((entry, index) => entry !== expected[index])) return false;
+  return expected.every((relative) => Buffer.from(fs.readFileSync(path.join(root, ...relative.split("/")))).equals(files[relative]));
+}
+
+function commitDirectory(temporary, target) {
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  if (!fs.existsSync(target)) {
+    fs.renameSync(temporary, target);
+    return;
+  }
+  const backup = `${target}.${process.pid}.${crypto.randomUUID()}.old`;
+  let moved = false;
+  try {
+    fs.renameSync(target, backup);
+    moved = true;
+    fs.renameSync(temporary, target);
+    fs.rmSync(backup, { recursive: true, force: true });
+  } catch (error) {
+    try { if (fs.existsSync(target)) fs.rmSync(target, { recursive: true, force: true }); } catch {}
+    try { if (moved && fs.existsSync(backup)) fs.renameSync(backup, target); } catch {}
+    throw scaffoldError("EXTENSION_INIT_COMMIT_FAILED", `Cannot commit extension package: ${target}`, { path: target, cause: error.code || error.message });
+  }
+}
+
+function shellEnvelope(metadata, packageSha256) {
+  return {
+    name: `@codew-ext/${metadata.id}`,
+    version: metadata.version,
+    description: metadata.description,
+    keywords: ["code-workspace-extension"],
+    codeWorkspace: { schemaVersion: 1, extensionId: metadata.id, extensionSpecVersion: 1, packageRoot: "extension", packageSha256 },
+    files: ["extension"],
+  };
+}
+
+function scaffoldExtensionPackage(target, options = {}) {
+  const targetRoot = path.resolve(target || ".");
+  const metadata = validateScaffoldMetadata(options, targetRoot);
+  const templateFiles = readTemplateFiles();
+  const entry = templateFiles["extension/init.js"];
+  if (!entry) throw scaffoldError("EXTENSION_TEMPLATE_INVALID", "Extension init template must contain extension/init.js", { path: "extension/init.js" });
+  const manifest = {
+    schemaVersion: 3,
+    extensionSpecVersion: 1,
+    experimental: true,
+    id: metadata.id,
+    name: metadata.name,
+    description: metadata.description,
+    version: metadata.version,
+    entry: "init.js",
+    entrySha256: sha256(Buffer.from(entry, "utf8")),
+    timeoutMs: 30000,
+  };
+  const files = {
+    ...templateFiles,
+    "package.json": null,
+    "extension/manifest.json": Buffer.from(`${JSON.stringify(manifest, null, 2)}\n`, "utf8"),
+  };
+  const temporary = fs.mkdtempSync(path.join(path.dirname(targetRoot), `.${path.basename(targetRoot)}-`));
+  try {
+    for (const [relative, content] of Object.entries(files)) {
+      if (!content) continue;
+      const file = path.join(temporary, ...relative.split("/"));
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      fs.writeFileSync(file, content, { mode: relative.endsWith(".js") ? 0o755 : 0o644 });
+    }
+    const packageSha256 = directoryDigest(path.join(temporary, "extension"));
+    const envelope = shellEnvelope(metadata, packageSha256);
+    validateExtensionTransportEnvelope(envelope, { expectedId: metadata.id, expectedVersion: metadata.version, expectedExtensionSpecVersion: 1, expectedPackageSha256: packageSha256 });
+    files["package.json"] = Buffer.from(`${JSON.stringify(envelope, null, 2)}\n`, "utf8");
+    fs.writeFileSync(path.join(temporary, "package.json"), files["package.json"]);
+    if (fs.existsSync(targetRoot)) {
+      const stat = fs.lstatSync(targetRoot);
+      if (!stat.isDirectory() || stat.isSymbolicLink()) throw scaffoldError("EXTENSION_INIT_TARGET_EXISTS", `Scaffold target is not a regular directory: ${targetRoot}`, { path: targetRoot });
+      if (filesMatch(targetRoot, files)) return Object.freeze({ action: "skip", reason: "already-current", path: targetRoot, extension: metadata, files: Object.keys(files).sort() });
+      if (fs.readdirSync(targetRoot).length > 0) throw scaffoldError("EXTENSION_INIT_TARGET_EXISTS", `Scaffold target is not empty: ${targetRoot}`, { path: targetRoot, remediation: "Choose another directory or remove its files before running extension init." });
+    }
+    commitDirectory(temporary, targetRoot);
+    return Object.freeze({ action: "created", path: targetRoot, extension: metadata, files: Object.keys(files).sort() });
+  } finally {
+    try { fs.rmSync(temporary, { recursive: true, force: true }); } catch {}
+  }
+}
+
+function digestUpdate(target) {
+  const packageRoot = path.resolve(target || ".");
+  const packageJsonFile = path.join(packageRoot, "package.json");
+  const extensionRoot = path.join(packageRoot, "extension");
+  const manifestFile = path.join(extensionRoot, "manifest.json");
+  const rawPackage = readJson(packageJsonFile, "EXTENSION_NPM_ENVELOPE_INVALID");
+  const rawManifest = readJson(manifestFile, "EXTENSION_MANIFEST_PARSE_FAILED");
+  const manifest = validateShellManifest(rawManifest);
+  validateExtensionTransportEnvelope(rawPackage, { expectedId: manifest.id, expectedVersion: manifest.version, expectedExtensionSpecVersion: manifest.extensionSpecVersion });
+  if (rawPackage.description !== rawManifest.description) throw scaffoldError("EXTENSION_NPM_IDENTITY_MISMATCH", "npm transport description does not match the Extension manifest", { field: "description", expected: rawManifest.description, actual: rawPackage.description });
+  const entryFile = path.join(extensionRoot, ...rawManifest.entry.split("/"));
+  if (!fs.existsSync(entryFile)) throw scaffoldError("EXTENSION_ENTRY_MISSING", `Extension entry is missing: ${entryFile}`, { path: entryFile });
+  const nextManifest = { ...rawManifest, entrySha256: sha256(fs.readFileSync(entryFile)) };
+  const temporary = fs.mkdtempSync(path.join(os.tmpdir(), "code-workspace-digest-"));
+  try {
+    const tempExtension = path.join(temporary, "extension");
+    fs.cpSync(extensionRoot, tempExtension, { recursive: true, force: true });
+    fs.writeFileSync(path.join(tempExtension, "manifest.json"), `${JSON.stringify(nextManifest, null, 2)}\n`);
+    const packageSha256 = directoryDigest(tempExtension);
+    const nextPackage = { ...rawPackage, codeWorkspace: { ...rawPackage.codeWorkspace, packageSha256 } };
+    validateExtensionTransportEnvelope(nextPackage, { expectedId: manifest.id, expectedVersion: manifest.version, expectedExtensionSpecVersion: manifest.extensionSpecVersion, expectedPackageSha256: packageSha256 });
+    const nextManifestBytes = Buffer.from(`${JSON.stringify(nextManifest, null, 2)}\n`, "utf8");
+    const nextPackageBytes = Buffer.from(`${JSON.stringify(nextPackage, null, 2)}\n`, "utf8");
+    if (fs.readFileSync(packageJsonFile).equals(nextPackageBytes) && fs.readFileSync(manifestFile).equals(nextManifestBytes)) return Object.freeze({ action: "skip", reason: "already-current", path: packageRoot, extension: { id: manifest.id, version: manifest.version }, entrySha256: nextManifest.entrySha256, packageSha256, updatedFiles: [] });
+    const transaction = createFileTransaction([packageJsonFile, manifestFile]);
+    try {
+      atomicWrite(manifestFile, nextManifestBytes);
+      atomicWrite(packageJsonFile, nextPackageBytes);
+      transaction.commit();
+    } catch (error) {
+      transaction.rollback(error);
+      throw error;
+    }
+    return Object.freeze({ action: "updated", path: packageRoot, extension: { id: manifest.id, version: manifest.version }, entrySha256: nextManifest.entrySha256, packageSha256, updatedFiles: ["extension/manifest.json", "package.json"] });
+  } finally {
+    try { fs.rmSync(temporary, { recursive: true, force: true }); } catch {}
+  }
+}
+
+module.exports = { digestUpdate, scaffoldExtensionPackage, validateScaffoldMetadata };

package/src/core/extensions.js

@@ -307,7 +307,10 @@ function validateManifest(value, options = {}) {
     throw extensionError("EXTENSION_MANIFEST_INVALID", `Extension ${id} outputs must be an array`, { extension: id });
   }
   if ((!Array.isArray(manifest.outputs) || manifest.outputs.length === 0) && hooks.length === 0 && !runtime) {
-    throw extensionError("EXTENSION_MANIFEST_INVALID", `Extension ${id} must declare at least one output, Hook or runtime`, { extension: id });
+    throw extensionError("EXTENSION_MANIFEST_INVALID", `Extension ${id} must declare at least one output, Hook or runtime`, {
+      extension: id,
+      remediation: "Add outputs, hooks, or runtime to extension/manifest.json before packing.",
+    });
   }
   const ids = new Set();
   const declaredArtifacts = [];
@@ -435,6 +438,7 @@ function inspectExtensionPackageDirectory(source, options = {}) {
       version: manifest.version,
       expectedSha256: manifest.entrySha256,
       actualSha256: entrySha256,
+      remediation: "Run codew extension digest update <package-path> before packing.",
     });
   }
   return Object.freeze({