@timekast/factory 1.20.0 → 1.22.0

package/dist/lib/atomic-swap.js

@@ -23,31 +23,44 @@
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmdirSync, rmSync, writeFileSync, } from 'node:fs';
 import path from 'node:path';
 import { CLIError } from './cli-error.js';
-import { CLAUDE_MD_FILE, TIMEKAST_DIR } from './constants.js';
+import { CLAUDE_MD_FILE, TIMEKAST_DIR, VITEST_SETUP_FILE } from './constants.js';
 import { parseLockfile } from './lockfile.js';
 /**
- * Roots a manifest path may live under (mirrors `profiles.json#track`).
+ * Directory roots a manifest path may live under (mirrors `profiles.json#track`).
  *
  * `.github/workflows/` is deliberately NARROWER than `.github/` — the tracked set is
  * only the CI workflows, and widening the guard to the whole directory would let a
  * tampered tarball rewrite issue templates, CODEOWNERS or funding config.
  */
 const ALLOWED_ROOTS = ['.claude/', 'scripts/', '.husky/', '.github/workflows/'];
+/**
+ * Repo-root FILES a manifest path may be (the non-directory half of `track`).
+ *
+ * Matched EXACTLY, never by prefix. Folding these into `ALLOWED_ROOTS` would be the
+ * short spelling, but `startsWith('vitest.setup.ts')` also accepts
+ * `vitest.setup.ts.evil` — the same widening `.github/workflows/` exists to avoid. A
+ * root file is a single path, so exact equality is what the track actually says.
+ */
+const ALLOWED_FILES = [CLAUDE_MD_FILE, VITEST_SETUP_FILE];
+/** Human-readable rendering of the tracked scope, for the error message. */
+const TRACKED_SCOPE_LABEL = [...ALLOWED_ROOTS, ...ALLOWED_FILES]
+    .map((entry) => `\`${entry}\``)
+    .join(', ');
 /**
  * Reject a manifest path that is unsafe to write: absolute, escaping via `..`, or
  * outside the tracked scope (`.claude/**`, `scripts/**`, `CLAUDE.md`, `.husky/**`,
- * `.github/workflows/**`). A correct release never produces these — this guards a
- * mispublished/tampered tarball from writing `src/` or escaping the repo root.
- * Separator-agnostic (Windows-safe).
+ * `.github/workflows/**`, `vitest.setup.ts`). A correct release never produces these —
+ * this guards a mispublished/tampered tarball from writing `src/` or escaping the repo
+ * root. Separator-agnostic (Windows-safe).
  */
 export function assertSafeTrackedPath(rel) {
     const segments = rel.split(/[\\/]/);
     if (rel.length === 0 || path.isAbsolute(rel) || segments.includes('..')) {
         throw new CLIError(`El manifest declara un path inseguro \`${rel}\` (absoluto o con \`..\`); no se tocó nada.`);
     }
-    const tracked = rel === CLAUDE_MD_FILE || ALLOWED_ROOTS.some((root) => rel.startsWith(root));
+    const tracked = ALLOWED_FILES.includes(rel) || ALLOWED_ROOTS.some((root) => rel.startsWith(root));
     if (!tracked) {
-        throw new CLIError(`El manifest declara \`${rel}\`, fuera del scope rastreado (\`.claude/\`, \`scripts/\`, \`CLAUDE.md\`, \`.husky/\`, \`.github/workflows/\`). ` +
+        throw new CLIError(`El manifest declara \`${rel}\`, fuera del scope rastreado (${TRACKED_SCOPE_LABEL}). ` +
             'El release está mal construido; no se tocó nada.');
     }
 }

package/dist/lib/constants.js

@@ -41,6 +41,17 @@ export const LOCKFILE_FILE = 'lockfile.json';
  * exists on disk (path-match path). See `diffLockfiles` + the install commands.
  */
 export const CLAUDE_MD_FILE = 'CLAUDE.md';
+/**
+ * Repo-root Vitest setup file. A tracked manifest file (via `track`), so it flows through
+ * the normal diff/install engine and `factory update` keeps it current in every derivative.
+ *
+ * It is KIT-OWNED, unlike `CLAUDE.md` above: it carries the kit's own wiring (RTL matchers,
+ * `cleanup()`, and the `server-only`/`client-only` neutralization that keeps a marked module
+ * loadable outside a bundler). A derivative's project-specific mocks belong in the sibling
+ * `vitest.setup.project.ts`, which is dev-owned and ships in NEITHER profile — the same
+ * split as `.husky/pre-commit` → `.husky/pre-commit.project`.
+ */
+export const VITEST_SETUP_FILE = 'vitest.setup.ts';
 /**
  * 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
@@ -158,6 +169,27 @@ export const GENERATOR_SCRIPTS = [
         file: 'scripts/tools/generate-api.ts',
     },
 ];
+/**
+ * Kit-local E2E debugging aliases — raw Playwright, but through the wrapper that arms the
+ * `server-only` / `client-only` compile-guard stub (`scripts/tools/e2e-direct.ts`).
+ *
+ * `pnpm test:e2e` gets the stub from `e2e-runner.ts`; these two used to shell `playwright
+ * test` straight from `package.json` and therefore did not, so a spec that transitively
+ * reached a server-guarded module died at load with `No tests found` — but only here, never
+ * under the full runner.
+ *
+ * FILE-GATED, exactly like `GENERATOR_SCRIPTS`: the alias is only ensured when the wrapper
+ * it shells actually exists in the repo, so a `core`/non-Factory derivative never receives a
+ * script pointing at a file it lacks. Both gate on the SAME file (one wrapper, two entry
+ * points — `--ui` is just an argument forwarded to Playwright). Insert-if-missing; a dev's
+ * own value is never overwritten, and the previously-shipped raw commands self-heal through
+ * `OBSOLETE_SCRIPT_CMDS` below.
+ */
+export const E2E_DIRECT_SCRIPT_FILE = 'scripts/tools/e2e-direct.ts';
+export const E2E_DIRECT_SCRIPT_NAME = 'test:e2e:direct';
+export const E2E_DIRECT_SCRIPT_CMD = `tsx ${E2E_DIRECT_SCRIPT_FILE}`;
+export const E2E_UI_SCRIPT_NAME = 'test:e2e:ui';
+export const E2E_UI_SCRIPT_CMD = `tsx ${E2E_DIRECT_SCRIPT_FILE} --ui`;
 /**
  * Aggregate that runs every shipped reference generator in one shot (the
  * one-command "regenerate everything" alias). Shells the files directly (not
@@ -168,6 +200,26 @@ export const GENERATOR_SCRIPTS = [
 export const GENERATE_REFERENCE_NAME = 'generate:reference';
 export const GENERATE_REFERENCE_CMD = 'tsx scripts/tools/generate-inventory.ts && tsx scripts/tools/generate-codebase.ts && tsx scripts/tools/generate-hooks.ts && tsx scripts/tools/generate-schema.ts && tsx scripts/tools/generate-api.ts';
 export const GENERATE_REFERENCE_GATE_FILE = 'scripts/tools/generate-schema.ts';
+/**
+ * The dev server's heap ceiling, carried inside the `dev:next` script the launcher shells
+ * (`scripts/tools/dev.mjs` → `pnpm dev:next`).
+ *
+ * WHY THE CLI OWNS IT. This value lives in `package.json`, which is frozen at bootstrap in a
+ * derivative (BR-FACTORY-006) and is NOT part of the tracked file set — so `factory update`
+ * swapping `.claude/` + `scripts/` can never reach it. The CLI is the only thing that can,
+ * exactly as it does for `agentKitVersion` and the retired e2e port. Without an entry here,
+ * every existing derivative would keep the old ceiling forever while new ones are born with
+ * the current one.
+ *
+ * FILE-GATED on the launcher, like `GENERATOR_SCRIPTS`: a `core`/non-Next derivative has no
+ * `dev.mjs` and never receives an alias for a dev server it does not run.
+ */
+export const DEV_NEXT_SCRIPT_NAME = 'dev:next';
+export const DEV_NEXT_GATE_FILE = 'scripts/tools/dev.mjs';
+export const DEV_NEXT_HEAP_MB = 4096;
+export const DEV_NEXT_SCRIPT_CMD = `NODE_OPTIONS='--max-old-space-size=${DEV_NEXT_HEAP_MB}' next dev --turbopack`;
+/** The ceiling(s) the kit shipped before — the ONLY values healing is allowed to overwrite. */
+export const DEV_NEXT_OBSOLETE_HEAPS_MB = [2048];
 /**
  * The `ports` block of a derivative's `package.json`, and the one key inside it the CLI
  * maintains.
@@ -206,4 +258,14 @@ export const OBSOLETE_SCRIPT_CMDS = {
     [GENERATE_REFERENCE_NAME]: [
         GENERATOR_SCRIPTS.map((g) => `node ${g.file.replace(/\.ts$/, '.mjs')}`).join(' && '),
     ],
+    // The raw Playwright invocations the kit shipped before `e2e-direct.ts` existed. They run,
+    // which is what makes them worth healing: they simply run WITHOUT the compile-guard stub,
+    // so the failure they produce is a spec reporting `No tests found` rather than an error a
+    // dev can act on. A derivative that pointed either alias somewhere of its own keeps it.
+    [E2E_DIRECT_SCRIPT_NAME]: ['playwright test'],
+    [E2E_UI_SCRIPT_NAME]: ['playwright test --ui'],
+    // Every heap ceiling the kit shipped for the dev server before the current one. Listed as
+    // whole COMMANDS (not just the number) so healing stays exact-match: a derivative that
+    // appended a flag of its own, or picked a ceiling the kit never shipped, is left alone.
+    [DEV_NEXT_SCRIPT_NAME]: DEV_NEXT_OBSOLETE_HEAPS_MB.map((mb) => `NODE_OPTIONS='--max-old-space-size=${mb}' next dev --turbopack`),
 };

package/dist/lib/neon-api.js

@@ -28,6 +28,28 @@ const NEON_API_TIMEOUT_MS = 30_000;
 export const NEON_MAIN_BRANCH = 'main';
 /** Name of the isolated, data-clean second branch this step creates. */
 export const NEON_DEVELOP_BRANCH = 'develop';
+/**
+ * Autoscaling bounds every compute this CLI creates is born with.
+ *
+ * We declare them EXPLICITLY instead of inheriting Neon's account default, which
+ * is not stable over time: projects provisioned in earlier eras were born at a
+ * fixed `1-1 CU` (min == max), which bills a full CU for every hour the compute
+ * is merely awake — 4x the floor below — and today's default is `0.25-8`, whose
+ * ceiling is 32x the floor. Neither is a deliberate choice for a fresh derivative.
+ *
+ * The floor is what an idle-but-awake compute bills, so it is the single biggest
+ * lever on the fleet's Neon bill; 0.25 CU is Neon's minimum. The ceiling is pure
+ * headroom (it costs nothing until traffic actually needs it), so 2 CU gives a
+ * new project 8x of burst room while keeping a runaway query from silently
+ * scaling to 8 CU. A project that outgrows it raises the ceiling deliberately.
+ */
+export const NEON_AUTOSCALING_MIN_CU = 0.25;
+export const NEON_AUTOSCALING_MAX_CU = 2;
+/** The autoscaling pair as the Neon REST API spells it — shared by both writes. */
+const NEON_AUTOSCALING_SETTINGS = {
+    autoscaling_limit_min_cu: NEON_AUTOSCALING_MIN_CU,
+    autoscaling_limit_max_cu: NEON_AUTOSCALING_MAX_CU,
+};
 /**
  * Neon returns 423 (Locked) while a freshly-created project runs its post-create
  * operations ("project already has running conflicting operations"). The develop
@@ -93,6 +115,10 @@ export async function createNeonProject(apiKey, projectName, orgId, deps = {}) {
                 ...(orgId ? { org_id: orgId } : {}),
                 // Name the auto-created primary branch `main` so production reads cleanly.
                 branch: { name: NEON_MAIN_BRANCH },
+                // Bind the autoscaling bounds at the PROJECT level so the primary compute
+                // AND every branch created later (by us or by hand in the console) inherit
+                // them — otherwise a new branch silently re-adopts Neon's account default.
+                default_endpoint_settings: { ...NEON_AUTOSCALING_SETTINGS },
             },
         }),
         signal: AbortSignal.timeout(NEON_API_TIMEOUT_MS),
@@ -129,7 +155,10 @@ export async function createDevelopBranch(apiKey, projectId, parentBranchId, dep
         headers: neonHeaders(apiKey),
         body: JSON.stringify({
             branch: { name: NEON_DEVELOP_BRANCH, parent_id: parentBranchId },
-            endpoints: [{ type: 'read_write' }],
+            // Stated explicitly rather than left to project inheritance: this branch is
+            // created in the same run as the project, and a bare `{type}` endpoint is
+            // exactly how the fleet ended up with computes nobody chose the size of.
+            endpoints: [{ type: 'read_write', ...NEON_AUTOSCALING_SETTINGS }],
         }),
         signal: AbortSignal.timeout(NEON_API_TIMEOUT_MS),
     });

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, 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';
+import { DEV_NEXT_GATE_FILE, DEV_NEXT_SCRIPT_CMD, DEV_NEXT_SCRIPT_NAME, E2E_DIRECT_SCRIPT_CMD, E2E_DIRECT_SCRIPT_FILE, E2E_DIRECT_SCRIPT_NAME, E2E_UI_SCRIPT_CMD, E2E_UI_SCRIPT_NAME, 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
@@ -110,6 +110,11 @@ function ensureFactoryScripts(pkg, extraScripts = {}) {
  *   tracked set on `update`/`beta`, so an existing derivative self-heals the
  *   aliases without the dev hand-editing `package.json`.
  * - `generate:reference` — the aggregate that runs the whole set in one command.
+ * - `test:e2e:direct` / `test:e2e:ui` — the two raw-Playwright debugging entry
+ *   points, routed through the wrapper that arms the compile-guard stub. Both
+ *   gate on that one wrapper file.
+ * - `dev:next` — the dev server the launcher shells, whose heap ceiling the kit
+ *   owns. Gated on the launcher (`dev.mjs`), which is what invokes it.
  *
  * Insert-if-missing for all: a dev's own value for any of these is never
  * overwritten (see `ensureFactoryScripts`).
@@ -127,6 +132,12 @@ export function kitLocalScripts(rootDir) {
     }
     if (has(GENERATE_REFERENCE_GATE_FILE))
         scripts[GENERATE_REFERENCE_NAME] = GENERATE_REFERENCE_CMD;
+    if (has(E2E_DIRECT_SCRIPT_FILE)) {
+        scripts[E2E_DIRECT_SCRIPT_NAME] = E2E_DIRECT_SCRIPT_CMD;
+        scripts[E2E_UI_SCRIPT_NAME] = E2E_UI_SCRIPT_CMD;
+    }
+    if (has(DEV_NEXT_GATE_FILE))
+        scripts[DEV_NEXT_SCRIPT_NAME] = DEV_NEXT_SCRIPT_CMD;
     return scripts;
 }
 /**

package/package.json

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