@doikayt/typescript-build-config 0.1.19 → 0.1.21

package/README.md

@@ -13,6 +13,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 +24,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)
@@ -123,7 +125,9 @@ small single-purpose scripts, and the check side mirrors the write side:
 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.
+  and `prepack`, so it publishes a compiled, typed ESM package on push. `init`
+  also prompts for the package name (default `@doikayt/<name>`; a bare name is
+  scoped to `@doikayt`, an already-scoped name is kept).
 - **App / CLI** (the default) — marked `private: true`, so a release versions and
   tags it but never publishes to npm.
 
@@ -134,7 +138,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
@@ -151,7 +155,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
@@ -171,6 +175,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
@@ -183,6 +203,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))
@@ -337,8 +359,8 @@ rely on it.
 ## Release Pipeline
 
 On install, the postinstall script copies the release pipeline files into your
-project automatically. The package name in `auto-changeset.sh` is substituted
-from your project's `package.json` at install time.
+project automatically. `auto-changeset.sh` reads the package name from your
+`package.json` at runtime, so renaming the package needs no pipeline edits.
 
 On `npm update`, the behavior per file is:
 
@@ -471,6 +493,31 @@ 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
+
+This repo doubles as the team's base setup. After cloning it, install the shared
+shell aliases — a **required** onboarding step, so everyone creates and scaffolds
+repos the same way:
+
+```bash
+git clone git@github.com:doikayt/typescript-build-config.git
+cd typescript-build-config
+./shell/install.sh          # adds a `source` line to ~/.zshrc / ~/.bashrc (idempotent)
+exec $SHELL                 # reload — or: source shell/aliases.sh
+```
+
+Manual alternative: add `source <clone-path>/shell/aliases.sh` to your shell rc.
+
+Aliases provided ([`shell/aliases.sh`](shell/aliases.sh)) — 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
@@ -507,7 +554,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.19",
+  "version": "0.1.21",
   "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/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));
 
@@ -62,14 +63,16 @@ function createAskYesNo() {
     closed = true;
     while (waiters.length) waiters.shift()("");
   });
-  const ask = (question) =>
+  const nextLine = (question) =>
     new Promise((res) => {
       process.stdout.write(question);
-      const answer = (line) => res(/^y(es)?$/i.test(line.trim()));
-      if (lines.length) answer(lines.shift());
-      else if (closed) answer("");
-      else waiters.push(answer);
+      if (lines.length) res(lines.shift());
+      else if (closed) res("");
+      else waiters.push(res);
     });
+  const ask = async (question) =>
+    /^y(es)?$/i.test((await nextLine(question)).trim());
+  ask.text = async (question) => (await nextLine(question)).trim();
   ask.close = () => rl.close();
   return ask;
 }
@@ -77,6 +80,7 @@ function createAskYesNo() {
 export async function runInit({
   cwd = process.cwd(),
   prompt,
+  promptText,
   resolveDevVersions = resolveVersions,
   log = console.log,
 } = {}) {
@@ -84,16 +88,32 @@ export async function runInit({
   // on error so a leftover interface never keeps the process alive.
   const ownAsk = prompt ? null : createAskYesNo();
   const ask = prompt ?? ownAsk;
+  // Free-text prompt (package name). Falls back to "" (accept the default) when a
+  // yes/no prompt is injected without a text one, so tests need not supply it.
+  const askText = promptText ?? ownAsk?.text ?? (async () => "");
   try {
-    return await collectAndScaffold({ cwd, ask, resolveDevVersions, log });
+    return await collectAndScaffold({
+      cwd,
+      ask,
+      askText,
+      resolveDevVersions,
+      log,
+    });
   } finally {
     ownAsk?.close();
   }
 }
 
-async function collectAndScaffold({ cwd, ask, resolveDevVersions, log }) {
+async function collectAndScaffold({
+  cwd,
+  ask,
+  askText,
+  resolveDevVersions,
+  log,
+}) {
   const pkgPath = resolve(cwd, "package.json");
   const raw = readFileSync(pkgPath, "utf8");
+  const currentName = JSON.parse(raw).name;
 
   // Collect every answer up front, before doing any work or printing next
   // steps, so the flow reads: ask everything → act → report.
@@ -102,10 +122,21 @@ async function collectAndScaffold({ cwd, ask, resolveDevVersions, log }) {
   );
 
   const library = await ask(
-    "Is this a publishable library (published to npm)? Default is No\n" +
-      "  — a non-library (an app/CLI) is marked private so it is never published. [y/N] ",
+    "Is this a publishable library (published to npm)? Default is No.\n" +
+      "  No = an app/CLI (marked private, never published). [y/N] ",
   );
 
+  // The package name is what gets published, so ask only for a library. A bare
+  // name gets the @doikayt scope; an already-scoped name is kept.
+  let libraryName;
+  if (library) {
+    const suggested = scopeName(currentName || "package");
+    const entered = await askText(
+      `Package name for publishing? [${suggested}] `,
+    );
+    libraryName = entered ? scopeName(entered) : suggested;
+  }
+
   const wantDemo = await ask(
     "Scaffold a starter demo (minimal src module + README + project.json) so\n" +
       "you can build, test, and release immediately? Default is No; existing\n" +
@@ -115,17 +146,25 @@ async function collectAndScaffold({ cwd, ask, resolveDevVersions, log }) {
   const scripts = canonicalScripts({ ui, library });
   const devDependencies = resolveDevVersions(devDependencyNames({ ui }));
 
+  const 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.
+  const replaceDefaults = {
+    scripts: { test: 'echo "Error: no test specified" && exit 1' },
+    fields: { main: "index.js" },
+  };
+  if (library) {
+    // The chosen name is a deliberate publish decision, so it replaces whatever
+    // name npm init left in place.
+    fields.name = libraryName;
+    if (currentName != null) replaceDefaults.fields.name = currentName;
+  }
+
   const { text, added, skipped } = applyToPackageJson(raw, {
     scripts,
     devDependencies,
-    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" },
-    },
+    fields,
+    replaceDefaults,
   });
   writeFileSync(pkgPath, text);
 

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/pipeline/auto-changeset.sh

@@ -15,7 +15,9 @@
 set -euo pipefail
 
 CHANGESET_DIR=".changeset"
-PACKAGES=("__PACKAGE_NAME__")
+# Read the package name from package.json at runtime, so it stays correct even if
+# the project is renamed after install — package.json is the single source of truth.
+PACKAGES=("$(node -p "require('./package.json').name")")
 
 # Skip if a manually-authored changeset already exists
 EXISTING=$(find "$CHANGESET_DIR" -name "*.md" ! -name "README.md" | wc -l)

package/src/postinstall.js

@@ -61,8 +61,6 @@ if (alreadyExist.length > 0) {
 
 // --- Pipeline files: per-file copy/warn/diff ---
 
-const projectName = projectPkg.name;
-
 const pipelineFiles = [
   { src: "release.yml", dest: ".github/workflows/release.yml" },
   { src: "changeset-config.json", dest: ".changeset/config.json" },
@@ -77,14 +75,7 @@ for (const { src, dest } of pipelineFiles) {
   const srcPath = resolve(pipelineDir, src);
   const destPath = resolve(projectRoot, dest);
 
-  let canonical = readFileSync(srcPath, "utf8");
-
-  if (src === "auto-changeset.sh") {
-    canonical = canonical.replace(
-      'PACKAGES=("__PACKAGE_NAME__")',
-      `PACKAGES=("${projectName}")`,
-    );
-  }
+  const canonical = readFileSync(srcPath, "utf8");
 
   if (!existsSync(destPath)) {
     mkdirSync(dirname(destPath), { recursive: true });

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}`;
+}