@timekast/factory 2.3.1 → 2.5.0

package/dist/lib/claude-settings.js

@@ -0,0 +1,104 @@
+/**
+ * `.claude/settings.json` is shared: the kit owns the top-level keys ITS file declares (today
+ * `$schema`, `hooks`, `permissions`); every other top-level key belongs to the project
+ * (`enabledPlugins`, `extraKnownMarketplaces`, `env`, `statusLine`…). `update` compares only
+ * the kit's keys, by CONTENT — a project that only added its own keys, or whose tools
+ * reformatted the file (prettier, `/plugin install --scope project`), is not "edited" — and
+ * after writing the kit's file it puts the project's keys back.
+ *
+ * The manifest entry of this path carries `keys` (the kit's keys in that version) and a
+ * {@link settingsContentHash} instead of the raw-bytes hash. Lockfiles written before that
+ * carry the raw hash; {@link KIT_SETTINGS_HISTORY} maps it to the content hash of the same file.
+ * Contract: `fx-extension-points` §3.
+ */
+import { createHash } from 'node:crypto';
+import KIT_SETTINGS_HISTORY_JSON from './kit-settings-history.json' with { type: 'json' };
+import { normalizeThenHash } from './lockfile.js';
+export const KIT_SETTINGS_PATH = '.claude/settings.json';
+/** The kit's top-level keys in every `settings.json` published before entries carried `keys`. */
+export const LEGACY_KIT_SETTINGS_KEYS = ['$schema', 'hooks', 'permissions'];
+/**
+ * Raw-bytes hash (`normalizeThenHash`) → content hash over {@link LEGACY_KIT_SETTINGS_KEYS}, for
+ * every distinct `settings.json` the kit published before content hashes. Frozen: generated once
+ * from the `v*` tags (every later release records a content hash with its `keys`).
+ */
+export const KIT_SETTINGS_HISTORY = KIT_SETTINGS_HISTORY_JSON;
+/** JSON with object keys sorted at every level and no whitespace — arrays keep their order. */
+export function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    if (value !== null && typeof value === 'object') {
+        const obj = value;
+        return `{${Object.keys(obj)
+            .sort()
+            .map((k) => `${JSON.stringify(k)}:${canonicalJson(obj[k])}`)
+            .join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+function parseObject(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * SHA-256 of the canonical JSON of the `keys` subset of `raw` (absent keys are left out).
+ * `null` when `raw` is not a JSON object. Parity-locked with `distribution/build-dist.ts`.
+ */
+export function settingsContentHash(raw, keys) {
+    const obj = parseObject(raw);
+    if (!obj)
+        return null;
+    const subset = {};
+    for (const key of keys)
+        if (key in obj)
+            subset[key] = obj[key];
+    return createHash('sha256').update(canonicalJson(subset), 'utf8').digest('hex');
+}
+/** Whether `raw` holds the kit's keys of `entry` unchanged (the project's own keys aside). */
+function matchesEntry(raw, entry) {
+    if (normalizeThenHash(raw) === entry.hash)
+        return true;
+    const keys = entry.keys ?? (KIT_SETTINGS_HISTORY[entry.hash] ? LEGACY_KIT_SETTINGS_KEYS : null);
+    const expected = entry.keys ? entry.hash : KIT_SETTINGS_HISTORY[entry.hash];
+    return keys !== null && expected !== undefined && settingsContentHash(raw, keys) === expected;
+}
+/**
+ * The hash `diffLockfiles` sees for `settings.json` on disk: the old or the new entry's hash when
+ * the kit's keys match it, the raw hash otherwise (= edited, as for any other file).
+ */
+export function effectiveSettingsHash(raw, entries) {
+    for (const entry of entries)
+        if (entry && matchesEntry(raw, entry))
+            return entry.hash;
+    return normalizeThenHash(raw);
+}
+/**
+ * The kit's file plus the project's keys of `previousRaw` (every top-level key the kit does not
+ * declare). `content` is `null` when there is nothing to carry over — the kit's file stays byte
+ * for byte. `replaced` names the project keys the kit now declares (the kit wins).
+ *
+ * @param previousKitKeys the kit's keys BEFORE this update (old entry's `keys`, or the legacy
+ *   ones): a previous key outside them was the project's.
+ */
+export function mergeProjectSettingsKeys(kitRaw, previousRaw, previousKitKeys) {
+    const kit = parseObject(kitRaw);
+    const previous = parseObject(previousRaw);
+    if (!kit || !previous)
+        return { content: null, kept: [], replaced: [] };
+    const projectKeys = Object.keys(previous).filter((k) => !previousKitKeys.includes(k));
+    const kept = projectKeys.filter((k) => !(k in kit));
+    const replaced = projectKeys.filter((k) => k in kit);
+    if (kept.length === 0)
+        return { content: null, kept, replaced };
+    const merged = { ...kit };
+    for (const key of kept)
+        merged[key] = previous[key];
+    return { content: `${JSON.stringify(merged, null, 2)}\n`, kept, replaced };
+}

package/dist/lib/constants.js

@@ -65,6 +65,12 @@ export const PROFILES = {
 export const TIMEKAST_DIR = '.timekast';
 export const MANIFEST_FILE = 'manifest.json';
 export const LOCKFILE_FILE = 'lockfile.json';
+/**
+ * The npm packages the kit's tracked files need (Factory#78), embedded by the builder next to
+ * `manifest.json`: `{ version, profile, packages: { name: range } }`. Read from the STAGED
+ * tarball by `add`/`update` (`kit-deps.ts`); never left in a derived repo.
+ */
+export const KIT_DEPS_FILE = 'kit-deps.json';
 /**
  * Repo-root path of the runtime entrypoint markdown. It is a tracked manifest
  * file (via `track` + the `core` rename `CLAUDE.core.md → CLAUDE.md`), so it
@@ -86,6 +92,21 @@ export const CLAUDE_MD_FILE = 'CLAUDE.md';
  * split as `.husky/pre-commit` → `.husky/pre-commit.project`.
  */
 export const VITEST_SETUP_FILE = 'vitest.setup.ts';
+/**
+ * Path prefixes of the brain proper: the two trees the kit's `.prettierignore` block has always
+ * covered whole. Every other path the manifest tracks (`CLAUDE.md`, `.husky/*`,
+ * `.github/workflows/*`, `vitest.setup.ts`) lives among the repo's own files, so the block lists
+ * those one by one, generated from the manifest at sync time (`renderPrettierignoreBlock`).
+ * Trailing slash so a prefix match cannot catch a sibling (`scripts/tools-extra/`).
+ */
+export const BRAIN_PREFIXES = ['.claude/', 'scripts/tools/'];
+/**
+ * Suffix of the kit's copy of a file the repo already had with its own content (`add` keeps the
+ * repo's and writes the kit's next to it). APPENDED to the whole name, never inserted before the
+ * extension: GitHub Actions runs every `*.yml` under `.github/workflows/`, so `ci.kit-example.yml`
+ * would run as a second CI, while `ci.yml.kit-example` is inert.
+ */
+export const KIT_EXAMPLE_SUFFIX = '.kit-example';
 /**
  * Repo-root `.gitattributes`. NOT a tracked manifest file (absent from `track`),
  * so it never flows through the diff/lockfile engine — a derived repo's own rules
@@ -104,6 +125,19 @@ export const GITATTRIBUTES_FILE = '.gitattributes';
  * turns every later `factory:update` into false conflicts (A2).
  */
 export const PRETTIERIGNORE_FILE = '.prettierignore';
+/**
+ * Repo-root `.gitignore`. Same managed-block treatment, but ONLY in a pruned repo
+ * (`factory prune`): the block lists the kit paths kept local to the members, generated
+ * from `.claude/policy/prune-tiers.json`. A repo without the switch below never gets one.
+ */
+export const GITIGNORE_FILE = '.gitignore';
+/**
+ * File name, under `.timekast/`, of the per-repo switch written by `factory prune prepare`
+ * (`{ tier, at }`). Its OWN file, not a lockfile field: `update` rewrites the lockfile whole.
+ * Without it every prune behavior — the `.gitignore` block, the untracking in `update`, the
+ * pre-commit guard — stays off.
+ */
+export const PRUNE_FILE = 'prune.json';
 /**
  * Managed-block sentinels. These are PREFIXES (the live source lines carry extra
  * descriptive text + trailing `>>>`/`<<<`), matched with `startsWith` so detection
@@ -131,6 +165,10 @@ export const UNPUBLISH_SCRIPT_CMD = 'npx @timekast/factory unpublish';
 // through `npx` so it resolves without a global install.
 export const ENV_PUSH_SCRIPT_NAME = 'env:push';
 export const ENV_PUSH_SCRIPT_CMD = 'npx @timekast/factory env push';
+// Agentic Dashboard: the team's local usage dashboard. It reads this machine's Claude Code
+// transcripts, not the repo, so it needs nothing the brain ships and goes to every derivative.
+export const DASHBOARD_SCRIPT_NAME = 'dashboard';
+export const DASHBOARD_SCRIPT_CMD = 'npx -y @timekast/agentic-dashboard --open';
 /**
  * All convenience scripts the installer ensures in a Node derivative's
  * package.json (each: add if missing, never overwrite a divergent value). Keyed
@@ -144,6 +182,7 @@ export const FACTORY_SCRIPTS = {
     [PUBLISH_SCRIPT_NAME]: PUBLISH_SCRIPT_CMD,
     [UNPUBLISH_SCRIPT_NAME]: UNPUBLISH_SCRIPT_CMD,
     [ENV_PUSH_SCRIPT_NAME]: ENV_PUSH_SCRIPT_CMD,
+    [DASHBOARD_SCRIPT_NAME]: DASHBOARD_SCRIPT_CMD,
 };
 /**
  * The local wrapper that injects the vault's environment into the kit's scripts (VAULT-003).

package/dist/lib/derived-dotfiles.js

@@ -0,0 +1,165 @@
+/**
+ * The derived project's dual-owned dotfiles — `.gitattributes` and `.prettierignore` — synced
+ * from the staged tarball after the brain lands. Shared by `add` and the three `update` paths
+ * (main, legacy auto-register, resume): `add` used to skip them, so the first commit of a fresh
+ * install ran the repo's `prettier --write` over every kit file and drifted them all from the
+ * lockfile hashes (Factory#83/#78).
+ *
+ * The generic block engine lives in `gitattributes.ts` (`extractManagedBlock`,
+ * `syncManagedBlock`); this module only decides WHICH block goes into WHICH file and reports it.
+ * Both syncs are best-effort: a tarball without the file (pre-block releases) is a silent no-op,
+ * and a write failure never fails an install that already happened.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { BRAIN_PREFIXES, CLAUDE_MD_FILE, GITATTRIBUTES_FILE, KIT_EXAMPLE_SUFFIX, MANAGED_BLOCK_END, PRETTIERIGNORE_FILE, } from './constants.js';
+import { extractManagedBlock, syncManagedBlock } from './gitattributes.js';
+import { MIGRATIONS_DIR } from './initial-migration.js';
+/** Config files drizzle-kit reads, in the order it would pick them. */
+const DRIZZLE_CONFIG_FILES = [
+    'drizzle.config.ts',
+    'drizzle.config.mts',
+    'drizzle.config.js',
+    'drizzle.config.mjs',
+    'drizzle.config.cjs',
+];
+/** The `out` key of a drizzle config, as a string literal. */
+const DRIZZLE_OUT_RE = /\bout\s*:\s*['"`]([^'"`]+)['"`]/;
+/** The kit's migration line inside the canonical block (`src/lib/db/migrations/`). */
+const KIT_MIGRATIONS_LINE = `${MIGRATIONS_DIR}/`;
+/**
+ * Where THIS repo keeps its drizzle migrations, as an ignore line (`lib/db/migrations/`), or
+ * `null` to keep the kit's. The `out` of the repo's drizzle config wins; without one, a repo with
+ * no `src/` gets the kit path without its `src/` prefix — the adjustment a derivative born before
+ * `src/` makes by hand, which the sync used to revert on every update (Factory#83).
+ */
+export function resolveMigrationsLine(root) {
+    for (const name of DRIZZLE_CONFIG_FILES) {
+        const file = path.join(root, name);
+        if (!existsSync(file))
+            continue;
+        const match = DRIZZLE_OUT_RE.exec(readFileSync(file, 'utf8'));
+        if (!match)
+            break;
+        const out = match[1].trim().replace(/^\.\//, '').replace(/\/+$/, '');
+        // An absolute path or one that climbs out of the repo is nothing prettier could match.
+        if (out === '' || out === '.' || path.isAbsolute(out) || out.split('/').includes('..'))
+            break;
+        return `${out}/`;
+    }
+    if (!existsSync(path.join(root, 'src')))
+        return KIT_MIGRATIONS_LINE.replace(/^src\//, '');
+    return null;
+}
+/**
+ * The kit files this repo's formatter must leave alone that live OUTSIDE the brain prefixes:
+ * every manifest path not under `BRAIN_PREFIXES`, minus `CLAUDE.md` (dev-owned content) and
+ * minus any path with a `<path>.kit-example` beside it — there the file on disk is the repo's
+ * own, and formatting it is the repo's business. Sorted, so the block is stable across runs.
+ */
+export function kitFilesOutsideBrain(manifestPaths, root) {
+    return [...new Set(manifestPaths)]
+        .filter((p) => !BRAIN_PREFIXES.some((prefix) => p.startsWith(prefix)))
+        .filter((p) => p !== CLAUDE_MD_FILE)
+        .filter((p) => !existsSync(path.join(root, `${p}${KIT_EXAMPLE_SUFFIX}`)))
+        .sort();
+}
+/**
+ * Render the `.prettierignore` block for THIS repo from the canonical one the tarball ships.
+ * The canonical block only knows the Factory's own layout and covers `.claude/` and
+ * `scripts/tools/`; two things are generated at sync time, the same precedent as
+ * `renderGitignoreBlock` in `prune`:
+ *
+ *   - the migrations line follows the repo's real drizzle `out` (`resolveMigrationsLine`);
+ *   - a section lists the kit files tracked outside the brain prefixes (`ci.yml`,
+ *     `vitest.setup.ts`, `.husky/*`). Prettier reformatted them in every derivative whose style
+ *     differs from the kit's, and each one became a false conflict on the next update.
+ *
+ * Reads the repo (drizzle config, `src/`, `.kit-example` files) but writes nothing. The same
+ * inputs always give the same block, so a second sync is a no-op.
+ */
+export function renderPrettierignoreBlock(canonical, ctx) {
+    const migrations = resolveMigrationsLine(ctx.root);
+    const lines = canonical
+        .replace(/\r\n/g, '\n')
+        .split('\n')
+        .map((line) => (migrations && line.trim() === KIT_MIGRATIONS_LINE ? migrations : line));
+    const present = new Set(lines.map((l) => l.trim()));
+    const extra = kitFilesOutsideBrain(ctx.manifestPaths, ctx.root).filter((p) => !present.has(p));
+    if (extra.length === 0)
+        return lines.join('\n');
+    const section = [
+        '# Kit files tracked outside .claude/ and scripts/tools/, generated from the manifest by',
+        '# factory add/update. A reformat drifts them from the lockfile just like the brain.',
+        ...extra,
+    ];
+    const end = lines.findIndex((l) => l.trimStart().startsWith(MANAGED_BLOCK_END));
+    if (end === -1)
+        return [...lines, ...section].join('\n');
+    return [...lines.slice(0, end), ...section, ...lines.slice(end)].join('\n');
+}
+/**
+ * Sync the Factory's managed `.gitattributes` block (the EOL/binary rules that
+ * keep the kit's committed binaries from being corrupted by CRLF→LF normalization)
+ * into the derived repo, preserving the dev's own rules. The canonical block is
+ * READ from the staged tarball (single SSOT), so the rules are never duplicated in
+ * the CLI. Runs even without package.json (a non-Node derivative needs the rules
+ * too).
+ */
+export function syncDerivedGitattributes(rootDir, stagedDir) {
+    try {
+        const srcPath = path.join(stagedDir, GITATTRIBUTES_FILE);
+        if (!existsSync(srcPath))
+            return;
+        const block = extractManagedBlock(readFileSync(srcPath, 'utf8'));
+        if (!block)
+            return;
+        const { action } = syncManagedBlock(rootDir, block);
+        if (action === 'unchanged')
+            return;
+        console.log(action === 'created'
+            ? '✔ `.gitattributes` creado con las reglas de normalización del kit.'
+            : '✔ `.gitattributes`: bloque de reglas del kit sincronizado.');
+    }
+    catch {
+        console.warn('Aviso: no se pudo sincronizar `.gitattributes`; el cerebro se instaló igual.');
+    }
+}
+/**
+ * Sync the Factory's managed `.prettierignore` block (keeps the derived repo's
+ * formatter away from `.claude/**` — a pre-commit `prettier --write` over the kit
+ * files drifts disk from the lockfile hashes and turns every later update into
+ * false conflicts) into the derived repo, preserving the dev's own ignore rules.
+ * The block is rendered for this repo (`renderPrettierignoreBlock`); otherwise the
+ * same contract as `syncDerivedGitattributes`.
+ */
+export function syncDerivedPrettierignore(rootDir, stagedDir, manifestPaths) {
+    try {
+        const srcPath = path.join(stagedDir, PRETTIERIGNORE_FILE);
+        if (!existsSync(srcPath))
+            return;
+        const canonical = extractManagedBlock(readFileSync(srcPath, 'utf8'));
+        if (!canonical)
+            return;
+        const block = renderPrettierignoreBlock(canonical, { manifestPaths, root: rootDir });
+        const { action } = syncManagedBlock(rootDir, block, PRETTIERIGNORE_FILE);
+        if (action === 'unchanged')
+            return;
+        console.log(action === 'created'
+            ? '✔ `.prettierignore` creado con el ignore del cerebro (`.claude/`) — evita falsos conflictos por formato en futuros updates.'
+            : '✔ `.prettierignore`: bloque del kit sincronizado (`.claude/` fuera del formatter).');
+    }
+    catch {
+        console.warn('Aviso: no se pudo sincronizar `.prettierignore`; el cerebro se instaló igual.');
+    }
+}
+/**
+ * Sync both managed blocks. `manifest` is the profile's manifest just installed (the
+ * `.prettierignore` block lists its files outside the brain prefixes). Must run while
+ * `stagedDir` still exists (it is the source of the blocks) and BEFORE any commit of the brain,
+ * so the ignore lands before a pre-commit hook could reformat the freshly-installed kit files.
+ */
+export function syncDerivedDotfiles(rootDir, stagedDir, manifest) {
+    syncDerivedGitattributes(rootDir, stagedDir);
+    syncDerivedPrettierignore(rootDir, stagedDir, manifest.files.map((f) => f.path));
+}

package/dist/lib/email-from.js

@@ -16,10 +16,7 @@
  * 🔒 TOTAL (never throws): it runs on values read from a deploy, which the CLI does not control.
  */
 export function sendingDomainOf(emailFrom) {
-    const value = emailFrom.trim();
-    const open = value.lastIndexOf('<');
-    const close = value.lastIndexOf('>');
-    const address = open !== -1 && close > open ? value.slice(open + 1, close) : value;
+    const address = senderAddressOf(emailFrom);
     const at = address.lastIndexOf('@');
     return at === -1
         ? ''
@@ -28,3 +25,14 @@ export function sendingDomainOf(emailFrom) {
             .trim()
             .toLowerCase();
 }
+/**
+ * The bare address of an `EMAIL_FROM` value: the part inside the LAST `<…>` when there is one,
+ * else the whole value, trimmed (`Agent Fleet <noreply@x.com>` → `noreply@x.com`). Same rule as
+ * {@link sendingDomainOf}. 🔒 TOTAL (never throws).
+ */
+export function senderAddressOf(emailFrom) {
+    const value = emailFrom.trim();
+    const open = value.lastIndexOf('<');
+    const close = value.lastIndexOf('>');
+    return (open !== -1 && close > open ? value.slice(open + 1, close) : value).trim();
+}

package/dist/lib/flags.js

@@ -0,0 +1,14 @@
+/** Read the value of a `--key=value` or `--key value` flag from an argv slice. */
+export function readValueFlag(argv, name) {
+    const prefix = `--${name}=`;
+    const inline = argv.find((arg) => arg.startsWith(prefix));
+    if (inline)
+        return inline.slice(prefix.length);
+    const idx = argv.indexOf(`--${name}`);
+    if (idx !== -1) {
+        const next = argv[idx + 1];
+        if (next && !next.startsWith('-'))
+            return next;
+    }
+    return undefined;
+}

package/dist/lib/initial-writes.js

@@ -0,0 +1,113 @@
+/**
+ * What a FIRST install (`factory add`, and the legacy auto-register of `factory update`) may
+ * write over a repo that already has files of its own (Factory#76).
+ *
+ * Both paths used to write every manifest file without looking, which is right for the brain
+ * (`.claude/`, `scripts/tools/`) and wrong for the handful of kit files that live among the
+ * repo's own: an `add --full` replaced a repo's `.github/workflows/ci.yml` with the kit
+ * template and dropped its build, E2E and gitleaks steps. Three classes, decided by path:
+ *
+ *   - brain (`BRAIN_PREFIXES`) → always written, as before;
+ *   - `CLAUDE.md`             → written only when absent (dev-owned content, unchanged rule);
+ *   - every other kit file    → written when absent; left alone when it already holds the kit's
+ *     content; KEPT when it holds something else, with the kit's copy written next to it as
+ *     `<path>.kit-example` for the team to compare.
+ *
+ * The lockfile still records the KIT hash for a kept file (it is the embedded manifest), the
+ * same as a preserved `CLAUDE.md`. On the next `update` the diff engine then reads it as a local
+ * edit: kept silently while the kit does not change it (`ignoreLocal`), a mine/theirs prompt
+ * when it does.
+ */
+import { copyFileSync, existsSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { BRAIN_PREFIXES, CLAUDE_MD_FILE, KIT_EXAMPLE_SUFFIX } from './constants.js';
+import { normalizeThenHash } from './lockfile.js';
+/** Classify a manifest path (see the module header for what each class does). */
+export function classifyInitialWrite(relPath) {
+    if (BRAIN_PREFIXES.some((prefix) => relPath.startsWith(prefix)))
+        return 'brain';
+    if (relPath === CLAUDE_MD_FILE)
+        return 'claude-md';
+    return 'repo';
+}
+/** The kit's copy of a kept repo file: the suffix goes after the WHOLE name. */
+export function kitExamplePath(relPath) {
+    return `${relPath}${KIT_EXAMPLE_SUFFIX}`;
+}
+/**
+ * Split the manifest into what a first install writes and what it keeps. Reads the repo, writes
+ * nothing. A `repo`-class file whose normalized hash equals the kit's is neither written nor
+ * kept: it already is the kit's file.
+ */
+export function partitionInitialWrites(root, manifest) {
+    const writes = [];
+    const kept = [];
+    for (const entry of manifest.files) {
+        const abs = path.join(root, entry.path);
+        const onDisk = existsSync(abs) && statSync(abs).isFile();
+        switch (classifyInitialWrite(entry.path)) {
+            case 'brain':
+                writes.push(entry.path);
+                break;
+            case 'claude-md':
+                if (!onDisk)
+                    writes.push(entry.path);
+                break;
+            case 'repo':
+                if (!onDisk)
+                    writes.push(entry.path);
+                else if (normalizeThenHash(readFileSync(abs, 'utf8')) !== entry.hash)
+                    kept.push(entry.path);
+                break;
+        }
+    }
+    return { writes, kept };
+}
+/**
+ * Copy the kit's version of each kept file from the staged tarball to `<path>.kit-example`.
+ * Returns the example paths actually written (a path missing from the staged dir is skipped).
+ */
+export function writeKitExamples(root, stagedDir, kept) {
+    const written = [];
+    for (const rel of kept) {
+        const src = path.join(stagedDir, rel);
+        if (!existsSync(src))
+            continue;
+        copyFileSync(src, path.join(root, kitExamplePath(rel)));
+        written.push(kitExamplePath(rel));
+    }
+    return written;
+}
+/**
+ * `update`: refresh every `<path>.kit-example` already on disk with the incoming kit version,
+ * so the copy the team compares against never goes stale. Only paths of the manifest, only
+ * examples that already exist (an update never creates one), only when the bytes change.
+ * Returns the example paths rewritten.
+ */
+export function refreshKitExamples(root, stagedDir, manifestPaths) {
+    const refreshed = [];
+    for (const rel of manifestPaths) {
+        if (classifyInitialWrite(rel) !== 'repo')
+            continue;
+        const example = path.join(root, kitExamplePath(rel));
+        const src = path.join(stagedDir, rel);
+        if (!existsSync(example) || !existsSync(src))
+            continue;
+        const incoming = readFileSync(src);
+        if (readFileSync(example).equals(incoming))
+            continue;
+        copyFileSync(src, example);
+        refreshed.push(kitExamplePath(rel));
+    }
+    return refreshed;
+}
+/** Tell the dev which files were kept and where the kit's version went. */
+export function reportKeptRepoFiles(kept) {
+    if (kept.length === 0)
+        return;
+    console.log('\nConservé estos archivos tuyos; la versión del kit quedó al lado para comparar:');
+    for (const rel of kept)
+        console.log(`  • ${rel} → ${kitExamplePath(rel)}`);
+    console.log('  Si quieres algo de la versión del kit, cópialo a mano. Mientras el kit no cambie esos ' +
+        'archivos, `factory update` los deja como están; si los cambia, te pregunta cuál conservar.');
+}

package/dist/lib/kit-deps.js

@@ -0,0 +1,163 @@
+/**
+ * The npm packages the kit's files need, against the ones the repo declares (Factory#78).
+ *
+ * A derivative of an older kit (or an app that never was one) gets kit files that import
+ * packages it does not have — `sharp`, `@testing-library/*`, `knip`… — and its typecheck,
+ * `next build` and CI go red with nothing telling it why. The builder embeds the list in
+ * every tarball (`.timekast/kit-deps.json`, `distribution/build-dist.ts#buildKitDeps`):
+ * each package with the range the Factory declares. `add` and `update` compare it with the
+ * repo's `package.json` and OFFER to install what is missing:
+ *
+ *   · interactive terminal → asks, and on yes runs `<pm> add -D …` in the repo;
+ *   · no terminal, or `--yes` → only prints the exact command (never installs blindly —
+ *     installing a dependency is the dev's call, `CODING.md §7`);
+ *   · `--dry-run` → only lists them.
+ *
+ * A repo without `package.json` is not a Node project: nothing is offered, and none is
+ * ever created. A tarball from before this list existed has no file: nothing is offered.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { execa } from 'execa';
+import prompts from 'prompts';
+import { KIT_DEPS_FILE, TIMEKAST_DIR } from './constants.js';
+import { PACKAGE_JSON_FILE, PNPM_LOCKFILE } from './initial-migration.js';
+/** Lockfile → package manager, in detection order. No lockfile → `pnpm` (the kit's). */
+const PM_LOCKFILES = [
+    [PNPM_LOCKFILE, 'pnpm'],
+    ['yarn.lock', 'yarn'],
+    ['package-lock.json', 'npm'],
+    ['bun.lockb', 'bun'],
+    ['bun.lock', 'bun'],
+];
+/** The "add as devDependency" verb of each package manager. */
+const PM_ADD_DEV = {
+    pnpm: ['add', '-D'],
+    yarn: ['add', '-D'],
+    npm: ['install', '-D'],
+    bun: ['add', '-d'],
+};
+/**
+ * Read the list from a STAGED tarball. Absent (a release from before the list) → `null`,
+ * silently. Unreadable or with the wrong shape → `null` with a warning: the brain still
+ * installs, the offer is just skipped.
+ */
+export function readKitDeps(stagedDir) {
+    const file = path.join(stagedDir, TIMEKAST_DIR, KIT_DEPS_FILE);
+    if (!existsSync(file))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(file, 'utf8'));
+        const packages = parsed.packages;
+        if (typeof packages !== 'object' ||
+            packages === null ||
+            Array.isArray(packages) ||
+            !Object.values(packages).every((range) => typeof range === 'string')) {
+            throw new Error('shape');
+        }
+        return parsed;
+    }
+    catch {
+        console.warn(`Aviso: el \`${TIMEKAST_DIR}/${KIT_DEPS_FILE}\` del tarball no se pudo leer; omito la revisión de dependencias.`);
+        return null;
+    }
+}
+/**
+ * The kit packages the repo's `package.json` does not declare (in `dependencies`,
+ * `devDependencies`, `optionalDependencies` or `peerDependencies`), as `name@range`
+ * specs sorted by name — pure.
+ */
+export function missingKitDeps(pkg, kitDeps) {
+    const declared = new Set();
+    for (const field of [
+        'dependencies',
+        'devDependencies',
+        'optionalDependencies',
+        'peerDependencies',
+    ]) {
+        const deps = pkg[field];
+        if (deps && typeof deps === 'object')
+            for (const name of Object.keys(deps))
+                declared.add(name);
+    }
+    return Object.keys(kitDeps.packages)
+        .filter((name) => !declared.has(name))
+        .sort()
+        .map((name) => `${name}@${kitDeps.packages[name]}`);
+}
+/** The repo's package manager, by its lockfile — pure over `exists`. */
+export function detectPackageManager(rootDir, exists = existsSync) {
+    return PM_LOCKFILES.find(([file]) => exists(path.join(rootDir, file)))?.[1] ?? 'pnpm';
+}
+/** `<pm>` + its args to add `specs` as devDependencies. */
+export function installArgs(pm, specs) {
+    return [pm, [...PM_ADD_DEV[pm], ...specs]];
+}
+/** The command as a dev types it: each spec quoted when the shell could read it (`^` in zsh). */
+export function installCommand(pm, specs) {
+    const [bin, args] = installArgs(pm, specs);
+    const quote = (arg) => (/^[A-Za-z0-9@/._=-]+$/.test(arg) ? arg : `'${arg}'`);
+    return [bin, ...args.map(quote)].join(' ');
+}
+async function defaultConfirm(question) {
+    const answer = (await prompts({
+        type: 'confirm',
+        name: 'ok',
+        message: question,
+        initial: true,
+    }));
+    return answer?.ok === true;
+}
+async function defaultRun(bin, args, cwd) {
+    const result = await execa(bin, args, { cwd, stdio: 'inherit', reject: false });
+    return result.exitCode ?? 1;
+}
+/**
+ * Compare the kit's list with the repo's `package.json` and offer to install what is
+ * missing (see the module doc for who gets asked). Never throws for a missing or invalid
+ * `package.json` — the brain is installed either way.
+ */
+export async function offerKitDeps(rootDir, kitDeps, opts = {}) {
+    const pkgPath = path.join(rootDir, PACKAGE_JSON_FILE);
+    if (kitDeps === null || !existsSync(pkgPath))
+        return { action: 'none', missing: [] };
+    let pkg;
+    try {
+        pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    }
+    catch {
+        return { action: 'none', missing: [] };
+    }
+    const missing = missingKitDeps(pkg, kitDeps);
+    if (missing.length === 0)
+        return { action: 'none', missing };
+    const pm = detectPackageManager(rootDir);
+    const command = installCommand(pm, missing);
+    console.log(`\nLos archivos del kit usan ${missing.length} paquete(s) que tu \`package.json\` no declara ` +
+        '(sin ellos el typecheck, el build o el CI pueden fallar):');
+    for (const spec of missing)
+        console.log(`  • ${spec}`);
+    if (opts.dryRun) {
+        console.log(`Para instalarlos: \`${command}\``);
+        return { action: 'listed', missing };
+    }
+    const isTTY = opts.isTTY ?? Boolean(process.stdin.isTTY && process.stdout.isTTY);
+    if (opts.assumeYes || !isTTY) {
+        console.log(`Instálalos con: \`${command}\``);
+        return { action: 'printed', missing };
+    }
+    const confirm = opts.confirm ?? defaultConfirm;
+    if (!(await confirm(`¿Los instalo ahora como devDependencies? (\`${command}\`)`))) {
+        console.log(`No instalé nada. Cuando quieras: \`${command}\``);
+        return { action: 'declined', missing };
+    }
+    const [bin, args] = installArgs(pm, missing);
+    const exitCode = await (opts.run ?? defaultRun)(bin, args, rootDir);
+    if (exitCode !== 0) {
+        console.warn(`Aviso: \`${command}\` falló (código ${exitCode}). Revísalo y repítelo a mano.`);
+        return { action: 'failed', missing };
+    }
+    console.log(`✔ Paquetes instalados. \`package.json\` y el lockfile de \`${pm}\` quedaron modificados ` +
+        'y sin commitear: revísalos y commitéalos tú.');
+    return { action: 'installed', missing };
+}