code-workspace-zhuiyi 1.0.0-beta.5 → 1.1.0

package/README.md

@@ -25,6 +25,8 @@ codew init .code-workspace
  
 `.code-workspace` is the directory name and can be determined by yourself.
 
+Interactive initialization asks for “Development mode: Yes/No”. New Workspaces default to “Yes”; existing Workspaces use their saved value as the default. Pass `--dev true` or `--dev false` to select it explicitly without prompting.
+
 Non-interactive initialization:
 
 ```bash

package/README.zh-CN.md

@@ -25,6 +25,8 @@ codew init .code-workspace
 
 `.code-workspace` 是目录名，可以自定义。
 
+交互式初始化会询问“开发模式：是/否”，新 Workspace 默认选择“是”；已有 Workspace 会以已保存的值作为默认选项。也可以通过 `--dev true` 或 `--dev false` 直接指定，不进入该选择。
+
 非交互式初始化：
 
 ```bash

package/artifacts/manifest.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 2,
-  "releaseVersion": "1.0.0-beta.5",
+  "releaseVersion": "1.1.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

@@ -45,12 +45,16 @@ codew extension init ./example-extension --yes
 
 ```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
@@ -120,6 +124,15 @@ codew extension digest update ./example-extension --yes
 
 该命令会先更新 `extension/manifest.json.entrySha256`，再更新 `package.json.codeWorkspace.packageSha256`。
 
+完成开发后，可以在上传 Registry 前使用最终 tarball 在本地 Workspace 安装测试：
+
+```bash
+codew extension pack ./example-extension --output ./dist
+codew extension install --local ./dist/codew-ext-example-extension-0.1.0.tgz --yes
+```
+
+`extension install --local` 只接受 `.tgz`，会复用正式安装的完整 tarball 校验、Extension Store 导入和 Workspace 事务；不支持直接安装源码目录，也不会覆盖相同 id/version 下的不同 package digest。`--local` 模式不能与 `--version`、`--allow-deprecated` 或 `--offline` 同时使用。
+
 ### 3.1 身份与展示
 
 - `schemaVersion` 必须是 `3`；

package/package.json

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

package/src/cli/commands/extension.js

@@ -14,6 +14,8 @@ const {
 const { loadInitManifest } = require("../../core/init");
 const { acquireInitLock } = require("../../core/init-lock");
 const { defaultExtensionStoreRoot } = require("../../core/extension-store");
+const { planLocalExtensionPackage } = require("../../core/extension-registry-lifecycle");
+const { importLocalExtensionTarball, prepareLocalExtensionTarball } = require("../../core/extension-local");
 const { packExtensionSourceToDirectory } = require("../../core/extension-package");
 const { digestUpdate, scaffoldExtensionPackage } = require("../../core/extension-scaffold");
 const { resolveExtensionSettings } = require("../../core/extension-settings");
@@ -207,6 +209,7 @@ function decorateBatchResults(batch, plans, options) {
 }
 
 async function executeExtensionInstall(invocation) {
+  if (invocation.options.local === true) return await executeExtensionInstallLocal(invocation);
   const command = "extension.install";
   const dependencies = registryDependencies(invocation.dependencies || {});
   validateInstallOptions(invocation);
@@ -315,6 +318,59 @@ async function executeExtensionInstall(invocation) {
   });
 }
 
+async function executeExtensionInstallLocal(invocation) {
+  const command = "extension.install";
+  const dependencies = invocation.dependencies || {};
+  if (invocation.args.length !== 1) {
+    throw new WorkspaceError("EXTENSION_INSTALL_MODE_CONFLICT", "--local requires exactly one tarball path and no extension names.", {
+      remediation: "Use `codew extension install --local <tarball> --yes`.",
+    });
+  }
+  if (invocation.options.version || invocation.options.allowDeprecated || invocation.options.offline) {
+    throw new WorkspaceError("EXTENSION_INSTALL_MODE_CONFLICT", "--local cannot be combined with Registry version, deprecation, or offline options.", {
+      remediation: "Remove --version, --allow-deprecated, and --offline when installing a local tarball.",
+    });
+  }
+  const storeRoot = dependencies.extensionStoreRoot || defaultExtensionStoreRoot();
+  const prepared = await prepareLocalExtensionTarball(invocation.args[0], dependencies);
+  try {
+    const stateInspection = inspectExtensionState(invocation.root);
+    const tools = resolveWorkspaceTools({ state: loadState(invocation.root), manifestTools: loadInitManifest().tools }).tools;
+    const plan = planLocalExtensionPackage(prepared.packageRecord, { tools, state: stateInspection.state });
+    const planText = formatInstallPlan([{ ...plan, source: "local" }]);
+    if (!(await (dependencies.confirm || confirm)(`${planText}\nContinue?`, invocation.options))) {
+      throw new WorkspaceError("CLI_CANCELLED", "Local extension installation cancelled.");
+    }
+    await importLocalExtensionTarball(invocation.args[0], { ...dependencies, extensionStoreRoot: storeRoot });
+    const workspace = invocation.config.workspace;
+    const batch = runExtensionBatch(invocation.root, [plan], (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: [plan.id],
+      useExtensionStore: true,
+      extensionStoreRoot: storeRoot,
+    });
+    const results = decorateBatchResults(batch, [plan], invocation.options);
+    const diagnostics = batch.results.filter((item) => item.status === "failed").map((item) => ({
+      code: item.code || "EXTENSION_LOCAL_INSTALL_FAILED",
+      severity: "error",
+      message: item.message || `Extension ${item.id} failed to install.`,
+      extension: item.id,
+      version: item.version,
+    }));
+    return selectionResult(command, [plan.id], results.map((item) => ({ ...lifecycleResultEntry(item, "install"), archive: prepared.archive })), {
+      diagnostics,
+      text: lifecycleResultText(results, "install"),
+    });
+  } finally {
+    prepared.cleanup();
+  }
+}
+
 async function executeExtensionSearch(invocation) {
   const dependencies = registryDependencies(invocation.dependencies || {});
   const interactive = dependencies.interactive ?? (!invocation.options.json && invocation.options.yes !== true && process.stdin.isTTY && process.stdout.isTTY);
@@ -648,6 +704,7 @@ module.exports = {
   collectRegistryExtensionInstallSelection,
   executeExtension,
   executeExtensionInstall,
+  executeExtensionInstallLocal,
   executeExtensionPack,
   executeExtensionInit,
   executeExtensionDigestUpdate,

package/src/cli/commands/init.js

@@ -99,7 +99,7 @@ async function executeInit(invocation) {
 async function executeInitUnlocked(invocation, root) {
   const { options } = invocation;
   const requestedDev = parseDevOption(options.dev);
-  const dev = resolveWorkspaceDev(root, requestedDev);
+  let dev = resolveWorkspaceDev(root, requestedDev);
   const dependencies = invocation.dependencies && Object.prototype.hasOwnProperty.call(invocation.dependencies, "defaultRegistryUrl")
     ? invocation.dependencies
     : { ...(invocation.dependencies || {}), defaultRegistryUrl: DEFAULT_NEXUS_REGISTRY };
@@ -132,15 +132,11 @@ async function executeInitUnlocked(invocation, root) {
   const extensionState = extensionStateInspection.state;
   const systemCatalogResult = inspectExtensions ? discoverSystemExtensions({ tolerant: true }) : { catalog: [], invalid: [] };
   const systemExtensionIds = systemCatalogResult.catalog.filter((entry) => entry.latestSupported).map((entry) => entry.id);
-  const systemRequestedExtensions = dev ? systemExtensionIds : [];
-  const systemRemovalPlans = dev || extensionStateInspection.error
-    ? []
-    : Object.entries(extensionState.extensions)
-      .filter(([id, entry]) => entry.installed?.system === true || systemExtensionIds.includes(id))
-      .map(([id]) => planExtensionUninstall(root, id, { systemManaged: true }));
+  let systemRequestedExtensions = dev ? systemExtensionIds : [];
   let systemPreparation = { plans: [], failures: [], diagnostics: [] };
   let planningState = extensionState;
-  const prepareSystemForTools = (tools) => {
+  const prepareSystemForTools = (tools, selectedDev = dev) => {
+    systemRequestedExtensions = selectedDev ? systemExtensionIds : [];
     systemPreparation = prepareExtensionPlans(systemCatalogResult, systemRequestedExtensions, {
       tools,
       state: extensionState,
@@ -183,6 +179,7 @@ async function executeInitUnlocked(invocation, root) {
         initialTools: resolvedTools.tools,
         workspaceName: options["workspace-name"],
         language: options.language,
+        dev: requestedDev,
         extensionState,
         extensions: explicitExtensions === null ? undefined : explicitExtensions,
         initialExtensions: explicitExtensions === null ? undefined : explicitExtensions,
@@ -198,6 +195,12 @@ async function executeInitUnlocked(invocation, root) {
       throw error;
     }
   }
+  if (plan?.workspace?.dev !== undefined) dev = plan.workspace.dev;
+  const systemRemovalPlans = dev || extensionStateInspection.error
+    ? []
+    : Object.entries(extensionState.extensions)
+      .filter(([id, entry]) => entry.installed?.system === true || systemExtensionIds.includes(id))
+      .map(([id]) => planExtensionUninstall(root, id, { systemManaged: true }));
   const tools = plan?.tools || resolvedTools.tools;
   const ordinaryRequestedExtensions = explicitExtensions !== null
     ? explicitExtensions

package/src/cli/registry.js

@@ -68,7 +68,7 @@ const COMMANDS = [
     tools: { type: "string" }, yes: { type: "boolean" },
   } },
   { path: ["extension", "install"], args: [{ name: "name", required: false, variadic: true }], workspace: "required", config: ["identity", "language"], interaction: "required", effects: "planned-write", options: {
-    yes: { type: "boolean" }, version: { type: "string" }, "allow-deprecated": { type: "boolean" }, offline: { type: "boolean" },
+    yes: { type: "boolean" }, local: { type: "boolean" }, version: { type: "string" }, "allow-deprecated": { type: "boolean" }, offline: { type: "boolean" },
   } },
   { 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 } } },

package/src/core/extension-local.js

@@ -0,0 +1,66 @@
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { pipeline } = require("node:stream/promises");
+
+const { WorkspaceError } = require("./errors");
+const { DEFAULT_PACKAGE_LIMITS, extractExtensionTransportTarball } = require("./extension-package");
+const { ensureStoredExtensionPackage, packageRecordFromDirectory } = require("./extension-store");
+
+function localError(code, message, details = {}) {
+  return new WorkspaceError(code, message, details);
+}
+
+async function sha512File(file) {
+  const hash = crypto.createHash("sha512");
+  await pipeline(fs.createReadStream(file), hash);
+  return `sha512-${hash.digest("base64")}`;
+}
+
+async function prepareLocalExtensionTarball(file, options = {}) {
+  const archive = path.resolve(String(file || ""));
+  if (!archive.toLowerCase().endsWith(".tgz")) {
+    throw localError("EXTENSION_LOCAL_ARCHIVE_INVALID", "Local extension installation accepts only a .tgz tarball.", { path: archive });
+  }
+  let stat;
+  try { stat = fs.lstatSync(archive); } catch (error) {
+    throw localError("EXTENSION_LOCAL_ARCHIVE_MISSING", `Local extension tarball is missing: ${archive}`, { path: archive, cause: error.code });
+  }
+  if (!stat.isFile() || stat.isSymbolicLink()) throw localError("EXTENSION_LOCAL_ARCHIVE_INVALID", `Local extension tarball must be a regular file: ${archive}`, { path: archive });
+  const temporaryRoot = fs.mkdtempSync(path.join(os.tmpdir(), "code-workspace-local-extension-"));
+  try {
+    const limits = options.packageLimits || DEFAULT_PACKAGE_LIMITS;
+    const inspected = await extractExtensionTransportTarball(archive, path.join(temporaryRoot, "unpacked"), { limits });
+    const integrity = await sha512File(archive);
+    const packageRecord = packageRecordFromDirectory(inspected.sourceRoot, {
+      id: inspected.manifest.id,
+      version: inspected.manifest.version,
+      validate: options.validate,
+    });
+    return Object.freeze({ sourceRoot: inspected.sourceRoot, packageRecord, archive: Object.freeze({ path: archive, integrity }), cleanup: () => fs.rmSync(temporaryRoot, { recursive: true, force: true }) });
+  } catch (error) {
+    fs.rmSync(temporaryRoot, { recursive: true, force: true });
+    if (error instanceof WorkspaceError) throw error;
+    throw localError("EXTENSION_LOCAL_ARCHIVE_INVALID", `Cannot import local extension tarball: ${error.message}`, { path: archive, cause: error.code });
+  }
+}
+
+async function importLocalExtensionTarball(file, options = {}) {
+  const prepared = await prepareLocalExtensionTarball(file, options);
+  try {
+    const stored = ensureStoredExtensionPackage({
+      sourceRoot: prepared.sourceRoot,
+      storeRoot: options.extensionStoreRoot,
+      id: prepared.packageRecord.id,
+      version: prepared.packageRecord.version,
+      provenance: { kind: "local", archiveIntegrity: prepared.archive.integrity },
+      validate: options.validate,
+    });
+    return Object.freeze({ ...stored, source: stored.source || "local", archive: prepared.archive, extensionSpecVersion: prepared.packageRecord.manifest.extensionSpecVersion });
+  } finally {
+    prepared.cleanup();
+  }
+}
+
+module.exports = { importLocalExtensionTarball, prepareLocalExtensionTarball };

package/src/core/extension-registry-lifecycle.js

@@ -717,6 +717,14 @@ function planFromPackageRecord(id, packageRecord, options = {}) {
   });
 }
 
+function planLocalExtensionPackage(packageRecord, options = {}) {
+  return planFromPackageRecord(packageRecord.id, packageRecord, {
+    ...options,
+    source: "local",
+    resolutionScope: "local",
+  });
+}
+
 async function prepareRegistryExtensionPlans(options = {}) {
   const requested = normalizeExtensionNames(options.requested || []);
   if (options.version && requested.length !== 1) {
@@ -791,6 +799,7 @@ module.exports = {
   getRegistryExtensionInfo,
   listRegistryExtensionChoices,
   prepareRegistryExtensionPlans,
+  planLocalExtensionPackage,
   resolveRegistryExtensionCandidate,
   searchRegistryExtensions,
 };

package/src/core/extension-scaffold.js

@@ -38,8 +38,25 @@ function validateScaffoldMetadata(options = {}, targetRoot) {
   return Object.freeze({ id, name, description, version });
 }
 
-function shellEntry() {
-  return "#!/usr/bin/env node\n\"use strict\";\n\n// TODO: implement the extension init protocol.\n";
+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) {
@@ -107,7 +124,9 @@ function shellEnvelope(metadata, packageSha256) {
 function scaffoldExtensionPackage(target, options = {}) {
   const targetRoot = path.resolve(target || ".");
   const metadata = validateScaffoldMetadata(options, targetRoot);
-  const entry = shellEntry();
+  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,
@@ -121,9 +140,9 @@ function scaffoldExtensionPackage(target, options = {}) {
     timeoutMs: 30000,
   };
   const files = {
+    ...templateFiles,
     "package.json": null,
     "extension/manifest.json": Buffer.from(`${JSON.stringify(manifest, null, 2)}\n`, "utf8"),
-    "extension/init.js": Buffer.from(entry, "utf8"),
   };
   const temporary = fs.mkdtempSync(path.join(path.dirname(targetRoot), `.${path.basename(targetRoot)}-`));
   try {

package/src/core/extension-store.js

@@ -113,6 +113,14 @@ function normalizeProvenance(value, key = "package") {
       archiveIntegrity,
     });
   }
+  if (value.kind === "local") {
+    const allowed = new Set(["kind", "archiveIntegrity"]);
+    const unknown = Object.keys(value).filter((field) => !allowed.has(field));
+    if (unknown.length > 0) throw storeError("EXTENSION_STORE_PROVENANCE_INVALID", `Local Store provenance contains unsupported field ${unknown[0]} for ${key}`, { package: key, field: unknown[0] });
+    const archiveIntegrity = String(value.archiveIntegrity || "");
+    if (!SHA512_SRI_PATTERN.test(archiveIntegrity)) throw storeError("EXTENSION_STORE_PROVENANCE_INVALID", `Invalid local archive integrity for ${key}`, { package: key });
+    return Object.freeze({ kind: "local", archiveIntegrity });
+  }
   throw storeError("EXTENSION_STORE_PROVENANCE_INVALID", `Unsupported Store provenance kind for ${key}: ${value.kind || "<missing>"}`, { package: key, kind: value.kind || null });
 }
 
@@ -142,7 +150,7 @@ function validatePackageRecord(key, value) {
     manifestSha256: value.manifestSha256,
     entrySha256: value.entrySha256,
     packageSha256: value.packageSha256,
-    source: provenance.kind === "builtin" ? "builtin" : "nexus",
+    source: provenance.kind === "builtin" ? "builtin" : provenance.kind === "local" ? "local" : "nexus",
     provenance,
     importedAt: value.importedAt || null,
     references: normalizeReferences(value.references),
@@ -276,7 +284,7 @@ function ensureStoredExtensionPackage(options = {}) {
         manifestSha256: copied.manifestSha256,
         entrySha256: copied.entrySha256,
         packageSha256: copied.packageSha256,
-        source: provenance.kind === "builtin" ? "builtin" : "nexus",
+        source: provenance.kind === "builtin" ? "builtin" : provenance.kind === "local" ? "local" : "nexus",
         provenance,
         importedAt: new Date().toISOString(),
         references: registry.packages[packageKey(source.id, source.version)]?.references || normalizeReferences(),

package/src/init/wizard.js

@@ -90,6 +90,17 @@ async function collectInitPlan(root, manifest, options = {}) {
   });
   const existing = fs.existsSync(configPath(root)) ? loadConfig(root, { defaultLanguage: existingLanguage }) : null;
   const name = existing?.workspace?.name || options.workspaceName || await ui.text("Workspace name", DEFAULT_WORKSPACE_NAME);
+  const initialDev = options.dev ?? existing?.workspace?.dev ?? true;
+  const dev = options.dev !== undefined
+      ? options.dev
+      : await ui.select(
+        "Development mode",
+        [
+          { value: true, label: "Yes" },
+          { value: false, label: "No" },
+        ],
+        initialDev ? 0 : 1
+      );
   const languageChoices = SUPPORTED_LANGUAGES.map((entry) => ({
     value: entry.value,
     label: `${entry.label} · ${entry.value}`,
@@ -109,14 +120,17 @@ async function collectInitPlan(root, manifest, options = {}) {
     options.initialTools || ["claude", "codex"]
   );
   const systemExtensions = typeof options.prepareSystemExtensions === "function"
-    ? await options.prepareSystemExtensions(tools)
+    ? await options.prepareSystemExtensions(tools, dev)
     : (options.systemExtensions || []);
   const ordinary = await collectExtensionPlans(options, ui, tools);
   const extensions = [
     ...systemExtensions,
     ...ordinary.plans,
   ];
-  const workspace = existing?.workspace || { name, uuid: randomUUID() };
+  const workspace = {
+    ...(existing?.workspace || { name, uuid: randomUUID() }),
+    dev,
+  };
   const extensionRemovals = ordinary.uninstallPlans || [];
   const plan = createInitPlan({ root, workspace, tools, language, extensions, extensionRemovals });
   const extensionChanges = [
@@ -125,6 +139,7 @@ async function collectInitPlan(root, manifest, options = {}) {
   ];
   ui.note("Ready to initialize", [
     `Workspace  ${workspace.name}`,
+    `Development mode  ${dev ? "Yes" : "No"}`,
     `Language   ${language}`,
     `Tools      ${tools.length ? tools.join(", ") : "none"}`,
     `Extensions ${extensions.length ? extensions.map((entry) => `${entry.id}@${entry.version} [Spec ${entry.extensionSpecVersion}] (${entry.manifestSha256})`).join(", ") : "none"}`,