@timekast/factory 1.23.1 → 1.25.0

package/dist/commands/update.js

@@ -48,6 +48,7 @@ import { diffLockfiles, hasLockfile, normalizeThenHash, planAutoRegister, readLo
 import { detectProfile, maintainKitScripts, setAgentKitVersion } from '../lib/package-json.js';
 import { runPreflight } from '../lib/preflight.js';
 import { printProvisionPointer } from '../lib/provision-pointer.js';
+import { printRetrofitReminder } from '../lib/retrofit-reminder.js';
 import { hasProvisionState } from '../lib/provision-state.js';
 import { detectRepo } from '../lib/repo-detection.js';
 import { downloadBetaProfileTarball, downloadProfileTarball, stageProfileTarball, } from '../lib/unpack.js';
@@ -849,6 +850,16 @@ export async function runUpdate(flags, deps = {}) {
         // the prompt, passed `--theirs-all`, or ran headless — there is no second path. The
         // package.json mutations ride the SAME closing summary, not three loose notices.
         reportSummary(diff, manifest, theirsConflicts, pkgMutations);
+        // 🔴 The retrofit reminder, on EVERY applied update and regardless of how conflicts
+        // were resolved — `--theirs-all`, `--mine-all`, per-file answers or none at all. A
+        // retrofit is not a conflict: it is work this command never attempted, living outside
+        // the tree it is allowed to touch. Deliberately NOT suppressed headless, unlike the
+        // pointer below: an agent updating unattended is the reader least able to notice a
+        // missing manual step on its own. Read from disk, so it lists what just arrived.
+        // `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 });
         // 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/lib/initial-migration.js

@@ -0,0 +1,131 @@
+/**
+ * The initial-migration predicate and the canonical "is this checkout the Factory"
+ * signal (GAP-001, fixed by `project/planning/decisions/ADR-003-factory-signal.md`).
+ *
+ * WHY THIS MODULE EXISTS. `factory provision` never ran `db:generate`, so a fresh
+ * derivative was born with a schema and no migrations while its `vercel-build`
+ * (`pnpm db:migrate && pnpm build`) migrated an empty database on the first deploy.
+ * The provision step that closes that gap has to decide, from disk alone, whether
+ * generating and committing a `0000` is the right thing to do — and the cost of a
+ * wrong "yes" is asymmetric.
+ *
+ * 🔴 THE SIGNAL FAILS TOWARD "DO NOT TOUCH". `.timekast/lockfile.json` is written by
+ * `new`/`add`/`update` in every derivative and does NOT exist in the Factory, so its
+ * ABSENCE means "this is the Factory, or a checkout that cannot be identified" and the
+ * predicate answers `false`. A false positive INSIDE the Factory would commit a `0000`
+ * here, and since the `full` distribution profile is `include: ["**"]` without excluding
+ * `src/lib/db/migrations/`, that `.sql` would ride the tarball into every new derivative
+ * — breaking BR-FACTORY-005 from the origin. A false negative only leaves the migration
+ * ungenerated, which the dev fixes with one `pnpm db:generate`.
+ *
+ * If this signal ever disagrees with the markdown detection `/deploy` uses (`is_factory`
+ * in `project/planning/project-config.md`), the ABSENCE OF THE LOCKFILE WINS and nothing
+ * is mutated — see ADR-003, which is the SSOT of that tie-break, not this comment.
+ *
+ * The predicate is intentionally PURE (it takes resolved facts, not a directory), so the
+ * `scripts/tools/` side of the distribution frontier can CALQUE it — never import it —
+ * the same way `backlog-parse.ts` calques `update-board.ts`.
+ */
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { hasLockfile } from './lockfile.js';
+/** Drizzle schema directory of a kit derivative (`drizzle.config.ts` `schema`). */
+export const SCHEMA_DIR = 'src/lib/db/schema';
+/**
+ * Drizzle migrations output directory (`drizzle.config.ts` `out`). Doubles as the
+ * COMMIT PATHSPEC of the provision step: with a shared index (multi-agent, `--resume`,
+ * `--adopt` over a live repo) a bare `git commit` would swallow whatever else is staged
+ * (GIT.md §3.6.1).
+ */
+export const MIGRATIONS_DIR = 'src/lib/db/migrations';
+/** Manifest of a Node derivative — its absence means there is nothing to install. */
+export const PACKAGE_JSON_FILE = 'package.json';
+/** The kit's package manager. Its lockfile is the positive signal for a pnpm project. */
+export const PNPM_LOCKFILE = 'pnpm-lock.yaml';
+/** Lockfiles of the other package managers — present WITHOUT pnpm's means "not ours". */
+export const FOREIGN_LOCKFILES = ['package-lock.json', 'yarn.lock', 'bun.lockb'];
+/** Extension of a generated drizzle migration. */
+export const MIGRATION_SQL_EXT = '.sql';
+/**
+ * Should the initial migration be generated for this checkout?
+ *
+ * PURE by design (see the module header): the caller resolves the facts, this decides.
+ * `isFactory` is checked FIRST and unconditionally — the fail-closed rule outranks
+ * every other consideration, including a project-config that claims otherwise.
+ */
+export function needsInitialMigration({ hasSchema, hasMigrations, isFactory, }) {
+    if (isFactory)
+        return false; // fail-closed: absence of the lockfile always wins
+    if (!hasSchema)
+        return false; // nothing to generate from
+    return !hasMigrations; // idempotence: an existing `.sql` means it was already done
+}
+/**
+ * The canonical machine signal (ADR-003): a derivative HAS `.timekast/lockfile.json`
+ * (written by `new`/`add`/`update`); the Factory does not. Absent → treat as Factory.
+ */
+export function isFactoryCheckout(rootDir) {
+    return !hasLockfile(rootDir);
+}
+/** True when the derivative ships a Drizzle schema directory. */
+export function hasSchemaDir(rootDir) {
+    return existsSync(join(rootDir, SCHEMA_DIR));
+}
+/** True when at least one generated `.sql` already lives in the migrations directory. */
+export function hasGeneratedMigrations(rootDir) {
+    const dir = join(rootDir, MIGRATIONS_DIR);
+    if (!existsSync(dir))
+        return false;
+    try {
+        return readdirSync(dir).some((entry) => entry.toLowerCase().endsWith(MIGRATION_SQL_EXT));
+    }
+    catch {
+        return false; // unreadable directory reads as "cannot confirm" → do not generate
+    }
+}
+/** Resolve the three facts from disk, ready for {@link needsInitialMigration}. */
+export function readMigrationFacts(rootDir) {
+    return {
+        hasSchema: hasSchemaDir(rootDir),
+        hasMigrations: hasGeneratedMigrations(rootDir),
+        isFactory: isFactoryCheckout(rootDir),
+    };
+}
+/**
+ * The es-MX narration per skip reason. Kept next to the reasons (and not inlined at the
+ * call site) so the copy is a named constant, never a magic string (CODING.md §5).
+ */
+export const MIGRATION_SKIP_MESSAGES = {
+    factory: 'No hay `.timekast/lockfile.json`: este checkout no se identifica como derivado ' +
+        '(podría ser el Factory) — omito la migración inicial.',
+    'no-schema': `No hay \`${SCHEMA_DIR}/\` en el repo — omito la migración inicial.`,
+    'has-migrations': `Ya hay migraciones en \`${MIGRATIONS_DIR}/\` — no genero otra.`,
+    'no-package-json': `No hay \`${PACKAGE_JSON_FILE}\` en el repo — omito la migración inicial.`,
+    'not-pnpm': 'El repo usa otro gestor de paquetes (no hay `pnpm-lock.yaml`) — omito la migración ' +
+        'inicial; genérala con el tooling del proyecto.',
+};
+/**
+ * Resolve {@link needsInitialMigration} plus the two tolerance edges the kit owes a
+ * divergent derivative (BR-FACTORY-006): no `package.json`, or a non-pnpm project. Both
+ * warn and continue — they never abort the provisioning.
+ *
+ * This does NOT evaluate the greenfield guard (whether the RUN creates birth
+ * infrastructure): that one reads the plan, not the disk, and lives with the plan.
+ */
+export function decideInitialMigration(rootDir) {
+    const facts = readMigrationFacts(rootDir);
+    if (facts.isFactory)
+        return { run: false, reason: 'factory' };
+    if (!facts.hasSchema)
+        return { run: false, reason: 'no-schema' };
+    if (facts.hasMigrations)
+        return { run: false, reason: 'has-migrations' };
+    if (!existsSync(join(rootDir, PACKAGE_JSON_FILE))) {
+        return { run: false, reason: 'no-package-json' };
+    }
+    const foreign = FOREIGN_LOCKFILES.some((lock) => existsSync(join(rootDir, lock)));
+    if (foreign && !existsSync(join(rootDir, PNPM_LOCKFILE))) {
+        return { run: false, reason: 'not-pnpm' };
+    }
+    return { run: true };
+}

package/dist/lib/neon-api.js

@@ -225,29 +225,60 @@ export async function getConnectionUri(apiKey, projectId, branchId, pooled, deps
     }
     return data.uri;
 }
+/** Page size for the project listing — Neon's documented maximum (`limit` ≤ 400). */
+const NEON_PROJECTS_PAGE_SIZE = 400;
+/** Hard stop on the pagination loop — 20 full pages is 8000 projects, far past any org. */
+const NEON_PROJECTS_MAX_PAGES = 20;
 /**
  * List the org's Neon projects — `GET /projects` (PROV-007 `--adopt`). STRICTLY
  * read-only: it never POSTs/PATCHes/DELETEs. The caller filters by slug/name to
  * reconstruct the adopted state and disambiguates when more than one matches
- * (issue §4). Neon paginates with `?limit=`; one page (default 100) covers the
- * org's project list for the adopt use case.
+ * (issue §4).
+ *
+ * Two things this endpoint does NOT forgive, both learned the hard way from an
+ * adopt that recorded `neonProjectId: unknown` on a project that plainly exists:
+ *
+ *   - `org_id` is REQUIRED for an org-scoped API key — the same requirement
+ *     {@link createNeonProject} already honors. Without it Neon answers `400
+ *     org_id is required`, so the adopt path had never once resolved a project.
+ *   - The default page size is 10. An org with a real fleet needs the FULL list,
+ *     or the answer to "does this project exist" is decided by how recently it
+ *     was touched. Pages are walked to exhaustion via `pagination.cursor`.
  *
  * @throws {NeonApiError} on any non-2xx (caller records the field as `unknown`).
  */
-export async function listNeonProjects(apiKey, deps = {}) {
+export async function listNeonProjects(apiKey, orgId, deps = {}) {
     const fetchImpl = deps.fetchImpl ?? fetch;
-    const response = await fetchImpl(`${NEON_API_BASE}/projects`, {
-        method: 'GET',
-        headers: neonHeaders(apiKey),
-        signal: AbortSignal.timeout(NEON_API_TIMEOUT_MS),
-    });
-    if (!response.ok) {
-        throw new NeonApiError(response.status, await safeBody(response), 'GET /projects');
+    const collected = [];
+    let cursor;
+    for (let page = 0; page < NEON_PROJECTS_MAX_PAGES; page += 1) {
+        const query = new URLSearchParams({ limit: String(NEON_PROJECTS_PAGE_SIZE) });
+        if (orgId)
+            query.set('org_id', orgId);
+        if (cursor)
+            query.set('cursor', cursor);
+        const response = await fetchImpl(`${NEON_API_BASE}/projects?${query.toString()}`, {
+            method: 'GET',
+            headers: neonHeaders(apiKey),
+            signal: AbortSignal.timeout(NEON_API_TIMEOUT_MS),
+        });
+        if (!response.ok) {
+            throw new NeonApiError(response.status, await safeBody(response), 'GET /projects');
+        }
+        const data = (await response.json());
+        const projects = data.projects ?? [];
+        for (const p of projects) {
+            if (p.id && p.name)
+                collected.push({ id: p.id, name: p.name });
+        }
+        // Neon returns a cursor even on the LAST page, so a short page — not a missing
+        // cursor — is what ends the walk; the cursor guard only catches a truncated body.
+        const next = data.pagination?.cursor;
+        if (projects.length < NEON_PROJECTS_PAGE_SIZE || !next || next === cursor)
+            break;
+        cursor = next;
     }
-    const data = (await response.json());
-    return (data.projects ?? [])
-        .filter((p) => Boolean(p.id) && Boolean(p.name))
-        .map((p) => ({ id: p.id, name: p.name }));
+    return collected;
 }
 /**
  * List a Neon project's branches — `GET /projects/{id}/branches` (PROV-007

package/dist/lib/retrofit-reminder.js

@@ -0,0 +1,228 @@
+/**
+ * The retrofit reminder printed at the tail of every applied `factory update`.
+ *
+ * WHY IT EXISTS. `update` refreshes the brain mechanically: it copies files, and when a file
+ * conflicts it asks and applies whichever side the dev picked. What it CANNOT do is the work
+ * that lives outside the tracked tree — a step to paste into a workflow the kit is not allowed
+ * to touch, a config the derivative owns, a decision only the project can make. Those ship as
+ * retrofit guides, and a guide nobody is told about is a guide nobody reads: the update ends
+ * "✔ actualizado", the dev moves on, and the half of the change that needed hands never lands.
+ *
+ * 🔴 PRINTED ON EVERY OUTCOME, unlike its sibling {@link printProvisionPointer}. `--theirs-all`,
+ * `--mine-all`, per-file choices, or no conflicts at all — the reminder does not depend on any
+ * of that, because a retrofit is not a conflict: it is work the update never attempted. And it
+ * is NOT suppressed headless. The pointer suppresses there to keep CI logs quiet; this one does
+ * the opposite, because the agent running the update unattended is precisely the reader who
+ * cannot notice a missing step on its own, and an agent reads the transcript it is handed.
+ *
+ * The list is read from disk AFTER the apply, so it reflects the guides that just arrived
+ * rather than a list baked into this binary that would drift from what the kit ships.
+ */
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** Where the kit ships its retrofit guides, inside the derivative. */
+export const RETROFITS_DIR = '.claude/docs/retrofits';
+/**
+ * The blockquote fields a guide uses to say who it is for, in the order they are tried.
+ *
+ * The corpus is heterogeneous by history — some guides lead with `Aplica si:`, older ones with
+ * `Para quién:` or `Audience:`. Rather than rewrite ten documents to satisfy a parser, the
+ * parser accepts what they already say, and a guide matching none of these is still LISTED,
+ * just without its one-liner. Silence about a guide would be the one failure that matters.
+ */
+const APPLICABILITY_FIELDS = [
+    'Aplica si:',
+    'Aplica a:',
+    'Para quién:',
+    'Para:',
+    'Audience:',
+    'Qué es:',
+    'Para quien:',
+];
+/** How much of the applicability line survives — enough to decide, short enough to scan. */
+const SUMMARY_MAX = 96;
+/**
+ * The field every guide declares: the first kit release that shipped it.
+ *
+ * Normalized across the corpus in v11.9 by asking git which release tag CONTAINS the commit
+ * that created each file (`git tag --contains`), rather than inferring it from dates. It is
+ * what lets the reminder separate "arrived in THIS update" from "was already here".
+ */
+const SHIPPED_SINCE_FIELD = 'Disponible desde:';
+/**
+ * Compare two dotted versions. Returns >0 when `a` is newer.
+ *
+ * Deliberately naive — no pre-release handling: these are kit release numbers, and a guide is
+ * never stamped with a beta. Non-numeric junk sorts as 0 rather than throwing, because a
+ * malformed field must degrade to "cannot tell", never break the reminder.
+ */
+export function compareVersions(a, b) {
+    const pa = a.split('.').map((n) => Number.parseInt(n, 10) || 0);
+    const pb = b.split('.').map((n) => Number.parseInt(n, 10) || 0);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const diff = (pa[i] ?? 0) - (pb[i] ?? 0);
+        if (diff !== 0)
+            return diff;
+    }
+    return 0;
+}
+/** Pull the `Disponible desde: kit vX.Y.Z` version out of a guide's header. */
+export function extractSince(markdown) {
+    for (const line of markdown.split('\n').slice(0, 20)) {
+        const at = line.indexOf(SHIPPED_SINCE_FIELD);
+        if (at === -1)
+            continue;
+        const match = line.slice(at).match(/v?(\d+\.\d+(?:\.\d+)?)/);
+        if (match)
+            return match[1];
+    }
+    return null;
+}
+/**
+ * Strip markdown emphasis and links down to the words, for a terminal line.
+ *
+ * 🔴 Only `**` and backticks come out. A lone `_` or `*` is left alone, because in this corpus
+ * both are punctuation of an IDENTIFIER far more often than emphasis: stripping them turned
+ * `NEXT_PUBLIC_AUTH_*` into `NEXTPUBLICAUTH` inside the very guide about that variable. Leaving
+ * a stray emphasis marker on screen is the cheaper mistake. These guides bold with `**`.
+ */
+function plainText(raw) {
+    return raw
+        .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1') // [text](link) → text
+        .replace(/\*\*/g, '') // bold — the only emphasis these headers use
+        .replace(/`/g, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+/**
+ * Pull the applicability one-liner out of a guide's header.
+ *
+ * Only the first lines are scanned: every guide states this in its opening blockquote, and
+ * reading further would start matching prose from the body.
+ */
+export function extractApplicability(markdown) {
+    const head = markdown.split('\n').slice(0, 12);
+    for (const field of APPLICABILITY_FIELDS) {
+        for (const line of head) {
+            const at = line.indexOf(field);
+            if (at === -1)
+                continue;
+            const text = plainText(line.slice(at + field.length));
+            if (!text)
+                continue;
+            return text.length > SUMMARY_MAX ? `${text.slice(0, SUMMARY_MAX - 1)}…` : text;
+        }
+    }
+    // The "Retrofit shipped (…) — aplica a X" shape of the older guides.
+    for (const line of head) {
+        const dash = line.match(/—\s*(aplica a .+)$/i);
+        if (dash) {
+            const text = plainText(dash[1]);
+            return text.length > SUMMARY_MAX ? `${text.slice(0, SUMMARY_MAX - 1)}…` : text;
+        }
+    }
+    return null;
+}
+/**
+ * The guides present in this checkout, alphabetical. An absent or empty directory yields `[]`
+ * — a `core`-profile derivative does not receive them, and it must not be told to read a
+ * directory it does not have.
+ */
+export function listRetrofits(rootDir, deps = {}) {
+    const readDir = deps.readDir ?? ((dir) => readdirSync(dir));
+    const readFile = deps.readFile ?? ((file) => readFileSync(file, 'utf8'));
+    let names;
+    try {
+        names = readDir(join(rootDir, RETROFITS_DIR));
+    }
+    catch {
+        return []; // no directory → nothing to remind about
+    }
+    return names
+        .filter((n) => n.endsWith('.md'))
+        .sort()
+        .map((name) => {
+        const path = `${RETROFITS_DIR}/${name}`;
+        let applies = null;
+        let since = null;
+        try {
+            const markdown = readFile(join(rootDir, RETROFITS_DIR, name));
+            applies = extractApplicability(markdown);
+            since = extractSince(markdown);
+        }
+        catch {
+            // unreadable → still listed, just bare
+        }
+        return { slug: name.replace(/\.md$/, ''), path, applies, since };
+    });
+}
+/**
+ * Split the guides into the ones this update just brought and the ones already there.
+ *
+ * `fromVersion` is the lockfile's version BEFORE the update. Without it — a first install, or
+ * a lockfile too old to say — everything lands in `carried`, which reads as "review them all"
+ * and is the honest answer: the reminder cannot know what you already saw.
+ *
+ * 🔴 A guide whose header states no version also lands in `carried`, NEVER in `arrived`. Both
+ * buckets are shown, so nothing is hidden either way; putting an unknown in `arrived` would
+ * cry wolf on every single update forever, which is how a notice trains people to skip it.
+ */
+export function splitByArrival(entries, fromVersion) {
+    if (!fromVersion)
+        return { arrived: [], carried: entries };
+    const arrived = entries.filter((e) => e.since && compareVersions(e.since, fromVersion) > 0);
+    const carried = entries.filter((e) => !arrived.includes(e));
+    return { arrived, carried };
+}
+/** Render the reminder, or `null` when this checkout ships no guides. */
+export function renderRetrofitReminder(entries, fromVersion = null) {
+    if (entries.length === 0)
+        return null;
+    const { arrived, carried } = splitByArrival(entries, fromVersion);
+    const rule = '═'.repeat(74);
+    const lines = [
+        '',
+        rule,
+        '  ⚠️   REVISA LAS GUÍAS DE RETROFIT ANTES DE DAR EL UPDATE POR TERMINADO',
+        rule,
+        '',
+        '  El update mueve archivos. Lo que NO puede mover es lo que vive fuera del árbol',
+        '  que el kit controla: un step en TU workflow, un config que es tuyo, una decisión',
+        '  que solo tu proyecto puede tomar. Eso viaja como guía, y NADA de esto se aplicó.',
+        '',
+    ];
+    const describe = (entry) => {
+        const out = [`  · ${entry.slug}`];
+        if (entry.applies)
+            out.push(`      ${entry.applies}`);
+        return out;
+    };
+    if (arrived.length > 0) {
+        lines.push(`  ▸ NUEVAS EN ESTE UPDATE (${arrived.length}) — empieza por aquí:`, '');
+        for (const entry of arrived)
+            lines.push(...describe(entry));
+        lines.push('');
+    }
+    if (carried.length > 0) {
+        // The heading changes with what we can claim: with no `fromVersion` there is no "already
+        // had", only "here they are".
+        lines.push(arrived.length > 0
+            ? `  ▸ Ya estaban (${carried.length}) — por si nunca las aplicaste:`
+            : `  ▸ Guías disponibles (${carried.length}):`, '');
+        for (const entry of carried)
+            lines.push(...describe(entry));
+        lines.push('');
+    }
+    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');
+}
+/**
+ * Print the reminder. Called on EVERY applied update — see the module header for why this one
+ * has no headless guard and no outcome condition.
+ */
+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);
+}

package/dist/lib/vercel-env.js

@@ -304,24 +304,113 @@ export async function removeVercelDomain(projectId, name, token, teamId, deps =
     }
 }
 /**
- * List the team's Vercel projects — `GET /v9/projects?teamId=&limit=20` (PROV-007
+ * Delete a Vercel PROJECT over REST, with the same token that created it.
+ *
+ * 🔴 Why REST and not the dev's `vercel remove`. The project is CREATED by
+ * {@link createVercelProject} with the rail token and a `teamId`, so it lives inside the
+ * team. `vercel remove` runs against whatever scope the dev's CLI session happens to be
+ * authenticated to — in a measured teardown that was a personal scope, so the delete failed
+ * with "Not authorized … under scope" and left a live project nobody was going to look for.
+ * Create and delete have to be able to reach the same place.
+ *
+ * This is not a widening of the rail token's blast radius, and it is not a new policy either:
+ * {@link removeVercelDomain}, called from the very same teardown, already deletes over REST
+ * with this token. The project delete was the outlier.
+ *
+ * Idempotency (same contract as its domain sibling): a 404 means it is already gone and
+ * resolves to `'absent'`, so a re-run after a partial teardown is a no-op.
+ *
+ * @throws {VercelApiError} on any non-2xx EXCEPT 404 (which → `'absent'`).
+ */
+export async function removeVercelProject(projectId, token, teamId, deps = {}) {
+    try {
+        await vercelApi('DELETE', `/v9/projects/${encodeURIComponent(projectId)}`, token, teamId, deps);
+        return 'removed';
+    }
+    catch (error) {
+        if (error instanceof VercelApiError && error.status === 404) {
+            return 'absent';
+        }
+        throw error;
+    }
+}
+/** Page size for the project listing — Vercel's documented maximum (`limit` ≤ 100). */
+const VERCEL_PROJECTS_PAGE_SIZE = 100;
+/** Hard stop on the pagination loop — 20 full pages is 2000 projects, far past any team. */
+const VERCEL_PROJECTS_MAX_PAGES = 20;
+/**
+ * Look up ONE Vercel project by name — `GET /v9/projects/{idOrName}` (PROV-007
+ * `--adopt`). Vercel accepts the project NAME in that path slot, which is the
+ * cheap exact answer to "is there a project called `{slug}`": one request, no
+ * pagination, no substring heuristic. Returns `null` on a 404 (no such project)
+ * so the caller can fall back to the fuzzy listing below.
+ *
+ * @throws {VercelApiError} on any non-2xx OTHER than 404 (401/403 must not be
+ *   read as "absent" — a bad token is a different fact from a missing project).
+ */
+export async function getVercelProjectByName(name, token, teamId, deps = {}) {
+    try {
+        const data = (await vercelApi('GET', `/v9/projects/${encodeURIComponent(name)}`, token, teamId, deps));
+        return data.id && data.name ? { id: data.id, name: data.name } : null;
+    }
+    catch (error) {
+        if (error instanceof VercelApiError && error.status === 404)
+            return null;
+        throw error;
+    }
+}
+/**
+ * List the team's Vercel projects — `GET /v9/projects?teamId=` (PROV-007
  * `--adopt`). STRICTLY read-only: it never POSTs/PATCHes/DELETEs anything. The
  * caller filters the returned summaries by slug/name to reconstruct the adopted
  * state; an exact-name match is preferred, but every project name that CONTAINS
  * the slug is returned as a candidate so the caller can disambiguate (issue §4).
  *
- * `limit` is threaded as a query param (default 20 — issue §6); `teamId` flows
- * through {@link vercelUrl} like every other call. Used by `--adopt` only.
+ * Pages are walked to exhaustion (`pagination.next` → `until`). It used to take
+ * the first 20 and stop, which on a real team meant the listing answered "are you
+ * among the 20 most recently touched projects", not "do you exist" — a project
+ * further down was recorded `unknown` with no way to tell that from absent.
  *
  * @throws {VercelApiError} on any non-2xx (caller maps it / records `unknown`).
  */
-export async function listVercelProjects(token, teamId, deps = {}, limit = 20) {
-    const data = (await vercelApi('GET', '/v9/projects', token, teamId, deps, undefined, {
-        limit: String(limit),
-    }));
-    return (data.projects ?? [])
-        .filter((p) => Boolean(p.id) && Boolean(p.name))
-        .map((p) => ({ id: p.id, name: p.name }));
+export async function listVercelProjects(token, teamId, deps = {}) {
+    const collected = [];
+    let until;
+    for (let page = 0; page < VERCEL_PROJECTS_MAX_PAGES; page += 1) {
+        const query = { limit: String(VERCEL_PROJECTS_PAGE_SIZE) };
+        if (until !== undefined)
+            query.until = String(until);
+        const data = (await vercelApi('GET', '/v9/projects', token, teamId, deps, undefined, query));
+        for (const p of data.projects ?? []) {
+            if (p.id && p.name)
+                collected.push({ id: p.id, name: p.name });
+        }
+        const next = data.pagination?.next;
+        if (next === undefined || next === null || next === until)
+            break;
+        until = next;
+    }
+    return collected;
+}
+/**
+ * Apex of the hosts Vercel mints on its own (`{project}.vercel.app`). Nobody
+ * created these and nobody can delete them, so they are the LAST choice when
+ * reconstructing a project's domains and are skipped by the teardown.
+ */
+export const VERCEL_AUTO_APEX = 'vercel.app';
+/**
+ * List the domains attached to a Vercel project — `GET /v9/projects/{id}/domains`
+ * (PROV-007 `--adopt`). STRICTLY read-only. This is the authority on where a
+ * derived app actually answers: a project on a client's own domain has no CNAME
+ * in any org zone, so DNS alone cannot reconstruct its hosts.
+ *
+ * @throws {VercelApiError} on any non-2xx (caller degrades, never fails the adopt).
+ */
+export async function listProjectDomains(projectId, token, teamId, deps = {}) {
+    const data = (await vercelApi('GET', `/v9/projects/${encodeURIComponent(projectId)}/domains`, token, teamId, deps));
+    return (data.domains ?? [])
+        .filter((d) => Boolean(d.name))
+        .map((d) => ({ name: d.name, apexName: d.apexName ?? '', gitBranch: d.gitBranch ?? null }));
 }
 /**
  * List the project's existing env vars (issue §8 idempotency: we PATCH a var that

package/package.json

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