@retasc/cli 1.36.0 → 1.36.1

package/CHANGELOG.md

@@ -6,6 +6,18 @@ release commits and the issues they reference.
 
 Dates are the npm publish date. Each entry names the RTSC issue behind it.
 
+## 1.36.1 (2026-08-25)
+
+- **RTSC-645** — `retasc gate install` no longer throws away your edits. It rewrites the
+  commit-msg hook and the Action on every run, so a gate you had customized (say, one that
+  also checks the branch number) used to vanish behind a green "✓ Updated" with nothing
+  saying so. Generated files now carry a hash of their own contents, so a later run can tell
+  "still exactly what we wrote" from "someone changed this". A changed file is copied to
+  `.bak` first, keeping its permissions, and the run tells you where the copy went; a second
+  round of edits goes to `.bak.2` rather than overwriting the first. Untouched files are
+  replaced silently as before, including when you re-key the gate to a different prefix, so
+  the common path gained no prompts and no flags.
+
 ## 1.36.0 (2026-08-25)
 
 - **RTSC-520** — the CLI now says when it is out of date. There was no version check

package/dist/commands/gate.js

@@ -1,6 +1,7 @@
 import { spawnSync } from "node:child_process";
-import { mkdirSync, writeFileSync, existsSync, chmodSync } from "node:fs";
-import { join, dirname } from "node:path";
+import { createHash } from "node:crypto";
+import { mkdirSync, writeFileSync, readFileSync, copyFileSync, statSync, existsSync, chmodSync, } from "node:fs";
+import { join, dirname, relative } from "node:path";
 import { resolveMcpConn, readMcpJson, workspacePrefix } from "../lib/claim.js";
 import { claudeLocalRetascEntry } from "../lib/binding.js";
 import { getBinding } from "../lib/keystore.js";
@@ -163,6 +164,135 @@ function writeFile(path, body, mode) {
         }
     }
 }
+// RTSC-645: never discard someone's edits silently. Both files are rewritten on
+// every run, so a hand-customized gate (e.g. one that also matches the branch
+// number) used to vanish behind a green "✓ Updated". We stamp what we generate
+// with a hash of its own body, so a later run can tell "still exactly what we
+// wrote" from "someone changed this" without keeping any state outside the file.
+//
+// Hashing the body against its OWN stamp — rather than re-rendering the current
+// template and diffing — is what keeps this stable across CLI versions: changing
+// template text would otherwise make every pristine file on every machine look
+// edited and warn on upgrade.
+const STAMP_PREFIX = "# retasc-gate: sha256=";
+const STAMP_RE = /^# retasc-gate: sha256=([0-9a-f]{64})$/;
+/** Compare and hash on normalized text: a CRLF checkout (Git for Windows'
+ *  autocrlf default) or a stray BOM must not make our own untouched file look
+ *  edited on every single run. */
+function normalizeText(s) {
+    return s.replace(/^/, "").replace(/\r\n/g, "\n");
+}
+function bodyHash(body) {
+    return createHash("sha256").update(normalizeText(body), "utf8").digest("hex");
+}
+/** Append the stamp as the final line — after the shebang and after any YAML, so
+ *  placement never depends on the file's syntax. Both layers take `#` comments. */
+export function withStamp(body) {
+    return `${body}${STAMP_PREFIX}${bodyHash(body)}\n`;
+}
+/** Split a stamped file back into (body, recorded hash), or null when the last
+ *  line isn't one of our stamps. */
+function splitStamp(raw) {
+    const trimmed = raw.endsWith("\n") ? raw.slice(0, -1) : raw;
+    const cut = trimmed.lastIndexOf("\n");
+    const last = cut === -1 ? trimmed : trimmed.slice(cut + 1);
+    const m = last.match(STAMP_RE);
+    if (!m)
+        return null;
+    return { body: cut === -1 ? "" : trimmed.slice(0, cut + 1), hash: m[1] };
+}
+/** Classify what's on disk. Anything we can't positively prove we generated —
+ *  no stamp, a broken stamp, an unreadable file — counts as `modified`, because
+ *  the cost of a needless backup is a stray file and the cost of the wrong call
+ *  is someone's work. */
+export function classifyGateFile(path) {
+    if (!existsSync(path))
+        return "absent";
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch {
+        return "modified";
+    }
+    // Normalize BEFORE splitting: on a CRLF checkout the stamp line ends in \r and
+    // would never match, so our own untouched file would look edited on every run
+    // and pile up a fresh .bak each time.
+    const s = splitStamp(normalizeText(raw));
+    if (!s)
+        return "modified";
+    return s.hash === bodyHash(s.body) ? "pristine" : "modified";
+}
+/** Pick where this backup goes. `<path>.bak` when it's free, or already holds
+ *  exactly these bytes (a repeated run of the same edit shouldn't pile up
+ *  copies); otherwise the first free `<path>.bak.2`, `.bak.3`, ... Overwriting a
+ *  backup that holds DIFFERENT bytes would lose the only copy of an earlier
+ *  edit — someone who edits, installs, edits again and installs again — which is
+ *  the exact data loss this change exists to stop. */
+function nextBackupPath(path) {
+    const first = `${path}.bak`;
+    if (!existsSync(first))
+        return first;
+    // Unreadable source (it classified as `modified` precisely because we couldn't
+    // read it): we can't compare, so take a fresh slot rather than crash or clobber.
+    let current = null;
+    try {
+        current = readFileSync(path);
+    }
+    catch {
+        current = null;
+    }
+    try {
+        if (current && readFileSync(first).equals(current))
+            return first;
+    }
+    catch {
+        /* unreadable backup: fall through and take a fresh slot rather than clobber it */
+    }
+    for (let n = 2; n < 100; n++) {
+        const candidate = `${path}.bak.${n}`;
+        if (!existsSync(candidate))
+            return candidate;
+        try {
+            if (current && readFileSync(candidate).equals(current))
+                return candidate;
+        }
+        catch {
+            /* keep looking */
+        }
+    }
+    throw new Error(`refusing to overwrite an existing backup: ${first} through ${path}.bak.99 are all taken — clear the ones you don't need and re-run`);
+}
+/** Copy to the slot `nextBackupPath` picked, preserving the mode so a restored
+ *  hook is still executable (a `mv` of a 0644 backup would silently stop
+ *  running). */
+function backupFile(path) {
+    const bak = nextBackupPath(path);
+    copyFileSync(path, bak);
+    try {
+        chmodSync(bak, statSync(path).mode & 0o777);
+    }
+    catch {
+        /* best effort (e.g. Windows) */
+    }
+    return bak;
+}
+/**
+ * Write one gate layer, backing up first when the file on disk isn't ours.
+ * Returns the line to print, so both layers report identically.
+ */
+function writeLayer(root, path, body, mode) {
+    const state = classifyGateFile(path);
+    const rel = relative(root, path);
+    const lines = [];
+    if (state === "modified") {
+        const bak = backupFile(path);
+        lines.push(`⚠ ${rel} had local edits — saved to ${relative(root, bak)} before replacing it.`);
+    }
+    writeFile(path, withStamp(body), mode);
+    lines.push(`✓ ${state === "absent" ? "Wrote" : "Updated"} ${rel}`);
+    return lines;
+}
 /**
  * Install the commit↔issue gate into the current repo, parameterized by `prefix`.
  * Writes the requested layers (hook and/or Action) and enables the hook path.
@@ -179,13 +309,14 @@ export function installGate(opts) {
     if (!hook && !action) {
         throw new Error("nothing to install — drop --no-hook/--no-action or pick at least one layer");
     }
+    let backedUp = false;
     if (hook) {
         const hookPath = join(root, ".githooks", "commit-msg");
-        const existed = existsSync(hookPath);
-        writeFile(hookPath, hookTemplate(opts.prefix), 0o755);
-        const enabled = setHooksPath(root);
-        console.log(`✓ ${existed ? "Updated" : "Wrote"} commit-msg hook (.githooks/commit-msg).`);
-        if (enabled) {
+        backedUp = classifyGateFile(hookPath) === "modified" || backedUp;
+        for (const line of writeLayer(root, hookPath, hookTemplate(opts.prefix), 0o755)) {
+            console.log(line);
+        }
+        if (setHooksPath(root)) {
             console.log("  Enabled: git config core.hooksPath .githooks");
         }
         else {
@@ -194,9 +325,10 @@ export function installGate(opts) {
     }
     if (action) {
         const actionPath = join(root, ".github", "workflows", "check-commit-message.yml");
-        const existed = existsSync(actionPath);
-        writeFile(actionPath, actionTemplate(opts.prefix));
-        console.log(`✓ ${existed ? "Updated" : "Wrote"} GitHub Action (.github/workflows/check-commit-message.yml).`);
+        backedUp = classifyGateFile(actionPath) === "modified" || backedUp;
+        for (const line of writeLayer(root, actionPath, actionTemplate(opts.prefix))) {
+            console.log(line);
+        }
     }
     console.log("");
     console.log(`Gate is keyed to prefix "${opts.prefix}" — commits/PRs need ${opts.prefix}-NN or [no-issue].`);
@@ -206,5 +338,8 @@ export function installGate(opts) {
     if (hook) {
         console.log("The hook is local fast-feedback only: opt-in per clone (git won't auto-install it) and bypassable with --no-verify.");
     }
+    if (backedUp) {
+        console.log("\nA file you had customized was replaced by the standard one. Diff the .bak against it before committing, and re-apply anything you want to keep.");
+    }
     console.log("\nCommit the written files so the gate ships with the repo.");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retasc/cli",
-  "version": "1.36.0",
+  "version": "1.36.1",
   "description": "Retasc CLI — the issue tracker AI agents pull work from. Sign in with GitHub or Google, create projects, mint agent API keys, and wire your agent to the Retasc MCP server in one command.",
   "type": "module",
   "bin": {