@timekast/factory 1.18.0 → 1.20.0

package/dist/lib/env-wizard.js

@@ -41,6 +41,12 @@ const DIVIDER = /^#\s*-{3,}\s*$/;
 const ACTIVE = /^([A-Z][A-Z0-9_]*)=(.*)$/;
 const COMMENTED = /^#\s*([A-Z][A-Z0-9_]*)=(.*)$/;
 const SECRET_KEY = /(_SECRET|_KEY|_TOKEN|_PASSWORD)$/;
+/**
+ * `NEXT_PUBLIC_*` vars are public by Next.js convention — they're inlined into
+ * the client bundle, so they can never be secrets regardless of their suffix
+ * (e.g. NEXT_PUBLIC_AUTH_PASSWORD is a boolean feature flag, not a credential).
+ */
+const PUBLIC_PREFIX = /^NEXT_PUBLIC_/;
 function unquote(raw) {
     const v = raw.trim();
     if (v.length >= 2 &&
@@ -104,10 +110,16 @@ export function parseEnvExample(text) {
     }
     return entries;
 }
-function questionKind(key, defaultValue) {
+/**
+ * Classify a var into the widget the wizard renders. Secret detection delegates
+ * to `isSecretKey` so classification, masking and review all share one rule
+ * (secret suffix AND not `NEXT_PUBLIC_*` — public-by-convention vars are never
+ * secrets, e.g. NEXT_PUBLIC_AUTH_PASSWORD="true" is a boolean flag).
+ */
+export function questionKind(key, defaultValue) {
     if (SELECTS[key])
         return 'select';
-    if (SECRET_KEY.test(key))
+    if (isSecretKey(key))
         return 'secret';
     if (defaultValue === 'true' || defaultValue === 'false')
         return 'boolean';
@@ -189,9 +201,13 @@ export function applyWizardAnswers(rootDir, answers) {
 // secret values, (c) auto-generate what a dev can't type, and (d) catch broken
 // setups (a provider flag on with empty creds). All pure over their inputs.
 // ─────────────────────────────────────────────────────────────────────────────
-/** True when `key`'s value is a secret (never printed in review/summary output). */
+/**
+ * True when `key`'s value is a secret (never printed in review/summary output).
+ * `NEXT_PUBLIC_*` keys are excluded: Next.js inlines them into the client bundle,
+ * so they're public by convention even when their suffix looks secret-ish.
+ */
 export function isSecretKey(key) {
-    return SECRET_KEY.test(key);
+    return !PUBLIC_PREFIX.test(key) && SECRET_KEY.test(key);
 }
 /** Parse an env-file body into `{ KEY: value }` (unquoted), skipping comments/blanks. */
 export function parseEnvBody(body) {
@@ -247,8 +263,12 @@ const OAUTH_PROVIDERS = [
 ];
 /**
  * Warn (do NOT block) about half-configured setups that would ship a broken app:
- * an OAuth provider enabled with empty creds → broken login button; notifications
- * enabled with no VAPID keys → dead push. Pure over the resolved env map.
+ * an OAuth flag on with missing creds → `next build` FAILS (BOOT-005: auth.ts
+ * resolves the provider credentials at module load, i.e. during the build — a
+ * deploy that never ships on derivatives whose frozen src/ predates the auth.ts
+ * guard); notifications enabled with no VAPID keys → dead push. Pure over the
+ * resolved env map. Warn-never-block by contract (headless-safe): the wizard
+ * stays pure + non-interactive, so escalation is message-only.
  */
 export function checkEnvCompleteness(env) {
     const warnings = [];
@@ -257,8 +277,10 @@ export function checkEnvCompleteness(env) {
             continue;
         const missing = [p.id, p.secret].filter((k) => !env[k]);
         if (missing.length) {
-            warnings.push(`Login con ${p.label} activado pero falta ${missing.join(' + ')} → el botón de login ` +
-                `quedará roto. Complétalas o pon ${p.flag}="false".`);
+            warnings.push(`Login con ${p.label} activado pero falta ${missing.join(' + ')} → EL BUILD FALLARÁ ` +
+                `mientras ${p.flag} quede en "true" sin credenciales (next build resuelve las ` +
+                `credenciales del provider al compilar — el deploy nunca sale). ` +
+                `Complétalas o pon ${p.flag}="false".`);
         }
     }
     if (env['NEXT_PUBLIC_NOTIFICATIONS_ENABLED'] === 'true' &&

package/dist/lib/package-json.js

@@ -8,7 +8,7 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { CLIError } from './cli-error.js';
-import { FACTORY_SCRIPTS, GENERATE_REFERENCE_CMD, GENERATE_REFERENCE_GATE_FILE, GENERATE_REFERENCE_NAME, GENERATOR_SCRIPTS, INVITE_ADMIN_SCRIPT_CMD, INVITE_ADMIN_SCRIPT_FILE, INVITE_ADMIN_SCRIPT_NAME, OBSOLETE_SCRIPT_CMDS, PREFLIGHT_SCRIPT_CMD, PREFLIGHT_SCRIPT_FILE, PREFLIGHT_SCRIPT_NAME, PROFILES, UPDATE_SCRIPT_NAME, } from './constants.js';
+import { FACTORY_SCRIPTS, GENERATE_REFERENCE_CMD, GENERATE_REFERENCE_GATE_FILE, GENERATE_REFERENCE_NAME, GENERATOR_SCRIPTS, INVITE_ADMIN_SCRIPT_CMD, INVITE_ADMIN_SCRIPT_FILE, INVITE_ADMIN_SCRIPT_NAME, OBSOLETE_SCRIPT_CMDS, PORTS_E2E_COMMENT, PORTS_E2E_COMMENT_KEY, PORTS_E2E_KEY, PORTS_KEY, PREFLIGHT_SCRIPT_CMD, PREFLIGHT_SCRIPT_FILE, PREFLIGHT_SCRIPT_NAME, PROFILES, SHIPPED_E2E_PORT, UPDATE_SCRIPT_NAME, } from './constants.js';
 /**
  * Auto-detect the profile to install into an existing repo from its
  * `package.json`: a `factoryVersion` field means the repo was born from the
@@ -197,6 +197,64 @@ export function insertFactoryUpdateScript(pkgPath) {
     }
     return primary;
 }
+/**
+ * Retire the E2E port the kit used to ship in a derivative's `package.json`: KEEP the key,
+ * EMPTY the value (`"e2e": null`), and add the `//e2e` sibling that explains why.
+ *
+ * WHY EMPTY RATHER THAN DELETE. `null` is a signal the e2e runner reads: with the key
+ * present and empty it derives a port from the checkout's absolute path, so two worktrees of
+ * one repo can run their suites at the same time. Deleting the key would say something
+ * different — "this project never had one" — which is the state that keeps a project on the
+ * runner's hardcoded fallback. So the key is the contract; only the value retires.
+ *
+ * WHY ONLY EXACTLY `3006`. Same discipline as `ensureFactoryScripts`: a KNOWN-OBSOLETE kit
+ * value is healed, a divergent one is never touched. A dev who pinned `4100` on purpose
+ * keeps `4100` through every future `factory update`; anything that is not the shipped
+ * number — including a `null` already written by an earlier update — is left alone, which is
+ * also what makes this idempotent (a second run writes nothing and cannot duplicate the
+ * comment).
+ *
+ * Surgical like the rest of this module: reads, mutates only inside `ports`, re-serializes
+ * with the original indentation + trailing newline, and writes ONLY on a real change. Key
+ * order inside `ports` is preserved and the comment is inserted immediately BEFORE `e2e`, so
+ * what a derivative sees in `git diff` is two lines: the emptied value and its explanation.
+ *
+ * @param pkgPath Absolute path to the derived project's `package.json`.
+ */
+export function emptyShippedE2EPort(pkgPath) {
+    const raw = readFileSync(pkgPath, 'utf8');
+    const indent = detectIndent(raw);
+    const pkg = parsePackageJson(raw);
+    const ports = pkg[PORTS_KEY];
+    if (typeof ports !== 'object' || ports === null || Array.isArray(ports))
+        return 'absent';
+    const block = ports;
+    const current = block[PORTS_E2E_KEY];
+    if (current === undefined)
+        return 'absent';
+    if (current === null)
+        return 'already-empty';
+    if (current !== SHIPPED_E2E_PORT)
+        return 'preserved';
+    // Rebuilt rather than assigned in place: an object literal's key order is its insertion
+    // order, so this is what puts the comment immediately before the key it describes while
+    // leaving every sibling (`dev`, whatever else the project keeps here) where it was. An
+    // existing `//e2e` is dropped on the way through and re-inserted once, never twice.
+    const rebuilt = {};
+    for (const [key, value] of Object.entries(block)) {
+        if (key === PORTS_E2E_COMMENT_KEY)
+            continue;
+        if (key === PORTS_E2E_KEY) {
+            rebuilt[PORTS_E2E_COMMENT_KEY] = PORTS_E2E_COMMENT;
+            rebuilt[PORTS_E2E_KEY] = null;
+            continue;
+        }
+        rebuilt[key] = value;
+    }
+    pkg[PORTS_KEY] = rebuilt;
+    writeFileSync(pkgPath, `${JSON.stringify(pkg, null, indent)}\n`, 'utf8');
+    return 'emptied';
+}
 /**
  * Surgically set the derived project's `package.json.agentKitVersion` to the
  * installed brain version, mirroring the lockfile's `version`. The Factory's own

package/dist/lib/provision-preflight.js

@@ -45,6 +45,14 @@ const SERVICE_TOKENS = {
     // at the scaffold stage.
     github: 'VERCEL_TOKEN',
     dns: 'CLOUDFLARE_API_TOKEN',
+    // `backlog` (BSYNC-003) registers the project in backlog.timekast.mx with the org
+    // `admin` token. NOTE: unlike the other gate tokens (fail-closed here), a missing
+    // `BACKLOG_ADMIN_TOKEN` degrades GRACEFULLY at the command layer — WARN + skip when
+    // backlog is one of several services (`resolveBacklogService` in provision.ts strips
+    // it BEFORE this preflight runs), a hard error only when it is the sole service. So
+    // by the time the preflight sees `backlog` in `services`, the token is present; this
+    // entry is the defense-in-depth double-check.
+    backlog: 'BACKLOG_ADMIN_TOKEN',
 };
 /** True when the thrown error is execa's "command not found" (ENOENT). */
 function isCommandNotFound(error) {

package/dist/lib/provision-state.js

@@ -247,6 +247,12 @@ export function isServiceComplete(state, service) {
             return state.github?.done === true;
         case 'dns':
             return state.dns !== undefined;
+        case 'backlog':
+            // Complete only when the per-project key was minted AND written — NOT on the
+            // mere presence of state.backlog (its `projectId` is recorded before the mint,
+            // so a run that created the project but failed to mint would be wrongly skipped
+            // on resume, and the show-once key would never reach `.env.local`).
+            return state.backlog?.keyMinted === true;
         default:
             return false;
     }
@@ -348,6 +354,9 @@ export function readDestroyTarget(rootDir) {
             neonBranchDevId: realId(adopted.neonBranchDevId),
             vercelProjectId: realId(adopted.vercelProjectId),
             githubRepo: realRepo(adopted.githubRepo),
+            // The adopt backfill (PROV-007) does not reconstruct backlog central — nothing
+            // to tear down from an adopted stack; a normal provision state carries it.
+            backlogProjectId: null,
             domains,
         };
     }
@@ -380,6 +389,7 @@ export function readDestroyTarget(rootDir) {
         neonBranchDevId: realId(step.neon?.developBranchId),
         vercelProjectId: realId(step.vercel?.projectId),
         githubRepo: realRepo(step.github?.repo),
+        backlogProjectId: realId(step.backlog?.projectId),
         domains,
     };
 }

package/dist/lib/vercel-env.js

@@ -334,19 +334,53 @@ export async function listEnvVars(projectId, token, teamId, deps = {}) {
     return data.envs ?? [];
 }
 /**
- * Idempotently set ONE env var for its targets (issue §4 + §8). If an existing
- * var already covers any of the requested targets, it is PATCHed
- * (`/v10/projects/{id}/env/{envId}`); otherwise it is POSTed
- * (`/v10/projects/{id}/env`). Either way the call threads `?teamId=`.
+ * Idempotently set ONE env var for its targets (issue §4 + §8). If existing vars
+ * already cover any of the requested targets, they are RECONCILED into a single
+ * record (PATCH `/v10/projects/{id}/env/{envId}`, DELETEing any surplus record —
+ * see below); otherwise the var is POSTed (`/v10/projects/{id}/env`). Either way
+ * every call threads `?teamId=`.
  *
  * Matching is by `key` + target overlap — a var pushed for `production` does not
  * clobber the same key's `preview` entry (they are distinct Vercel env records,
- * which is exactly how `AUTH_SECRET` can differ per environment).
+ * which is exactly how `AUTH_SECRET` can differ per environment). Same-key
+ * records whose target does NOT overlap the plan are never touched, so the
+ * intentional split pairs `buildEnvPlan` creates (distinct values per env) are
+ * never collapsed by a per-target push.
+ *
+ * Split-target reconciliation (BOOT-002): `buildEnvPlan` intentionally creates
+ * SPLIT records per target for some keys (e.g. `NEXT_PUBLIC_APP_URL` as
+ * `['production']` + `['preview']`). When a later plan re-points that key with a
+ * COMBINED target (`['production','preview']` — e.g. the `--domain` go-live),
+ * ALL overlapping records are gathered, the surplus ones are DELETEd FIRST
+ * (Vercel rejects a PATCH whose expanded target collides with a sibling record),
+ * and the first record is then PATCHed with the plan's value + target — leaving
+ * ONE consistent record for the key. A re-run over the already-reconciled state
+ * finds a single record and simply re-PATCHes it in place: no duplicate, no 400.
+ *
+ * @throws {CLIError} when a surplus-record DELETE fails mid-reconciliation — the
+ * message names the key and the step stays re-runnable with `--resume` (the next
+ * run re-lists the records and retries the cleanup).
+ * @throws {VercelApiError} on any other non-2xx (the caller maps it).
  */
 export async function upsertEnvVar(projectId, token, teamId, plan, existing, deps = {}) {
-    const match = existing.find((e) => e.key === plan.key && (e.target ?? []).some((t) => plan.target.includes(t)));
-    if (match) {
-        await vercelApi('PATCH', `/v10/projects/${encodeURIComponent(projectId)}/env/${encodeURIComponent(match.id)}`, token, teamId, deps, {
+    // EVERY record of the key whose target overlaps the plan — not just the first
+    // (a combined-target plan over split records must reconcile the whole set).
+    const matches = existing.filter((e) => e.key === plan.key && (e.target ?? []).some((t) => plan.target.includes(t)));
+    if (matches.length > 0) {
+        const [survivor, ...surplus] = matches;
+        // DELETE the surplus records BEFORE the PATCH: expanding the survivor's
+        // target while a sibling still owns one of those targets 400s on Vercel.
+        for (const record of surplus) {
+            try {
+                await vercelApi('DELETE', `/v10/projects/${encodeURIComponent(projectId)}/env/${encodeURIComponent(record.id)}`, token, teamId, deps);
+            }
+            catch (error) {
+                throw new CLIError(`No se pudo eliminar el record duplicado de \`${plan.key}\` en Vercel al reconciliar ` +
+                    `sus targets (${error?.message ?? 'error desconocido'}).\n` +
+                    'La variable quedó a medio reconciliar; reintenta con `--resume` para completar la limpieza.');
+            }
+        }
+        await vercelApi('PATCH', `/v10/projects/${encodeURIComponent(projectId)}/env/${encodeURIComponent(survivor.id)}`, token, teamId, deps, {
             value: plan.value,
             target: plan.target,
             type: 'encrypted',

package/package.json

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