@homepages/create-workspace 0.9.0-dev-20260719224319 → 0.9.1

package/dist/index.js

@@ -2,7 +2,7 @@
 // `npm create @homepages/workspace <name>` — stamp a workspace container: shared
 // root context + one working starter template, then install and git-init.
 import { execFileSync } from "node:child_process";
-import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { existsSync, realpathSync } from "node:fs";
 import { mkdir } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
@@ -10,6 +10,14 @@ import { fileURLToPath } from "node:url";
 import { stampTree } from "./stamp.js";
 const ASSETS = join(dirname(fileURLToPath(import.meta.url)), "..", "scaffold");
 const NAME_RE = /^[a-z][a-z0-9-]*$/;
+/**
+ * The kit's caret pin. The kit versions independently of this scaffolder, so
+ * it cannot be derived from this package's own version and is a committed
+ * constant — same reasoning as ESLINT_PLUGIN_VERSION below — bumped when the
+ * kit releases a new minor. A scaffolded workspace pinned to a stale range
+ * never picks up the kit's current contract.
+ */
+const KIT_VERSION = "0.9.0";
 /**
  * The authoring ESLint preset's caret pin. Unlike the kit it cannot be derived from
  * this package's own version — @homepages/eslint-plugin-template versions
@@ -18,12 +26,43 @@ const NAME_RE = /^[a-z][a-z0-9-]*$/;
  * on fails at `npm install`, not at lint time, so this is not optional.
  */
 const ESLINT_PLUGIN_VERSION = "0.1.0";
+/**
+ * The CLI's caret pin. Same reasoning as ESLINT_PLUGIN_VERSION: @homepages/template-cli
+ * versions independently of the kit, so it cannot be derived from this package's own
+ * version and is a committed constant, bumped when that package releases a new minor.
+ *
+ * It is what supplies the `template-kit` command the scaffolded scripts invoke — the
+ * kit no longer carries a bin — so a workspace missing it fails on `npm run dev` with
+ * "command not found", which reads as a broken scaffold rather than a missing pin.
+ */
+const TEMPLATE_CLI_VERSION = "0.1.0";
+/**
+ * The dev media pack's caret pin. Same committed-constant reasoning as the pins
+ * above — the pack versions independently of this scaffolder.
+ *
+ * The pack is what the `dev` server serves asset BYTES from: the kit carries only
+ * the manifest (copied into its dist at build time), so a workspace without this
+ * dependency has an index of media it cannot resolve a single pixel of, and every
+ * fixture image renders broken.
+ *
+ * It is a devDependency, not a dependency: media is dev-time authoring content, in
+ * the same category as vite and the rest of the toolchain, and nothing in a packed
+ * template references it.
+ *
+ * This range must cover the pack's actual published version on npm, or a
+ * scaffolded workspace outside this monorepo dies on `npm install` with a 404 —
+ * the drift guard in `src/index.test.ts` (the stamped dev-media range covers the
+ * pack's actual version) fails the moment this constant falls behind a real bump.
+ */
+const DEV_MEDIA_VERSION = "0.0.0";
 export async function scaffoldWorkspace(name, targetDir, opts) {
     await mkdir(targetDir, { recursive: true });
     await stampTree(join(ASSETS, "workspace"), targetDir, {
         WORKSPACE_NAME: name,
-        KIT_VERSION: opts.kitVersion,
+        KIT_VERSION: opts.kitVersion ?? KIT_VERSION,
         ESLINT_PLUGIN_VERSION: opts.eslintPluginVersion ?? ESLINT_PLUGIN_VERSION,
+        TEMPLATE_CLI_VERSION: opts.templateCliVersion ?? TEMPLATE_CLI_VERSION,
+        DEV_MEDIA_VERSION: opts.devMediaVersion ?? DEV_MEDIA_VERSION,
     });
     await stampTree(join(ASSETS, "template"), join(targetDir, "templates", "starter"), {
         TEMPLATE_KEY: "starter",
@@ -34,17 +73,6 @@ export async function scaffoldWorkspace(name, targetDir, opts) {
     if (opts.install !== false)
         execFileSync("npm", ["install"], { cwd: targetDir, stdio: "inherit" });
 }
-/**
- * The kit version to caret-pin: this scaffolder is published version-synced
- * with the kit, so its own `version` IS the kit version. Read at runtime
- * (rather than a static JSON import) because `../package.json` sits outside
- * `rootDir: "src"` and trips TS6059 under a static import.
- */
-function kitVersion() {
-    const raw = readFileSync(new URL("../package.json", import.meta.url), "utf8");
-    const pkg = JSON.parse(raw);
-    return typeof pkg.version === "string" ? pkg.version : "0.0.0";
-}
 async function promptName() {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     try {
@@ -66,7 +94,7 @@ async function main() {
         process.stderr.write(`create-workspace: ${name}/ already exists.\n`);
         return 1;
     }
-    await scaffoldWorkspace(name, targetDir, { kitVersion: kitVersion() });
+    await scaffoldWorkspace(name, targetDir, {});
     process.stdout.write(`\nCreated ${name}/\n\n` +
         `  cd ${name}\n` +
         `  npm run dev        # preview the starter (the island hydrates)\n` +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homepages/create-workspace",
-  "version": "0.9.0-dev-20260719224319",
+  "version": "0.9.1",
   "description": "Scaffold a HomePages template workspace.",
   "license": "UNLICENSED",
   "type": "module",

package/scaffold/workspace/AGENTS.md

@@ -9,9 +9,12 @@ You are authoring HomePages marketing-section templates in this workspace.
 - **Templates live in `templates/`.** Each is a plain folder — not an npm package.
   Add one with `npx template-kit new <name>`; add a section with
   `npx template-kit new-section <name>`.
-- **One kit, one version.** `@homepages/template-kit` is the only toolchain
-  dependency; every template shares it. Do not add per-template `package.json`,
-  `tsconfig`, or `eslint` files — there is exactly one of each, at this root.
+- **One kit, one version.** `@homepages/template-kit` carries the authoring
+  contract every template imports; `@homepages/template-cli` provides the
+  `template-kit` command and `@homepages/eslint-plugin-template` the lint preset.
+  All three are declared once, at this root, and every template shares them. Do not
+  add per-template `package.json`, `tsconfig`, or `eslint` files — there is exactly
+  one of each, at this root.
 - **The docs corpus is your whole universe:** `node_modules/@homepages/template-kit/guide/`
   (`llms.txt` is the router). Read it before authoring; do not guess the contract.
 

package/scaffold/workspace/CLAUDE.md

@@ -7,9 +7,12 @@ You are authoring HomePages marketing-section templates in this workspace.
 - **Templates live in `templates/`.** Each is a plain folder — not an npm package.
   Add one with `npx template-kit new <name>`; add a section with
   `npx template-kit new-section <name>`.
-- **One kit, one version.** `@homepages/template-kit` is the only toolchain
-  dependency; every template shares it. Do not add per-template `package.json`,
-  `tsconfig`, or `eslint` files — there is exactly one of each, at this root.
+- **One kit, one version.** `@homepages/template-kit` carries the authoring
+  contract every template imports; `@homepages/template-cli` provides the
+  `template-kit` command and `@homepages/eslint-plugin-template` the lint preset.
+  All three are declared once, at this root, and every template shares them. Do not
+  add per-template `package.json`, `tsconfig`, or `eslint` files — there is exactly
+  one of each, at this root.
 - **The docs corpus is your whole universe:** `node_modules/@homepages/template-kit/guide/`
   (`llms.txt` is the router). Read it before authoring; do not guess the contract.
 

package/scaffold/workspace/README.md

@@ -1,7 +1,10 @@
 # {{WORKSPACE_NAME}}
 
-A HomePages template workspace. Templates live in `templates/`. The kit toolchain
-is one dependency (`@homepages/template-kit`) shared by every template here.
+A HomePages template workspace. Templates live in `templates/`. The toolchain is
+declared once at this root — `@homepages/template-kit` (the authoring contract),
+`@homepages/template-cli` (the `template-kit` command) and
+`@homepages/eslint-plugin-template` (the lint preset) — and shared by every
+template here.
 
 ## Commands
 

package/scaffold/workspace/_package.json

@@ -13,7 +13,9 @@
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
+    "@homepages/dev-media": "^{{DEV_MEDIA_VERSION}}",
     "@homepages/eslint-plugin-template": "^{{ESLINT_PLUGIN_VERSION}}",
+    "@homepages/template-cli": "^{{TEMPLATE_CLI_VERSION}}",
     "@tailwindcss/cli": "^4.3.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",