@timekast/factory 1.20.0 → 1.21.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
@@ -206,4 +238,10 @@ 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'],
 };

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 { 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,9 @@ 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.
  *
  * Insert-if-missing for all: a dev's own value for any of these is never
  * overwritten (see `ensureFactoryScripts`).
@@ -127,6 +130,10 @@ 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;
+    }
     return scripts;
 }
 /**

package/package.json

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