@doikayt/typescript-build-config 0.1.25 → 0.1.27

package/README.md

@@ -6,15 +6,14 @@ Shared build configuration presets for TypeScript-based projects.
 - [@doikayt/typescript-build-config](#doikayttypescript-build-config)
   - [Purpose](#purpose)
   - [Quick start](#quick-start)
+    - [Trying it out](#trying-it-out)
   - [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)
+    - [Optional Playwright config for Web / UI testing](#optional-playwright-config-for-web--ui-testing)
     - [Existing project](#existing-project)
-    - [Trying it out (demo + scratch repo)](#trying-it-out-demo--scratch-repo)
   - [Dependency Strategy](#dependency-strategy)
   - [Current Contents](#current-contents)
   - [Delivery Model](#delivery-model)
@@ -44,11 +43,15 @@ via the pipeline files it installs into each consumer repo and the canonical rel
 
 ## Quick start
 
-From a fresh machine to a pushed, scaffolded repo. Steps are minimal here — each
-links to the section that explains _what_ and _why_.
+These steps set up — in a fresh "new-developer" environment — a local git repo
+with a skeleton demo app plus all the standard Doikayt build configuration:
+tooling that auto-documents the code in the repo and lets it be pushed to
+GitHub, built, and (for a library) published to npm. Steps are minimal here —
+each links to the section that explains _what_ and _why_.
 
-**1. One-time machine setup.** Clone this base repo and install the shared team
-[shell aliases](#team-shell-aliases):
+**1. One-time machine setup — once per machine.** Clone this base repo and
+install the shared team [shell aliases](#team-shell-aliases). This only sets up
+the aliases (`dk-scaffold`, `mkrepo`); it does **not** configure any project:
 
 ```bash
 git clone git@github.com:doikayt/typescript-build-config.git
@@ -57,9 +60,12 @@ cd typescript-build-config
 exec $SHELL                 # reload
 ```
 
-**2. Create a new project.** One command creates the GitHub repo, scaffolds it
-(build config + a runnable demo), and pushes it — choose `lib` (published) or
-`app` (private, the default); see [library vs app](#usage) and
+**2. Create a new project — once per project.** The two paths below are
+**alternatives that reach the same result** — a project wired to this base
+package. `dk-scaffold` is the one-command wrapper that *also* creates the GitHub
+repo and pushes it; the hand-run steps are what it runs under the hood. It
+scaffolds build config + a runnable demo — choose `lib` (published) or `app`
+(private, the default); see [library vs app](#usage) and
 [Packaging concepts](docs/packaging-concepts.md):
 
 ```bash
@@ -76,6 +82,45 @@ npx @doikayt/typescript-build-config init                 # scripts, deps, publi
 npm install                                               # fetch declared devDependencies
 ```
 
+### Trying it out
+
+One wrapper, three levels — each adds one thing you bring and one thing you see.
+Each scaffolds a throwaway **app** (nothing publishes) unless noted. Do the
+one-time [Quick start step 1](#quick-start) first so `dk-scaffold` is on your
+PATH.
+
+**Level 0 — local, no accounts.** Scaffold and run the same gate CI runs — no
+GitHub repo, no push:
+
+```bash
+dk-scaffold my-demo --local
+```
+
+Under the hood it runs `init` (demo=yes, app, no Playwright) then `npm run ci`.
+You'll see the vitest demo tests pass, `npm run build` emit `dist/` + type
+declarations, and `update-all-format` fill the README's TOC + UML markers
+(mermaid **source** — rendered at Level 1). `npm publish --dry-run` **refuses** —
+proof the app archetype never publishes.
+
+**Level 1 — push to your own GitHub.** Add a GitHub account and `gh`
+(`gh auth login`). Point the wrapper at your account and drop `--local`:
+
+```bash
+export DOIKAYT_ORG=<your-github-username>   # target owner for the repo
+dk-scaffold my-demo                          # app (private) — no npm creds
+```
+
+It creates the repo and pushes. On GitHub you'll see the **mermaid diagrams
+rendered** and the **CI job go green**. Push a follow-up **`feat:`** commit and
+the **release job** version-bumps + tags — nothing published (app). (The initial
+`chore: scaffold` push releases nothing; `feat:` / `fix:` triggers it.)
+
+**Level 2 — publish to your own npm.** Scaffold a `lib` and bring your own npm
+scope + `NPM` secret to watch `changeset publish` ship a real package. Full
+procedure: [docs/verification-runbook.md](docs/verification-runbook.md);
+non-`@doikayt`-scope setup:
+[docs/verification-byo-prerequisites.md](docs/verification-byo-prerequisites.md).
+
 ## Design Goals
 
 The  package housed in this repo is designed to be 'upstream-most' -- i.e., all other
@@ -135,10 +180,12 @@ 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.
+[canonical npm-script set](#the-canonical-script-set), declare the dev
+dependencies those scripts need — `vitest`, `@doikayt/autogen-markdown-doc`,
+`typescript`, and `@changesets/cli` (the release pipeline needs it) — and seed a
+commented `vitest.config.ts`. `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
 
@@ -158,8 +205,10 @@ small single-purpose scripts, and the check side mirrors the write side:
 | `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):
+`init` also asks whether the project is a **publishable library**. That answer
+sets the `package.json` fields that control publishing — `main`, `types`,
+`exports`, `files`, `prepack`, `private` — non-destructively (it merges, it
+doesn't overwrite your other keys):
 
 - **Library** — `main` / `types` / `exports` → `dist/index.js`, `files: ["dist"]`,
   and `prepack`, so it publishes a compiled, typed ESM package on push. `init`
@@ -172,7 +221,15 @@ publish config accordingly (non-destructively):
 `dist/`, publish fields, library vs app)? See
 [Packaging concepts](docs/packaging-concepts.md) for the background.
 
-### Console / CLI project
+### Optional Playwright config for Web / UI testing
+
+The above section covers _what_ `init` decides; the two recipes below are _how_
+you run it. They differ only in the **Playwright?** answer — `n` for a
+console/CLI or plain library, `y` for a UI / web project that needs end-to-end
+tests. Library-vs-app is an orthogonal choice, so either shape can still be
+published or kept private.
+
+**Console / CLI or plain library — answer `n`:**
 
 ```bash
 npx @doikayt/typescript-build-config new              # npm init -y + @doikayt scope
@@ -181,15 +238,9 @@ npx @doikayt/typescript-build-config init             # answer "n" to Playwright
 npm install                                            # fetch the declared devDependencies
 ```
 
-`init` writes the canonical scripts (`ci`, `build`, `test`, `update-all-format`,
-`check-all-format`, and their sub-tasks), declares `vitest` +
-`@doikayt/autogen-markdown-doc` + `typescript` + `@changesets/cli` (the release
-pipeline needs it), 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)
+**UI / web — answer `y`:** injects the end-to-end setup — 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.
 
 ```bash
 npx @doikayt/typescript-build-config new              # npm init -y + @doikayt scope
@@ -199,11 +250,9 @@ 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.
+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
 
@@ -212,22 +261,6 @@ 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)).
 
-### Trying it out (demo + scratch repo)
-
-Answer **yes** to the demo prompt and `init` seeds a minimal starter — a `src/`
-module, a `README` with doc-generator markers, and a `project.json` — so a
-brand-new project builds, tests, and (for a library) publishes on push.
-
-To exercise a scaffold end-to-end without standing up a repo, push it to the
-shared throwaway repo
-**[`doikayt/scratch-pad`](https://github.com/doikayt/scratch-pad)** (force-overwrite
-each run). The full procedure — for both a library and an app, with what to look
-for at each step — is in [docs/verification-runbook.md](docs/verification-runbook.md):
-
-- [Pushing to the scratch repo](docs/verification-runbook.md#pushing-to-a-reusable-scratch-repo)
-- [Testing publish without cluttering npm](docs/verification-runbook.md#testing-publish-without-cluttering-npm)
-  — dry-run / verdaccio, and deleting a real test publish afterward.
-
 ## Dependency Strategy
 
 `eslint` and `prettier` are listed as `dependencies` and are pulled in

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doikayt/typescript-build-config",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "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'.",
@@ -26,8 +26,8 @@
   "scripts": {
     "prepack": "echo no build step required",
     "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",
+    "update-all-format": "prettier --write src/ && update-markdown-toc README.md && update-markdown-toc docs/verification-runbook.md",
+    "check-format": "prettier --check src/ && update-markdown-toc --check README.md && update-markdown-toc --check docs/verification-runbook.md",
     "ci": "npm run check-format && node --test tests/*.test.js",
     "test": "node --test tests/*.test.js"
   },