@doikayt/typescript-build-config 0.1.20 → 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)
@@ -136,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
@@ -153,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
@@ -173,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
@@ -185,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))
@@ -473,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
@@ -509,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.20",
+  "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));
 
@@ -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/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}`;
+}