@doikayt/typescript-build-config 0.1.14 → 0.1.16

package/README.md

@@ -110,25 +110,42 @@ 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`). |
 | `test` | Unit / integration tests (`vitest run`). |
 | `test:e2e` | End-to-end tests (`playwright test`) — UI projects only. |
+| `prepack` | Runs `build` before packing, so `changeset publish` ships compiled `dist/` — **libraries 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, …). |
 
+`init` also asks whether the project is a **publishable library**, which sets the
+publish config accordingly (non-destructively):
+
+- **Library** — `main` / `types` / `exports` → `dist/index.js`, `files: ["dist"]`,
+  and `prepack`, so it publishes a compiled, typed ESM package on push.
+- **App / CLI** (the default) — marked `private: true`, so a release versions and
+  tags it but never publishes to npm.
+
+`type: "module"` and `build` are set either way. New to these terms (compiled
+`dist/`, publish fields, library vs app)? See
+[Packaging concepts](docs/packaging-concepts.md) for the background.
+
 ### 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
+npx @doikayt/typescript-build-config init             # answer "n" to Playwright; "n" (app) or "y" (library)
 npm install                                            # fetch the declared devDependencies
 ```
 
-`init` writes the canonical scripts (`ci`, `test`, `update-all-format`,
+`init` writes the canonical scripts (`ci`, `build`, `test`, `update-all-format`,
 `check-all-format`, and their sub-tasks), declares `vitest` +
-`@doikayt/autogen-markdown-doc`, and seeds a commented `vitest.config.ts`.
+`@doikayt/autogen-markdown-doc` + `typescript`, and seeds a commented
+`vitest.config.ts`. Answering the "publishable library?" prompt sets the publish
+config — `private` for an app, or `prepack` + the `dist/`-based fields for a
+library (see [The canonical script set](#the-canonical-script-set)).
 
 ### UI / web project (with Playwright e2e)
 
@@ -487,6 +504,10 @@ To auto-fix formatting before verifying:
 npm run update-all-format && npm run ci
 ```
 
+To verify end-to-end that `init` scaffolds and ships both a library and an app —
+by hand, with what to look for at each step — follow
+[docs/e2e-verification.md](docs/e2e-verification.md).
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doikayt/typescript-build-config",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "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'.",
@@ -28,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

@@ -1,16 +1,18 @@
 // 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).
+// thin targets that delegate to `npm run <x>` — never the reverse. Two axes vary
+// the set: UI/console (Playwright e2e) and library/app. `build` is universal
+// (both archetypes compile); only a publishable library adds `prepack`, which
+// builds dist/ at publish time so `changeset publish` ships compiled output.
 
-export function canonicalScripts({ ui = false } = {}) {
+export function canonicalScripts({ ui = false, library = 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",
@@ -23,12 +25,37 @@ export function canonicalScripts({ ui = false } = {}) {
   };
 
   if (ui) scripts["test:e2e"] = "doikayt-playwright-install && playwright test";
+  if (library) scripts.prepack = "npm run build";
 
   return scripts;
 }
 
 export function devDependencyNames({ ui = false } = {}) {
-  const names = ["vitest", "@doikayt/autogen-markdown-doc"];
+  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). `type: "module"`
+// is universal. A publishable **library** also gets the dist/-based entry points
+// (main/types/exports) and the tarball allow-list (files), assuming the canonical
+// src/index.ts entry. An **app** is instead marked `private` so `changeset
+// publish` never publishes it — its release is a version bump + tag only. Either
+// way, fields a consumer already set are left untouched by the caller.
+export function packageFields({ library = false } = {}) {
+  const fields = { type: "module" };
+  if (library) {
+    fields.main = "dist/index.js";
+    fields.types = "dist/index.d.ts";
+    fields.exports = {
+      ".": {
+        types: "./dist/index.d.ts",
+        default: "./dist/index.js",
+      },
+    };
+    fields.files = ["dist"];
+  } else {
+    fields.private = true;
+  }
+  return fields;
+}

package/src/init.js

@@ -1,8 +1,19 @@
-import { readFileSync, writeFileSync, existsSync, copyFileSync } from "fs";
+import {
+  readFileSync,
+  writeFileSync,
+  existsSync,
+  copyFileSync,
+  mkdirSync,
+  readdirSync,
+} from "fs";
 import { resolve } from "path";
 import { fileURLToPath } from "url";
 import { createInterface } from "readline";
-import { canonicalScripts, devDependencyNames } from "./canonical-scripts.js";
+import {
+  canonicalScripts,
+  devDependencyNames,
+  packageFields,
+} from "./canonical-scripts.js";
 import { applyToPackageJson } from "./package-json.js";
 import { resolveVersions } from "./dep-versions.js";
 
@@ -16,6 +27,21 @@ function seedFile(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 });
@@ -40,12 +66,18 @@ export async function runInit({
     "Is this a UI project that needs Playwright (e2e)? [y/N] ",
   );
 
-  const scripts = canonicalScripts({ ui });
+  const library = await prompt(
+    "Is this a publishable library (published to npm)? Apps/CLIs answer No and\n" +
+      "are marked private so they are never published. [y/N] ",
+  );
+
+  const scripts = canonicalScripts({ ui, library });
   const devDependencies = resolveDevVersions(devDependencyNames({ ui }));
 
   const { text, added, skipped } = applyToPackageJson(raw, {
     scripts,
     devDependencies,
+    fields: packageFields({ library }),
   });
   writeFileSync(pkgPath, text);
 
@@ -65,10 +97,68 @@ export async function runInit({
   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.");
 
-  return { added, skipped, seededConfigs, keptConfigs };
+  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 release 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

@@ -28,24 +28,29 @@ export function detectIndent(text) {
  * 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>}} additions
+ * @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[] },
- *   skipped: { scripts: string[], devDependencies: 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 = {} } = {},
+  { 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 = { ...pkg };
+  const next = { ...f.merged };
   if (Object.keys(s.merged).length) next.scripts = s.merged;
   if (Object.keys(d.merged).length) next.devDependencies = d.merged;
 
@@ -54,7 +59,11 @@ export function applyToPackageJson(
 
   return {
     text,
-    added: { scripts: s.added, devDependencies: d.added },
-    skipped: { scripts: s.skipped, devDependencies: d.skipped },
+    added: { scripts: s.added, devDependencies: d.added, fields: f.added },
+    skipped: {
+      scripts: s.skipped,
+      devDependencies: d.skipped,
+      fields: f.skipped,
+    },
   };
 }

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: cut a release (npm publish if a library)
+```

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/top-level/tsconfig.json

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