@timekast/factory 1.25.0 → 1.26.0

package/dist/commands/add.js

@@ -94,6 +94,8 @@ export async function runAdd(flags = { core: false, full: false }) {
             // `add` is interactive: keep the legacy confirm prompt. Only the GUI/headless
             // caller passes `--yes` (via `update` directly), never this redirect.
             yes: false,
+            // The legacy `add` redirect never requests the GUI signal — only `update --launcher` does.
+            launcher: false,
         });
         return;
     }

package/dist/commands/update.js

@@ -67,6 +67,7 @@ export function parseUpdateFlags(argv) {
         beta: argv.includes('--beta'),
         stable: argv.includes('--stable'),
         yes: argv.includes('--yes') || argv.includes('-y'),
+        launcher: argv.includes('--launcher'),
     };
 }
 /** Default acquire: download the sticky-profile tarball, stage + validate it. */
@@ -566,7 +567,17 @@ function syncDerivedPrettierignore(rootDir, stagedDir) {
 const KIT_TESTS_DIR = 'scripts/tools/__tests__/';
 /** Exit code of `--dry-run` when the preview found conflicts (0 = none). Lets a
  * non-interactive caller (the GUI) branch on the result instead of clobbering. */
-const DRY_RUN_CONFLICTS_EXIT = 2;
+/**
+ * 🔴 FROZEN WIRE FORMAT — the same class of contract as the retrofit signal marker
+ * (ADR-004 §1/§4), and for the same reason. `update --dry-run` reports "the preview found
+ * conflicts" with this code, and the GUI launcher reads it to decide whether it may chain the
+ * real apply. Its twin is calqued BY VALUE in `desktop/renderer/panels/update-project.tsx`
+ * (`DRY_RUN_CONFLICTS_EXIT`) — two npm packages with no dependency edge, so no compiler will
+ * ever catch a drift. Changing this number silently kills the launcher's clobber guard, which
+ * is exactly the failure that shipped once already (see `cli/src/lib/exit-code.ts`).
+ * Exported so the golden pin in the test suite can assert it.
+ */
+export const DRY_RUN_CONFLICTS_EXIT = 2;
 /**
  * `--dry-run`: preview the plan (buckets + the explicit conflict list) and apply
  * NOTHING. Prints the conflicting paths so a human or agent sees exactly what
@@ -859,7 +870,7 @@ export async function runUpdate(flags, deps = {}) {
         // `oldLock.version` is the version BEFORE this update, which is what separates the guides
         // that just arrived from the ones that were already sitting there. A legacy repo carries
         // `0.0.0`, so every guide reads as new — correct: it has seen none of them.
-        printRetrofitReminder({ rootDir, fromVersion: oldLock.version });
+        printRetrofitReminder({ rootDir, fromVersion: oldLock.version, guiSignal: flags.launcher });
         // End-pointer to the next step (PVSKILL-002). Reached only after a clean apply;
         // `--verify`/`--resume` short-circuit above (verify NEVER prints), an error path
         // throws earlier, and headless `--yes` is suppressed (CI noise).

package/dist/index.js

@@ -10,6 +10,7 @@ import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { CLIError } from './lib/cli-error.js';
+import { resolveSuccessExitCode } from './lib/exit-code.js';
 import { parseAddFlags, runAdd } from './commands/add.js';
 import { parseBacklogPushFlags, parseBacklogSyncFlags, runBacklogPush, runBacklogSync, } from './commands/backlog.js';
 import { parseEnvPushFlags, parseEnvWizardFlags, runEnvPush, runEnvWizardApply, runEnvWizardGenVapid, runEnvWizardPlan, runEnvWizardReview, } from './commands/env.js';
@@ -328,7 +329,11 @@ async function main(argv) {
     }
 }
 main(process.argv.slice(2)).then(() => {
-    process.exit(0);
+    // NOT a bare `process.exit(0)`. An explicit argument overrides `process.exitCode`, so
+    // hardcoding 0 threw away the outcome code of any command that succeeded but had
+    // something to report — `update --dry-run`'s "there are conflicts" (exit 2) among them,
+    // which left the launcher's clobber guard dead. See `resolveSuccessExitCode`.
+    process.exit(resolveSuccessExitCode(process.exitCode));
 }, (error) => {
     if (error instanceof CLIError) {
         // An empty message is intentional (the command already rendered its own

package/dist/lib/constants.js

@@ -214,6 +214,44 @@ export const GENERATE_REFERENCE_GATE_FILE = 'scripts/tools/generate-schema.ts';
  * FILE-GATED on the launcher, like `GENERATOR_SCRIPTS`: a `core`/non-Next derivative has no
  * `dev.mjs` and never receives an alias for a dev server it does not run.
  */
+/**
+ * `verify` — la compuerta de calidad, movida de una cadena de shell a un script del cerebro.
+ *
+ * WHY THE CLI OWNS IT. Mismo razonamiento que `dev:next` justo abajo, y por la misma causa:
+ * el valor vive en `package.json`, que nace congelado en el derivado y no viaja en el set
+ * trackeado, así que `factory update` no lo alcanza por sí solo. La diferencia es QUÉ se gana
+ * al alcanzarlo. Aquí el valor nuevo no es otro parámetro: es un PUNTERO a un archivo que sí
+ * viaja (`scripts/**`). Sanar esta clave una vez es lo que vuelve viva a la compuerta — de ahí
+ * en adelante el Factory la mejora editando el script, y la flota lo recibe en el update
+ * siguiente sin que nadie abra su repo. Es la única entrada de este registro cuyo objetivo es
+ * dejar de necesitar entradas en este registro.
+ *
+ * FILE-GATED sobre el script mismo: `applyPlan` escribe `scripts/**` ANTES de que corra el
+ * mantenimiento del `package.json`, así que en la misma pasada el archivo ya está en disco
+ * cuando se evalúa el gate. Un derivado `core` que no reciba el archivo nunca recibe un alias
+ * apuntando a un script que no tiene.
+ */
+export const VERIFY_SCRIPT_NAME = 'verify';
+export const VERIFY_SCRIPT_FILE = 'scripts/tools/verify.mjs';
+export const VERIFY_SCRIPT_CMD = `node ${VERIFY_SCRIPT_FILE}`;
+/**
+ * La cadena de shell que el kit shippeó antes del script. Listada como COMANDO COMPLETO —
+ * igual que los heaps de `dev:next`— para que el sanado sea exact-match: un derivado que le
+ * agregó un paso propio (`&& pnpm format:check`, un `test:e2e`) tiene un valor que el kit
+ * nunca shippeó, y se queda EXACTAMENTE como está. Esa es la mitad importante del contrato:
+ * la compuerta se moderniza sola donde nadie la tocó, y no pisa a quien la hizo suya.
+ */
+/**
+ * `verify:quick` — el bucle de trabajo, NO la compuerta.
+ *
+ * Comparte archivo y gate con `verify` (mismo script, distinto flag), así que un derivado que
+ * recibe uno recibe el otro. No tiene entrada en `OBSOLETE_SCRIPT_CMDS` y no la va a tener: es
+ * un alias que el kit nunca shippeó antes, así que no hay valor viejo que sanar — solo
+ * insert-if-missing. Si un equipo ya tenía un `verify:quick` propio, ese gana y se queda.
+ */
+export const VERIFY_QUICK_SCRIPT_NAME = 'verify:quick';
+export const VERIFY_QUICK_SCRIPT_CMD = `node ${VERIFY_SCRIPT_FILE} --quick`;
+export const VERIFY_OBSOLETE_CMDS = ['pnpm lint && pnpm typecheck && pnpm test'];
 export const DEV_NEXT_SCRIPT_NAME = 'dev:next';
 export const DEV_NEXT_GATE_FILE = 'scripts/tools/dev.mjs';
 export const DEV_NEXT_HEAP_MB = 4096;
@@ -269,6 +307,7 @@ export const OBSOLETE_SCRIPT_CMDS = {
     // Every heap ceiling the kit shipped for the dev server before the current one. Listed as
     // whole COMMANDS (not just the number) so healing stays exact-match: a derivative that
     // appended a flag of its own, or picked a ceiling the kit never shipped, is left alone.
+    [VERIFY_SCRIPT_NAME]: VERIFY_OBSOLETE_CMDS,
     [DEV_NEXT_SCRIPT_NAME]: DEV_NEXT_OBSOLETE_HEAPS_MB.map((mb) => `NODE_OPTIONS='--max-old-space-size=${mb}' next dev --turbopack`),
 };
 /**

package/dist/lib/exit-code.js

@@ -0,0 +1,31 @@
+/**
+ * How the CLI turns a resolved `main()` into a process exit code.
+ *
+ * 🔴 The bug this exists to fix, stated plainly: `main(...).then(() => process.exit(0))`
+ * passes an EXPLICIT code, and an explicit argument to `process.exit` overrides whatever a
+ * command assigned to `process.exitCode`. So a command that finished its work successfully
+ * but wanted to report a non-zero *outcome* had its signal silently dropped.
+ *
+ * That is not hypothetical. `update --dry-run` sets `process.exitCode = 2` when it finds
+ * conflicts, and the GUI launcher chains the real apply (`--theirs-all --yes`) only when the
+ * preview exited 0 — its comment says "never clobber local edits with `--theirs-all` behind
+ * the dev's back". With the 2 discarded, that guard was dead: the launcher read 0 on every
+ * preview and applied unconditionally, overwriting local edits to tracked kit files.
+ *
+ * Note the distinction this function keeps: a **thrown** `CLIError` is a failure and still
+ * exits with its own code (that path never went through here). `process.exitCode` is for a
+ * command that succeeded and is reporting a RESULT — the dry-run's "there are conflicts" —
+ * which is exactly the case that was being swallowed.
+ */
+export function resolveSuccessExitCode(pending) {
+    // Node types `process.exitCode` as `number | string | null | undefined` — `null` included,
+    // which is why this takes the whole union instead of narrowing at the call site. A string is
+    // only reachable if something assigned one; coerce rather than forward it, because
+    // `process.exit('2')` is not the same call as `process.exit(2)`.
+    if (typeof pending === 'number' && Number.isInteger(pending))
+        return pending;
+    if (typeof pending === 'string' && /^\d+$/.test(pending))
+        return Number(pending);
+    // Unset (the overwhelmingly common case) or unusable ⇒ success.
+    return 0;
+}

package/dist/lib/package-json.js

@@ -8,7 +8,7 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { CLIError } from './cli-error.js';
-import { DEV_NEXT_GATE_FILE, DEV_NEXT_SCRIPT_CMD, DEV_NEXT_SCRIPT_NAME, FACTORY_SCRIPTS, GENERATE_REFERENCE_CMD, GENERATE_REFERENCE_GATE_FILE, GENERATE_REFERENCE_NAME, GENERATOR_SCRIPTS, INVITE_ADMIN_SCRIPT_CMD, INVITE_ADMIN_SCRIPT_FILE, INVITE_ADMIN_SCRIPT_NAME, OBSOLETE_SCRIPT_CMDS, PORTS_E2E_COMMENT, PORTS_E2E_COMMENT_KEY, PORTS_E2E_KEY, PORTS_KEY, PREFLIGHT_SCRIPT_CMD, PREFLIGHT_SCRIPT_FILE, PREFLIGHT_SCRIPT_NAME, PROFILES, RETIRED_SCRIPT_CMDS, SHIPPED_E2E_PORT, UPDATE_SCRIPT_NAME, } from './constants.js';
+import { DEV_NEXT_GATE_FILE, DEV_NEXT_SCRIPT_CMD, DEV_NEXT_SCRIPT_NAME, FACTORY_SCRIPTS, GENERATE_REFERENCE_CMD, GENERATE_REFERENCE_GATE_FILE, GENERATE_REFERENCE_NAME, GENERATOR_SCRIPTS, INVITE_ADMIN_SCRIPT_CMD, INVITE_ADMIN_SCRIPT_FILE, INVITE_ADMIN_SCRIPT_NAME, OBSOLETE_SCRIPT_CMDS, VERIFY_QUICK_SCRIPT_CMD, VERIFY_QUICK_SCRIPT_NAME, VERIFY_SCRIPT_CMD, VERIFY_SCRIPT_FILE, VERIFY_SCRIPT_NAME, PORTS_E2E_COMMENT, PORTS_E2E_COMMENT_KEY, PORTS_E2E_KEY, PORTS_KEY, PREFLIGHT_SCRIPT_CMD, PREFLIGHT_SCRIPT_FILE, PREFLIGHT_SCRIPT_NAME, PROFILES, RETIRED_SCRIPT_CMDS, SHIPPED_E2E_PORT, UPDATE_SCRIPT_NAME, } from './constants.js';
 /**
  * Auto-detect the profile to install into an existing repo from its
  * `package.json`: a `factoryVersion` field means the repo was born from the
@@ -146,6 +146,10 @@ export function kitLocalScripts(rootDir) {
     }
     if (has(GENERATE_REFERENCE_GATE_FILE))
         scripts[GENERATE_REFERENCE_NAME] = GENERATE_REFERENCE_CMD;
+    if (has(VERIFY_SCRIPT_FILE))
+        scripts[VERIFY_SCRIPT_NAME] = VERIFY_SCRIPT_CMD;
+    if (has(VERIFY_SCRIPT_FILE))
+        scripts[VERIFY_QUICK_SCRIPT_NAME] = VERIFY_QUICK_SCRIPT_CMD;
     if (has(DEV_NEXT_GATE_FILE))
         scripts[DEV_NEXT_SCRIPT_NAME] = DEV_NEXT_SCRIPT_CMD;
     return scripts;

package/dist/lib/retrofit-reminder.js

@@ -216,13 +216,56 @@ export function renderRetrofitReminder(entries, fromVersion = null) {
     lines.push(`  No todas te aplican: cada una abre diciendo a quién le toca. En ${RETROFITS_DIR}/`, '  Si trabajas con un agente, pídele que las lea y te diga cuáles te aplican.', rule, '');
     return lines.join('\n');
 }
+/**
+ * 🔴 FROZEN WIRE FORMAT — see ADR-004 §1/§4. Once a launcher is installed on someone else's
+ * machine, renaming this marker leaves it mute forever, silently: it does not error, it just
+ * stops seeing the signal. Never rename it; the pin in the test suite is what makes that
+ * mistake loud instead of silent. Adding NEW fields to the payload is fine (ADR-004 §3) —
+ * this is about the marker string itself and the shape it prefixes.
+ */
+export const RETROFIT_SIGNAL_MARKER = '::timekast:retrofit-signal::';
+/**
+ * Render the machine-readable signal line, or `null` under the same gate as the banner
+ * (`renderRetrofitReminder` — no guides shipped, nothing to signal either).
+ *
+ * Reuses `splitByArrival` rather than recomputing the arrival cut — that logic already lives
+ * there and this must never drift from what the banner counts.
+ *
+ * 🔴 One line, no pretty-printing: `JSON.stringify` with no `indent` arg. The consumer detects
+ * this by line PREFIX (ADR-004 §1); a payload that spans multiple lines breaks that detection.
+ */
+export function renderRetrofitSignal(entries, fromVersion = null) {
+    if (renderRetrofitReminder(entries, fromVersion) === null)
+        return null;
+    const { arrived, carried } = splitByArrival(entries, fromVersion);
+    const payload = {
+        dir: RETROFITS_DIR,
+        arrived: arrived.length,
+        carried: carried.length,
+    };
+    return `${RETROFIT_SIGNAL_MARKER}${JSON.stringify(payload)}`;
+}
 /**
  * Print the reminder. Called on EVERY applied update — see the module header for why this one
  * has no headless guard and no outcome condition.
+ *
+ * 🔴 With `guiSignal: true`, the signal line is written FIRST, the banner second — not the
+ * other way around. `cli/src/index.ts` calls `process.exit(0)` right after `main` resolves, and
+ * writes to a pipe are async on Windows, where `process.exit` can truncate the tail. Under
+ * `--yes` the signal would otherwise be the LAST line written; writing it first leaves the
+ * banner (cosmetic text) as the one at risk of truncation instead of the machine-readable line.
  */
 export function printRetrofitReminder(opts) {
     const log = opts.log ?? ((m) => console.log(m));
-    const rendered = renderRetrofitReminder(listRetrofits(opts.rootDir, opts), opts.fromVersion ?? null);
-    if (rendered)
-        log(rendered);
+    const entries = listRetrofits(opts.rootDir, opts);
+    const fromVersion = opts.fromVersion ?? null;
+    const rendered = renderRetrofitReminder(entries, fromVersion);
+    if (!rendered)
+        return;
+    if (opts.guiSignal) {
+        const signal = renderRetrofitSignal(entries, fromVersion);
+        if (signal)
+            log(signal);
+    }
+    log(rendered);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timekast/factory",
-  "version": "1.25.0",
+  "version": "1.26.0",
   "description": "Public, thin CLI to bootstrap and maintain TimeKast Factory derived projects.",
   "type": "module",
   "license": "UNLICENSED",