@doikayt/typescript-build-config 0.1.13 → 0.1.15

package/README.md

@@ -5,10 +5,18 @@ Shared build configuration presets for TypeScript-based projects.
 <!-- TOC:START -->
 - [@doikayt/typescript-build-config](#doikayttypescript-build-config)
   - [Purpose](#purpose)
+  - [Design Goals](#design-goals)
+    - [What each component is for](#what-each-component-is-for)
   - [Installation](#installation)
+  - [Usage](#usage)
+    - [The canonical script set](#the-canonical-script-set)
+    - [Console / CLI project](#console--cli-project)
+    - [UI / web project (with Playwright e2e)](#ui--web-project-with-playwright-e2e)
+    - [Existing project](#existing-project)
   - [Dependency Strategy](#dependency-strategy)
   - [Current Contents](#current-contents)
   - [Delivery Model](#delivery-model)
+  - [Enforcement Model](#enforcement-model)
   - [Release Pipeline](#release-pipeline)
   - [Conventions Every Project Must Adhere To](#conventions-every-project-must-adhere-to)
     - [The `ci` script](#the-ci-script)
@@ -31,6 +39,51 @@ The plugin encapsulates common build **policy** and release **workflow logic**
 via the pipeline files it installs into each consumer repo and the canonical release process in
 [docs/RELEASE-PROCESS.md](docs/RELEASE-PROCESS.md).
 
+## Design Goals
+
+The  package housed in this repo is designed to be 'upstream-most' -- i.e., all other
+packages depend on it (possibly transitively) and this package has no other 
+dependencies in this repo.
+
+Two goals drive every design decision made for this package, and they pull in different
+directions:
+
+1. **Consistency enforcement** — every `@doikayt` TypeScript repo should expose
+   the same command surface (`ci` and `update-all-format`) and share the same
+   lint / format / release policy, so tooling, CI, and contributors can assume
+   an identical shape in any repo.
+2. **Minimal per-project setup** — standing up a new repo, or absorbing a policy
+   change into an old one, should cost as close to zero manual wiring as
+   possible.
+
+This package reconciles these two via one architectural choice: **it both
+_defines_ the conventions and _distributes_ them.** A plain template repo would
+copy conventions once and let them drift; a linter would enforce them but set
+nothing up. The npm package defined in this repo does both — it is the single
+artifact that decides "every repo has a `ci` gate" and also installs and
+re-checks it. That single source of truth is what keeps the ecosystem coherent
+as it grows.
+
+### What each component is for
+
+Each artifact this package ships exists to serve one or both goals. (See
+[Delivery Model](#delivery-model) for _how_ each is delivered; the table below
+is _why_.)
+
+| Component | Value it delivers | Serves |
+| --- | --- | --- |
+| **Presets** — `src/eslint.js`, Prettier, base tsconfig, living in `node_modules` | One lint / format / TS ruleset; change it once here and every repo picks it up on `npm update` | Consistency |
+| **Stubs** — `src/top-level/*` seeded into the project root | Zero-config entry points that only `extends` the presets | Minimal setup |
+| **Pipeline** — `src/pipeline/*` copied on install | A working release + changeset workflow with no hand-wiring; drift is diff-warned | Both |
+| **Convention checks** — postinstall warns on missing `ci` / `update-all-format` | An install-time nudge toward the shared command surface | Consistency |
+| **`ci` gate** — `release.yml` runs `npm run ci` | Fail-closed enforcement: a repo that ignores the convention cannot release | Consistency (hard teeth) |
+| **Policy doc** — `docs/RELEASE-PROCESS.md`, linked never copied | One canonical release policy, impossible to drift | Consistency |
+| **Assets** — `assets/*` seeded into `docs/assets/` | Shared brand logos with no per-repo copies to maintain | Minimal setup |
+
+The two goals map onto two lifecycle phases — **delivery** (getting canonical
+artifacts into a consuming repo) and **enforcement** (keeping that repo conformant over
+time). Each has its own top-level section below.
+
 ## Installation
 
 ```bash
@@ -40,6 +93,75 @@ npm install --save-dev @doikayt/typescript-build-config
 The postinstall script copies starter config files into your project root and
 sets up the release pipeline (see below).
 
+## Usage
+
+After installing, run the `init` scaffolder to write the
+[canonical npm-script set](#the-canonical-script-set) and declare the dev
+dependencies those scripts need. `init` is interactive and **idempotent** — it
+only adds what is missing and never overwrites a script or config you already
+have, so it is safe to re-run.
+
+### The canonical script set
+
+Every project gets the same named scripts, so any repo responds identically to
+`npm run ci`, `npm run update-all-format`, and so on. The aggregates chain to
+small single-purpose scripts, and the check side mirrors the write side:
+
+| Script | What it does |
+| --- | --- |
+| `ci` | The release gate: `check-all-format` then `test` (plus `test:e2e` for UI). |
+| `build` | Compile TypeScript to `dist/` (`tsc`). |
+| `prepack` | Runs `build` before packing, so `changeset publish` ships compiled `dist/`. |
+| `test` | Unit / integration tests (`vitest run`). |
+| `test:e2e` | End-to-end tests (`playwright test`) — UI projects only. |
+| `update-all-format` | Reformat everything: code + markdown docs (write). |
+| `check-all-format` | Verify formatting: code + markdown docs (used by `ci`). |
+| `update-code-formatting` / `check-code-formatting` | Prettier write / check. |
+| `update-markdown-docs` / `check-markdown-docs` | Regenerate / verify generated markdown (TOC, UML, …). |
+
+Alongside the scripts, `init` sets the publish config a fresh package needs —
+`type: "module"`, `main` / `types` / `exports` pointing at `dist/index.js`, and
+`files: ["dist"]` — each only if you have not already set it. Combined with
+`prepack`, a brand-new project builds and publishes a compiled, typed ESM
+package on push with no extra wiring.
+
+### Console / CLI project
+
+```bash
+npm init -y                                            # if starting fresh
+npm install --save-dev @doikayt/typescript-build-config
+npx @doikayt/typescript-build-config init             # answer "n" to the Playwright prompt
+npm install                                            # fetch the declared devDependencies
+```
+
+`init` writes the canonical scripts (`ci`, `build`, `test`, `update-all-format`,
+`check-all-format`, `prepack`, and their sub-tasks), sets the `dist/`-based
+publish config, declares `vitest` + `@doikayt/autogen-markdown-doc` +
+`typescript`, and seeds a commented `vitest.config.ts`.
+
+### UI / web project (with Playwright e2e)
+
+```bash
+npm init -y
+npm install --save-dev @doikayt/typescript-build-config
+npx @doikayt/typescript-build-config init             # answer "y" to the Playwright prompt
+npm install
+# then fill in the TODOs in the generated playwright.config.ts (webServer, baseURL)
+```
+
+Answering **yes** to the Playwright prompt additionally: adds a `test:e2e`
+script and folds it into `ci` (so the release gate runs e2e), declares
+`@playwright/test`, and seeds a `playwright.config.ts` template. Browsers are
+installed on demand by the bundled `doikayt-playwright-install` wrapper the
+`test:e2e` script calls — no manual `playwright install` step, locally or in CI.
+
+### Existing project
+
+Skip `init` if you prefer. On install, `postinstall` warns about any missing
+required targets (`ci`, `update-all-format`) until you add them — either by
+running `init` to adopt the full canonical set, or by defining the two scripts
+by hand (see [Conventions](#conventions-every-project-must-adhere-to)).
+
 ## Dependency Strategy
 
 `eslint` and `prettier` are listed as `dependencies` and are pulled in
@@ -52,6 +174,11 @@ versions of these tools may produce peer dependency conflicts.
 
 ## Current Contents
 
+- `init` scaffolder CLI (`npx @doikayt/typescript-build-config init`) — writes
+  the canonical npm-script set, declares dev dependencies, and seeds config
+  templates (see [Usage](#usage))
+- `doikayt-playwright-install` bin — env-gated Playwright browser installer used
+  by a UI project's `test:e2e` script (adds `--with-deps` only on CI+Linux)
 - ESLint config
 - Prettier config
 - TypeScript config (`tsconfig.json`, `tsconfig.test.json`, `tsconfig.eslint.json`)
@@ -87,9 +214,21 @@ versions of these tools may produce peer dependency conflicts.
 
 ## Delivery Model
 
-This package standardizes downstream repos through three delivery channels — script and
-config artifacts that _implement_ the common policy, and a canonical document that
-_states_ it:
+_Phase 1 of 2: getting canonical artifacts **into** a repo. Keeping a repo
+conformant over time is the [Enforcement Model](#enforcement-model)._
+
+This package standardizes downstream repos by delivering **five components through three
+channels** — so as you read the diagram, note that the component count and the channel
+count deliberately differ; several components share a channel. The components are the
+presets, stubs, pipeline, and assets that _implement_ the common policy, plus a canonical
+document that _states_ it. Each reaches the consumer via one of three channels:
+
+1. **Referenced in place** — presets (stay in `node_modules`)
+2. **Copied on install** — stubs, pipeline, assets
+3. **Linked, never copied** — policy
+
+The diagram below numbers those three channels; the terms after it define the five
+components.
 
 ```
         ┌─────────────────────────────────────────────────┐
@@ -150,6 +289,42 @@ _states_ it:
   their own contributor docs (as the consumer box shows) — never copied, so it cannot
   drift.
 
+## Enforcement Model
+
+_Phase 2 of 2: keeping a repo **conformant** over time, once delivery has seeded
+it. Getting artifacts in is the [Delivery Model](#delivery-model) above._
+
+Delivery gets canonical artifacts into a consuming repo; enforcement keeps that repo aligned
+as both it and the upstream evolve. The two phases share machinery:
+**`postinstall` is the workhorse of both** — it _delivers_ on first install
+(copying absent files) and _enforces_ on every subsequent run that rebuilds this
+package into `node_modules` — a fresh `npm install`, an `npm ci` (which always
+rebuilds the whole tree), or an `npm update` that bumps this package — warning on
+drift and on missing conventions. A no-op `npm install` with an unchanged tree
+does not re-trigger it.
+
+Enforcement runs on a spectrum from soft to hard:
+
+- **Soft — install-time warnings (name-level).** On every `npm install` /
+  `npm update`, postinstall warns (non-fatal) when a required target
+  (`ci`, `update-all-format`) is missing, and prints a diff when a copied
+  pipeline or asset file has drifted from its canonical template. See
+  [Release Pipeline](#release-pipeline) for the per-file drift behavior and
+  [Conventions Every Project Must Adhere To](#conventions-every-project-must-adhere-to)
+  for the required targets.
+- **Hard — the fail-closed `ci` gate.** The release workflow runs `npm run ci`;
+  a repo without a working `ci` gate fails the build and cannot publish. This is
+  the only enforcement with real teeth — see
+  [The `ci` script](#the-ci-script).
+
+One deliberate limitation: the soft checks are **name-level only**. They verify
+a `ci` script _exists_, not that it runs anything meaningful — `"ci": "echo ok"`
+satisfies the warning. Guaranteeing that `ci` actually does its job is left to
+the fail-closed pipeline, where a broken gate surfaces as a red build. Put
+differently: delivery is "deep" (full config seeded) while continuous
+enforcement is "shallow" (presence, not behavior) — a gap worth knowing when you
+rely on it.
+
 ## Release Pipeline
 
 On install, the postinstall script copies the release pipeline files into your
@@ -173,8 +348,8 @@ configuration is needed.
 ## Conventions Every Project Must Adhere To
 
 Every project that installs this package must implement two named entry points.
-`postinstall` warns on every `npm install` or `npm update` until each is in
-place.
+`postinstall` warns whenever it re-runs (a fresh `npm install`, an `npm ci`, or
+an `npm update` that bumps this package) until each is in place.
 
 ### The `ci` script
 
@@ -199,11 +374,27 @@ remote CI job will pass.
 
 #### NX projects
 
-NX-based projects must still expose `ci` as a thin shim in `package.json`, even
-if it only delegates to NX targets:
+`package.json` is the source of truth — it is always present, and the release
+workflow calls `npm run ci` directly. So an NX project keeps the **real** `ci`
+command in `package.json`, exactly like any other project — it does *not*
+delegate package.json to NX. If you want NX orchestration, add NX targets that
+delegate **to** npm, never the reverse:
 
 ```json
-{ "scripts": { "ci": "nx run-many --target=ci --all" } }
+// package.json — the real command lives here
+{ "scripts": { "ci": "npm run check-all-format && npm run test" } }
+```
+
+```json
+// project.json (optional) — an NX target delegates to the npm script
+{
+  "targets": {
+    "ci": {
+      "executor": "nx:run-commands",
+      "options": { "command": "npm run ci" }
+    }
+  }
+}
 ```
 
 The release workflow is NX-agnostic — it calls `npm run ci`, never NX directly.
@@ -238,8 +429,9 @@ Or as an NX target:
 }
 ```
 
-If neither is found, `postinstall` prints a warning (non-fatal) on every
-`npm install` or `npm update` until the target is added.
+If neither is found, `postinstall` prints a warning (non-fatal) each time it
+re-runs (a fresh `npm install`, an `npm ci`, or an `npm update` that bumps this
+package) until the target is added.
 
 NX projects may define the target in `project.json` instead of `package.json`
 scripts — the postinstall check recognises both. There is no shim requirement

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doikayt/typescript-build-config",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Shared build configuration for TypeScript projects — ESLint, Prettier, tsconfig, and Playwright presets",
   "_comments": {
     "exports": "This block lists the config files that will be extended by files in in src/toplevel - which are copied to consuming project root folder. An example: eslint.config.js imports from '@doikayt/typescript-build-config/eslint'.",
@@ -14,6 +14,10 @@
     "./tsconfig": "./src/tsconfig.base.json",
     "./playwright": "./src/playwright.js"
   },
+  "bin": {
+    "typescript-build-config": "src/cli.js",
+    "doikayt-playwright-install": "src/playwright-install.js"
+  },
   "files": [
     "src/",
     "src/top-level/.gitignore",
@@ -24,8 +28,8 @@
     "postinstall": "node src/postinstall.js",
     "update-all-format": "prettier --write src/ && update-markdown-toc README.md",
     "check-format": "prettier --check src/ && update-markdown-toc --check README.md",
-    "ci": "npm run check-format && node --test",
-    "test": "node --test"
+    "ci": "npm run check-format && node --test tests/*.test.js",
+    "test": "node --test tests/*.test.js"
   },
   "publishConfig": {
     "access": "public"

package/src/canonical-scripts.js

@@ -0,0 +1,57 @@
+// The canonical npm-script set init writes into every consumer. package.json is
+// the single source of truth (it is always present); NX projects, if any, add
+// thin targets that delegate to `npm run <x>` — never the reverse. So this set
+// is identical regardless of orchestrator; only the UI/console distinction
+// changes it (Playwright e2e).
+
+export function canonicalScripts({ ui = false } = {}) {
+  const ci = ui
+    ? "npm run check-all-format && npm run test && npm run test:e2e"
+    : "npm run check-all-format && npm run test";
+
+  const scripts = {
+    ci,
+    build: "tsc",
+    test: "vitest run",
+    "update-all-format":
+      "npm run update-code-formatting && npm run update-markdown-docs",
+    "update-code-formatting": "prettier --write src/",
+    "update-markdown-docs": "autogen-markdown-doc",
+    "check-all-format":
+      "npm run check-code-formatting && npm run check-markdown-docs",
+    "check-code-formatting": "prettier --check src/",
+    "check-markdown-docs": "autogen-markdown-doc check",
+    // Build at publish time so `changeset publish` ships compiled dist/ without
+    // the release workflow needing a build step.
+    prepack: "npm run build",
+  };
+
+  if (ui) scripts["test:e2e"] = "doikayt-playwright-install && playwright test";
+
+  return scripts;
+}
+
+export function devDependencyNames({ ui = false } = {}) {
+  const names = ["vitest", "@doikayt/autogen-markdown-doc", "typescript"];
+  if (ui) names.push("@playwright/test");
+  return names;
+}
+
+// Top-level package.json fields init sets (non-destructively) so a fresh project
+// builds to dist/ and publishes a compiled, importable ESM package. Assumes the
+// canonical src/index.ts entry point; a consumer that wants a different shape
+// sets these first and init leaves them untouched.
+export function packageFields() {
+  return {
+    type: "module",
+    main: "dist/index.js",
+    types: "dist/index.d.ts",
+    exports: {
+      ".": {
+        types: "./dist/index.d.ts",
+        default: "./dist/index.js",
+      },
+    },
+    files: ["dist"],
+  };
+}

package/src/cli.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+// Main CLI entry for this package, registered as the `typescript-build-config`
+// bin. Invoked as `npx @doikayt/typescript-build-config <subcommand>` — npx
+// resolves the bin whose name matches the package. argv[2] is the subcommand
+// (argv[0]=node, argv[1]=this file). Today the only subcommand is `init`; this
+// dispatcher is the seam where future ones (e.g. `check-conventions`) plug in.
+import { runInit } from "./init.js";
+
+const sub = process.argv[2];
+
+if (sub === "init") {
+  // runInit is async (it prompts via readline); translate resolve/reject into
+  // process exit codes so the shell sees success/failure.
+  runInit().then(
+    () => process.exit(0),
+    (err) => {
+      console.error(err?.message ?? err);
+      process.exit(1);
+    },
+  );
+} else {
+  console.error(
+    `Unknown command: ${sub ?? "(none)"}\nUsage: typescript-build-config init`,
+  );
+  process.exit(1);
+}

package/src/dep-versions.js

@@ -0,0 +1,29 @@
+import { execFileSync } from "child_process";
+
+export function toCaretRange(version) {
+  return `^${version}`;
+}
+
+// Default view: ask npm for a package's latest published version. Injectable so
+// resolveVersions stays unit-testable without shelling out.
+export function npmView(name) {
+  return execFileSync("npm", ["view", name, "version"], {
+    encoding: "utf8",
+  }).trim();
+}
+
+// Resolve each package name to a caret range on its latest version. If the
+// lookup fails (offline) or returns nothing, fall back to "latest" so the
+// declared devDependency is still installable once the user runs `npm install`.
+export function resolveVersions(names, view = npmView) {
+  const out = {};
+  for (const name of names) {
+    try {
+      const version = view(name);
+      out[name] = version ? toCaretRange(version) : "latest";
+    } catch {
+      out[name] = "latest";
+    }
+  }
+  return out;
+}

package/src/init.js

@@ -0,0 +1,159 @@
+import {
+  readFileSync,
+  writeFileSync,
+  existsSync,
+  copyFileSync,
+  mkdirSync,
+  readdirSync,
+} from "fs";
+import { resolve } from "path";
+import { fileURLToPath } from "url";
+import { createInterface } from "readline";
+import {
+  canonicalScripts,
+  devDependencyNames,
+  packageFields,
+} from "./canonical-scripts.js";
+import { applyToPackageJson } from "./package-json.js";
+import { resolveVersions } from "./dep-versions.js";
+
+const templatesDir = fileURLToPath(new URL("templates/", import.meta.url));
+
+// Copy a template into the project only when the destination is absent, so a
+// consumer's existing config is never overwritten. Returns what happened.
+function seedFile(src, destPath) {
+  if (existsSync(destPath)) return "skipped";
+  copyFileSync(resolve(templatesDir, src), destPath);
+  return "seeded";
+}
+
+// Recursively copy a template directory tree into the project.
+function copyDir(srcDir, destDir) {
+  mkdirSync(destDir, { recursive: true });
+  for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
+    const from = resolve(srcDir, entry.name);
+    const to = resolve(destDir, entry.name);
+    if (entry.isDirectory()) copyDir(from, to);
+    else copyFileSync(from, to);
+  }
+}
+
+function dirIsEmpty(dir) {
+  return !existsSync(dir) || readdirSync(dir).length === 0;
+}
+
+// Default interactive prompt. Injectable so runInit is testable without stdin.
+async function askYesNo(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await new Promise((res) => rl.question(question, res));
+    return /^y(es)?$/i.test(answer.trim());
+  } finally {
+    rl.close();
+  }
+}
+
+export async function runInit({
+  cwd = process.cwd(),
+  prompt = askYesNo,
+  resolveDevVersions = resolveVersions,
+  log = console.log,
+} = {}) {
+  const pkgPath = resolve(cwd, "package.json");
+  const raw = readFileSync(pkgPath, "utf8");
+
+  const ui = await prompt(
+    "Is this a UI project that needs Playwright (e2e)? [y/N] ",
+  );
+
+  const scripts = canonicalScripts({ ui });
+  const devDependencies = resolveDevVersions(devDependencyNames({ ui }));
+
+  const { text, added, skipped } = applyToPackageJson(raw, {
+    scripts,
+    devDependencies,
+    fields: packageFields(),
+  });
+  writeFileSync(pkgPath, text);
+
+  const configs = [{ name: "vitest.config.ts" }];
+  if (ui) configs.push({ name: "playwright.config.ts" });
+  const seededConfigs = [];
+  const keptConfigs = [];
+  for (const { name } of configs) {
+    const result = seedFile(name, resolve(cwd, name));
+    (result === "seeded" ? seededConfigs : keptConfigs).push(name);
+  }
+
+  const report = (label, keys) => {
+    if (keys.length) log(`${label}: ${keys.join(", ")}`);
+  };
+  report("Added scripts", added.scripts);
+  report("Kept existing scripts", skipped.scripts);
+  report("Declared devDependencies", added.devDependencies);
+  report("Kept existing devDependencies", skipped.devDependencies);
+  report("Set package fields", added.fields);
+  report("Kept existing package fields", skipped.fields);
+  report("Seeded config files", seededConfigs);
+  report("Kept existing config files", keptConfigs);
+  log("");
+  log("Next: run `npm install` to fetch the newly declared devDependencies.");
+
+  const demo = await maybeScaffoldDemo({ cwd, prompt, log });
+
+  return { added, skipped, seededConfigs, keptConfigs, demo };
+}
+
+// Opt-in starter scaffold for a new project. Seeds a minimal src/ module, a
+// README with doc-generator markers, and a project.json — each independently and
+// only when its slot is empty, so nothing a consumer already has is overwritten.
+// It writes files only; the user runs npm install / test / push themselves.
+async function maybeScaffoldDemo({ cwd, prompt, log }) {
+  const wantDemo = await prompt(
+    "Scaffold a starter demo (minimal src module + README + project.json) so you\n" +
+      "can build, test, and publish immediately? Existing files are never\n" +
+      "overwritten. [y/N] ",
+  );
+  if (!wantDemo) {
+    return { scaffolded: false, reason: "declined", wrote: [], skipped: [] };
+  }
+
+  const demoTemplate = resolve(templatesDir, "demo");
+  const wrote = [];
+  const skipped = [];
+  const paths = [];
+
+  // src/: seed the module only when src/ has no files, so starter code never
+  // gets mixed into a project that already has source.
+  const srcDir = resolve(cwd, "src");
+  if (dirIsEmpty(srcDir)) {
+    copyDir(resolve(demoTemplate, "src"), srcDir);
+    for (const entry of readdirSync(resolve(demoTemplate, "src"))) {
+      paths.push(`src/${entry}`);
+    }
+    wrote.push("src/ module");
+  } else {
+    skipped.push("src/ (already has files)");
+  }
+
+  // README.md and project.json: single files, seeded only when absent.
+  for (const name of ["README.md", "project.json"]) {
+    if (existsSync(resolve(cwd, name))) {
+      skipped.push(name);
+    } else {
+      copyFileSync(resolve(demoTemplate, name), resolve(cwd, name));
+      wrote.push(name);
+      paths.push(name);
+    }
+  }
+
+  log("");
+  if (wrote.length) log(`Demo: seeded ${wrote.join(", ")}.`);
+  if (skipped.length) log(`Demo: kept existing ${skipped.join(", ")}.`);
+  if (paths.length) {
+    log(`To remove the starter files later: rm -r ${paths.join(" ")}`);
+    log("Then: npm install → npm test → npm run update-all-format → push.");
+  }
+
+  return { scaffolded: paths.length > 0, reason: null, wrote, skipped, paths };
+}

package/src/package-json.js

@@ -0,0 +1,69 @@
+// Idempotent helpers for editing a consumer's package.json: add keys only when
+// absent, never overwrite what the consumer already has, and preserve the
+// file's original indentation and trailing-newline style.
+
+export function mergeAbsent(existing = {}, additions = {}) {
+  const merged = { ...existing };
+  const added = [];
+  const skipped = [];
+  for (const [key, value] of Object.entries(additions)) {
+    if (Object.prototype.hasOwnProperty.call(merged, key)) {
+      skipped.push(key);
+    } else {
+      merged[key] = value;
+      added.push(key);
+    }
+  }
+  return { merged, added, skipped };
+}
+
+export function detectIndent(text) {
+  const m = text.match(/\n([\t ]+)/);
+  return m ? m[1] : "  ";
+}
+
+/**
+ * Merge scripts / devDependencies into package.json text, adding only absent
+ * keys and preserving the file's indentation and trailing-newline style. Does
+ * not touch disk — returns the new text plus a report of what changed.
+ *
+ * @param {string} rawText - current package.json contents
+ * @param {{
+ *   scripts?: Record<string,string>,
+ *   devDependencies?: Record<string,string>,
+ *   fields?: Record<string,unknown>
+ * }} additions - `fields` are top-level keys (main, type, files, …)
+ * @returns {{
+ *   text: string,
+ *   added: { scripts: string[], devDependencies: string[], fields: string[] },
+ *   skipped: { scripts: string[], devDependencies: string[], fields: string[] }
+ * }} new file text, plus keys added vs. skipped (already present)
+ */
+export function applyToPackageJson(
+  rawText,
+  { scripts = {}, devDependencies = {}, fields = {} } = {},
+) {
+  const pkg = JSON.parse(rawText);
+  const indent = detectIndent(rawText);
+
+  const s = mergeAbsent(pkg.scripts, scripts);
+  const d = mergeAbsent(pkg.devDependencies, devDependencies);
+  const f = mergeAbsent(pkg, fields);
+
+  const next = { ...f.merged };
+  if (Object.keys(s.merged).length) next.scripts = s.merged;
+  if (Object.keys(d.merged).length) next.devDependencies = d.merged;
+
+  const trailingNewline = rawText.endsWith("\n") ? "\n" : "";
+  const text = JSON.stringify(next, null, indent) + trailingNewline;
+
+  return {
+    text,
+    added: { scripts: s.added, devDependencies: d.added, fields: f.added },
+    skipped: {
+      scripts: s.skipped,
+      devDependencies: d.skipped,
+      fields: f.skipped,
+    },
+  };
+}

package/src/playwright-install.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+import { spawnSync } from "child_process";
+import { realpathSync } from "fs";
+import { fileURLToPath } from "url";
+
+// Treat CI as active when the CI env var is present and not an explicit falsy
+// value. Most CI systems (including GitHub Actions) set CI=true.
+export function isCI(env = process.env) {
+  const v = env.CI;
+  if (v === undefined) return false;
+  return v !== "" && v !== "false" && v !== "0";
+}
+
+// --with-deps installs OS-level libraries and requires root, so it is only safe
+// (and only needed) on Linux CI runners. Everywhere else — dev laptops, NixOS,
+// macOS — install just the browser binary.
+export function playwrightInstallArgs({ ci, platform }) {
+  const args = ["install"];
+  if (ci && platform === "linux") args.push("--with-deps");
+  args.push("chromium");
+  return args;
+}
+
+export function run({ env = process.env, platform = process.platform } = {}) {
+  const args = [
+    "playwright",
+    ...playwrightInstallArgs({ ci: isCI(env), platform }),
+  ];
+  const result = spawnSync("npx", args, { stdio: "inherit" });
+  return result.status ?? 1;
+}
+
+// This file is both an importable module (unit tests import the pure functions)
+// and an executable bin. Guard the CLI action so `run()` — which shells out to
+// `playwright install` — fires only when the file is run directly, never on
+// import. When launched via the npm `.bin/doikayt-playwright-install` shim,
+// argv[1] is a symlink, so realpath both sides before comparing.
+function invokedDirectly() {
+  const entry = process.argv[1];
+  if (!entry) return false;
+  try {
+    return realpathSync(entry) === fileURLToPath(import.meta.url);
+  } catch {
+    return false;
+  }
+}
+
+if (invokedDirectly()) {
+  process.exit(run());
+}

package/src/postinstall.js

@@ -147,7 +147,7 @@ const missingTargets = [];
 if (!projectPkg.scripts?.["ci"]) {
   missingTargets.push({
     name: "ci",
-    hint: '  "ci": "npm run check-all-format && npm run test"',
+    hint: '  "ci": "prettier --check src/ && npm test"',
     nxNote: false,
   });
 }
@@ -170,7 +170,7 @@ if (!hasUpdateAllFormat) {
 if (!hasUpdateAllFormat) {
   missingTargets.push({
     name: "update-all-format",
-    hint: '  "update-all-format": "npm run update-code-formatting && npm run update-markdown-docs"',
+    hint: '  "update-all-format": "prettier --write src/"',
     nxNote: true,
   });
 }

package/src/templates/demo/README.md

@@ -0,0 +1,42 @@
+<!-- TOC:START -->
+<!-- TOC:END -->
+
+# Starter project
+
+> **Seeded by `init` — safe to replace.** These starter files (this README, a
+> `math-engine` component under `src/`, and `project.json`) exist so a brand-new
+> project can run its tests, publish on push, and watch the doc generator work
+> before you write any code. Replace them with your own whenever you like —
+> `init` printed the exact paths to delete.
+
+Run `npm run update-all-format` to fill the blocks below; GitHub renders the
+Mermaid diagrams inline from the fenced blocks.
+
+## Build Pipeline
+
+<!-- NX_GRAPH:START -->
+<!-- NX_GRAPH:END -->
+
+## Component Diagram
+
+<!-- UML:components:START -->
+<!-- UML:components:END -->
+
+## Components Table
+
+<!-- UML:components-table:START -->
+<!-- UML:components-table:END -->
+
+## Component Details
+
+<!-- UML:component-details:START -->
+<!-- UML:component-details:END -->
+
+## Try it
+
+```bash
+npm install                 # fetch the dev deps init declared
+npm test                    # the seeded vitest test passes
+npm run update-all-format   # fills the doc blocks above
+git commit -am "feat: initial version" && git push   # feat:/fix: trigger a publish
+```

package/src/templates/demo/project.json

@@ -0,0 +1,24 @@
+{
+  "name": "demo",
+  "targets": {
+    "install": {
+      "description": "Install npm dependencies"
+    },
+    "build": {
+      "description": "Compile TypeScript source to JavaScript",
+      "dependsOn": ["install"]
+    },
+    "lint": {
+      "description": "Run ESLint on TypeScript source files",
+      "dependsOn": ["install"]
+    },
+    "type-check": {
+      "description": "Type-check source without emitting",
+      "dependsOn": ["build"]
+    },
+    "test": {
+      "description": "Run unit tests with vitest",
+      "dependsOn": ["build"]
+    }
+  }
+}

package/src/templates/demo/src/index.ts

@@ -0,0 +1,7 @@
+// Starter file from `init` — replace with your own code.
+// Package entry point: re-exports the demo component so the built package has a
+// public surface to publish.
+export { MathEngine } from "./math-engine/MathEngine.js";
+export { MathError } from "./math-engine/MathError.js";
+export type { MathResult } from "./math-engine/MathResult.js";
+export type { Operation } from "./math-engine/Operation.js";

package/src/templates/demo/src/math-engine/MathEngine.test.ts

@@ -0,0 +1,24 @@
+// Starter file from `init` — replace with your own code.
+import { describe, test, expect } from "vitest";
+import { MathEngine } from "./MathEngine.js";
+import { MathError } from "./MathError.js";
+
+describe("MathEngine", () => {
+    const engine = new MathEngine();
+
+    test("add returns the sum and echoes the operation", () => {
+        expect(engine.add(3, 4)).toEqual({
+            value: 7,
+            operation: "add",
+            operands: [3, 4],
+        });
+    });
+
+    test("subtract returns the difference", () => {
+        expect(engine.subtract(10, 4).value).toBe(6);
+    });
+
+    test("rejects non-finite operands with a MathError", () => {
+        expect(() => engine.add(1, Infinity)).toThrow(MathError);
+    });
+});

package/src/templates/demo/src/math-engine/MathEngine.ts

@@ -0,0 +1,22 @@
+// Starter file from `init` — replace with your own code.
+import { MathError } from "./MathError.js";
+import type { MathResult } from "./MathResult.js";
+import type { Operation } from "./Operation.js";
+
+export class MathEngine {
+    add(a: number, b: number): MathResult {
+        this.validate("add", a, b);
+        return { value: a + b, operation: "add", operands: [a, b] };
+    }
+
+    subtract(a: number, b: number): MathResult {
+        this.validate("subtract", a, b);
+        return { value: a - b, operation: "subtract", operands: [a, b] };
+    }
+
+    private validate(op: Operation, a: number, b: number): void {
+        if (!Number.isFinite(a) || !Number.isFinite(b)) {
+            throw new MathError(op, "Operands must be finite numbers");
+        }
+    }
+}

package/src/templates/demo/src/math-engine/MathError.ts

@@ -0,0 +1,11 @@
+import type { Operation } from "./Operation.js";
+
+export class MathError extends Error {
+    readonly operation: Operation;
+
+    constructor(operation: Operation, message: string) {
+        super(message);
+        this.name = "MathError";
+        this.operation = operation;
+    }
+}

package/src/templates/demo/src/math-engine/MathResult.ts

@@ -0,0 +1,7 @@
+import type { Operation } from "./Operation.js";
+
+export interface MathResult {
+    value: number;
+    operation: Operation;
+    operands: [number, number];
+}

package/src/templates/demo/src/math-engine/Operation.ts

@@ -0,0 +1 @@
+export type Operation = "add" | "subtract";

package/src/templates/demo/src/math-engine/_COMPONENT_INFO.md

@@ -0,0 +1,2 @@
+The math-engine component: a small, dependency-free arithmetic core. It validates
+operands and returns a structured result describing the operation performed.

package/src/templates/playwright.config.ts

@@ -0,0 +1,17 @@
+import { definePlaywrightConfig } from "@doikayt/typescript-build-config/playwright";
+
+// Seeded by `typescript-build-config init`. definePlaywrightConfig merges the
+// NixOS system-Chromium path automatically; fill in the TODOs for your app.
+export default definePlaywrightConfig({
+  testDir: "tests/e2e",
+  // Playwright starts your app before the run and waits for it to be reachable,
+  // so `npm run test:e2e` needs no separate server step in CI.
+  webServer: {
+    command: "npm run start", // TODO: the command that starts your app
+    url: "http://localhost:3000", // TODO: the URL Playwright waits for
+    reuseExistingServer: true,
+  },
+  use: {
+    baseURL: "http://localhost:3000", // TODO: base URL for page.goto("/")
+  },
+});

package/src/templates/vitest.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from "vitest/config";
+
+// Seeded by `typescript-build-config init`. Vitest runs TypeScript with zero
+// config, so everything here is optional — it exists as a signpost for the
+// common knobs. Uncomment and adjust as your project needs.
+export default defineConfig({
+  test: {
+    // include: ["src/**/*.test.ts"],
+    // environment: "node", // or "jsdom" / "happy-dom" for DOM tests
+    // coverage: { provider: "v8", reporter: ["text", "html"] },
+  },
+});

package/src/top-level/tsconfig.json

@@ -4,5 +4,6 @@
         "outDir": "dist",
         "rootDir": "src"
     },
-    "include": ["src"]
+    "include": ["src"],
+    "exclude": ["node_modules", "dist", "src/**/*.test.ts"]
 }