yadflow 4.0.0-next.3 → 4.0.0

package/cli/lib.mjs

@@ -1,7 +1,7 @@
 // Shared helpers for the `yad` CLI. Node >=18 built-ins only — no dependencies.
-import { createHash } from 'node:crypto';
+import { createHash, randomBytes } from 'node:crypto';
 import { err } from './errors.mjs';
-import { MIRRORED_FILES, SCHEMA_VERSION, VERSION } from './manifest.mjs';
+import { MIRRORED_FILES, SCHEMA_VERSION, VERSION, mirrorDrift, preferring } from './manifest.mjs';
 import { spawnSync } from 'node:child_process';
 import * as readline from 'node:readline/promises';
 import { stdin as input, stdout as output } from 'node:process';
@@ -24,7 +24,19 @@ export const PKG_ROOT = fileURLToPath(new URL('../', import.meta.url));
 // holds the one object and nothing else — a progress line printed before the answer would otherwise
 // make the whole output unparseable. Each `warn` is also collected into `warnings`, as plain text.
 // A command never calls JSON.stringify toward stdout itself; a test greps for it.
-export const JSON_VERSION = 1;
+// Text read from a shared file (a repo name, a path) is shown in the terminal: every control character
+// (C0, DEL and C1 — U+0080–U+009F, which some terminals obey too) becomes a space, so a registry entry cannot move the cursor or recolour what follows.
+// So do the line and paragraph separators and the bidi controls, which can make a line read in another
+// order than it holds (E81 review 9).
+const INVISIBLE = new Set([0x2028, 0x2029, 0x200e, 0x200f, 0x202a, 0x202b, 0x202c, 0x202d, 0x202e, 0x2066, 0x2067, 0x2068, 0x2069, 0x061c]);
+export const forTerminal = (s) => [...String(s ?? '')].map((ch) => { const n = ch.charCodeAt(0); return n < 32 || (n >= 127 && n <= 159) || INVISIBLE.has(n) ? ' ' : ch; }).join('');
+
+// A registry name inside a command the person is invited to copy: as it is only when it is one plain
+// word that starts with a letter or digit (never an option like `--push`), else `<name>` — the shared
+// file could hold `api; curl …|sh` (E81 reviews 9–10; here since review 15, for doctor and people.mjs).
+export const asArg = (name) => (typeof name === 'string' && /^\w[\w.-]*$/.test(name) ? name : '<name>');
+
+export const JSON_VERSION = 2;
 export const ENVELOPE_KEYS = ['jsonVersion', 'version', 'command'];
 let jsonRun = null;
 export function beginJSON(command) { jsonRun = { command, emitted: false, warnings: [], failures: [] }; }
@@ -151,14 +163,39 @@ export async function askYesNo(question, def = true) {
 export const asset = (...p) => path.join(PKG_ROOT, ...p);
 export const exists = (p) => fs.existsSync(p);
 
+// Do two paths name the same existing file or folder? Used where one path comes from git and one from Node,
+// which can spell the same place differently: on Windows git answers with the long name while Node's temp
+// folder is often an 8.3 short name (`C:\Users\RUNNER~1\…`) that the JS realpath keeps; `.native` asks
+// Windows for the final name. Windows also compares without case, and a macOS `/var` is `/private/var`.
+// A path that does not exist is never the same as anything (E48).
+export function samePath(a, b, platform = process.platform) {
+  const real = (p) => { try { return fs.realpathSync.native(p); } catch { return null; } };
+  const ra = real(a);
+  const rb = real(b);
+  if (ra === null || rb === null) return false;
+  return platform === 'win32' ? ra.toLowerCase() === rb.toLowerCase() : ra === rb;
+}
+
 export function fileSha(p) {
   if (!fs.existsSync(p)) return null;
   return 'sha256:' + createHash('sha256').update(fs.readFileSync(p)).digest('hex');
 }
-// True when dest exists and its bytes match src exactly.
+// The sha of a file yad INSTALLS, read the way git would give it back: every CRLF counted as LF (E113).
+// On Windows git checks text out with CRLF (`core.autocrlf`, on by default there), so a teammate's clone
+// holds each shipped file with different bytes and the same content — and a byte compare would call every
+// one of them outdated, or edited, for ever. A file with no CR in it hashes exactly as `fileSha` does, so
+// every sha already recorded in `.sdlc/managed.json` still matches. Not for artifact hashes: those are
+// `fileSha`, and an approval is bound to them.
+export function contentSha(p) {
+  if (!fs.existsSync(p)) return null;
+  const bytes = fs.readFileSync(p);
+  const text = bytes.includes(13) ? Buffer.from(bytes.toString('latin1').replace(/\r\n/g, '\n'), 'latin1') : bytes;
+  return 'sha256:' + createHash('sha256').update(text).digest('hex');
+}
+// True when dest exists and its content matches src, line endings aside (see `contentSha`).
 export function sameContent(src, dest) {
-  const a = fileSha(src);
-  const b = fileSha(dest);
+  const a = contentSha(src);
+  const b = contentSha(dest);
   return a !== null && a === b;
 }
 
@@ -276,13 +313,28 @@ export function writeJSON(p, obj) {
   try {
     if (fs.readFileSync(p, 'utf8') === data) return;
   } catch { /* missing or unreadable — fall through and write it */ }
+  writeFileAtomic(p, data);
+}
+
+// Write `data` to `p` through a fresh temporary file and a rename: a crash leaves the old file or the new
+// one, never half of either, and a link standing at `p` is replaced rather than followed.
+export function writeFileAtomic(p, data) {
   fs.mkdirSync(path.dirname(p), { recursive: true });
-  const tmp = `${p}.${process.pid}.tmp`;
-  fs.writeFileSync(tmp, data);
+  // A name nobody can guess, created exclusively (`wx`): a Product can commit `repos.json.<pid>.tmp` as a
+  // link, and a plain write follows it — a dangling one too — putting this file's text wherever the link
+  // points (`~/.zshenv`; E81 review 17). `wx` refuses any entry already there, links included.
+  const tmp = `${p}.${process.pid}.${randomBytes(8).toString('hex')}.tmp`;
+  try { fs.writeFileSync(tmp, data, { flag: 'wx' }); }
+  catch (e) {
+    // A half-written file of our own (a full disk) is removed; an entry that was already there (EEXIST)
+    // is not ours to delete.
+    if (e.code !== 'EEXIST') { try { fs.rmSync(tmp, { force: true }); } catch { /* keep the write's own error */ } }
+    throw e;
+  }
   try {
     fs.renameSync(tmp, p);
   } catch (e) {
-    fs.rmSync(tmp, { force: true });
+    try { fs.rmSync(tmp, { force: true }); } catch { /* keep the rename's own error */ }
     throw e;
   }
 }
@@ -304,6 +356,18 @@ export function run(cmd, args = [], opts = {}) {
 }
 export const has = (cmd) => run(process.platform === 'win32' ? 'where' : 'which', [cmd]).ok;
 
+// An npm launcher (`npm`, `npx`) is a `.cmd` file on Windows, which Node will not start without a shell
+// (since 18.20.2) — a plain spawn fails with EINVAL there. So on Windows it runs through one, each word in
+// double quotes (a Windows path cannot hold a `"`); everywhere else it is spawned directly (E113).
+export function launcherInvocation(cmd, args, platform = process.platform) {
+  if (platform !== 'win32') return { cmd, args, shell: false };
+  return { cmd: [cmd, ...args].map((a) => `"${String(a).replace(/"/g, '')}"`).join(' '), args: [], shell: true };
+}
+export function runLauncher(cmd, args = [], opts = {}) {
+  const inv = launcherInvocation(cmd, args);
+  return run(inv.cmd, inv.args, { ...opts, ...(inv.shell ? { shell: true } : {}) });
+}
+
 // Push HEAD to origin/<target>, rebasing onto it and retrying on rejection — both the Shape gate
 // sync and the Build checkpoint push append-only ledgers to the default branch, so a concurrent
 // push is a normal race, not an error. Returns { ok } after up to `attempts` tries; logs each retry.
@@ -320,26 +384,23 @@ export function pushWithRebase(cwd, target, { attempts = 3 } = {}) {
   return { ok: false };
 }
 
-// ---- the product config, which lives under two names for one major -----------------------------
+// ---- the product config, which lives under two names until v5 ----------------------------------
 //
-// Read through `productConfigPath` (manifest.mjs), which every reader in cli/ now does. Write
-// through here: BOTH names, every time.
+// Read through `productConfigPath` (manifest.mjs), which every reader in cli/ does. Write through
+// here: BOTH names, every time.
 //
-// The duplicate is not sloppiness. `templates/checks/ledger-guard.sh` sits committed inside the
-// user's own repository and opens `.sdlc/hub.json` by that literal path; it is refreshed by
-// `yad update`, which is a separate act from `yad migrate`. So a migrated-but-not-updated project is
-// a real state, and if only the new name existed its guard would find nothing, read no platform,
-// call the ledger local, and stop rejecting human commits to it. An upgrade that silently disarms a
-// safety gate is worse than a duplicated file.
+// The duplicate is not sloppiness. The check gates sit committed inside the user's own repository,
+// and the ones installed before E122 open `.sdlc/hub.json` by that literal path; they are refreshed by
+// `yad update`, which is a separate act from `yad migrate`. So a project whose gates are older than
+// its CLI is a real state, and if only the new name existed its `ledger-guard` would find nothing,
+// read no platform, call the ledger local, and stop rejecting human commits to it. An upgrade that
+// silently disarms a safety gate is worse than a duplicated file. v5 deletes the old name.
 //
-// Order matters, and it follows which file is AUTHORITATIVE — the old name, this major
-// (`productConfigPath`, cli/manifest.mjs). The new name is written first, so if the second write
-// fails the readers are all still on the untouched old copy: nothing has half-changed underneath
-// them. Writing the authoritative file first would leave every reader on new settings while the
-// mirror still says something else, which is the harder failure to notice.
+// Order: the old name first, then the new one, which readers use (`preferring`, cli/manifest.mjs).
+// If the second write fails, the pair disagrees and every command refuses until `yad migrate`
+// settles it (`mirrorDrift`) — loud, never a silent half-change. The authoritative copy is the one
+// left untouched in that case, so the refusal shows the settings every reader was already using.
 //
-// `yad doctor` reports the two copies disagreeing either way, so a half-written pair is visible
-// rather than silent.
 // Write a file that lives under two names. Returns the paths it actually wrote — empty when there
 // was nothing to do.
 //
@@ -352,19 +413,20 @@ export function pushWithRebase(cwd, target, { attempts = 3 } = {}) {
 // readable; only a genuine change writes, and then it writes both.
 export function writeMirrored(canonicalPath, legacyPath, obj) {
   // Compare against the AUTHORITATIVE copy — the same one readers use (`preferring`,
-  // cli/manifest.mjs), which is the legacy name while it exists. Comparing against the other file
+  // cli/manifest.mjs), which is the new name whenever it exists. Comparing against the other file
   // would let the two rules disagree about whether anything changed.
-  const readable = fs.existsSync(legacyPath) ? legacyPath : canonicalPath;
+  const readable = preferring(canonicalPath, legacyPath);
   const next = `${JSON.stringify(writeShape(canonicalPath, obj), null, 2)}\n`;
   // "Unchanged" means BOTH names are already right. A half-made pair — one side missing — is work
   // to do even when the readable copy matches, or the pair can never be repaired: the comparison
   // says nothing changed, nothing is written, and `yad doctor` reports the missing file for ever.
+  // A drifted pair fails the same test (the other copy is not `next`), so a write repairs it too.
   const bothPresent = fs.existsSync(canonicalPath) && fs.existsSync(legacyPath);
   try {
-    if (bothPresent && fs.readFileSync(readable, 'utf8') === next) return [];
+    if (bothPresent && fs.readFileSync(readable, 'utf8') === next && !mirrorDrift(canonicalPath, legacyPath)) return [];
   } catch { /* unreadable — treat as a first write and fall through */ }
-  writeJSON(canonicalPath, obj);
   writeJSON(legacyPath, obj);
+  writeJSON(canonicalPath, obj);
   return [canonicalPath, legacyPath];
 }