@opengsd/gsd-path 1.3.1 → 1.5.0

package/scripts/install.mjs

@@ -14,32 +14,12 @@ export const CLAUDE_BRIDGE = "@../AGENTS.md\n@../WORKFLOW.md\n";
 export const HOOKS_DIRECTORY = ".gsd-path";
 export const GUARD_SCRIPTS = ["guard_hook.py", "git_guard.py"];
 export const GUARD_MARKER = "gsd-path guard";
-export const PROJECT_RUNTIME_SCRIPTS = [
-  "pipeline_state.py",
-  "roadmap.py",
-  "check_handoffs.py",
-  "check_task_briefs.py",
-  "isolation.py",
-  "discussion_records.py",
-  "pipeline_git.py",
-  "promote_lookahead.py",
-  "detect_project.py",
-  "pipeline_diagnose.py",
-  "pipeline_undo.py",
-  "archive_milestone.py",
-  "review_panel.py",
-  "_common.py",
-  "worktree_paths.py",
-  "build_recovery.py",
-  "state_checkpoint.py",
-  "state_promote.py",
-  "discussion_validate.py",
-  "integration.py",
-];
 export const PROJECT_RUNTIME_MARKER = "gsd-path project runtime";
 export const PROJECT_STATUS_LAUNCHER = "status_runtime.py";
 export const PROJECT_STATUS_MARKER = "gsd-path project status launcher";
 const INSTALL_LOCK_NAME = ".gsd-path-install-lock";
+const LOCAL_EDITS_NOTE =
+  "; local edits inside these skills are not carried forward (see UPDATE.md#local-additions)";
 const INSTALL_LOCK_OWNER = "owner.json";
 const INSTALL_LOCK_SCHEMA = "gsd-path/install-lock/v2";
 export const CLAUDE_MATCHER = ".*";
@@ -151,15 +131,22 @@ export const GIT_HOOKS = [
 ];
 export const GIT_HOOK_NAMES = GIT_HOOKS.map(([name]) => name);
 
-// Every interpreter a managed hook may legitimately be pinned to.
-const INTERPRETER_CANDIDATES = ["python3", "python"];
+// Every interpreter a managed hook may legitimately be pinned to. Each is a
+// command prefix: python.org Windows installs may put only `py` on PATH.
+const INTERPRETER_CANDIDATES = ["python3", "python", "py -3"];
+
+// Run a Python interpreter command prefix (for example "py -3") with args.
+function spawnPython(interpreter, args, options) {
+  const [command, ...prefix] = interpreter.split(" ");
+  return spawnSync(command, [...prefix, ...args], options);
+}
 
-// Probe for a runnable Python interpreter (python3, then python) so emitted
-// hooks never hard-code an interpreter that does not exist on this machine
-// (python3 is typically absent on Windows).
+// Probe for a runnable Python interpreter (python3, then python, then py -3)
+// so emitted hooks never hard-code an interpreter that does not exist on this
+// machine (python3 is typically absent on Windows).
 export function detectPythonInterpreter() {
   for (const candidate of INTERPRETER_CANDIDATES) {
-    const result = spawnSync(
+    const result = spawnPython(
       candidate,
       ["-B", "-c", "import sys; raise SystemExit(sys.version_info < (3, 9))"],
       { stdio: "ignore" }
@@ -225,9 +212,10 @@ export const EXPLICIT_ONLY_TARGETS = new Set([
   "cursor",
   "zed",
   "kimi",
+  "muse",
   "shared-agents",
 ]);
-const SHARED_AGENT_TARGETS = new Set(["codex", "antigravity", "zed"]);
+const SHARED_AGENT_TARGETS = new Set(["codex", "antigravity", "zed", "muse"]);
 export const SHARED_AGENT_PROFILE = "shared-agents";
 export const CURSOR_AGENT_FILENAME = "gsd-path.md";
 export const CURSOR_AGENT_BACKUP_NAME = "cursor-agent-gsd-path.md";
@@ -241,7 +229,7 @@ const MANIFEST = JSON.parse(
 );
 
 function sharedInvocations(text) {
-  const pattern = /(`?)(\$gsd-path(?:-[a-z0-9]+)*|\$path)( status)?\1(?: \(Codex\) (?:and|or) (`?)\/(gsd-path(?:-[a-z0-9]+)*|path)( status)?\4 \((?:other hosts|Antigravity\/Zed)\))?/g;
+  const pattern = /(`?)(\$gsd-path(?:-[a-z0-9]+)*|\$path)( status)?\1(?: \(Codex\) (?:and|or) (`?)\/(gsd-path(?:-[a-z0-9]+)*|path)( status)?\4 \((?:other hosts|Antigravity\/Zed\/Muse)\))?/g;
   return text.replace(pattern, (_match, quote, token, arguments_, pairedQuote, pairedSkill, pairedArguments) => {
     const skill = token.slice(1);
     const argumentsText = arguments_ || "";
@@ -250,7 +238,7 @@ function sharedInvocations(text) {
     }
     const codex = `${MANIFEST.hosts.codex.invocation_prefix}${skill}`;
     const others = `${MANIFEST.hosts.antigravity.invocation_prefix}${skill}`;
-    return `${quote}${codex}${argumentsText}${quote} (Codex) or ${quote}${others}${argumentsText}${quote} (Antigravity/Zed)`;
+    return `${quote}${codex}${argumentsText}${quote} (Codex) or ${quote}${others}${argumentsText}${quote} (Antigravity/Zed/Muse)`;
   });
 }
 export function skillNamesForManifest(manifest) {
@@ -368,7 +356,7 @@ export function defaultRoot(target, env = process.env) {
   }
   if (target === "antigravity") return absolutePath("~/.gemini/antigravity-cli/skills");
   if (target === "cursor") return absolutePath("~/.cursor/skills");
-  if (target === "zed") return absolutePath("~/.agents/skills");
+  if (target === "zed" || target === "muse") return absolutePath("~/.agents/skills");
   if (target === "kiro") {
     return absolutePath(path.join(env.KIRO_HOME || expandUser("~/.kiro"), "skills"));
   }
@@ -399,7 +387,9 @@ function isOwnedRouterAlias(skillDir) {
   const versionFile = path.join(skillDir, "VERSION");
   if (!isFile(versionFile)) return isManagedProjectRuntime(runtime); // installs before alias version stamping
   try {
-    return /^[0-9]+(?:\.[0-9]+)+$/.test(fs.readFileSync(versionFile, "utf8").trim());
+    return /^[0-9]+(?:\.[0-9]+)+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.test(
+      fs.readFileSync(versionFile, "utf8").trim()
+    );
   } catch {
     return false;
   }
@@ -475,12 +465,17 @@ function materializedResourceBytes(source, destination) {
   return Buffer.from(rewriteRouterAliasSkill(data.toString("utf8"), alias, canonical));
 }
 
+// The JavaScript realpath keeps Windows 8.3 short names (C:\Users\LONGNA~1);
+// Python's resolve() expands them, and both installers must hash one lock
+// identity per target, so Windows asks the OS for the final path as Python does.
+const realpath = process.platform === "win32" ? fs.realpathSync.native : fs.realpathSync;
+
 function resolveNonStrict(value) {
   let prefix = path.resolve(value);
   const suffix = [];
   for (;;) {
     try {
-      return path.join(fs.realpathSync(prefix), ...suffix);
+      return path.join(realpath(prefix), ...suffix);
     } catch {
       const parent = path.dirname(prefix);
       if (parent === prefix) return path.join(prefix, ...suffix);
@@ -1045,7 +1040,7 @@ async function applyTarget(plan, stagedRoot, transaction) {
     const destination = path.join(plan.root, name);
     hooks.reserveDirectory(destination);
     transaction.installed.push(destination);
-    fs.cpSync(path.join(stagedRoot, name), destination, { recursive: true, errorOnExist: true, force: false });
+    copyIntoReservedDirectory(path.join(stagedRoot, name), destination);
     await tick();
   }
   if (cursorAgent !== null) {
@@ -1059,6 +1054,18 @@ function reserveDirectory(destination) {
   fs.mkdirSync(destination);
 }
 
+// Node 26 rejects recursive cpSync when the destination directory already exists
+// and errorOnExist is set. Reserve the skill directory, then copy each staged entry.
+export function copyIntoReservedDirectory(source, destination) {
+  for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
+    fs.cpSync(path.join(source, entry.name), path.join(destination, entry.name), {
+      recursive: true,
+      errorOnExist: true,
+      force: false,
+    });
+  }
+}
+
 function reserveFile(destination) {
   const descriptor = fs.openSync(destination, "wx", 0o644);
   try {
@@ -1090,7 +1097,7 @@ function rollbackTarget(transaction) {
     removePath(destination);
   }
   for (const [original, stored] of [...transaction.moved].reverse()) {
-    if (lexists(stored)) fs.renameSync(stored, original);
+    if (lexists(stored)) renameRetrying(stored, original);
   }
   if (transaction.backup !== null) {
     try {
@@ -1200,7 +1207,7 @@ export function deploymentPlans(plans) {
     if (group.length > 1) {
       if (!targets.every((name) => SHARED_AGENT_TARGETS.has(name))) {
         throw new InstallerError(
-          `only Codex, Antigravity, and Zed may share a skills root: ${targets.join(", ")}`
+          `only Codex, Antigravity, Zed, and Muse may share a skills root: ${targets.join(", ")}`
         );
       }
       profile = SHARED_AGENT_PROFILE;
@@ -1314,13 +1321,34 @@ function plannedBackupRoots(legacyRoot, deployments) {
   return planned;
 }
 
+// Access denied and busy: on Windows a scanner or indexer that briefly opens a
+// freshly written file blocks moving it or the directory holding it.
+const WINDOWS_BUSY_CODES = new Set(["EPERM", "EACCES", "EBUSY"]);
+const RENAME_ATTEMPTS = 20;
+
+function renameRetrying(from, to) {
+  if (process.platform !== "win32") return fs.renameSync(from, to);
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      return fs.renameSync(from, to);
+    } catch (error) {
+      // A directory moved onto an existing directory also reports EPERM; that
+      // is not transient, so never retry it.
+      if (!WINDOWS_BUSY_CODES.has(error.code)
+          || fs.lstatSync(to, { throwIfNoEntry: false })?.isDirectory()
+          || attempt === RENAME_ATTEMPTS - 1) throw error;
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, Math.min(10 * 2 ** attempt, 250));
+    }
+  }
+}
+
 // Test-injection points; production callers never touch these.
 export const hooks = {
   mismatches,
   applyTarget,
-  rename: fs.renameSync.bind(fs),
+  rename: renameRetrying,
   renameInstallLock: fs.renameSync.bind(fs),
-  renameInstallStage: fs.renameSync.bind(fs),
+  renameInstallStage: renameRetrying,
   processIdentity,
   reserveDirectory,
   reserveFile,
@@ -1332,7 +1360,7 @@ export const hooks = {
 // Project installation already requires Python; keep runtime lifecycle ownership there.
 function projectAdapter(source, project, action, payload = {}, env = process.env) {
   const interpreter = requiredPythonRuntime("project runtime");
-  const result = spawnSync(interpreter, ["-B", path.join(SCRIPT_DIRECTORY, "install.py"), "--adapter-request"], {
+  const result = spawnPython(interpreter, ["-B", path.join(SCRIPT_DIRECTORY, "install.py"), "--adapter-request"], {
     input: JSON.stringify({ source, project, action, ...payload }), encoding: "utf8", env: { ...process.env, ...env },
   });
   if (result.error || result.status !== 0) {
@@ -1484,7 +1512,7 @@ export async function install(sourceRoot, plans, options = {}) {
         if (legacyTransaction.backup !== null) {
           results.push(
             `codex-legacy: backed up ${legacyTransaction.moved.length} entries to ` +
-              `${legacyTransaction.backup}`
+              `${legacyTransaction.backup}${LOCAL_EDITS_NOTE}`
           );
         }
       }
@@ -1503,7 +1531,7 @@ export async function install(sourceRoot, plans, options = {}) {
         if (transaction.backup !== null) {
           results.push(
             `${plan.targets.join("+")}: backed up ${transaction.moved.length} entries ` +
-              `to ${transaction.backup}`
+              `to ${transaction.backup}${LOCAL_EDITS_NOTE}`
           );
         }
       }
@@ -1533,7 +1561,7 @@ export async function install(sourceRoot, plans, options = {}) {
 }
 
 // Documented project-relative skill roots (verified against each host's
-// official skills docs). Codex, Zed, and Antigravity all discover the
+// official skills docs). Codex, Zed, Muse, and Antigravity all discover the
 // project-level .agents/skills standard directory.
 export function localRoot(target, projectDir) {
   const relative = LOCAL_ROOTS[target];
@@ -1559,6 +1587,7 @@ export function parseCli(argv) {
     "dry-run": { type: "boolean", default: false },
     local: { type: "boolean", default: false },
     project: { type: "string" },
+    "member-of": { type: "string" },
     doctor: { type: "boolean", default: false },
     hooks: { type: "boolean", default: false },
     "hooks-init": { type: "boolean", default: false },
@@ -1653,6 +1682,7 @@ function usage() {
     "  --doctor              read-only health check of installs, hooks, and state\n" +
     "  --hooks               with --project: install guard hooks (see HOOKS.md)\n" +
     "  --hooks-init          add guards to an existing project without changing its contracts\n" +
+    "  --member-of PATH      with --project: install member git hooks that run PATH's guard\n" +
     "  --runtime-restore     restore the exact declared runtime from --source-root\n" +
     "  --runtime-upgrade     explicitly select the supplied package runtime\n" +
     "  --runtime-migrate     migrate a legacy runtime for review; add --update to continue upgrading\n" +
@@ -1702,9 +1732,10 @@ export async function main(argv, env = process.env) {
     ui.error("--runtime-migrate --update requires --project and cannot be combined with another runtime, doctor, or hook operation");
     return 2;
   }
-  if (!migrateAndUpdate && ["runtime-restore", "runtime-upgrade", "runtime-migrate"].some(name => values[name])) {
+  if (!migrateAndUpdate && (values["member-of"] !== undefined
+      || ["runtime-restore", "runtime-upgrade", "runtime-migrate"].some(name => values[name]))) {
     const interpreter = requiredPythonRuntime("project runtime");
-    const result = spawnSync(interpreter, ["-B", path.join(SCRIPT_DIRECTORY, "install.py"),
+    const result = spawnPython(interpreter, ["-B", path.join(SCRIPT_DIRECTORY, "install.py"),
       ...argv.filter(arg => arg !== "--no-color")], { stdio: "inherit", env });
     return result.status ?? 1;
   }
@@ -1809,7 +1840,7 @@ export async function main(argv, env = process.env) {
   }
   if (migrateAndUpdate) {
     const interpreter = requiredPythonRuntime("project runtime");
-    const migration = spawnSync(interpreter, ["-B", path.join(SCRIPT_DIRECTORY, "install.py"),
+    const migration = spawnPython(interpreter, ["-B", path.join(SCRIPT_DIRECTORY, "install.py"),
       "--runtime-migrate", "--project", project, "--source-root", sourceRoot,
       ...(values["dry-run"] ? ["--dry-run"] : [])], { stdio: "inherit", env });
     if (migration.error || migration.status !== 0) {