@doikayt/typescript-build-config 0.1.26 → 0.1.28

package/README.md

@@ -6,15 +6,18 @@ Shared build configuration presets for TypeScript-based projects.
 - [@doikayt/typescript-build-config](#doikayttypescript-build-config)
   - [Purpose](#purpose)
   - [Quick start](#quick-start)
+    - [1. One-time machine setup (once per machine)](#1-one-time-machine-setup-once-per-machine)
+    - [2. Create a new project (repeatable)](#2-create-a-new-project-repeatable)
+      - [dk-scaffold](#dk-scaffold)
+      - [Run dk-scaffold's steps individually](#run-dk-scaffolds-steps-individually)
+    - [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,30 +47,47 @@ 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 on GitHub's CI servers, 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
+git clone https://github.com/doikayt/typescript-build-config.git   # HTTPS: no SSH key needed
 cd typescript-build-config
 ./assets/shell/install.sh   # adds `source assets/shell/aliases.sh` to your rc (idempotent)
 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 (repeatable)
+
+The two paths below are **alternatives that reach the same result** — a project
+wired to this base package.
+
+#### dk-scaffold
+
+`dk-scaffold` is the one-command wrapper that also (optionally) creates the
+GitHub repo and pushes it. Just run it with a first argument naming your project
+and a second indicating `lib` (a published library) or `app` (a standalone
+app/utility, the default) — see [library vs app](#usage) and
 [Packaging concepts](docs/packaging-concepts.md):
 
 ```bash
 dk-scaffold my-project lib
 ```
 
-Or do it by hand / in an **existing** project — the same steps `dk-scaffold`
-runs ([Installation](#installation) and [Usage](#usage) explain each):
+#### Run dk-scaffold's steps individually
+
+The steps below mirror the work `dk-scaffold` does under the hood — either for a
+brand-new project or to adopt Doikayt standard build config into an existing one.
+([Installation](#installation) and [Usage](#usage) explain each in detail.)
 
 ```bash
 npx @doikayt/typescript-build-config new                  # npm init -y + @doikayt scope
@@ -76,6 +96,53 @@ npx @doikayt/typescript-build-config init                 # scripts, deps, publi
 npm install                                               # fetch declared devDependencies
 ```
 
+### Trying it out
+
+`dk-scaffold` does a lot under the hood, so the best way to get familiar with it
+is to run it at the three levels it supports — each requiring a little more setup
+than the last, and revealing a little more of the process. Each level scaffolds a
+throwaway **app** (nothing publishes) unless noted. Do the one-time
+[machine setup](#1-one-time-machine-setup-once-per-machine) first so `dk-scaffold`
+is on your PATH.
+
+**Level 0 — local (no external GitHub/npm accounts needed).** Scaffold and run
+the same gate CI runs — no GitHub repo, no push:
+
+```bash
+dk-scaffold my-demo --local
+```
+
+That single command 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.** Bring a GitHub account and the `gh` CLI.
+Sign in, point the wrapper at your account, and drop `--local`:
+
+```bash
+gh auth login                                # one-time: sign in to GitHub
+export DOIKAYT_ORG=<your-github-username>    # target owner for the repo
+dk-scaffold my-demo                          # app (private) — no npm creds
+```
+
+Now it creates the repo and pushes — and you see what Level 0 couldn't: the
+**mermaid diagrams rendered** (example
+[here](https://github.com/doikayt/build-tools/blob/main/javascript/tooling-core/README.md#package-structure))
+and the **CI job go green** in Actions (example:
+[this project's runs](https://github.com/doikayt/typescript-build-config/actions)).
+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.** The last rung swaps the app for a `lib`
+and adds your own npm scope + `NPM` secret — then you see the one thing the other
+levels can't: `changeset publish` shipping a real, dist-only 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 +202,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 +227,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 +243,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 +260,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 +272,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 +283,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.26",
+  "version": "0.1.28",
   "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"
   },