@timekast/factory 1.12.0 → 1.14.2

package/dist/lib/provision-state.js

@@ -0,0 +1,385 @@
+/**
+ * Atomic state model for `factory provision` (PROV-001).
+ *
+ * `provision` creates external resources one at a time (Neon project, Vercel
+ * project, GitHub repo, DNS). After EACH successful create it persists the new
+ * provider id into `.timekast/provision.json` so the run is resumable: if a later
+ * step fails (or the process is killed), `--resume` re-reads this file and skips
+ * the steps already recorded. The state is COMMITTED to the repo (it holds
+ * provider IDs + scope + lifecycle — NEVER secret values, NEVER a connection
+ * string with embedded `user:password`), so a teammate or the `--destroy` flow
+ * (PROV-008) can act on the exact resources that were created. The DB connection
+ * strings are NEVER persisted anywhere — the consumers (env sync, migrate secrets,
+ * `.env.local`) re-derive them fresh from Neon on demand (`resolveNeonSecrets` in
+ * `provision.ts`), using the branch ids below + the rail `NEON_API_KEY`. Neon is the
+ * single source of truth for credentials.
+ *
+ * Atomicity contract (issue §8 — "Interrupción durante escritura atómica"):
+ * every write goes to a sibling temp file first, then `renameSync` swaps it into
+ * place. `rename(2)` is atomic on the same filesystem, so a process killed
+ * mid-write leaves the PREVIOUS `provision.json` fully intact — never a truncated
+ * half-written JSON. This mirrors the backup-and-swap discipline of
+ * `atomic-swap.ts` (which the `update` engine uses), scoped down to a single
+ * single-file document.
+ *
+ * Robustness (issue §8 — "`.timekast/provision.json` corrupto"): the reader
+ * tolerates a missing OR corrupt file. A missing file → `null` (nothing to
+ * resume). A corrupt file → a typed `CLIError` that points the dev at `--force`
+ * (which discards the bad state and starts over), never a raw `JSON.parse` stack
+ * trace.
+ *
+ * Pure + FS-light: `rootDir` is always explicit so the unit tests drive every
+ * branch against a temp dir — no real `.timekast/` and no cwd coupling.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { CLIError } from './cli-error.js';
+import { provisionDomains } from './cloudflare-api.js';
+import { TIMEKAST_DIR } from './constants.js';
+/**
+ * Directory (repo-root relative) the provision state lives in. This is the SAME
+ * `.timekast/` dir the update lockfile uses, so ALL Factory CLI metadata sits in
+ * ONE place instead of scattered across folders. COMMITTED — see `.gitignore`
+ * (provision.json committed; the `*.local.json` rule is kept as a defensive guard so
+ * any credentials file dropped here can never be tracked — provision writes none).
+ */
+export const PROVISION_DIR = TIMEKAST_DIR;
+/** Filename of the provision state document inside {@link PROVISION_DIR}. */
+export const PROVISION_STATE_FILE = 'provision.json';
+/** Absolute path to the provision state file under a repo root. */
+export function provisionStatePath(rootDir) {
+    return path.join(rootDir, PROVISION_DIR, PROVISION_STATE_FILE);
+}
+/** True when a provision state file already exists (a run is in progress / done). */
+export function hasProvisionState(rootDir) {
+    return existsSync(provisionStatePath(rootDir));
+}
+/**
+ * Validate the structural shape of a parsed state object. Returns the typed
+ * state on success, or `null` when the shape is wrong (the caller turns that into
+ * a corrupt-state error). Keeps the JSON-parse and the shape-check separate so
+ * the reader can distinguish "not JSON" from "JSON but wrong shape" — both are
+ * "corrupt" to the dev, but the distinction keeps the validator pure/testable.
+ */
+function asProvisionState(parsed) {
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+        return null;
+    const obj = parsed;
+    if (typeof obj.projectName !== 'string' || obj.projectName === '')
+        return null;
+    if (obj.lifecycle !== 'ephemeral' && obj.lifecycle !== 'live')
+        return null;
+    if (typeof obj.scope !== 'string')
+        return null;
+    if (typeof obj.createdAt !== 'string')
+        return null;
+    return obj;
+}
+/**
+ * Read the provision state, tolerating absence and corruption (issue §8).
+ *
+ *   - file absent          → `null` (nothing to resume — a fresh run)
+ *   - file present + valid  → the typed {@link ProvisionState}
+ *   - file present + broken → `CLIError` pointing at `--force` to start over
+ *
+ * "Broken" covers an unreadable file (perms/race), non-JSON content, and
+ * JSON-of-the-wrong-shape. Never throws a raw `JSON.parse` error.
+ *
+ * @throws {CLIError} when the file exists but cannot be parsed into a valid state.
+ */
+export function readProvisionState(rootDir) {
+    const file = provisionStatePath(rootDir);
+    if (!existsSync(file))
+        return null;
+    let text;
+    try {
+        text = readFileSync(file, 'utf8');
+    }
+    catch {
+        throw new CLIError(`No se pudo leer el estado de provision (\`${PROVISION_DIR}/${PROVISION_STATE_FILE}\`). ` +
+            'Si está dañado, vuelve a correr con `--force` para descartarlo y empezar de cero.');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new CLIError(`El estado de provision (\`${PROVISION_DIR}/${PROVISION_STATE_FILE}\`) está corrupto (JSON inválido). ` +
+            'Vuelve a correr con `--force` para descartarlo y empezar de cero.');
+    }
+    const state = asProvisionState(parsed);
+    if (!state) {
+        throw new CLIError(`El estado de provision (\`${PROVISION_DIR}/${PROVISION_STATE_FILE}\`) tiene una estructura inesperada. ` +
+            'Vuelve a correr con `--force` para descartarlo y empezar de cero.');
+    }
+    return state;
+}
+/**
+ * Persist the provision state ATOMICALLY (issue §6 + §8).
+ *
+ * Ensures `.timekast/` exists (`mkdir -p` before the first write — issue §8 edge
+ * case), writes the JSON to a sibling temp file, then `renameSync`s it over the
+ * target. The rename is atomic on the same filesystem, so an interruption mid-
+ * write leaves the previous `provision.json` intact (or no file at all on the
+ * very first write) — never a truncated document.
+ *
+ * Call this AFTER each individual provider create succeeds, so the freshly-
+ * created resource's id is durable before the next (riskier) step runs.
+ */
+export function writeProvisionState(rootDir, state) {
+    const dir = path.join(rootDir, PROVISION_DIR);
+    mkdirSync(dir, { recursive: true });
+    const target = provisionStatePath(rootDir);
+    const tmp = path.join(dir, `.${PROVISION_STATE_FILE}.tmp`);
+    const body = `${JSON.stringify(state, null, 2)}\n`;
+    try {
+        writeFileSync(tmp, body, 'utf8');
+        renameSync(tmp, target);
+    }
+    catch (error) {
+        // Best-effort cleanup of the temp file so a failed swap leaves no litter.
+        rmSync(tmp, { force: true });
+        throw new CLIError(`No se pudo escribir el estado de provision (\`${PROVISION_DIR}/${PROVISION_STATE_FILE}\`): ` +
+            `${error?.message ?? 'error desconocido'}.`);
+    }
+}
+/**
+ * Discard the provision state (the `--force` path). Best-effort: a missing file
+ * is a no-op, so `--force` is safe to pass on a fresh run.
+ */
+export function clearProvisionState(rootDir) {
+    rmSync(provisionStatePath(rootDir), { force: true });
+}
+/**
+ * Delete `.timekast/provision.json` AFTER a successful `--destroy` teardown
+ * (PROV-008 §4). Distinct in INTENT from {@link clearProvisionState} (the
+ * `--force` "start over" path) though it removes the same file: `--destroy` calls
+ * this ONLY once every provider teardown completed without leaving a recorded
+ * resource behind, so the state file is never removed while a half-destroyed stack
+ * still has live resources to act on. Best-effort delete (a missing file is a
+ * no-op), so a re-run after a manual delete is safe.
+ */
+export function clearState(rootDir) {
+    rmSync(provisionStatePath(rootDir), { force: true });
+}
+/**
+ * The "unknown" sentinel a `--adopt` field carries when a provider could not be
+ * read (no token / no access / no response — issue §4). It is a STRING (not
+ * `undefined`/absent) so the persisted state explicitly records "we looked and
+ * could not resolve this", distinct from "this provider was not queried". A later
+ * `factory provision --adopt --force` (once the token is available) overwrites it.
+ */
+export const ADOPT_UNKNOWN = 'unknown';
+/**
+ * Persist a `--adopt`-reconstructed state ATOMICALLY (PROV-007 §6). Merges the
+ * partial provider fields the adopt resolved over a fully-`unknown` baseline (so
+ * a provider that was skipped/failed is recorded as {@link ADOPT_UNKNOWN}, never
+ * left absent), stamps `lifecycle: 'live'` + `adoptedAt`, and writes it through
+ * the SAME temp-file + `renameSync` swap as {@link writeProvisionState}.
+ *
+ * Overwrite guard (issue §4): if a state file already exists this throws a clear
+ * `CLIError` UNLESS `options.force` is set — the adopt must not silently clobber a
+ * normally-provisioned project's state. (`runAdopt` checks existence up-front for
+ * a friendlier message; this is the durable last-line guard.)
+ *
+ * Pure-ish + FS-light: `rootDir` and the clock (`now`) are explicit so the unit
+ * test drives every branch against a temp dir with a fixed timestamp.
+ *
+ * @throws {CLIError} when a state file already exists and `force` is not set.
+ */
+export function adoptState(rootDir, partial, options = {}) {
+    if (hasProvisionState(rootDir) && !options.force) {
+        throw new CLIError(`Ya existe un estado de provision (\`${PROVISION_DIR}/${PROVISION_STATE_FILE}\`). ` +
+            'Usa `--force` para sobrescribirlo con el resultado del adopt, o bórralo si reutilizas este directorio.');
+    }
+    const slug = partial.slug ?? ADOPT_UNKNOWN;
+    const now = options.now ?? (() => new Date());
+    const state = {
+        lifecycle: 'live',
+        slug,
+        vercelProjectId: partial.vercelProjectId ?? ADOPT_UNKNOWN,
+        neonProjectId: partial.neonProjectId ?? ADOPT_UNKNOWN,
+        neonBranchDevId: partial.neonBranchDevId ?? ADOPT_UNKNOWN,
+        githubRepo: partial.githubRepo ?? ADOPT_UNKNOWN,
+        domains: partial.domains ?? { dev: ADOPT_UNKNOWN, prod: ADOPT_UNKNOWN },
+        adoptedAt: now().toISOString(),
+    };
+    const dir = path.join(rootDir, PROVISION_DIR);
+    mkdirSync(dir, { recursive: true });
+    const target = provisionStatePath(rootDir);
+    const tmp = path.join(dir, `.${PROVISION_STATE_FILE}.tmp`);
+    const body = `${JSON.stringify(state, null, 2)}\n`;
+    try {
+        writeFileSync(tmp, body, 'utf8');
+        renameSync(tmp, target);
+    }
+    catch (error) {
+        rmSync(tmp, { force: true });
+        throw new CLIError(`No se pudo escribir el estado de adopt (\`${PROVISION_DIR}/${PROVISION_STATE_FILE}\`): ` +
+            `${error?.message ?? 'error desconocido'}.`);
+    }
+    return state;
+}
+/**
+ * True when `service`'s create step is already recorded in `state` — the check
+ * `--resume` uses to skip a completed step. A `null` state (no prior run) means
+ * nothing is complete.
+ */
+export function isServiceComplete(state, service) {
+    if (!state)
+        return false;
+    switch (service) {
+        case 'neon':
+            // Neon is complete only when the FINAL step landed (key minted + stored as
+            // the GitHub Secret). developBranchId alone is NOT done — the steps after it
+            // (connection strings, API key, secret) must still run, and re-minting the
+            // key would orphan a duplicate. A partial run resumes from where it stopped.
+            return state.neon?.apiKeySecretDone === true;
+        case 'vercel':
+            // Complete only when the env sync landed — NOT on the mere presence of
+            // state.vercel (the github step writes `projectId` before the vercel step
+            // runs, so that alone would wrongly skip the env push).
+            return state.vercel?.envSynced === true;
+        case 'github':
+            // Complete only when the whole step finished — NOT on the mere presence of
+            // state.github (its `repo` is recorded at the START of the step, so a step
+            // that failed mid-way would be wrongly skipped on resume).
+            return state.github?.done === true;
+        case 'dns':
+            return state.dns !== undefined;
+        default:
+            return false;
+    }
+}
+/** Coerce a persisted field to a real id, mapping the `unknown` sentinel + empties to `null`. */
+function realId(value) {
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim();
+    if (trimmed === '' || trimmed === ADOPT_UNKNOWN)
+        return null;
+    return trimmed;
+}
+/**
+ * `owner/repo` shape gate for a `githubRepo` field read from the LOW-TRUST state
+ * file (the file is committed, but a teammate/attacker could edit it). A
+ * malformed value (wrong shape, or a leading `-` that could smuggle a flag into
+ * `gh repo delete`) → `null` (skip), never passed to a command. Mirrors the
+ * runtime re-validation in `runDestroy` so the corruption is dropped at the
+ * read boundary too (FIX 3 — validate the shape, don't act on garbage).
+ */
+const GITHUB_REPO_RE = /^[A-Za-z0-9_.][A-Za-z0-9_.-]*\/[A-Za-z0-9_.][A-Za-z0-9_.-]*$/;
+/** Coerce a persisted `githubRepo` to a valid `owner/repo`, else `null` (skip). */
+function realRepo(value) {
+    const id = realId(value);
+    if (id === null)
+        return null;
+    // Reject any segment starting with `-` (anti flag-smuggling) + enforce owner/repo.
+    if (id.startsWith('-') || !GITHUB_REPO_RE.test(id))
+        return null;
+    return id;
+}
+/**
+ * Coerce a persisted domain to a safe DNS host, else `null` (skip). A domain
+ * read from the low-trust state file that starts with `-` (flag smuggling) or
+ * carries characters outside the DNS host alphabet is dropped, never acted on.
+ */
+const DOMAIN_RE = /^[A-Za-z0-9]([A-Za-z0-9.-]*[A-Za-z0-9])?$/;
+function realDomain(value) {
+    const id = realId(value);
+    if (id === null)
+        return null;
+    if (id.startsWith('-') || !DOMAIN_RE.test(id))
+        return null;
+    return id;
+}
+/** True when a parsed object looks like the flat {@link AdoptedState} (adopt backfill). */
+function isAdoptedShape(obj) {
+    // The adopt shape uses `slug` + `vercelProjectId` (flat); the step shape uses
+    // `projectName` + nested `vercel.projectId`. `slug` present = adopt.
+    return typeof obj.slug === 'string';
+}
+/**
+ * Read the provision state file as a {@link DestroyTarget}, tolerating BOTH the
+ * step-by-step {@link ProvisionState} and the flat {@link AdoptedState} shapes
+ * (PROV-008 §4). Returns `null` when no state file exists (the caller turns that
+ * into the "run `--adopt` first" error). A present-but-unparsable file throws a
+ * typed {@link CLIError} (never a raw `JSON.parse` trace).
+ *
+ * This is the ONE authority `--destroy` reads: the `lifecycle` it carries is the
+ * single guard between an auto-nuke (`ephemeral`) and a refusal (`live`), with no
+ * `version` sub-check.
+ *
+ * @throws {CLIError} when the file exists but cannot be parsed into a known shape.
+ */
+export function readDestroyTarget(rootDir) {
+    const file = provisionStatePath(rootDir);
+    if (!existsSync(file))
+        return null;
+    let text;
+    try {
+        text = readFileSync(file, 'utf8');
+    }
+    catch {
+        throw new CLIError(`No se pudo leer el estado de provision (\`${PROVISION_DIR}/${PROVISION_STATE_FILE}\`). ` +
+            'Si está dañado, bórralo o reconstrúyelo con `--adopt`.');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new CLIError(`El estado de provision (\`${PROVISION_DIR}/${PROVISION_STATE_FILE}\`) está corrupto (JSON inválido). ` +
+            'Bórralo o reconstrúyelo con `--adopt`.');
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new CLIError(`El estado de provision (\`${PROVISION_DIR}/${PROVISION_STATE_FILE}\`) tiene una estructura inesperada. ` +
+            'Bórralo o reconstrúyelo con `--adopt`.');
+    }
+    const obj = parsed;
+    if (isAdoptedShape(obj)) {
+        const adopted = obj;
+        const domains = [realDomain(adopted.domains?.dev), realDomain(adopted.domains?.prod)].filter((d) => d !== null);
+        return {
+            slug: typeof adopted.slug === 'string' ? adopted.slug : '',
+            lifecycle: adopted.lifecycle === 'live' ? 'live' : 'live', // adopt is always live
+            scope: null, // the adopt shape does not persist the team scope
+            neonProjectId: realId(adopted.neonProjectId),
+            neonBranchDevId: realId(adopted.neonBranchDevId),
+            vercelProjectId: realId(adopted.vercelProjectId),
+            githubRepo: realRepo(adopted.githubRepo),
+            domains,
+        };
+    }
+    // Step-by-step ProvisionState shape.
+    const step = obj;
+    if (typeof step.projectName !== 'string' || step.projectName === '') {
+        throw new CLIError(`El estado de provision (\`${PROVISION_DIR}/${PROVISION_STATE_FILE}\`) no tiene un \`projectName\`/\`slug\` válido. ` +
+            'Bórralo o reconstrúyelo con `--adopt`.');
+    }
+    const lifecycle = step.lifecycle === 'ephemeral' ? 'ephemeral' : 'live';
+    // The `dns` block now records the interim DEV domain (`{slug}-dev.timekast.mx`)
+    // alongside prod, but it stays derivable from the slug. Prefer the persisted value
+    // and fall back to deriving it (state files written before `devDomain` existed) so
+    // `--destroy` tears down the dev CNAME instead of orphaning it. Gated on `dns` being
+    // present (no DNS step → no dev domain to remove); passed through the same
+    // `realDomain` shape guard as every other low-trust domain field.
+    const devDomain = step.dns
+        ? realDomain(step.dns.devDomain ?? provisionDomains(step.projectName).dev)
+        : null;
+    const domains = [
+        realDomain(step.dns?.domain),
+        devDomain,
+        realDomain(step.dns?.clientDomain),
+    ].filter((d) => d !== null);
+    return {
+        slug: step.projectName,
+        lifecycle,
+        scope: realId(step.scope),
+        neonProjectId: realId(step.neon?.projectId),
+        neonBranchDevId: realId(step.neon?.developBranchId),
+        vercelProjectId: realId(step.vercel?.projectId),
+        githubRepo: realRepo(step.github?.repo),
+        domains,
+    };
+}

package/dist/lib/unpack.js

@@ -23,9 +23,9 @@ import { compare } from './semver.js';
 /** Download the profile tarball into `tmpDir`; returns the tarball path. */
 export async function downloadProfileTarball(profile, tmpDir) {
     // List releases and resolve the latest KIT release by tag, then download BY TAG.
-    // We do NOT let `gh` resolve repo-wide "latest": the repo also hosts the launcher
-    // release line (`launcher-v*`), whose assets are not kit tarballs, so "latest"
-    // can point at a launcher release. Filtering to `v*` keeps the kit line isolated.
+    // We do NOT let `gh` resolve repo-wide "latest": the repo also hosts the GUI
+    // launcher release line (`gui-v*`), whose assets are installers, not kit tarballs,
+    // so "latest" can point at a launcher release. Filtering to `v*` isolates the kit.
     const { stdout } = await execa('gh', [
         'release',
         'list',
@@ -104,18 +104,19 @@ export function resolveLatestBeta(releases) {
 }
 /**
  * True when a release tag belongs to the KIT's release line (`v<semver>`, e.g.
- * `v10.9.0`). The same repo hosts the launcher line (`launcher-v*`) and — via npm,
- * not GitHub Releases — the CLI line (`cli-v*`); neither starts with `v<digit>`,
- * so this predicate isolates the kit from every other release line in the repo.
- * Without it, `gh`'s repo-wide "latest" / a non-prerelease `launcher-v*` could be
- * mistaken for the latest kit version and break `status` / `update`.
+ * `v10.9.0`). The same repo hosts the GUI launcher line (`gui-v*`, Electron app
+ * GitHub Releases) and — via npm, not GitHub Releases — the CLI line (`cli-v*`);
+ * neither starts with `v<digit>`, so this predicate isolates the kit from every
+ * other release line in the repo. Without it, `gh`'s repo-wide "latest" / a
+ * non-prerelease `gui-v*` could be mistaken for the latest kit version and break
+ * `status` / `update`.
  */
 export function isKitReleaseTag(tagName) {
     return /^v\d/.test(tagName);
 }
 /**
  * Pick the latest STABLE kit release from a list: filter to kit tags (excluding
- * `launcher-v*` / any non-kit line) AND non-prerelease, then the highest by semver.
+ * `gui-v*` / any non-kit line) AND non-prerelease, then the highest by semver.
  * Returns null when no stable kit release exists.
  */
 export function resolveLatestKitRelease(releases) {

package/dist/lib/validate-name.js

@@ -13,7 +13,12 @@ const VALID_NAME = /^[A-Za-z0-9._-]+$/;
 const FORMAT_HINT = 'El nombre solo puede contener letras, números, guiones (-), guiones bajos (_) y puntos (.), ' +
     'sin espacios, y no puede empezar con `-` ni `.`.';
 /**
- * Validate a project name. Returns the trimmed name on success.
+ * Validate a project name. Returns the trimmed, LOWERCASED name on success — every
+ * derived resource (local dir, GitHub repo, `package.json.name`, the `{slug}` /
+ * `{slug}-dev` provision subdomains) must be lowercase, so this is the single
+ * chokepoint that normalizes it. GitHub repo names and DNS labels are
+ * case-insensitive, and `provision` rejects an uppercase slug outright — creating
+ * the repo lowercase here keeps `new` and `provision` from disagreeing on casing.
  * @throws {CLIError} with the allowed-format hint on any invalid input.
  */
 export function validateProjectName(raw) {
@@ -30,5 +35,5 @@ export function validateProjectName(raw) {
     if (!VALID_NAME.test(name)) {
         throw new CLIError(`Nombre inválido: \`${name}\` contiene caracteres no permitidos.\n${FORMAT_HINT}`);
     }
-    return name;
+    return name.toLowerCase();
 }