@doikayt/typescript-build-config 0.1.21 → 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)
@@ -41,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
@@ -80,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
 
@@ -240,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
@@ -268,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            │
         └─────────┬───────────────┬───────────────┬───────┘
                   │               │               │
@@ -320,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
@@ -495,21 +542,9 @@ release job until one is committed.
 
 ## 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`:
+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 |
 | --- | --- |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doikayt/typescript-build-config",
-  "version": "0.1.21",
+  "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/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}`,
   );
 }