arcane-cli 0.16.1 → 0.16.3

package/dist/assets/.arcane/governance/git-conventions.md

@@ -220,6 +220,13 @@ Create the session branch as the **first action** of any session, before any fil
   1. `git branch -m <old> <new>`
   2. `git push -u origin <new>`
   3. `git push origin --delete <old>` (skip this if an active PR still depends on `<old>`).
+- **EF-20 hazard:** on some Windows/Git-for-Windows filesystems, a rename or delete can trigger
+  an interactive retry prompt (e.g. a file lock from an editor or antivirus scan) that blocks
+  indefinitely on a terminal with no non-interactive fallback. When running these commands
+  directly through a tool that supports a per-call timeout (an agent's shell tool, a CI step),
+  set one rather than assuming the command will return. Arcane's own TypeScript Git helper
+  (`src/modules/git.ts`) applies this as a standing contract — closed stdin plus a
+  command-class timeout — for every `git` invocation the CLI itself makes.
 
 **Agents:**
 

package/dist/assets/.github/prompts/spell-close-session.prompt.md

@@ -101,7 +101,8 @@ Rules:
 
 9. **Stage and commit session-close docs.**
 
-   **Remote-capability check:** classify the state created by `spell-open-session` before branching, staging, push, or PR operations.
+   **Remote-capability check:** classify the state created by `spell-open-session` before branching, staging, push, or PR operations. Check for **not a repository at all** first — every other classification assumes a `.git` directory exists.
+   - **Not a Git repository (EF-05):** `git rev-parse --is-inside-work-tree` fails. Do not attempt any git operation (branch, add, commit, push). Fail closed with: `No Git repository detected. Run \`git init -b main\` first (explicit -b avoids landing on "master" on systems where that's the init.defaultBranch default), then re-run spell-close-session.` This mirrors `spell init`'s own next-steps guidance for the same state.
    - **Usable supported remote/merge path:** requires an authenticated supported provider (`github.com`, `dev.azure.com`, or `visualstudio.com`). Keep the current compliant session/PR/worktree branch, resolve the actual remote name and integration branch, and use the provider-neutral PR path below.
    - **No usable remote/merge path:** remain on the current trunk. Do not create a dead session branch, push, pull, or open a PR. Apply the EF-28 interactive commit approval gate, commit locally on trunk after approval, report `Local-only close: committed on <trunk>; no remote PR/pull performed`, and skip steps 9a, 9c, and 10's remote operations.
    - **Read-only session:** if no repository mutation occurred, do not create a branch or commit.

package/dist/index.js

@@ -1599,15 +1599,140 @@ async function runAgentsList(targetDir) {
 
 // src/modules/git.ts
 import { execFile } from "child_process";
-import { promisify } from "util";
-var execFileAsync = promisify(execFile);
-async function inspectGitRepository(cwd) {
-  try {
-    const { stdout: stdout2 } = await execFileAsync(
+var GitTimeoutError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "GitTimeoutError";
+  }
+};
+var NETWORK_SUBCOMMANDS = /* @__PURE__ */ new Set(["fetch", "pull", "push", "clone", "ls-remote", "send-email"]);
+var WRITE_SUBCOMMANDS = /* @__PURE__ */ new Set([
+  "init",
+  "commit",
+  "add",
+  "checkout",
+  "switch",
+  "merge",
+  "rebase",
+  "reset",
+  "tag",
+  "mv",
+  "rm",
+  "cherry-pick",
+  "revert",
+  "stash",
+  "apply",
+  "am",
+  "restore",
+  "submodule",
+  "sparse-checkout",
+  "maintenance",
+  "notes"
+]);
+var AMBIGUOUS_AS_WRITE = /* @__PURE__ */ new Set(["branch", "config", "remote", "worktree"]);
+var READ_SUBCOMMANDS = /* @__PURE__ */ new Set([
+  "status",
+  "rev-parse",
+  "log",
+  "diff",
+  "show",
+  "describe",
+  "cat-file",
+  "ls-files",
+  "ls-tree",
+  "symbolic-ref",
+  "merge-base",
+  "blame",
+  "shortlog",
+  "grep",
+  "reflog",
+  "diff-tree",
+  "rev-list",
+  "name-rev",
+  "count-objects",
+  "verify-commit",
+  "verify-tag",
+  "help",
+  "version"
+]);
+var GLOBAL_FLAGS_WITH_SEPARATE_VALUE = /* @__PURE__ */ new Set(["-c", "-C"]);
+var DEFAULT_TIMEOUTS_MS = {
+  read: 15e3,
+  write: 3e4,
+  network: 12e4
+};
+function classifyGitCommand(args) {
+  let subcommand;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (GLOBAL_FLAGS_WITH_SEPARATE_VALUE.has(arg)) {
+      i++;
+      continue;
+    }
+    if (arg.startsWith("-")) continue;
+    subcommand = arg;
+    break;
+  }
+  if (!subcommand) return "read";
+  if (NETWORK_SUBCOMMANDS.has(subcommand)) return "network";
+  if (WRITE_SUBCOMMANDS.has(subcommand) || AMBIGUOUS_AS_WRITE.has(subcommand)) return "write";
+  if (READ_SUBCOMMANDS.has(subcommand)) return "read";
+  return "write";
+}
+function buildGitEnv() {
+  return {
+    ...process.env,
+    GIT_TERMINAL_PROMPT: "0",
+    GCM_INTERACTIVE: "Never",
+    GIT_OPTIONAL_LOCKS: "0"
+  };
+}
+function runGit(cwd, args, options = {}) {
+  const commandClass = options.commandClass ?? classifyGitCommand(args);
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUTS_MS[commandClass] ?? DEFAULT_TIMEOUTS_MS.write;
+  return new Promise((resolve, reject) => {
+    const child = execFile(
       "git",
-      ["rev-parse", "--is-inside-work-tree"],
-      { cwd }
+      args,
+      {
+        cwd,
+        env: buildGitEnv(),
+        timeout: timeoutMs,
+        // SIGTERM (Node's default) rather than SIGKILL: gives git a chance
+        // to run its own cleanup on POSIX, relevant to EF-20's own concern
+        // about a killed operation leaving refs/locks in an uncertain state.
+        // Moot on Windows -- Node docs: both map to an abrupt TerminateProcess
+        // there -- but this module isn't Windows-gated.
+        killSignal: "SIGTERM",
+        windowsHide: true,
+        encoding: "utf8"
+      },
+      (error, stdout, stderr) => {
+        if (error) {
+          if (error.killed) {
+            reject(
+              new GitTimeoutError(
+                // NOTE: embeds the raw args, including any secrets a future
+                // network-class caller might pass (e.g. a credentialed
+                // clone URL). No current caller does; redact before one does.
+                `git ${args.join(" ")} timed out after ${timeoutMs}ms (class: ${commandClass})`,
+                { cause: error }
+              )
+            );
+            return;
+          }
+          reject(error);
+          return;
+        }
+        resolve({ stdout, stderr });
+      }
     );
+    child.stdin?.end();
+  });
+}
+async function inspectGitRepository(cwd) {
+  try {
+    const { stdout: stdout2 } = await runGit(cwd, ["rev-parse", "--is-inside-work-tree"]);
     if (stdout2.trim() !== "true") {
       return { status: "not-repository" };
     }
@@ -1615,28 +1740,61 @@ async function inspectGitRepository(cwd) {
     return { status: "not-repository" };
   }
   try {
-    await execFileAsync("git", ["rev-parse", "--verify", "HEAD"], { cwd });
+    await runGit(cwd, ["rev-parse", "--verify", "HEAD"]);
   } catch {
     return { status: "no-commits" };
   }
-  const { stdout } = await execFileAsync(
-    "git",
-    ["status", "--porcelain", "-uall"],
-    { cwd }
-  );
+  const { stdout } = await runGit(cwd, ["status", "--porcelain", "-uall"]);
   const lines = stdout.trim();
   return {
     status: "ready",
     uncommittedChanges: lines.length === 0 ? 0 : lines.split("\n").length
   };
 }
-async function countUncommittedChanges(cwd) {
+async function correctUnbornMasterDefault(cwd) {
+  let current;
+  try {
+    const { stdout } = await runGit(cwd, ["symbolic-ref", "--short", "HEAD"]);
+    current = stdout.trim();
+  } catch {
+    return { corrected: false, to: "main" };
+  }
+  if (current !== "master") {
+    return { corrected: false, to: "main" };
+  }
+  try {
+    await runGit(cwd, ["rev-parse", "--verify", "HEAD"]);
+    return { corrected: false, to: "main" };
+  } catch {
+  }
   try {
-    const { stdout } = await execFileAsync("git", ["status", "--porcelain", "-uall"], { cwd });
-    const lines = stdout.trim();
-    return lines.length === 0 ? 0 : lines.split("\n").length;
+    await runGit(cwd, ["rev-parse", "--verify", "refs/heads/main"]);
+    return { corrected: false, to: "main" };
   } catch {
-    return 0;
+  }
+  await runGit(cwd, ["symbolic-ref", "HEAD", "refs/heads/main"]);
+  return { corrected: true, from: current, to: "main" };
+}
+async function ensureLocalPullRebase(cwd) {
+  let rawLocalValue;
+  try {
+    const { stdout } = await runGit(cwd, ["config", "--local", "--get", "pull.rebase"]);
+    rawLocalValue = stdout.trim();
+  } catch {
+    rawLocalValue = void 0;
+  }
+  if (rawLocalValue === void 0) {
+    await runGit(cwd, ["config", "--local", "pull.rebase", "true"]);
+    return { action: "set" };
+  }
+  try {
+    const { stdout } = await runGit(cwd, ["config", "--local", "--type=bool", "--get", "pull.rebase"]);
+    if (stdout.trim() === "false") {
+      return { action: "explicit-false-preserved" };
+    }
+    return { action: "already-set" };
+  } catch {
+    return { action: "already-set" };
   }
 }
 
@@ -1716,21 +1874,42 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
   console.log(chalk2.hex("#a855f7")(`
   \u2726 Arcane v${packageVersion}
 `));
+  let repoNotFound = false;
   if (!options.dryRun) {
-    const dirtyCount = await countUncommittedChanges(targetDir);
-    if (dirtyCount > 0) {
-      printWarning(`This repo has ${dirtyCount} uncommitted change${dirtyCount === 1 ? "" : "s"}.`);
-      printInfo("Running spell init will add new files to your working tree.");
-      console.log();
-      const continueAnyway = await confirm({
-        message: "Continue anyway?",
-        default: true
-      });
-      if (!continueAnyway) {
-        console.log("\nCancelled. Commit or stash your changes first.");
-        return;
+    const gitState = await inspectGitRepository(targetDir);
+    if (gitState.status === "not-repository") {
+      repoNotFound = true;
+    } else {
+      if (gitState.status === "no-commits") {
+        const correction = await correctUnbornMasterDefault(targetDir);
+        if (correction.corrected) {
+          printInfo(
+            `Repointed the unborn branch from "${correction.from}" to "${correction.to}" (avoids the Git for Windows default-branch trap).`
+          );
+        }
+      }
+      if (gitState.status === "ready" && gitState.uncommittedChanges > 0) {
+        printWarning(
+          `This repo has ${gitState.uncommittedChanges} uncommitted change${gitState.uncommittedChanges === 1 ? "" : "s"}.`
+        );
+        printInfo("Running spell init will add new files to your working tree.");
+        console.log();
+        const continueAnyway = await confirm({
+          message: "Continue anyway?",
+          default: true
+        });
+        if (!continueAnyway) {
+          console.log("\nCancelled. Commit or stash your changes first.");
+          return;
+        }
+        console.log();
+      }
+      const rebaseResult = await ensureLocalPullRebase(targetDir);
+      if (rebaseResult.action === "explicit-false-preserved") {
+        printWarning(
+          "This repo's pull.rebase is explicitly set to false, but Arcane's governance mandates rebase-and-fast-forward (see .arcane/governance/git-conventions.md). Left as-is since you set it explicitly."
+        );
       }
-      console.log();
     }
   }
   let profile = options.profile;
@@ -1879,6 +2058,12 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
       "Review .arcane/governance/ docs and customize for your project"
     );
   }
+  if (repoNotFound) {
+    printNextStep(
+      step++,
+      'Initialize Git for this project: `git init -b main` (avoids defaulting to "master" on systems where that\'s the system default)'
+    );
+  }
   printNextStep(
     step++,
     "Commit the new files: git add .arcane .github .claude AGENTS.md CLAUDE.md .arcane.json"
@@ -2391,7 +2576,7 @@ async function runUninstall(options, targetDir) {
 import { access as access3, readFile as readFile5, mkdir as mkdir5, copyFile as fsCopyFile2 } from "fs/promises";
 import { join as join10, dirname as dirname2 } from "path";
 import { execFile as execFile2 } from "child_process";
-import { promisify as promisify2 } from "util";
+import { promisify } from "util";
 
 // src/config/incidents.ts
 var INCIDENT_QUEUE = [
@@ -2459,7 +2644,7 @@ function evaluateIncidentGate(records) {
 }
 
 // src/commands/doctor.ts
-var execFileAsync2 = promisify2(execFile2);
+var execFileAsync = promisify(execFile2);
 async function checkNodeVersion() {
   const name = "Node.js version";
   const raw = process.version;
@@ -2497,7 +2682,7 @@ async function checkVSCodeExtension(id, label) {
   let installBin = "code";
   for (const bin of ["code", "code-insiders"]) {
     try {
-      await execFileAsync2(bin, ["--version"]);
+      await execFileAsync(bin, ["--version"]);
       installBin = bin;
       break;
     } catch {
@@ -2559,6 +2744,29 @@ async function checkArcaneManifest(targetDir) {
     };
   }
 }
+async function checkPullRebase(targetDir) {
+  const name = "Git pull.rebase (rebase-and-fast-forward mandate)";
+  try {
+    const { stdout } = await runGit(targetDir, ["config", "--type=bool", "--get", "pull.rebase"]);
+    const value = stdout.trim();
+    if (value === "true") {
+      return { name, passed: true, message: "pull.rebase=true" };
+    }
+    return {
+      name,
+      passed: false,
+      message: `pull.rebase resolves to "${value}", not "true" -- a bare \`git pull\` will create merge commits, contradicting git-conventions.md's rebase-and-fast-forward mandate. Run: git config --local pull.rebase true`,
+      blocking: false
+    };
+  } catch {
+    return {
+      name,
+      passed: false,
+      message: "pull.rebase is unset, not a recognized boolean, or this isn't a Git repository -- effective behavior may not be rebase-and-fast-forward, and Git for Windows defaults this to false when unset. Run: git config --local pull.rebase true",
+      blocking: false
+    };
+  }
+}
 function checkIncidentReleaseGate() {
   const result = evaluateIncidentGate(INCIDENT_QUEUE);
   if (result.blocked) {
@@ -2621,7 +2829,8 @@ async function runDoctor(targetDir, options = {}, assetsDir) {
     checkNodeVersion(),
     checkVSCodeExtension("GitHub.copilot-chat", "GitHub Copilot (Chat)"),
     checkArcaneManifest(targetDir),
-    Promise.resolve(checkIncidentReleaseGate())
+    Promise.resolve(checkIncidentReleaseGate()),
+    checkPullRebase(targetDir)
   ]);
   const sessionResults = await checkSessionContinuity(targetDir);
   results.push(...sessionResults);