msdevflow 0.6.0

package/lib/bootstrap.js

@@ -0,0 +1,923 @@
+import { spawnSync } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import {
+  closeSync,
+  cpSync,
+  fchmodSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  readdirSync,
+  readSync,
+  renameSync,
+  rmSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+
+const REGISTRY = "https://registry.npmjs.org";
+const GITCODE_PACKAGE = "@gitcode-cli/cli@latest";
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const BUNDLED_SKILL_DIR = path.join(PACKAGE_ROOT, "skill", "msdevflow");
+const REQUIRED_SCHEMAS = {
+  "auth login": ["web"],
+  "auth status": ["json"],
+  "issue create": ["body-file", "dry-run", "json", "repo", "title"],
+  "issue list": ["assignee", "json", "repo", "state"],
+  "issue view": ["comments", "json", "repo"],
+  "issue edit": ["assignee", "json", "repo", "state"],
+  "issue comment": ["body-file", "json", "repo"],
+  "issue prs": ["json", "repo"],
+  "pr create": ["base", "body-file", "fork", "head", "json", "repo", "title"],
+  "pr list": ["direction", "head", "json", "limit", "repo", "sort", "state"],
+  "pr view": ["comments", "json", "repo"],
+  "pr diff": ["json", "repo"],
+  "pr comments": ["json", "repo"],
+  "pr comment": ["body-file", "json", "path", "position", "repo"],
+  "pr reply": ["body", "discussion", "repo"],
+  "pr merge": ["json", "method", "repo", "yes"],
+};
+
+export class BootstrapError extends Error {
+  constructor(message, exitCode = 1) {
+    super(message);
+    this.exitCode = exitCode;
+  }
+}
+
+export function usage() {
+  return `Usage:
+  msdevflow setup [options]
+
+Options:
+  --skills-dir <path>   Installed skills directory (default: ~/.claude/skills)
+  --dry-run             Diagnose and print the plan without changing the environment
+  --yes                 Apply the displayed plan without an interactive confirmation
+  --json                Print the final result as JSON
+  -h, --help            Show this help
+
+The setup installs or updates the bundled msdevflow skill, installs or upgrades
+the official GitCode npm CLI, and installs all reviewed Python runtime
+dependencies. It never downloads or launches Chromium. If GitCode is not
+authenticated, it starts the CLI's official browser login; setup never reads or
+prints a token.`;
+}
+
+export function parseArgs(argv) {
+  if (argv.includes("--help") || argv.includes("-h")) {
+    return { help: true };
+  }
+  if (argv[0] !== "setup") {
+    throw new BootstrapError("Expected the setup command.\n\n" + usage(), 2);
+  }
+
+  const options = {
+    skillsDir: "",
+    dryRun: false,
+    yes: false,
+    json: false,
+  };
+  for (let index = 1; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === "--skills-dir") {
+      index += 1;
+      if (!argv[index]) {
+        throw new BootstrapError("--skills-dir requires a path.", 2);
+      }
+      options.skillsDir = argv[index];
+      continue;
+    }
+    if (argument === "--dry-run") {
+      options.dryRun = true;
+      continue;
+    }
+    if (argument === "--yes") {
+      options.yes = true;
+      continue;
+    }
+    if (argument === "--json") {
+      options.json = true;
+      continue;
+    }
+    throw new BootstrapError(`Unknown argument: ${argument}`, 2);
+  }
+  return options;
+}
+
+function defaultSkillsDir(environment) {
+  return environment.CLAUDE_SKILLS_DIR || path.join(homedir(), ".claude", "skills");
+}
+
+export function resolveLayout(options, environment = process.env, bundledSkillDir = BUNDLED_SKILL_DIR) {
+  const skillsDir = path.resolve(options.skillsDir || defaultSkillsDir(environment));
+  const workflowDir = path.join(skillsDir, "msdevflow");
+  const bundledWorkflowDir = path.resolve(bundledSkillDir);
+  return {
+    skillsDir,
+    workflowDir,
+    workflowManifest: path.join(workflowDir, "SKILL.md"),
+    pythonRequirements: path.join(workflowDir, "scripts", "requirements.txt"),
+    bundledSkillDir: bundledWorkflowDir,
+    bundledManifest: path.join(bundledWorkflowDir, "SKILL.md"),
+    bundledPythonRequirements: path.join(bundledWorkflowDir, "scripts", "requirements.txt"),
+  };
+}
+
+function namedCommand(command, args, platform) {
+  return executableCommand(platform === "win32" && command === "npm" ? "npm.cmd" : command, args, platform);
+}
+
+function executableCommand(executable, args, platform) {
+  if (platform !== "win32") {
+    return { command: executable, args };
+  }
+  if (/\.ps1$/i.test(executable)) {
+    return {
+      command: "powershell.exe",
+      args: ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", executable, ...args],
+    };
+  }
+  if (!/\.(?:cmd|bat)$/i.test(executable)) {
+    return { command: executable, args };
+  }
+  return {
+    command: "powershell.exe",
+    args: [
+      "-NoProfile",
+      "-Command",
+      "& { $exe = $args[0]; $rest = @($args | Select-Object -Skip 1); & $exe @rest; exit $LASTEXITCODE }",
+      executable,
+      ...args,
+    ],
+  };
+}
+
+export function formatCommand(invocation) {
+  return [invocation.command, ...invocation.args]
+    .map((value) => (/^[A-Za-z0-9_./:@=\\-]+$/.test(value) ? value : JSON.stringify(value)))
+    .join(" ");
+}
+
+function execute(invocation, { allowFailure = false, inherit = false, outputToStderr = false } = {}) {
+  const result = spawnSync(invocation.command, invocation.args, {
+    encoding: "utf8",
+    stdio: inherit
+      ? ["inherit", outputToStderr ? process.stderr : "inherit", "inherit"]
+      : "pipe",
+    maxBuffer: 20 * 1024 * 1024,
+    windowsHide: false,
+  });
+  if (result.error) {
+    throw new BootstrapError(`Failed to run ${invocation.command}: ${result.error.message}`);
+  }
+  const status = result.status ?? 1;
+  if (status !== 0 && !allowFailure) {
+    const detail = inherit ? "" : `\n${(result.stderr || result.stdout || "").trim()}`;
+    throw new BootstrapError(`Command failed (${status}): ${formatCommand(invocation)}${detail}`);
+  }
+  return {
+    status,
+    stdout: result.stdout || "",
+    stderr: result.stderr || "",
+  };
+}
+
+function runOptional(run, invocation) {
+  try {
+    return run(invocation, { allowFailure: true });
+  } catch (error) {
+    if (error instanceof BootstrapError && error.message.startsWith("Failed to run ")) {
+      return { status: 1, stdout: "", stderr: error.message };
+    }
+    throw error;
+  }
+}
+
+function verifyFile(file, missingMessage) {
+  let descriptor;
+  try {
+    descriptor = openSync(file, "r");
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      throw new BootstrapError(missingMessage);
+    }
+    throw error;
+  } finally {
+    if (descriptor !== undefined) {
+      closeSync(descriptor);
+    }
+  }
+}
+
+function requireFile(file, description) {
+  verifyFile(file, `${description} not found: ${file}. Reinstall the msdevflow npm package.`);
+}
+
+function skillManifestIsOwned(file) {
+  try {
+    const metadata = lstatSync(file);
+    if (metadata.isSymbolicLink() || !metadata.isFile()) {
+      return false;
+    }
+    const frontmatter = readFileSync(file, "utf8").match(/^---\s*\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+    if (frontmatter === null) {
+      return false;
+    }
+    const names = [...frontmatter[1].matchAll(/^name:\s*([^\s#]+)\s*$/gm)];
+    return names.length === 1 && names[0][1] === "msdevflow";
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return false;
+    }
+    throw error;
+  }
+}
+
+function skillEntries(root) {
+  const entries = [];
+  const visit = (directory, relativeDirectory = "") => {
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+      const relative = path.join(relativeDirectory, entry.name);
+      const absolute = path.join(directory, entry.name);
+      if (entry.isSymbolicLink() || (!entry.isDirectory() && !entry.isFile())) {
+        throw new BootstrapError(`Bundled skill contains an unsupported entry: ${absolute}`, 3);
+      }
+      if (entry.isDirectory()) {
+        visit(absolute, relative);
+      } else {
+        entries.push(relative);
+      }
+    }
+  };
+  visit(root);
+  return entries.sort();
+}
+
+function skillDigest(root) {
+  const digest = createHash("sha256");
+  for (const relative of skillEntries(root)) {
+    digest.update(relative.replaceAll("\\", "/"));
+    digest.update("\0");
+    digest.update(readFileSync(path.join(root, relative)));
+    digest.update("\0");
+  }
+  return digest.digest("hex");
+}
+
+function skillInstallDetails(layout) {
+  requireFile(layout.bundledManifest, "bundled msdevflow skill manifest");
+  requireFile(layout.bundledPythonRequirements, "bundled workflow Python requirements file");
+  if (!skillManifestIsOwned(layout.bundledManifest)) {
+    throw new BootstrapError("Bundled skill manifest does not identify msdevflow.", 3);
+  }
+  validatePythonRequirements(layout.bundledPythonRequirements);
+  const bundledDigest = skillDigest(layout.bundledSkillDir);
+  let status = "absent";
+  let existingDigest = null;
+  try {
+    const metadata = lstatSync(layout.workflowDir);
+    if (metadata.isSymbolicLink() || !metadata.isDirectory()
+        || !skillManifestIsOwned(layout.workflowManifest)) {
+      throw new BootstrapError(
+        `Refusing to overwrite a skills entry not owned by msdevflow: ${layout.workflowDir}`,
+        3,
+      );
+    }
+    existingDigest = skillDigest(layout.workflowDir);
+    status = existingDigest === bundledDigest ? "current" : "update";
+  } catch (error) {
+    if (error?.code !== "ENOENT") {
+      throw error;
+    }
+  }
+  return {
+    source: layout.bundledSkillDir,
+    target: layout.workflowDir,
+    status,
+    bundledDigest,
+    existingDigest,
+  };
+}
+
+function installBundledSkill(details) {
+  const parent = path.dirname(details.target);
+  mkdirSync(parent, { recursive: true });
+  const current = skillInstallDetails({
+    bundledSkillDir: details.source,
+    bundledManifest: path.join(details.source, "SKILL.md"),
+    bundledPythonRequirements: path.join(details.source, "scripts", "requirements.txt"),
+    workflowDir: details.target,
+    workflowManifest: path.join(details.target, "SKILL.md"),
+  });
+  if (current.status !== details.status || current.existingDigest !== details.existingDigest) {
+    throw new BootstrapError("msdevflow skill target changed after confirmation; refusing to overwrite it.", 3);
+  }
+  if (current.status === "current") {
+    return "current";
+  }
+  const staging = path.join(parent, `.msdevflow-${randomUUID()}.tmp`);
+  const backup = path.join(parent, `.msdevflow-${randomUUID()}.backup`);
+  let movedExisting = false;
+  try {
+    cpSync(details.source, staging, { recursive: true, errorOnExist: true });
+    if (skillDigest(staging) !== details.bundledDigest) {
+      throw new BootstrapError("Bundled skill verification failed after staging.", 3);
+    }
+    if (current.status === "update") {
+      renameSync(details.target, backup);
+      movedExisting = true;
+    }
+    try {
+      renameSync(staging, details.target);
+    } catch (error) {
+      if (movedExisting) {
+        renameSync(backup, details.target);
+        movedExisting = false;
+      }
+      throw error;
+    }
+    if (movedExisting) {
+      movedExisting = false;
+      try {
+        rmSync(backup, { recursive: true, force: true });
+      } catch {
+        // The verified target is already live; stale backup cleanup must not invalidate it.
+      }
+    }
+    return current.status === "absent" ? "installed" : "updated";
+  } finally {
+    rmSync(staging, { recursive: true, force: true });
+    if (movedExisting) {
+      try {
+        renameSync(backup, details.target);
+      } catch {
+        throw new BootstrapError(`Failed to restore previous msdevflow skill from ${backup}.`, 3);
+      }
+    }
+  }
+}
+
+function validatePythonRequirements(file) {
+  const requirements = readFileSync(file, "utf8")
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line && !line.startsWith("#"));
+  const playwrightRequirement = /^playwright(?:\[[a-z0-9_,.-]+\])?(?:(?:===|==|~=|!=|<=|>=|<|>)[a-z0-9.*+_-]+(?:,(?:===|==|~=|!=|<=|>=|<|>)[a-z0-9.*+_-]+)*)?$/i;
+  if (requirements.length !== 1 || !playwrightRequirement.test(requirements[0])) {
+    throw new BootstrapError("Unexpected workflow requirements; refusing to install unreviewed Python packages.", 3);
+  }
+}
+
+function firstOutputLine(output) {
+  return output.split(/\r?\n/).map((line) => line.trim()).find(Boolean) || "";
+}
+
+export function resolveExecutable(name, run, platform) {
+  const invocation = platform === "win32"
+    ? { command: "where.exe", args: [name] }
+    : { command: "sh", args: ["-c", "command -v -- \"$1\"", "sh", name] };
+  const result = runOptional(run, invocation);
+  return result.status === 0 ? firstOutputLine(result.stdout) : "";
+}
+
+function normalizedPath(value, platform) {
+  const normalized = value.replaceAll("\\", "/").replace(/\/+$/, "");
+  return platform === "win32" ? normalized.toLowerCase() : normalized;
+}
+
+function executableDirectory(value, platform) {
+  return platform === "win32" ? path.win32.dirname(value) : path.posix.dirname(value);
+}
+
+function hasPythonShebang(file) {
+  let descriptor;
+  try {
+    descriptor = openSync(file, "r");
+    const buffer = Buffer.alloc(256);
+    const bytesRead = readSync(descriptor, buffer, 0, buffer.length, 0);
+    return /^#!.*\bpython(?:[0-9.]*)?\b/i.test(buffer.toString("utf8", 0, bytesRead).split(/\r?\n/, 1)[0]);
+  } catch {
+    return false;
+  } finally {
+    if (descriptor !== undefined) {
+      closeSync(descriptor);
+    }
+  }
+}
+
+function pythonScriptDirectories(run, platform) {
+  const candidates = platform === "win32"
+    ? [{ command: "py", prefix: ["-3"] }, { command: "python", prefix: [] }, { command: "python3", prefix: [] }]
+    : [{ command: "python3", prefix: [] }, { command: "python", prefix: [] }];
+  const probe = "import json,sysconfig; print(json.dumps(sysconfig.get_path('scripts')))";
+  const directories = [];
+  for (const candidate of candidates) {
+    const result = runOptional(run, {
+      command: candidate.command,
+      args: [...candidate.prefix, "-c", probe],
+    });
+    if (result.status !== 0) {
+      continue;
+    }
+    try {
+      const directory = JSON.parse(result.stdout.trim());
+      if (typeof directory === "string" && directory) {
+        directories.push(directory);
+      }
+    } catch {
+      continue;
+    }
+  }
+  return directories;
+}
+
+function isPythonGitcode(executable, run, platform) {
+  if (/[\\/]Python[^\\/]*[\\/]Scripts[\\/]gitcode(?:\.exe)?$/i.test(executable)
+      || /[\\/]pipx[\\/]/i.test(executable)
+      || hasPythonShebang(executable)) {
+    return true;
+  }
+  const directory = normalizedPath(executableDirectory(executable, platform), platform);
+  return pythonScriptDirectories(run, platform)
+    .some((candidate) => normalizedPath(candidate, platform) === directory);
+}
+
+export function diagnoseGitcode(run, platform) {
+  const executable = resolveExecutable("gitcode", run, platform);
+  if (!executable) {
+    return {
+      classification: "absent",
+      existingExecutable: null,
+      workflowCommand: "gitcode",
+    };
+  }
+  if (isPythonGitcode(executable, run, platform)) {
+    return {
+      classification: "python",
+      existingExecutable: executable,
+      workflowCommand: "gitcode-npm",
+    };
+  }
+  const doctor = runOptional(run, executableCommand(executable, ["doctor", "install", "--json"], platform));
+  if (doctor.status === 0) {
+    try {
+      const metadata = JSON.parse(doctor.stdout);
+      if (metadata.distribution === "npm") {
+        return {
+          classification: "npm-official",
+          existingExecutable: executable,
+          workflowCommand: "gitcode",
+        };
+      }
+    } catch {
+      // Fall through to the fail-closed ownership error.
+    }
+  }
+  throw new BootstrapError(`Existing gitcode has unknown ownership: ${executable}. Refusing to overwrite it.`, 3);
+}
+
+function detectPython(run, platform) {
+  const candidates = platform === "win32"
+    ? [{ command: "py", prefix: ["-3"] }, { command: "python", prefix: [] }, { command: "python3", prefix: [] }]
+    : [{ command: "python3", prefix: [] }, { command: "python", prefix: [] }];
+  const probe = "import json,sys; print(json.dumps({'executable':sys.executable,'version':list(sys.version_info[:3])}))";
+  for (const candidate of candidates) {
+    const result = runOptional(run, { command: candidate.command, args: [...candidate.prefix, "-c", probe] });
+    if (result.status !== 0) {
+      continue;
+    }
+    try {
+      const data = JSON.parse(result.stdout.trim());
+      if (data.version[0] > 3 || (data.version[0] === 3 && data.version[1] >= 10)) {
+        return data;
+      }
+    } catch {
+      continue;
+    }
+  }
+  throw new BootstrapError("Python >=3.10 is required for workflow scripts.", 2);
+}
+
+function environmentHome(environment, platform) {
+  if (platform === "win32") {
+    return environment.USERPROFILE || homedir();
+  }
+  return environment.HOME || homedir();
+}
+
+export function gitcodeInstallDetails(
+  classification,
+  environment = process.env,
+  platform = process.platform,
+  npmPrefix = "",
+) {
+  const pathApi = platform === "win32" ? path.win32 : path.posix;
+  if (classification === "python") {
+    if (platform === "win32") {
+      const installPrefix = environment.GITCODE_NPM_PREFIX
+        || pathApi.join(environment.LOCALAPPDATA || "<LOCALAPPDATA>", "gitcode-npm");
+      const wrapperDir = environment.GITCODE_NPM_WRAPPER_DIR || npmPrefix || "<npm-user-prefix>";
+      return {
+        mode: "coexist",
+        workflowCommand: "gitcode-npm",
+        target: installPrefix,
+        cliTarget: pathApi.join(installPrefix, "gitcode.cmd"),
+        wrapperDir,
+        wrapper: pathApi.join(wrapperDir, "gitcode-npm.cmd"),
+        npmCommand: ["npm", "install", "-g", GITCODE_PACKAGE, "--prefix", installPrefix, `--registry=${REGISTRY}`],
+      };
+    }
+    const home = environmentHome(environment, platform);
+    const installPrefix = environment.GITCODE_NPM_PREFIX
+      || pathApi.join(environment.XDG_DATA_HOME || pathApi.join(home, ".local", "share"), "gitcode-npm");
+    const wrapperDir = environment.GITCODE_NPM_WRAPPER_DIR || pathApi.join(home, ".local", "bin");
+    return {
+      mode: "coexist",
+      workflowCommand: "gitcode-npm",
+      target: installPrefix,
+      cliTarget: pathApi.join(installPrefix, "bin", "gitcode"),
+      wrapperDir,
+      wrapper: pathApi.join(wrapperDir, "gitcode-npm"),
+      npmCommand: ["npm", "install", "-g", GITCODE_PACKAGE, "--prefix", installPrefix, `--registry=${REGISTRY}`],
+    };
+  }
+  return {
+    mode: classification === "npm-official" ? "upgrade-npm" : "standard",
+    workflowCommand: "gitcode",
+    target: npmPrefix || "<npm-global-prefix>",
+    cliTarget: null,
+    wrapperDir: null,
+    wrapper: null,
+    npmCommand: ["npm", "install", "-g", GITCODE_PACKAGE, `--registry=${REGISTRY}`],
+  };
+}
+
+function readOptionalFile(file) {
+  try {
+    const metadata = lstatSync(file);
+    if (metadata.isSymbolicLink() || !metadata.isFile()) {
+      throw new BootstrapError(`Refusing to overwrite unrelated wrapper: ${file}`, 3);
+    }
+    return readFileSync(file, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+}
+
+function shellQuote(value) {
+  return `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+
+function wrapperContent(details, platform) {
+  return platform === "win32"
+    ? `@echo off\r\ncall "${details.cliTarget}" %*\r\n`
+    : `#!/usr/bin/env bash\nexec ${shellQuote(details.cliTarget)} "$@"\n`;
+}
+
+function validateWrapper(details, platform) {
+  const existing = readOptionalFile(details.wrapper);
+  if (existing === null) {
+    return;
+  }
+  const accepted = [wrapperContent(details, platform)];
+  if (platform !== "win32") {
+    accepted.push(`#!/usr/bin/env bash\nexec "${details.cliTarget}" "$@"\n`);
+  }
+  if (!accepted.includes(existing)) {
+    throw new BootstrapError(`Refusing to overwrite unrelated wrapper: ${details.wrapper}`, 3);
+  }
+}
+
+function writeWrapper(details, platform) {
+  const content = wrapperContent(details, platform);
+  if (readOptionalFile(details.wrapper) === content) {
+    return;
+  }
+  validateWrapper(details, platform);
+  mkdirSync(details.wrapperDir, { recursive: true });
+  const temporary = path.join(details.wrapperDir, `.gitcode-npm-${randomUUID()}.tmp`);
+  let descriptor;
+  try {
+    descriptor = openSync(temporary, "wx");
+    writeFileSync(descriptor, content, "utf8");
+    if (platform !== "win32") {
+      fchmodSync(descriptor, 0o755);
+    }
+    closeSync(descriptor);
+    descriptor = undefined;
+    validateWrapper(details, platform);
+    if (platform === "win32" && readOptionalFile(details.wrapper) !== null) {
+      unlinkSync(details.wrapper);
+    }
+    renameSync(temporary, details.wrapper);
+  } finally {
+    if (descriptor !== undefined) {
+      closeSync(descriptor);
+    }
+    try {
+      unlinkSync(temporary);
+    } catch (error) {
+      if (error?.code !== "ENOENT") {
+        throw error;
+      }
+    }
+  }
+}
+
+function installGitcode(plan, run, platform) {
+  run(plan.installInvocation);
+  if (plan.gitcodeInstall.mode === "coexist") {
+    verifyFile(
+      plan.gitcodeInstall.cliTarget,
+      `Installed GitCode npm CLI target not found: ${plan.gitcodeInstall.cliTarget}.`,
+    );
+    writeWrapper(plan.gitcodeInstall, platform);
+    return {
+      command: plan.gitcodeInstall.workflowCommand,
+      executable: plan.gitcodeInstall.wrapper,
+    };
+  }
+  const executable = resolveExecutable("gitcode", run, platform);
+  if (!executable) {
+    throw new BootstrapError("GitCode npm CLI was installed but the gitcode executable is not available on PATH.");
+  }
+  return {
+    command: plan.gitcodeInstall.workflowCommand,
+    executable,
+  };
+}
+
+function safeAuthStatus(output) {
+  try {
+    const status = JSON.parse(output.trim());
+    return {
+      logged_in: status.logged_in === true,
+      username: typeof status.username === "string" ? status.username : null,
+      token_source: typeof status.token_source === "string" ? status.token_source : null,
+      git_protocol: typeof status.git_protocol === "string" ? status.git_protocol : null,
+    };
+  } catch {
+    return {
+      logged_in: false,
+      username: null,
+      token_source: null,
+      git_protocol: null,
+    };
+  }
+}
+
+function printPlan(plan, write) {
+  write("Setup plan (no changes made yet):");
+  write(`  Skills directory: ${plan.layout.skillsDir}`);
+  write(`  Bundled skill: ${plan.skillInstall.source}`);
+  write(`  Skill target: ${plan.skillInstall.target}`);
+  write(`  Skill action: ${plan.skillInstall.status}`);
+  write(`  Existing gitcode: ${plan.diagnosis.classification}`);
+  if (plan.diagnosis.existingExecutable) {
+    write(`  Existing executable: ${plan.diagnosis.existingExecutable}`);
+  }
+  write(`  Installation mode: ${plan.gitcodeInstall.mode}`);
+  write(`  Workflow command: ${plan.gitcodeInstall.workflowCommand}`);
+  write(`  GitCode package: ${GITCODE_PACKAGE}`);
+  write(`  Registry latest: ${plan.diagnosis.officialLatest || "unavailable"}`);
+  write(`  Registry: ${REGISTRY}`);
+  write(`  Target prefix: ${plan.gitcodeInstall.target}`);
+  if (plan.gitcodeInstall.wrapper) {
+    write(`  Wrapper: ${plan.gitcodeInstall.wrapper}`);
+    write(`  Wrapper target: ${plan.gitcodeInstall.cliTarget}`);
+  }
+  write(`  npm command: ${formatCommand(plan.installInvocation)}`);
+  write(`  Python: ${plan.python.executable} (${plan.python.version.join(".")})`);
+  write(`  Python dependency command: ${formatCommand(plan.pipInvocation)}`);
+  write("  Browser binary download: disabled");
+  write(`  GitCode authentication command when needed: ${plan.gitcodeInstall.workflowCommand} auth login --web`);
+  write("  Token handling: delegated to GitCode CLI; setup never reads or prints it");
+}
+
+async function confirmPlan(input, output) {
+  if (!input.isTTY || !output.isTTY) {
+    throw new BootstrapError("Refusing to modify the environment without --yes in a non-interactive session.", 2);
+  }
+  const terminal = createInterface({ input, output });
+  try {
+    const answer = await terminal.question("Apply this plan? [y/N] ");
+    return /^(?:y|yes)$/i.test(answer.trim());
+  } finally {
+    terminal.close();
+  }
+}
+
+function cliInvoker(cliExecutable, run, platform) {
+  return (args, options) => run(executableCommand(cliExecutable, args, platform), options);
+}
+
+function validateCore(cliExecutable, run, platform) {
+  const invoke = cliInvoker(cliExecutable, run, platform);
+  const version = invoke(["version"]).stdout.trim();
+  const doctor = invoke(["doctor", "install", "--json"], { allowFailure: true });
+  const missing = [];
+  try {
+    const metadata = JSON.parse(doctor.stdout);
+    if (doctor.status !== 0 || metadata.distribution !== "npm") {
+      missing.push("doctor install (official npm distribution)");
+    }
+  } catch {
+    missing.push("doctor install (invalid JSON)");
+  }
+  for (const [schema, requiredFlags] of Object.entries(REQUIRED_SCHEMAS)) {
+    const result = invoke(["schema", schema], { allowFailure: true });
+    if (result.status !== 0) {
+      missing.push(schema);
+      continue;
+    }
+    try {
+      const payload = JSON.parse(result.stdout);
+      const flags = new Set(Array.isArray(payload.flags) ? payload.flags.map((flag) => flag.name) : []);
+      for (const flag of requiredFlags) {
+        if (!flags.has(flag)) {
+          missing.push(`${schema} --${flag}`);
+        }
+      }
+    } catch {
+      missing.push(`${schema} (invalid schema JSON)`);
+    }
+  }
+  if (invoke(["api", "--help"], { allowFailure: true }).status !== 0) {
+    missing.push("api");
+  }
+  if (missing.length) {
+    throw new BootstrapError(`GitCode CLI is missing required capabilities: ${missing.join(", ")}.`);
+  }
+  const authentication = safeAuthStatus(invoke(["auth", "status", "--json"], { allowFailure: true }).stdout);
+  return { version, authentication, capabilities: "passed" };
+}
+
+function authenticateGitcode(cliExecutable, authentication, run, platform, write, jsonOutput) {
+  if (authentication.logged_in) {
+    return authentication;
+  }
+  const invoke = cliInvoker(cliExecutable, run, platform);
+  write("GitCode authentication is required. Opening the official browser login.");
+  write("Complete the GitCode page shown by the CLI; do not paste a token into this terminal or the conversation.");
+  invoke(["auth", "login", "--web"], {
+    inherit: true,
+    outputToStderr: jsonOutput,
+  });
+  authentication = safeAuthStatus(invoke(["auth", "status", "--json"], { allowFailure: true }).stdout);
+  if (!authentication.logged_in) {
+    throw new BootstrapError("GitCode browser login did not produce an authenticated CLI session.", 2);
+  }
+  return authentication;
+}
+
+function textResult(result, write) {
+  write("Setup completed:");
+  write(`  Skill: ${result.skill.status} at ${result.skill.target}`);
+  write(`  Workflow CLI command: ${result.gitcode.command}`);
+  write(`  GitCode CLI: ${result.gitcode.version}`);
+  write(`  Required capabilities: ${result.gitcode.capabilities}`);
+  write("  Authentication: authenticated via GitCode CLI");
+  if (result.gitcode.authentication.username) {
+    write(`  Username: ${result.gitcode.authentication.username}`);
+  }
+  write(`  Python: ${result.python.executable} ${result.python.version}`);
+  write("  Playwright Python package: installed");
+  write("  Chromium: not downloaded");
+}
+
+export async function runSetup(options, dependencies = {}) {
+  const platform = dependencies.platform || process.platform;
+  const environment = dependencies.environment || process.env;
+  const run = dependencies.run || execute;
+  const write = dependencies.write || ((line) => console.log(line));
+  const writePlan = dependencies.writePlan || write;
+  const layout = resolveLayout(options, environment, dependencies.bundledSkillDir);
+  const skillInstall = skillInstallDetails(layout);
+
+  if (Number(process.versions.node.split(".")[0]) < 18) {
+    throw new BootstrapError(`Node.js >=18 is required; found ${process.version}.`, 2);
+  }
+  run(namedCommand("npm", ["--version"], platform));
+  const npmPrefix = run(namedCommand("npm", ["config", "get", "prefix"], platform)).stdout.trim();
+  const gitVersion = run(namedCommand("git", ["--version"], platform)).stdout.trim();
+  const latestResult = runOptional(run, namedCommand(
+    "npm",
+    ["view", "@gitcode-cli/cli", "version", `--registry=${REGISTRY}`],
+    platform,
+  ));
+  const diagnosis = diagnoseGitcode(run, platform);
+  diagnosis.officialLatest = latestResult.status === 0 ? latestResult.stdout.trim() || null : null;
+  const gitcodeInstall = gitcodeInstallDetails(diagnosis.classification, environment, platform, npmPrefix);
+  if (gitcodeInstall.wrapper) {
+    validateWrapper(gitcodeInstall, platform);
+  }
+  const installInvocation = namedCommand(
+    gitcodeInstall.npmCommand[0],
+    gitcodeInstall.npmCommand.slice(1),
+    platform,
+  );
+
+  const python = detectPython(run, platform);
+  run({ command: python.executable, args: ["-m", "pip", "--version"] });
+  const pipInvocation = {
+    command: python.executable,
+    args: ["-m", "pip", "install", "-r", layout.bundledPythonRequirements],
+  };
+  const plan = {
+    layout,
+    skillInstall,
+    diagnosis,
+    installInvocation,
+    gitcodeInstall,
+    python,
+    pipInvocation,
+  };
+  printPlan(plan, writePlan);
+  if (options.dryRun) {
+    return { state: "planned", git: gitVersion, plan };
+  }
+  if (!options.yes && !(await (dependencies.confirm || confirmPlan)(process.stdin, process.stdout))) {
+    throw new BootstrapError("Setup cancelled; no changes were applied.", 2);
+  }
+  const currentDiagnosis = diagnoseGitcode(run, platform);
+  if (currentDiagnosis.classification !== diagnosis.classification
+      || currentDiagnosis.existingExecutable !== diagnosis.existingExecutable) {
+    throw new BootstrapError("GitCode command ownership changed after confirmation; refusing to install.", 3);
+  }
+  if (gitcodeInstall.wrapper) {
+    validateWrapper(gitcodeInstall, platform);
+  }
+
+  const installed = installGitcode(plan, run, platform);
+  const gitcode = validateCore(installed.executable, run, platform);
+  gitcode.command = installed.command;
+  gitcode.executable = installed.executable;
+
+  run(pipInvocation);
+  run({ command: python.executable, args: ["-c", "import playwright.sync_api"] });
+  gitcode.authentication = authenticateGitcode(
+    installed.executable,
+    gitcode.authentication,
+    run,
+    platform,
+    options.json ? writePlan : write,
+    options.json,
+  );
+  const skillStatus = installBundledSkill(skillInstall);
+  return {
+    state: "ready",
+    git: gitVersion,
+    skill: {
+      status: skillStatus,
+      target: layout.workflowDir,
+    },
+    gitcode,
+    python: {
+      executable: python.executable,
+      version: python.version.join("."),
+      playwright: "installed",
+      chromium: "not-downloaded",
+    },
+  };
+}
+
+export async function main(argv, dependencies = {}) {
+  const write = dependencies.write || ((line) => console.log(line));
+  const writeError = dependencies.writeError || ((line) => console.error(line));
+  const writePlan = dependencies.writePlan || (argv.includes("--json") ? writeError : write);
+  let options;
+  try {
+    options = parseArgs(argv);
+    if (options.help) {
+      write(usage());
+      return 0;
+    }
+    const result = await runSetup(options, { ...dependencies, write, writePlan });
+    if (options.json) {
+      write(JSON.stringify(result, null, 2));
+    } else if (result.state === "planned") {
+      write("Dry run completed; no changes were applied.");
+    } else {
+      textResult(result, write);
+    }
+    return 0;
+  } catch (error) {
+    const exitCode = error instanceof BootstrapError ? error.exitCode : 1;
+    const message = error instanceof Error ? error.message : String(error);
+    if (options?.json) {
+      write(JSON.stringify({ state: "blocked", error: message }));
+    } else {
+      writeError(`Error: ${message}`);
+    }
+    return exitCode;
+  }
+}