@timekast/factory 1.28.0 → 2.0.0

package/dist/commands/backlog.js

@@ -9,8 +9,10 @@
  * parser/mapping (`backlog-parse.ts` / `backlog-mapping.ts`) — this file only
  * orchestrates; it re-implements neither the HTTP nor the field mapping.
  *
- * READ-ONLY BY DEFAULT: with no `BACKLOG_API_KEY` / `BACKLOG_PROJECT_ID` in
- * `.env.local`, it prints a note and exits 0 — the push NEVER blocks `/backlog`.
+ * READ-ONLY BY DEFAULT: with no `BACKLOG_API_KEY` / `BACKLOG_PROJECT_ID` — read from the
+ * `local` environment of the repo's vault when `.timekast/provision.json` carries a `vault`
+ * block, else from `.env.local` (VAULT-006) — it prints a note with the real cause and exits 0:
+ * the push NEVER blocks `/backlog`.
  *
  * IDEMPOTENCY (smoke Hallazgo 3): a re-POST of an existing client-supplied `id`
  * returns `500` on the live API, NOT the documented `409` — so a status code is an
@@ -195,7 +197,7 @@ async function loadSyncState(apiKey, projectId, api, existing, items) {
  * abort the run — §4).
  */
 export async function runBacklogPush(flags, rootDir = process.cwd(), deps = {}) {
-    const creds = (deps.credentials ?? ((dir) => resolveBacklogCredentials(dir)))(rootDir);
+    const creds = await (deps.credentials ?? ((dir) => resolveBacklogCredentials(dir, deps.credentialDeps)))(rootDir);
     if (creds.status === 'not-configured') {
         console.log(`ℹ️  Push al backlog central omitido: ${creds.reason}`);
         console.log('   (read-only por defecto — el push nunca bloquea `/backlog`.)');
@@ -666,22 +668,35 @@ async function runWithDeadline(ms, work, deadlineSleep) {
 }
 /**
  * Orchestrate `factory backlog sync`. Read-only degradation: no credentials → note +
- * return (exit 0 — the sync NEVER blocks the workflow). The point sync (unless
- * `--heal-only`) + the self-healing heartbeat both run under a single 5s deadline;
- * on timeout the command cuts clean and the caller continues (fire-and-forget, §4).
+ * return (exit 0 — the sync NEVER blocks the workflow). The credential resolution —
+ * which in a repo with a vault is a network read (VAULT-006) —, the point sync (unless
+ * `--heal-only`) and the self-healing heartbeat ALL run under a single 5s deadline: a
+ * slow vault cannot stretch the heartbeat. A cut before the credentials resolve is a
+ * `not-configured` note; a cut after is the usual clean cut. Either way the caller
+ * continues (fire-and-forget, §4).
  */
 export async function runBacklogSync(flags, rootDir = process.cwd(), deps = {}) {
-    const creds = (deps.credentials ?? ((dir) => resolveBacklogCredentials(dir)))(rootDir);
-    if (creds.status === 'not-configured') {
-        console.log(`ℹ️  Sync al backlog central omitido: ${creds.reason}`);
-        console.log('   (fire-and-forget — el sync nunca bloquea el workflow.)');
-        return;
-    }
-    const { apiKey, projectId } = creds;
+    const resolveCredentials = deps.credentials ?? ((dir) => resolveBacklogCredentials(dir, deps.credentialDeps));
     const api = deps.api ?? {};
-    const collected = (deps.collect ?? collectBacklog)(rootDir);
+    let creds;
+    let collectFailure;
+    let cut = false;
     let heal = { repaired: 0, failed: 0, skippedNoUuid: 0 };
     const work = async () => {
+        const resolved = await resolveCredentials(rootDir);
+        creds = resolved;
+        // Resolved after the deadline already fired: the run was reported as cut — do nothing more.
+        if (cut || resolved.status === 'not-configured')
+            return;
+        const { apiKey, projectId } = resolved;
+        let collected;
+        try {
+            collected = (deps.collect ?? collectBacklog)(rootDir);
+        }
+        catch (error) {
+            collectFailure = { error };
+            return;
+        }
         if (!flags.healOnly) {
             await runPointSync(flags, collected, apiKey, projectId, api);
         }
@@ -689,7 +704,29 @@ export async function runBacklogSync(flags, rootDir = process.cwd(), deps = {})
     };
     const completed = await runWithDeadline(SYNC_TIMEOUT_MS, work, deps.deadlineSleep);
     if (!completed) {
-        console.warn(`⚠ Sync al backlog central cortado a los ${SYNC_TIMEOUT_MS / 1000}s — el workflow continúa sin esperar.`);
+        cut = true;
+        if (creds === undefined) {
+            console.log(`ℹ️  Sync al backlog central omitido: la lectura de credenciales no terminó en ` +
+                `${SYNC_TIMEOUT_MS / 1000}s (la bóveda de secretos no respondió a tiempo).`);
+            console.log('   (fire-and-forget — el sync nunca bloquea el workflow.)');
+            return;
+        }
+        if (creds.status === 'configured') {
+            console.warn(`⚠ Sync al backlog central cortado a los ${SYNC_TIMEOUT_MS / 1000}s — el workflow continúa sin esperar.`);
+            return;
+        }
+        // Resolved to `not-configured` right at the deadline: narrate its real reason below.
+    }
+    if (collectFailure)
+        throw collectFailure.error;
+    // `completed` with no credentials only happens if the resolver seam rejected: fail closed.
+    const resolved = creds ?? {
+        status: 'not-configured',
+        reason: 'no pude resolver las credenciales del backlog central.',
+    };
+    if (resolved.status === 'not-configured') {
+        console.log(`ℹ️  Sync al backlog central omitido: ${resolved.reason}`);
+        console.log('   (fire-and-forget — el sync nunca bloquea el workflow.)');
         return;
     }
     if (heal.repaired || heal.failed) {

package/dist/commands/doctor.js

@@ -13,9 +13,21 @@
  *     post-bootstrap, and that the patch channel for `src/` is EPIC 2 (agentic
  *     update, not yet available).
  *   - MISSING INITIAL MIGRATION: a derivative that ships a Drizzle schema and no
- *     generated `.sql`, so its `vercel-build` (`pnpm build && pnpm db:migrate`)
- *     has nothing to apply and its first deploy never creates the tables.
+ *     generated `.sql`, so the migration step of its deploy — `vercel-build`
+ *     (`pnpm build && pnpm db:migrate`) on Vercel, the pre-deploy (`pnpm db:migrate`)
+ *     on Railway — has nothing to apply and its first deploy never creates the tables.
  *     INFORMATIONAL — see below.
+ *   - STALE RAIL FILE: a `~/.claude/.env` left on the machine from the file-based
+ *     rail. The rail is read from the vault now (`fx-secrets-vault §3`), so that file
+ *     is a dead copy of tokens nobody rotates: doctor names its absolute path and asks
+ *     to delete it. It only checks EXISTENCE (`lstat`, no symlink follow) — it never
+ *     opens, reads or deletes the file.
+ *   - VAULT MODE (ADOPT-004): `bóveda` · `declinado` · `sin decidir` · `no aplica`, read from
+ *     `.timekast/provision.json` (local, synchronous — part of `computeDoctor`). Only `sin decidir`
+ *     suggests `factory vault adopt`: a declined repo is never asked again, `core` never. In
+ *     `bóveda`, `runDoctor` adds the vault ↔ Vercel DRIFT by display hash as a SEPARATE, bounded
+ *     and degradable step (`computeVaultDrift`): without a session or network it is "no
+ *     verificable" with the cause — the offline part of the report never waits on it otherwise.
  *
  * No lockfile (pre-CLI repo) → delegate to the "run factory:update" advice, exit
  * 0, never abort (same pattern as `status` / the §8 edge case).
@@ -27,18 +39,27 @@
  * turn a notice into a blocked command through the back door. If it ever has to
  * live there, it goes as `warn` (`LauncherCheckStatus`), which never trips the exit.
  */
-import { existsSync, readFileSync, statSync } from 'node:fs';
+import { existsSync, lstatSync, readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
 import path from 'node:path';
 import { CLIError } from '../lib/cli-error.js';
+import { KIT_RULE_PATH_RE, RULES_DIR, bareImportPaths, resolveImportFrom, } from '../lib/claude-md.js';
 import { collectClaudePaths } from '../lib/claude-paths.js';
 import { CLAUDE_MD_FILE } from '../lib/constants.js';
 import { MIGRATIONS_DIR, SCHEMA_DIR, needsInitialMigration, readMigrationFacts, } from '../lib/initial-migration.js';
 import { hasLockfile, normalizeThenHash, readLockfile } from '../lib/lockfile.js';
-import { runLauncherPreflight, } from '../lib/preflight.js';
+import { LAUNCHER_RAIL_TIMEOUT_MS, runLauncherPreflight, } from '../lib/preflight.js';
+import { readNeonRevokePending } from '../lib/provision-state.js';
+import { createRailResolver } from '../lib/rail.js';
 import { detectRepo } from '../lib/repo-detection.js';
+import { readVaultMode, renderRepoVault, repoVaultReportFor, } from '../lib/vault-adopt.js';
 import { BETA_BANNER } from './status.js';
-/** Matches a flat always-on rule file shipped by the kit (`.claude/rules/<name>.md`). */
-const RULE_PATH_RE = /^\.claude\/rules\/[^/]+\.md$/;
+/**
+ * Matches a flat always-on rule file shipped by the kit (`.claude/rules/<name>.md`).
+ * Imported from the retrofit module so ONE definition governs both the check here and
+ * the A/B/C classification `update` runs over the same set.
+ */
+const RULE_PATH_RE = KIT_RULE_PATH_RE;
 /**
  * Matches ONLY the reserved on-demand rules heading (`Rules (on-demand reference)`
  * and close variants), not any heading that merely contains "on-demand" (e.g.
@@ -66,10 +87,67 @@ export const A1_WARNING = 'Aviso de seguridad (A1): el boilerplate `src/` y sus
  */
 export const MISSING_INITIAL_MIGRATION_NOTICE = `⚠ Falta la migración inicial: hay schema en \`${SCHEMA_DIR}/\` y ningún \`.sql\` en ` +
     `\`${MIGRATIONS_DIR}/\`.\n` +
-    '  El deploy corre `pnpm build && pnpm db:migrate`, así que el primer deploy no crearía ' +
+    '  Cada deploy migra (en Vercel, `vercel-build` corre `pnpm build && pnpm db:migrate`; en ' +
+    'Railway, el pre-deploy corre `pnpm db:migrate`), así que el primer deploy no crearía ' +
     'ninguna tabla. Genera la migración con `pnpm db:generate` y commitéala antes del próximo ' +
     'deploy.\n' +
     '  (Aviso informativo: `factory doctor` no bloquea — sale con éxito de todos modos.)';
+/**
+ * Where the retired file-based rail lived, relative to the home directory. Only its
+ * EXISTENCE is ever checked (see {@link findStaleRailFile}).
+ */
+export const STALE_RAIL_FILE_REL = path.join('.claude', '.env');
+/**
+ * The notice for a rail file left on the machine. Names the ABSOLUTE path and reads
+ * unambiguously as "delete it, it is no longer used" — and says doctor did not touch it.
+ * Exported for the tests.
+ */
+export function staleRailFileNotice(absPath) {
+    return (`⚠ Archivo del rail que ya no se usa: ${absPath}\n` +
+        '  El rail ahora se lee de la bóveda con tu sesión (`infisical login`), no de ese archivo. ' +
+        'Lo que tenga es una copia de tokens que ya nadie rota: bórralo.\n' +
+        '  (`factory doctor` no lo abrió, no lo leyó ni lo borró.)');
+}
+/**
+ * The absolute path of a stale `~/.claude/.env`, or `null` when there is none.
+ * `lstat` so a symlink is reported as itself (never followed) and a directory counts
+ * too; nothing is opened or read. Any stat failure → `null` (nothing to report).
+ */
+export function findStaleRailFile(homeDir) {
+    const abs = path.join(homeDir, STALE_RAIL_FILE_REL);
+    try {
+        lstatSync(abs);
+        return abs;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The line `doctor` prints while replaced Neon keys are still alive, waiting for the delivery
+ * proof: how many, and which run settles them. `null` when there are none.
+ */
+export function neonRevokePendingNotice(count) {
+    if (count <= 0)
+        return null;
+    return (`⚠ ${count === 1 ? '1 key de Neon anterior sigue viva' : `${count} keys de Neon anteriores siguen vivas`} ` +
+        'por revocar (bloque `vault` de `.timekast/provision.json`): esperan a que el sync ' +
+        '`develop:/ci → secrets de GitHub Actions` confirme que entregó la nueva. Las revoca la siguiente ' +
+        'corrida de `factory provision` con bóveda (p. ej. `--resume`).');
+}
+/** The count of {@link DoctorResult.neonRevokePending} — never throws (the mode reports errors). */
+function countNeonRevokePending(rootDir) {
+    try {
+        return readNeonRevokePending(rootDir)?.keyIds.length ?? 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/** The repo root `doctor` diagnoses: the root of the repo cwd is in, not cwd itself. */
+function doctorRoot(rootDir) {
+    return rootDir ?? detectRepo(process.cwd()).repoRoot ?? process.cwd();
+}
 /** Parse `doctor`'s argv slice into flags. Unknown flags are ignored. */
 export function parseDoctorFlags(argv) {
     return {
@@ -111,18 +189,49 @@ function onDemandSectionText(claudeMd) {
     }
     return out.join('\n');
 }
+/**
+ * True when a path a CLAUDE.md imports is an INDEX of rules worth following: it must
+ * live under `.claude/rules/` and still be there after normalization (a `..` segment
+ * that climbs out of the dir is refused — nothing outside the rules tree is read).
+ */
+function isRulesIndexCandidate(rel) {
+    if (!rel.startsWith(`${RULES_DIR}/`) || !rel.endsWith('.md'))
+        return false;
+    return path.posix.normalize(rel).startsWith(`${RULES_DIR}/`);
+}
 /**
  * Collect the rule paths a CLAUDE.md actually `@import`s — a line whose trimmed
- * text is `@<path>` (the real import directive). A prose mention or a fenced
- * code block ("no agregues `@.claude/rules/SK.md`") is NOT a bare directive line,
- * so it does not count as imported.
+ * text is `@<path>` (the real import directive). A prose mention is NOT a bare
+ * directive line, and neither is a line inside a fenced code block: the shared
+ * reader (`bareImportPaths`) tracks fence state, so a doc that SHOWS the directive
+ * in a ``` sample is never read as performing it.
+ *
+ * 🔴 Follows an INDEX **one hop**. The kit's CLAUDE.md now imports a single
+ * `@.claude/rules/INDEX.md` that fans out to the six always-on rules; reading only
+ * the top-level file would report all six as "not imported" on every healthy repo.
+ * So when an imported path lives under `.claude/rules/` AND exists on disk (the kit's
+ * INDEX, or any index the dev wrote), its own `@<path>` lines count as imported too.
+ *
+ * The nested paths are resolved RELATIVE TO THE FILE THAT CONTAINS THEM (the Claude
+ * Code rule for memory imports) and normalized back to repo-relative — that is why
+ * `INDEX.md` lists `@CORE.md`, not `@.claude/rules/CORE.md`.
+ *
+ * One hop only: no recursion, so there is no cycle to guard and no depth to bound. An
+ * INDEX that is referenced but NOT on disk (the `core` profile, which ships no INDEX)
+ * is simply not followed — never an error, never a crash.
  */
-function importedRulePaths(claudeMd) {
-    const paths = new Set();
-    for (const raw of claudeMd.split('\n')) {
-        const line = raw.trim();
-        if (line.startsWith('@'))
-            paths.add(line.slice(1).trim());
+function importedRulePaths(claudeMd, rootDir) {
+    const direct = bareImportPaths(claudeMd);
+    const paths = new Set(direct);
+    for (const rel of direct) {
+        if (!isRulesIndexCandidate(rel))
+            continue;
+        const abs = path.join(rootDir, rel);
+        if (!existsSync(abs) || !statSync(abs).isFile())
+            continue;
+        for (const nested of bareImportPaths(readFileSync(abs, 'utf8'))) {
+            paths.add(resolveImportFrom(rel, nested));
+        }
     }
     return paths;
 }
@@ -137,11 +246,16 @@ export function computeDoctor(deps = {}) {
     // Diagnose at the REPO ROOT (where the brain + lockfile live), not cwd — so
     // `doctor` from a subdir of a managed repo reports the real state instead of
     // "no lockfile" (consistency with `add`/`update`). Tests inject `rootDir`.
-    const rootDir = deps.rootDir ?? detectRepo(process.cwd()).repoRoot ?? process.cwd();
+    const rootDir = doctorRoot(deps.rootDir);
+    // Vault mode (ADOPT-004) — local and synchronous; the drift is `runDoctor`'s separate step.
+    const vault = readVaultMode(rootDir);
+    const neonRevokePending = countNeonRevokePending(rootDir);
     // Initial-migration gap (GAP-002). Delegated WHOLE to the provision predicate —
     // facts read from disk, decision (Factory exception included) taken there. Doctor
     // does not re-derive "is this the Factory": one copy of that rule, in one place.
     const missingInitialMigration = needsInitialMigration(readMigrationFacts(rootDir));
+    // Stale file-based rail on this machine (RAIL-003) — existence only, never read.
+    const staleRailFile = findStaleRailFile(deps.homeDir ?? homedir());
     if (!hasLockfile(rootDir)) {
         return {
             orphans: [],
@@ -152,8 +266,13 @@ export function computeDoctor(deps = {}) {
             // Always false on this branch, and by the predicate rather than by a literal:
             // no lockfile IS the Factory signal, which `needsInitialMigration` short-circuits.
             missingInitialMigration,
+            staleRailFile,
             noLockfile: true,
             beta: false,
+            vault,
+            // `vault adopt` requires a lockfile: suggesting it here would send the dev to a refusal.
+            suggestAdopt: false,
+            neonRevokePending,
         };
     }
     const lock = readLockfile(rootDir);
@@ -188,7 +307,8 @@ export function computeDoctor(deps = {}) {
     const claudeMdMissing = !existsSync(claudeMdPath);
     if (!claudeMdMissing) {
         const claudeMd = readFileSync(claudeMdPath, 'utf8');
-        const imported = importedRulePaths(claudeMd); // bare `@<path>` directive lines
+        // Bare `@<path>` directive lines, plus one hop through an INDEX under `.claude/rules/`.
+        const imported = importedRulePaths(claudeMd, rootDir);
         const onDemand = onDemandSectionText(claudeMd);
         for (const entry of lock.files) {
             if (!RULE_PATH_RE.test(entry.path))
@@ -206,17 +326,28 @@ export function computeDoctor(deps = {}) {
         claudeMdMissing,
         a1Warning: A1_WARNING,
         missingInitialMigration,
+        staleRailFile,
         noLockfile: false,
         beta,
+        vault,
+        suggestAdopt: vault.mode === 'sin decidir',
+        neonRevokePending,
     };
 }
 /** Render the doctor result to the console. The A1 notice is ALWAYS last. */
-function renderDoctor(result) {
+function renderDoctor(result, repoVault) {
+    const vaultLines = renderRepoVault(repoVault, { suggestAdopt: result.suggestAdopt });
+    const neonNotice = neonRevokePendingNotice(result.neonRevokePending);
+    if (neonNotice)
+        vaultLines.push(neonNotice);
     if (result.noLockfile) {
         // Nothing to say about migrations here: no lockfile IS the Factory signal, so
         // `missingInitialMigration` is false by construction on this branch.
         console.log('Sin lockfile detectado.');
         console.log('Ejecuta `factory:update` para inicializar el tracking de versión.');
+        console.log(`\n${vaultLines.join('\n')}`);
+        if (result.staleRailFile)
+            console.log(`\n${staleRailFileNotice(result.staleRailFile)}`);
         // The A1 notice is emitted even without a lockfile (always present).
         console.log(`\n${result.a1Warning}`);
         return;
@@ -263,6 +394,12 @@ function renderDoctor(result) {
     if (result.missingInitialMigration) {
         console.log(`\n${MISSING_INITIAL_MIGRATION_NOTICE}`);
     }
+    // Vault mode + drift (ADOPT-004): informative, never a failure.
+    console.log(`\n${vaultLines.join('\n')}`);
+    // Stale rail file (RAIL-003): machine-level, advisory, never deleted by doctor.
+    if (result.staleRailFile) {
+        console.log(`\n${staleRailFileNotice(result.staleRailFile)}`);
+    }
     // The A1 security notice is always emitted at the end (design §1 + §11).
     console.log(`\n${result.a1Warning}`);
 }
@@ -270,17 +407,51 @@ function renderDoctor(result) {
  * Run `factory doctor`. Always exits 0 — a missing lockfile is advisory, not a
  * failure (DIST-006 §8). The A1 notice is emitted on every run.
  *
- * Synchronous: the standard doctor report has no network/async seam. The
- * additive `--launcher` flow is async (it spawns `gh`) and lives in its own
- * entrypoint, {@link runLauncherDoctor}.
+ * The offline report (`computeDoctor`) is synchronous and has no network seam. Only a repo in
+ * `bóveda` mode adds the drift, a separate bounded step that degrades to "no verificable" (no
+ * session, no network, no Vercel project or `railway` block) and never throws for that. Outside `bóveda` nothing is
+ * awaited, so the report is rendered synchronously, exactly as before.
  */
-export function runDoctor(deps = {}) {
-    const result = computeDoctor(deps);
-    renderDoctor(result);
+export async function runDoctor(deps = {}) {
+    const rootDir = doctorRoot(deps.rootDir);
+    const result = computeDoctor({ ...deps, rootDir });
+    if (result.vault.mode !== 'bóveda') {
+        renderDoctor(result, {
+            mode: result.vault.mode,
+            modeError: result.vault.error,
+            drift: { status: 'no aplica' },
+        });
+        return;
+    }
+    renderDoctor(result, await repoVaultReportFor(rootDir, result.vault, deps.drift));
+}
+/**
+ * The repo's vault report for the launcher document, within the launcher's budget. The document
+ * must ALWAYS come out (the launcher waits for it), so any failure here — even the Vitest seam
+ * refusal, which fires before any request — degrades to "no verificable" with its message.
+ */
+async function launcherRepoVault(deps, rail) {
+    const rootDir = doctorRoot(deps.rootDir);
+    const reading = readVaultMode(rootDir);
+    try {
+        return await repoVaultReportFor(rootDir, reading, {
+            rail,
+            timeoutMs: LAUNCHER_RAIL_TIMEOUT_MS,
+            ...deps.drift,
+        });
+    }
+    catch (error) {
+        return {
+            mode: reading.mode,
+            modeError: reading.error,
+            drift: {
+                status: 'no verificable',
+                reason: error instanceof CLIError ? error.message : 'error interno al calcular el drift.',
+                railway: 'no verificado',
+            },
+        };
+    }
 }
-// ---------------------------------------------------------------------------
-// `factory doctor --launcher` (LTUI-002) — env preflight, any-platform/any-shell
-// ---------------------------------------------------------------------------
 /** The glyph per launcher-check status. */
 const STATUS_GLYPH = {
     ok: '✅',
@@ -340,12 +511,22 @@ export function renderLauncherDoctor(checks) {
  * Node version + the gh steps without spawning sub-processes).
  */
 export async function runLauncherDoctor(deps = {}, json = false) {
-    const checks = await runLauncherPreflight(deps);
+    // ONE rail resolver for the secrets check and the drift: the vault is read once per run.
+    const rail = deps.rail ?? createRailResolver({ timeoutMs: LAUNCHER_RAIL_TIMEOUT_MS });
+    const [preflight, repoVault] = await Promise.all([
+        runLauncherPreflight({ ...deps, rail }),
+        launcherRepoVault(deps, rail),
+    ]);
+    // ADOPT-004: mode + drift ride ADDITIVELY on the `secrets` element — its id, status and message
+    // are untouched (RAIL-003: `warn` = keys missing / no session, never `fail`), so an installed
+    // launcher that predates the field ignores it (ADR-004 §3).
+    const checks = preflight.map((check) => check.id === 'secrets' ? { ...check, repoVault } : check);
     if (json) {
         process.stdout.write(`${JSON.stringify(checks)}\n`);
         return;
     }
     renderLauncherDoctor(checks);
+    console.log(`\n${renderRepoVault(repoVault, { suggestAdopt: false }).join('\n')}`);
     if (checks.some((c) => c.status === 'fail')) {
         // Non-zero exit without a duplicate error dump: the per-check ❌ lines above
         // already told the user what to fix. The empty message keeps the top-level