code-workspace-zhuiyi 0.1.0-beta.1

package/src/core/fs.js

@@ -0,0 +1,32 @@
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const path = require("node:path");
+
+function atomicWrite(file, content) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temporary = path.join(
+    path.dirname(file),
+    `.${path.basename(file)}.${process.pid}.${Date.now()}.tmp`
+  );
+  fs.writeFileSync(temporary, content);
+  fs.renameSync(temporary, file);
+}
+
+function sha256(content) {
+  return crypto.createHash("sha256").update(content).digest("hex");
+}
+
+function readTextIfExists(file) {
+  return fs.existsSync(file) ? fs.readFileSync(file, "utf8") : null;
+}
+
+function removeFileIfExists(file) {
+  if (fs.existsSync(file)) fs.unlinkSync(file);
+}
+
+module.exports = {
+  atomicWrite,
+  readTextIfExists,
+  removeFileIfExists,
+  sha256,
+};

package/src/core/init-lock-holder.js

@@ -0,0 +1,30 @@
+const { parentPort, workerData } = require("node:worker_threads");
+
+const properLockfile = require("proper-lockfile");
+
+(async () => {
+  let release;
+  try {
+    release = await properLockfile.lock(workerData.target, {
+      realpath: false,
+      retries: false,
+      update: workerData.update,
+      stale: workerData.stale,
+    });
+    parentPort.postMessage({ type: "ready" });
+    parentPort.on("message", async (message) => {
+      if (message?.type !== "release") return;
+      try {
+        await release();
+        parentPort.postMessage({ type: "released" });
+      } catch (error) {
+        parentPort.postMessage({ type: "release-error", code: error.code, message: error.message });
+      } finally {
+        process.exit(0);
+      }
+    });
+  } catch (error) {
+    parentPort.postMessage({ type: "error", code: error.code, message: error.message });
+    process.exit(1);
+  }
+})();

package/src/core/init-lock.js

@@ -0,0 +1,159 @@
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { Worker } = require("node:worker_threads");
+
+const { WorkspaceError } = require("./errors");
+
+const PACKAGE_ROOT = path.resolve(__dirname, "..", "..");
+const LOCK_DIRECTORY = path.join(os.tmpdir(), "code-workspace-init-locks");
+const UPDATE_ENV = "CODE_WORKSPACE_INIT_LOCK_UPDATE_MS";
+const STALE_ENV = "CODE_WORKSPACE_INIT_LOCK_STALE_MS";
+const DEFAULT_UPDATE_MS = 5000;
+const DEFAULT_STALE_MS = 30000;
+
+let projectEnvLoaded = false;
+
+function loadProjectEnv() {
+  if (projectEnvLoaded) return;
+  projectEnvLoaded = true;
+  if (typeof process.loadEnvFile !== "function") return;
+  const envFile = path.join(PACKAGE_ROOT, ".env");
+  try {
+    process.loadEnvFile(envFile);
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw new WorkspaceError("INIT_LOCK_CONFIG_INVALID", `Cannot load Code Workspace .env: ${error.message}`, { file: envFile });
+    }
+  }
+}
+
+function parseMilliseconds(value, fallback, name) {
+  if (value === undefined || value === "") return fallback;
+  const text = String(value).trim();
+  if (!/^\d+$/.test(text)) {
+    throw new WorkspaceError("INIT_LOCK_CONFIG_INVALID", `${name} must be a positive integer in milliseconds`, { variable: name, value });
+  }
+  const parsed = Number(text);
+  if (!Number.isSafeInteger(parsed) || parsed < 1) {
+    throw new WorkspaceError("INIT_LOCK_CONFIG_INVALID", `${name} must be a positive integer in milliseconds`, { variable: name, value });
+  }
+  return parsed;
+}
+
+function readInitLockConfig(options = {}) {
+  if (!options.env) loadProjectEnv();
+  const env = options.env || process.env;
+  const update = parseMilliseconds(env[UPDATE_ENV], DEFAULT_UPDATE_MS, UPDATE_ENV);
+  const stale = parseMilliseconds(env[STALE_ENV], DEFAULT_STALE_MS, STALE_ENV);
+  if (stale <= update * 2) {
+    throw new WorkspaceError("INIT_LOCK_CONFIG_INVALID", `${STALE_ENV} must be greater than twice ${UPDATE_ENV}`, {
+      update,
+      stale,
+      updateVariable: UPDATE_ENV,
+      staleVariable: STALE_ENV,
+    });
+  }
+  return Object.freeze({ update, stale });
+}
+
+function canonicalWorkspacePath(root) {
+  const resolved = path.resolve(root);
+  try {
+    return fs.realpathSync.native(resolved);
+  } catch {
+    return resolved;
+  }
+}
+
+function workspaceLockTarget(root) {
+  const key = crypto.createHash("sha256").update(canonicalWorkspacePath(root)).digest("hex");
+  fs.mkdirSync(LOCK_DIRECTORY, { recursive: true });
+  return path.join(LOCK_DIRECTORY, key);
+}
+
+async function acquireInitLock(root, options = {}) {
+  const config = options.config || readInitLockConfig(options);
+  const target = options.target || workspaceLockTarget(root);
+  const worker = new Worker(path.join(__dirname, "init-lock-holder.js"), {
+    workerData: { target, update: config.update, stale: config.stale },
+  });
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    let releasing = false;
+    let releaseResolve;
+    let releaseReject;
+    const fail = (error) => {
+      if (settled) return;
+      settled = true;
+      reject(error);
+    };
+    worker.on("message", (message) => {
+      if (message.type === "ready") {
+        if (settled) return;
+        settled = true;
+        resolve(() => new Promise((releaseDone, releaseFailed) => {
+          if (releasing) {
+            releaseFailed(new WorkspaceError("INIT_LOCK_RELEASE_FAILED", "The init lock is already being released."));
+            return;
+          }
+          releasing = true;
+          releaseResolve = releaseDone;
+          releaseReject = releaseFailed;
+          worker.postMessage({ type: "release" });
+        }));
+      } else if (message.type === "released") {
+        releaseResolve?.();
+        releaseResolve = null;
+        releaseReject = null;
+      } else if (message.type === "release-error") {
+        releaseReject?.(new WorkspaceError("INIT_LOCK_RELEASE_FAILED", `Could not release the init lock: ${message.message}`, { cause: message.code }));
+        releaseResolve = null;
+        releaseReject = null;
+      } else if (message.type === "error") {
+        const error = message.code === "ELOCKED"
+          ? new WorkspaceError("INIT_ALREADY_RUNNING", "Another init operation is already running for this Workspace.", {
+            workspace: canonicalWorkspacePath(root),
+            remediation: "Wait for the existing init operation to finish, then retry.",
+          })
+          : new WorkspaceError("INIT_LOCK_ACQUIRE_FAILED", `Could not acquire the init lock: ${message.message}`, {
+            workspace: canonicalWorkspacePath(root),
+            cause: message.code,
+          });
+        fail(error);
+      }
+    });
+    worker.on("error", (error) => {
+      if (releasing) {
+        releaseReject?.(new WorkspaceError("INIT_LOCK_RELEASE_FAILED", `Could not release the init lock: ${error.message}`, { cause: error.code || error.name }));
+        releaseResolve = null;
+        releaseReject = null;
+      } else {
+        fail(new WorkspaceError("INIT_LOCK_ACQUIRE_FAILED", `Could not acquire the init lock: ${error.message}`, {
+          workspace: canonicalWorkspacePath(root),
+          cause: error.code || error.name,
+        }));
+      }
+    });
+    worker.on("exit", (code) => {
+      if (!releasing && !settled) {
+        fail(new WorkspaceError("INIT_LOCK_ACQUIRE_FAILED", `The init lock worker exited before acquiring the lock (status ${code}).`, {
+          workspace: canonicalWorkspacePath(root),
+          exitCode: code,
+        }));
+      }
+    });
+  });
+}
+
+module.exports = {
+  DEFAULT_STALE_MS,
+  DEFAULT_UPDATE_MS,
+  STALE_ENV,
+  UPDATE_ENV,
+  acquireInitLock,
+  canonicalWorkspacePath,
+  readInitLockConfig,
+  workspaceLockTarget,
+};

package/src/core/init.js

@@ -0,0 +1,160 @@
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+const packageJson = require("../../package.json");
+const { WorkspaceError } = require("./errors");
+const { sha256 } = require("./fs");
+const { loadState, saveState } = require("./config");
+const { MANIFEST_FILE, loadManagedManifest } = require("./managed-files");
+const { attachRetainedEffects } = require("./transaction");
+
+const PACKAGE_ROOT = path.resolve(__dirname, "..", "..");
+
+function parseVersion(value) {
+  const match = String(value || "").trim().match(/^v?(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/);
+  if (!match) throw new Error(`Invalid semantic version: ${value}`);
+  return match.slice(1).map(Number);
+}
+
+function compareVersions(left, right) {
+  const a = parseVersion(left);
+  const b = parseVersion(right);
+  for (let index = 0; index < 3; index += 1) {
+    if (a[index] < b[index]) return -1;
+    if (a[index] > b[index]) return 1;
+  }
+  return 0;
+}
+
+function minimumFromRange(range) {
+  const match = String(range || "").trim().match(/^>=\s*(v?\d+\.\d+\.\d+)$/);
+  if (!match) throw new Error(`Unsupported version range: ${range}`);
+  return match[1];
+}
+
+function runCommand(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    cwd: options.cwd,
+    env: options.env || process.env,
+    encoding: "utf8",
+    stdio: options.capture ? ["ignore", "pipe", "pipe"] : "inherit",
+    timeout: options.timeout,
+  });
+  if (result.error && !options.allowFailure) throw result.error;
+  if (result.status !== 0 && !options.allowFailure) {
+    const detail = String(result.stderr || result.stdout || "").trim().split(/\r?\n/)[0];
+    throw new Error(`Command failed (${result.status ?? "spawn"}): ${command} ${args.join(" ")}${detail ? ` — ${detail}` : ""}`);
+  }
+  return result;
+}
+
+function loadInitManifest(file = MANIFEST_FILE) {
+  const manifest = loadManagedManifest(file);
+  minimumFromRange(manifest.requirements?.node);
+  return manifest;
+}
+
+function installWorkspaceDependencies(root, options = {}) {
+  const packageFile = path.join(root, "package.json");
+  if (!fs.existsSync(packageFile)) return { action: "skip", reason: "target has no package.json" };
+  let targetPackage;
+  try {
+    targetPackage = JSON.parse(fs.readFileSync(packageFile, "utf8"));
+  } catch (error) {
+    throw new Error(`Failed to parse target package.json: ${error.message}`);
+  }
+  if (targetPackage.name !== packageJson.name) {
+    return { action: "skip", reason: `target package is ${targetPackage.name || "unnamed"}` };
+  }
+  const scope = ["node_modules", "package-lock.json"];
+  const before = Object.fromEntries(scope.map((target) => [target, fs.existsSync(path.join(root, target))]));
+  const retainedEffect = (missing = []) => {
+    const after = Object.fromEntries(scope.map((target) => [target, fs.existsSync(path.join(root, target))]));
+    const created = scope.filter((target) => !before[target] && after[target]);
+    return {
+      kind: "retained-local-effect",
+      status: created.length > 0 ? "applied" : "possibly-applied",
+      name: "workspace dependencies",
+      command: "npm install",
+      targets: scope,
+      scope: { enumeration: "dependency-roots-only", complete: false },
+      evidence: { before, after, ...(missing.length > 0 ? { missingPackages: missing } : {}) },
+      remediation: "Run npm install again and verify the declared dependencies before continuing.",
+    };
+  };
+  let installCompleted = false;
+  try {
+    (options.run || runCommand)("npm", ["install"], { cwd: root });
+    installCompleted = true;
+  } catch (cause) {
+    const error = cause.code ? cause : new WorkspaceError("WORKSPACE_DEPENDENCY_INSTALL_FAILED", cause.message, { cause: cause.name });
+    throw attachRetainedEffects(error, [retainedEffect()]);
+  }
+  const dependencies = {
+    ...(targetPackage.dependencies || {}),
+    ...(targetPackage.devDependencies || {}),
+  };
+  const missing = Object.keys(dependencies).filter((name) => !fs.existsSync(path.join(root, "node_modules", name, "package.json")));
+  if (missing.length > 0) {
+    const error = new WorkspaceError(
+      "WORKSPACE_DEPENDENCY_VERIFICATION_FAILED",
+      `Workspace dependency verification failed; missing installed packages: ${missing.join(", ")}`,
+      { missing }
+    );
+    throw attachRetainedEffects(error, [retainedEffect(missing)]);
+  }
+  return {
+    action: "install",
+    verified: installCompleted,
+    retainedPaths: ["node_modules", ...(fs.existsSync(path.join(root, "package-lock.json")) ? ["package-lock.json"] : [])],
+  };
+}
+
+function commitInitializationState(root, manifest, options = {}) {
+  const current = loadState(root) || {};
+  const state = {
+    ...current,
+    schemaVersion: 2,
+    status: "healthy",
+    appliedReleaseVersion: manifest.releaseVersion,
+    appliedManifestSha256: sha256(fs.readFileSync(options.manifestFile || MANIFEST_FILE)),
+    tools: options.tools || manifest.tools,
+  };
+  delete state.workspaceLanguage;
+  saveState(root, state);
+  return state;
+}
+
+function commitUpdateState(root, manifest, options = {}) {
+  const current = loadState(root);
+  if (!current) {
+    throw new WorkspaceError(
+      "UPDATE_STATE_MISSING",
+      "Local initialization state is missing; update can only commit an existing workspace state.",
+      { remediation: "Re-run code-w init . --yes before updating this workspace." }
+    );
+  }
+  const state = {
+    ...current,
+    appliedReleaseVersion: manifest.releaseVersion,
+    appliedManifestSha256: sha256(fs.readFileSync(options.manifestFile || MANIFEST_FILE)),
+    ...(options.tools !== undefined ? { tools: options.tools } : {}),
+  };
+  if (options.removeLegacyWorkspaceLanguage === true) delete state.workspaceLanguage;
+  saveState(root, state);
+  return state;
+}
+
+module.exports = {
+  MANIFEST_FILE,
+  PACKAGE_ROOT,
+  compareVersions,
+  commitInitializationState,
+  commitUpdateState,
+  installWorkspaceDependencies,
+  loadInitManifest,
+  minimumFromRange,
+  parseVersion,
+  runCommand,
+};

package/src/core/initializer.js

@@ -0,0 +1,233 @@
+const fs = require("node:fs");
+const path = require("node:path");
+const { randomUUID } = require("node:crypto");
+const readline = require("node:readline/promises");
+
+const { cleanupObsoleteAssets, OBSOLETE_ASSETS } = require("./assets");
+const {
+  DEFAULT_MONITOR_URL,
+  DEFAULT_WORKSPACE_NAME,
+  configPath,
+  ensureLocalIgnore,
+  loadConfig,
+  normalizeConfig,
+  saveConfig,
+  statePath,
+} = require("./config");
+const { doctorWorkspace } = require("./doctor");
+const {
+  MANIFEST_FILE,
+  commitInitializationState,
+  compareVersions,
+  installWorkspaceDependencies,
+  loadInitManifest,
+  minimumFromRange,
+  runCommand,
+} = require("./init");
+const { applyPermissionPlan, permissionTargets, planPermissionChanges } = require("./permissions");
+const { installManagedFiles } = require("./managed-files");
+const { DEFAULT_WORKSPACE_LANGUAGE, workspaceGuide } = require("./language");
+const { planWorkspaceMaintenance } = require("./migration");
+const { createFileTransaction } = require("./transaction");
+const { validateProjects } = require("./validation");
+
+const INITIALIZATION_STAGE_IDS = Object.freeze({
+  "Configure workspace identity": "configure-workspace",
+  "Validate manifest": "validate-manifest",
+  "Install workspace dependencies": "install-dependencies",
+  "Remove obsolete managed files": "cleanup-obsolete",
+  "Install managed files": "install-managed-files",
+  "Prepare local workspace configuration": "save-config",
+  "Apply Agent workspace permissions": "apply-permissions",
+  "Run strict workspace doctor": "strict-doctor",
+  "Commit local initialization state": "commit-state",
+  "Verify local initialization state": "final-verify",
+});
+
+async function collectWorkspaceSetup(root, options = {}) {
+  const language = options.language || DEFAULT_WORKSPACE_LANGUAGE;
+  const file = configPath(root);
+  if (fs.existsSync(file)) {
+    const current = loadConfig(root, { defaultLanguage: language });
+    return normalizeConfig({
+      ...current,
+      workspace: current.workspace || {
+        name: options.workspaceName || DEFAULT_WORKSPACE_NAME,
+        uuid: randomUUID(),
+      },
+      monitor: {
+        ...current.monitor,
+        ...(options.monitor !== undefined ? { enable: options.monitor === true } : {}),
+        ...(options.monitorUrl ? { url: options.monitorUrl } : {}),
+      },
+    });
+  }
+
+  const interactive = options.interactive ?? (process.stdin.isTTY && process.stdout.isTTY);
+  let name = options.workspaceName;
+  let monitorEnabled = options.monitor;
+  if (interactive && (!name || (monitorEnabled === undefined && options.tools.includes("codex")))) {
+    const prompt = readline.createInterface({ input: options.input || process.stdin, output: options.output || process.stdout });
+    try {
+      if (!name) name = (await prompt.question(`Workspace name [${DEFAULT_WORKSPACE_NAME}]: `)).trim() || DEFAULT_WORKSPACE_NAME;
+      if (monitorEnabled === undefined && options.tools.includes("codex")) {
+        monitorEnabled = /^y(?:es)?$/i.test((await prompt.question("Enable Codex Agent monitoring hooks? [y/N] ")).trim());
+      }
+    } finally {
+      prompt.close();
+    }
+  }
+  return normalizeConfig({
+    schemaVersion: 2,
+    workspace: { name: name || DEFAULT_WORKSPACE_NAME, uuid: options.workspaceUuid || randomUUID(), language },
+    monitor: {
+      enable: options.tools.includes("codex") && monitorEnabled !== false,
+      url: options.monitorUrl || DEFAULT_MONITOR_URL,
+    },
+    projects: [],
+  });
+}
+
+async function initializeWorkspaceStages(rootInput, options = {}) {
+  const root = path.resolve(rootInput || ".");
+  const migration = options.migration || planWorkspaceMaintenance(root, {
+    language: options.language,
+    defaultLanguage: DEFAULT_WORKSPACE_LANGUAGE,
+    allowLegacy: true,
+  });
+  const language = migration.language.value;
+  fs.mkdirSync(root, { recursive: true });
+  const run = options.run || runCommand;
+  options = { ...options, language };
+  const stages = [];
+  const stage = async (name, action) => {
+    options.onStage?.(name);
+    const value = await action();
+    options.injectFailure?.(INITIALIZATION_STAGE_IDS[name] || name, value);
+    stages.push({ name, result: value });
+    return value;
+  };
+
+  const workspaceConfig = await stage("Configure workspace identity", () => collectWorkspaceSetup(root, options));
+  const capabilities = workspaceConfig.monitor.enable ? ["monitor"] : [];
+
+  const manifest = await stage("Validate manifest", () => loadInitManifest(options.manifestFile || MANIFEST_FILE));
+  const minimumNode = minimumFromRange(manifest.requirements.node);
+  const nodeVersion = options.nodeVersion || process.versions.node;
+  if (compareVersions(nodeVersion, minimumNode) < 0) {
+    throw new Error(`Node ${minimumNode} or newer is required; found ${nodeVersion}`);
+  }
+
+  const dependencies = await stage("Install workspace dependencies", () =>
+    installWorkspaceDependencies(root, { run })
+  );
+  if (dependencies.action === "install") {
+    options.transaction?.recordExternalEffect({
+      kind: "retained-local-effect",
+      name: "workspace dependencies",
+      targets: dependencies.retainedPaths,
+      verified: dependencies.verified === true,
+    });
+  }
+
+  const obsoleteFiles = await stage("Remove obsolete managed files", () =>
+    cleanupObsoleteAssets(root, options.tools, { force: options.force === true })
+  );
+
+  const managedFiles = await stage("Install managed files", () =>
+    installManagedFiles(root, manifest, options.tools, {
+      force: options.force === true,
+      capabilities,
+      variables: { WORKSPACE_LANGUAGE: language, WORKSPACE_USER_GUIDE: workspaceGuide(language) },
+    })
+  );
+
+  const localConfig = await stage("Prepare local workspace configuration", () => {
+    const file = configPath(root);
+    const action = fs.existsSync(file) ? "skip" : "write";
+    saveConfig(root, workspaceConfig);
+    return { action, file: path.relative(root, file), gitignore: ensureLocalIgnore(root) };
+  });
+
+  const config = loadConfig(root);
+  const projects = validateProjects(root, config);
+  if (projects.errors.length > 0) {
+    throw new Error(`Local project verification failed: ${projects.errors.join("; ")}`);
+  }
+  const permissions = await stage("Apply Agent workspace permissions", () => {
+    const permissionPlan = planPermissionChanges({
+      root,
+      tools: options.tools,
+      grants: config.projects.map((project) => project.location),
+    });
+    return applyPermissionPlan(permissionPlan, { transaction: options.transaction });
+  });
+
+  await stage("Run strict workspace doctor", () => {
+    const result = doctorWorkspace(root, manifest, {
+      allowIncompleteState: true,
+      run,
+      tools: options.tools,
+      capabilities,
+    });
+    if (result.errors.length > 0) throw new Error(`Workspace doctor failed: ${result.errors.join("; ")}`);
+    return { warnings: result.warnings, projects: config.projects.length };
+  });
+
+  const state = await stage("Commit local initialization state", () =>
+    commitInitializationState(root, manifest, {
+      manifestFile: options.manifestFile || MANIFEST_FILE,
+      tools: options.tools,
+      language,
+    })
+  );
+
+  const verification = await stage("Verify local initialization state", () => {
+    const result = doctorWorkspace(root, manifest, { run, tools: options.tools, capabilities });
+    if (result.errors.length > 0) throw new Error(`Final workspace verification failed: ${result.errors.join("; ")}`);
+    return { warnings: result.warnings, projects: config.projects.length };
+  });
+
+  return {
+    root,
+    manifest,
+    nodeVersion,
+    language,
+    migration,
+    dependencies,
+    obsoleteFiles,
+    managedFiles,
+    localConfig,
+    workspaceConfig: config,
+    permissions,
+    state,
+    verification,
+    initPlan: options.initPlan || null,
+    stages,
+  };
+}
+
+async function initializeWorkspace(rootInput, options = {}) {
+  const root = path.resolve(rootInput || ".");
+  const manifest = loadInitManifest(options.manifestFile || MANIFEST_FILE);
+  const files = [
+    statePath(root),
+    configPath(root),
+    path.join(root, ".gitignore"),
+    path.join(root, ".codex", "config.toml"),
+    ...permissionTargets(root, options.tools),
+    ...manifest.managedFiles.map((entry) => path.join(root, entry.target)),
+    ...OBSOLETE_ASSETS.map((target) => path.join(root, target)),
+  ];
+  const transaction = createFileTransaction(files);
+  try {
+    const result = await initializeWorkspaceStages(root, { ...options, transaction });
+    transaction.commit();
+    return result;
+  } catch (error) {
+    transaction.rollback(error);
+    throw error;
+  }
+}
+
+module.exports = { INITIALIZATION_STAGE_IDS, collectWorkspaceSetup, initializeWorkspace, initializeWorkspaceStages };