@doikayt/typescript-build-config 0.1.27 → 0.1.29

package/README.md

@@ -6,6 +6,10 @@ 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)
@@ -46,34 +50,44 @@ via the pipeline files it installs into each consumer repo and the canonical rel
 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_.
+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 — 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:
+### 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 — 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
+### 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
@@ -84,42 +98,56 @@ npm install                                               # fetch declared devDe
 
 ### 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.
+`dk-scaffold` does a lot under the hood, so the best way to get familiar with it
+is to run it at the two 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 accounts.** Scaffold and run the same gate CI runs — no
-GitHub repo, no push:
+**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
 ```
 
-Under the hood it runs `init` (demo=yes, app, no Playwright) then `npm run ci`.
+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.** Add a GitHub account and `gh`
-(`gh auth login`). Point the wrapper at your account and drop `--local`:
+**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
-export DOIKAYT_ORG=<your-github-username>   # target owner for the repo
+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
 ```
 
-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.)
+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.)
+
+
+The screen cast below shows the process:
+
+<p align="center">
+  <img
+    src="docs/demo.gif"
+    width="720"
+    alt="update-markdown-toc demo">
+</p>
+
+
 
-**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
 

package/package.json

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