@doikayt/typescript-build-config 0.1.15 → 0.1.17

package/README.md

@@ -111,33 +111,41 @@ small single-purpose scripts, and the check side mirrors the write side:
 | --- | --- |
 | `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. |
+| `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, …). |
 
-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.
+`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`, `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`.
+`check-all-format`, and their sub-tasks), declares `vitest` +
+`@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)
 
@@ -496,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.15",
+  "version": "0.1.17",
   "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'.",

package/src/canonical-scripts.js

@@ -1,10 +1,11 @@
 // 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";
@@ -21,12 +22,10 @@ export function canonicalScripts({ ui = false } = {}) {
       "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";
+  if (library) scripts.prepack = "npm run build";
 
   return scripts;
 }
@@ -37,21 +36,26 @@ export function devDependencyNames({ ui = false } = {}) {
   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: {
+// 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",
       },
-    },
-    files: ["dist"],
-  };
+    };
+    fields.files = ["dist"];
+  } else {
+    fields.private = true;
+  }
+  return fields;
 }

package/src/init.js

@@ -62,17 +62,37 @@ export async function runInit({
   const pkgPath = resolve(cwd, "package.json");
   const raw = readFileSync(pkgPath, "utf8");
 
+  // Collect every answer up front, before doing any work or printing next
+  // steps, so the flow reads: ask everything → act → report.
   const ui = await prompt(
-    "Is this a UI project that needs Playwright (e2e)? [y/N] ",
+    "Is this a UI project that needs Playwright (e2e)? Default is No. [y/N] ",
   );
 
-  const scripts = canonicalScripts({ ui });
+  const library = await prompt(
+    "Is this a publishable library (published to npm)? Default is No — an\n" +
+      "app/CLI, marked private so it is never published. [y/N] ",
+  );
+
+  const wantDemo = await prompt(
+    "Scaffold a starter demo (minimal src module + README + project.json) so\n" +
+      "you can build, test, and release immediately? Default is No; existing\n" +
+      "files are never overwritten. [y/N] ",
+  );
+
+  const scripts = canonicalScripts({ ui, library });
   const devDependencies = resolveDevVersions(devDependencyNames({ ui }));
 
   const { text, added, skipped } = applyToPackageJson(raw, {
     scripts,
     devDependencies,
-    fields: packageFields(),
+    fields: packageFields({ library }),
+    // `npm init -y` seeds these placeholders; treat them as unset so the
+    // canonical `test` script and (for a library) `main` replace them instead of
+    // shadowing them.
+    replaceDefaults: {
+      scripts: { test: 'echo "Error: no test specified" && exit 1' },
+      fields: { main: "index.js" },
+    },
   });
   writeFileSync(pkgPath, text);
 
@@ -85,6 +105,16 @@ export async function runInit({
     (result === "seeded" ? seededConfigs : keptConfigs).push(name);
   }
 
+  const demo = wantDemo
+    ? scaffoldDemo({ cwd })
+    : {
+        scaffolded: false,
+        reason: "declined",
+        wrote: [],
+        skipped: [],
+        paths: [],
+      };
+
   const report = (label, keys) => {
     if (keys.length) log(`${label}: ${keys.join(", ")}`);
   };
@@ -96,28 +126,28 @@ export async function runInit({
   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.");
+  report("Demo seeded", demo.wrote);
+  report("Demo kept existing", demo.skipped);
 
-  const demo = await maybeScaffoldDemo({ cwd, prompt, log });
+  log("");
+  if (demo.scaffolded) {
+    log(
+      "Next: `npm install`, then `npm test` and `npm run update-all-format`, " +
+        "then commit and push to cut a release.",
+    );
+    log(`To remove the starter files later: rm -r ${demo.paths.join(" ")}`);
+  } else {
+    log("Next: run `npm install` to fetch the newly declared devDependencies.");
+  }
 
   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: [] };
-  }
-
+// Seed a minimal starter into a new project: a 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. Writes
+// files only and returns what it did; the caller reports and prints next steps.
+function scaffoldDemo({ cwd }) {
   const demoTemplate = resolve(templatesDir, "demo");
   const wrote = [];
   const skipped = [];
@@ -147,13 +177,5 @@ async function maybeScaffoldDemo({ cwd, prompt, log }) {
     }
   }
 
-  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

@@ -38,14 +38,33 @@ export function detectIndent(text) {
  *   added: { scripts: string[], devDependencies: string[], fields: string[] },
  *   skipped: { scripts: string[], devDependencies: string[], fields: string[] }
  * }} new file text, plus keys added vs. skipped (already present)
+ *
+ * `replaceDefaults` names placeholder values that `npm init -y` inserts (e.g.
+ * `scripts.test: 'echo "Error: no test specified" && exit 1'`, `main: "index.js"`).
+ * A key whose current value exactly equals its placeholder is treated as unset,
+ * so a canonical value can replace it instead of being skipped as "present".
  */
 export function applyToPackageJson(
   rawText,
-  { scripts = {}, devDependencies = {}, fields = {} } = {},
+  {
+    scripts = {},
+    devDependencies = {},
+    fields = {},
+    replaceDefaults = {},
+  } = {},
 ) {
   const pkg = JSON.parse(rawText);
   const indent = detectIndent(rawText);
 
+  const stripDefaults = (obj, defaults = {}) => {
+    if (!obj) return;
+    for (const [key, placeholder] of Object.entries(defaults)) {
+      if (obj[key] === placeholder) delete obj[key];
+    }
+  };
+  stripDefaults(pkg, replaceDefaults.fields);
+  stripDefaults(pkg.scripts, replaceDefaults.scripts);
+
   const s = mergeAbsent(pkg.scripts, scripts);
   const d = mergeAbsent(pkg.devDependencies, devDependencies);
   const f = mergeAbsent(pkg, fields);

package/src/templates/demo/README.md

@@ -38,5 +38,5 @@ Mermaid diagrams inline from the fenced blocks.
 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
+git commit -am "feat: initial version" && git push   # feat:/fix: cut a release (npm publish if a library)
 ```