@doikayt/typescript-build-config 0.1.20 → 0.1.22

package/README.md

@@ -5,6 +5,7 @@ Shared build configuration presets for TypeScript-based projects.
 <!-- TOC:START -->
 - [@doikayt/typescript-build-config](#doikayttypescript-build-config)
   - [Purpose](#purpose)
+  - [Quick start](#quick-start)
   - [Design Goals](#design-goals)
     - [What each component is for](#what-each-component-is-for)
   - [Installation](#installation)
@@ -13,6 +14,7 @@ Shared build configuration presets for TypeScript-based projects.
     - [Console / CLI project](#console--cli-project)
     - [UI / web project (with Playwright e2e)](#ui--web-project-with-playwright-e2e)
     - [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)
@@ -23,6 +25,7 @@ Shared build configuration presets for TypeScript-based projects.
       - [NX projects](#nx-projects)
     - [The `update-all-format` target](#the-update-all-format-target)
   - [Publishing](#publishing)
+  - [Team shell aliases](#team-shell-aliases)
   - [For Maintainers](#for-maintainers)
     - [Clone and install](#clone-and-install)
     - [Run the full CI suite](#run-the-full-ci-suite)
@@ -39,6 +42,40 @@ The plugin encapsulates common build **policy** and release **workflow logic**
 via the pipeline files it installs into each consumer repo and the canonical release process in
 [docs/RELEASE-PROCESS.md](docs/RELEASE-PROCESS.md).
 
+## 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_.
+
+**1. One-time machine setup.** Clone this base repo and install the shared team
+[shell aliases](#team-shell-aliases):
+
+```bash
+git clone git@github.com:doikayt/typescript-build-config.git
+cd typescript-build-config
+./shell-assets/install.sh   # adds `source shell-assets/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
+[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):
+
+```bash
+npx @doikayt/typescript-build-config new                  # npm init -y + @doikayt scope
+npm install --save-dev @doikayt/typescript-build-config   # postinstall seeds configs + pipeline
+npx @doikayt/typescript-build-config init                 # scripts, deps, publish config, demo
+npm install                                               # fetch declared devDependencies
+```
+
 ## Design Goals
 
 The  package housed in this repo is designed to be 'upstream-most' -- i.e., all other
@@ -78,11 +115,13 @@ is _why_.)
 | **Convention checks** — postinstall warns on missing `ci` / `update-all-format` | An install-time nudge toward the shared command surface | Consistency |
 | **`ci` gate** — `release.yml` runs `npm run ci` | Fail-closed enforcement: a repo that ignores the convention cannot release | Consistency (hard teeth) |
 | **Policy doc** — `docs/RELEASE-PROCESS.md`, linked never copied | One canonical release policy, impossible to drift | Consistency |
-| **Assets** — `assets/*` seeded into `docs/assets/` | Shared brand logos with no per-repo copies to maintain | Minimal setup |
+| **Assets** — `image-assets/*` seeded into `docs/assets/` | Shared brand logos with no per-repo copies to maintain | Minimal setup |
+| **Shell aliases** — `shell-assets/aliases.sh`, cloned + sourced (never shipped to npm) | One standard way for the team to create and scaffold repos (`mkrepo`, `dk-*`) | Consistency |
 
-The two goals map onto two lifecycle phases — **delivery** (getting canonical
-artifacts into a consuming repo) and **enforcement** (keeping that repo conformant over
-time). Each has its own top-level section below.
+The two goals map onto two lifecycle phases — **[delivery](#delivery-model)**
+(getting canonical artifacts into a consuming repo) and
+**[enforcement](#enforcement-model)** (keeping that repo conformant over time).
+Each has its own top-level section below.
 
 ## Installation
 
@@ -136,7 +175,7 @@ publish config accordingly (non-destructively):
 ### Console / CLI project
 
 ```bash
-npm init -y                                            # if starting fresh
+npx @doikayt/typescript-build-config new              # npm init -y + @doikayt scope
 npm install --save-dev @doikayt/typescript-build-config
 npx @doikayt/typescript-build-config init             # answer "n" to Playwright; "n" (app) or "y" (library)
 npm install                                            # fetch the declared devDependencies
@@ -153,7 +192,7 @@ library (see [The canonical script set](#the-canonical-script-set)).
 ### UI / web project (with Playwright e2e)
 
 ```bash
-npm init -y
+npx @doikayt/typescript-build-config new              # npm init -y + @doikayt scope
 npm install --save-dev @doikayt/typescript-build-config
 npx @doikayt/typescript-build-config init             # answer "y" to the Playwright prompt
 npm install
@@ -173,6 +212,22 @@ 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
@@ -185,6 +240,8 @@ versions of these tools may produce peer dependency conflicts.
 
 ## Current Contents
 
+- `new` command (`npx @doikayt/typescript-build-config new`) — runs `npm init -y`
+  then scopes the package name to `@doikayt` (an existing scope is kept)
 - `init` scaffolder CLI (`npx @doikayt/typescript-build-config init`) — writes
   the canonical npm-script set, declares dev dependencies, and seeds config
   templates (see [Usage](#usage))
@@ -220,7 +277,7 @@ versions of these tools may produce peer dependency conflicts.
   });
   ```
 
-- Brand assets (`assets/doikayt-logo.png`, `assets/doikayt-logo.svg`) — shared logos for use
+- Brand assets (`image-assets/doikayt-logo.png`, `image-assets/doikayt-logo.svg`) — shared logos for use
   across all `@doikayt` project READMEs and documentation
 
 ## Delivery Model
@@ -248,7 +305,7 @@ components.
         │  presets  eslint  prettier  tsconfig  playwright│
         │  stubs       src/top-level/*                    │
         │  pipeline    src/pipeline/*                     │
-        │  assets      assets/*                           │
+        │  assets      image-assets/*                     │
         │  policy      docs/RELEASE-PROCESS.md            │
         └─────────┬───────────────┬───────────────┬───────┘
                   │               │               │
@@ -300,6 +357,16 @@ components.
   their own contributor docs (as the consumer box shows) — never copied, so it cannot
   drift.
 
+**Beyond consumer repos — the shell aliases.** The five components above all reach
+a _consuming repo_ through npm (channels 1–3). The team
+[shell aliases](#team-shell-aliases) are the exception: they target the
+_developer's machine_, not a repo, through a fourth channel — **cloned and
+sourced** (`git clone` this repo + `source shell-assets/aliases.sh`, via
+`shell-assets/install.sh`). npm never touches them and they never land in a consumer's
+`package.json` or tree. Same goal (a standard way to create repos), different
+destination — which is why they sit outside the five-components / three-channels
+model rather than as a sixth row in it.
+
 ## Enforcement Model
 
 _Phase 2 of 2: keeping a repo **conformant** over time, once delivery has seeded
@@ -473,6 +540,19 @@ release job until one is committed.
 **Manual publish (emergency):** trigger the workflow manually via
 **GitHub Actions → CI / Release → Run workflow** on the `main` branch.
 
+## Team shell aliases
+
+Installed by [Quick start](#quick-start) step 1 (or manually: add
+`source <clone-path>/shell-assets/aliases.sh` to your shell rc). They require `gh`
+(authenticated) and `node`/`npm`.
+
+| Alias | What it does |
+| --- | --- |
+| `mkrepo <name>` | Create a public repo in the `doikayt` org (guards against duplicates). |
+| `dk-new` | `npm init -y` + `@doikayt` scope. |
+| `dk-init` | Scaffold the build config into the current project. |
+| `dk-scaffold <name> [lib\|app]` | Create the repo, scaffold, and push — one command (defaults to app). |
+
 ## For Maintainers
 
 ### Clone and install
@@ -509,7 +589,7 @@ 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).
+[docs/verification-runbook.md](docs/verification-runbook.md).
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doikayt/typescript-build-config",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "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'.",
@@ -21,7 +21,7 @@
   "files": [
     "src/",
     "src/top-level/.gitignore",
-    "assets/"
+    "image-assets/"
   ],
   "scripts": {
     "prepack": "echo no build step required",

package/src/cli.js

@@ -2,9 +2,10 @@
 // Main CLI entry for this package, registered as the `typescript-build-config`
 // bin. Invoked as `npx @doikayt/typescript-build-config <subcommand>` — npx
 // resolves the bin whose name matches the package. argv[2] is the subcommand
-// (argv[0]=node, argv[1]=this file). Today the only subcommand is `init`; this
-// dispatcher is the seam where future ones (e.g. `check-conventions`) plug in.
+// (argv[0]=node, argv[1]=this file). This dispatcher is the seam where future
+// subcommands (e.g. `check-conventions`) plug in.
 import { runInit } from "./init.js";
+import { runNew } from "./new-package.js";
 
 const sub = process.argv[2];
 
@@ -18,9 +19,19 @@ if (sub === "init") {
       process.exit(1);
     },
   );
+} else if (sub === "new") {
+  // `npm init -y` + @doikayt scope. Synchronous (spawnSync).
+  try {
+    runNew();
+    process.exit(0);
+  } catch (err) {
+    console.error(err?.message ?? err);
+    process.exit(1);
+  }
 } else {
   console.error(
-    `Unknown command: ${sub ?? "(none)"}\nUsage: typescript-build-config init`,
+    `Unknown command: ${sub ?? "(none)"}\n` +
+      `Usage: typescript-build-config <new|init>`,
   );
   process.exit(1);
 }

package/src/init.js

@@ -16,6 +16,7 @@ import {
 } from "./canonical-scripts.js";
 import { applyToPackageJson } from "./package-json.js";
 import { resolveVersions } from "./dep-versions.js";
+import { scopeName } from "./scope-name.js";
 
 const templatesDir = fileURLToPath(new URL("templates/", import.meta.url));
 
@@ -76,11 +77,6 @@ function createAskYesNo() {
   return ask;
 }
 
-// Prepend the @doikayt scope unless the name is already scoped.
-function scopeName(name) {
-  return name.startsWith("@") ? name : `@doikayt/${name}`;
-}
-
 export async function runInit({
   cwd = process.cwd(),
   prompt,

package/src/new-package.js

@@ -0,0 +1,38 @@
+import { readFileSync, writeFileSync } from "fs";
+import { resolve } from "path";
+import { spawnSync } from "child_process";
+import { scopeName } from "./scope-name.js";
+
+// Default `npm init -y` runner. Injectable so runNew is testable without npm.
+function npmInitY(cwd) {
+  const res = spawnSync("npm", ["init", "-y"], { cwd, stdio: "inherit" });
+  if (res.error) throw res.error;
+  if (res.status !== 0)
+    throw new Error(`npm init -y exited with ${res.status}`);
+}
+
+// Run `npm init -y`, then scope the generated package name to @doikayt unless it
+// is already scoped (any @scope/ is left alone). Writes package.json back and
+// returns the final name plus whether it changed.
+export function runNew({
+  cwd = process.cwd(),
+  npmInit = npmInitY,
+  log = console.log,
+} = {}) {
+  npmInit(cwd);
+
+  const pkgPath = resolve(cwd, "package.json");
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+  const before = pkg.name || "package";
+  const scoped = scopeName(before);
+
+  if (scoped !== pkg.name) {
+    pkg.name = scoped;
+    writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+    log(`Scoped package name: ${before} → ${scoped}`);
+  } else {
+    log(`Package name already scoped: ${scoped}`);
+  }
+
+  return { name: scoped, changed: scoped !== before };
+}

package/src/postinstall.js

@@ -15,9 +15,19 @@ const PREFIX = "[@doikayt/typescript-build-config]";
 console.log(`${PREFIX} Running postinstall...`);
 
 const projectRoot = process.env.INIT_CWD ?? process.cwd();
-const projectPkg = JSON.parse(
-  readFileSync(resolve(projectRoot, "package.json"), "utf8"),
-);
+const projectPkgPath = resolve(projectRoot, "package.json");
+
+// Installed via `npx @doikayt/... new` into a bare dir (or otherwise before a
+// consuming project has a package.json) — nothing to configure. Postinstall is
+// warn-only, so no-op instead of crashing.
+if (!existsSync(projectPkgPath)) {
+  console.log(
+    `${PREFIX} No package.json in ${projectRoot} — nothing to configure. Skipping.`,
+  );
+  process.exit(0);
+}
+
+const projectPkg = JSON.parse(readFileSync(projectPkgPath, "utf8"));
 
 if (projectPkg.name === "@doikayt/typescript-build-config") {
   console.log(`${PREFIX} Self-install detected — postinstall is a no-op.`);
@@ -101,7 +111,7 @@ for (const { src, dest } of pipelineFiles) {
 
 // --- Asset files: seeded into docs/assets/, same per-file copy/warn as pipeline ---
 
-const assetDir = new URL("../assets", import.meta.url).pathname;
+const assetDir = new URL("../image-assets", import.meta.url).pathname;
 
 const assetFiles = [
   { src: "doikayt-logo.png", dest: "docs/assets/doikayt-logo.png" },
@@ -125,7 +135,7 @@ for (const { src, dest } of assetFiles) {
 
   console.warn(
     `${PREFIX} WARNING: ${dest} differs from canonical version — skipping. ` +
-      `To resync: cp node_modules/@doikayt/typescript-build-config/assets/${src} ${dest}`,
+      `To resync: cp node_modules/@doikayt/typescript-build-config/image-assets/${src} ${dest}`,
   );
 }
 

package/src/scope-name.js

@@ -0,0 +1,6 @@
+// Prepend the @doikayt scope unless the name is already scoped — any existing
+// @scope/ is left as-is. Shared by `init` (library name prompt) and the `new`
+// command (scoped `npm init`).
+export function scopeName(name) {
+  return name.startsWith("@") ? name : `@doikayt/${name}`;
+}