create-codebase-snapshot 4.0.6 → 4.1.0

package/README.md

@@ -8,8 +8,10 @@ npm create codebase-snapshot
 ```
 
 It detects the project type, asks a handful of questions with sensible defaults,
-and writes a `snapshot.config.mjs` that lists **every setting at its default** —
-so the config doubles as the documentation.
+and writes the config file this project can actually load — `snapshot.config.ts`
+for an ES-module project on Node ≥ 22.6, `snapshot.config.mjs` everywhere else —
+listing **every setting at its default**, so the config doubles as the
+documentation.
 
 ```bash
 npm create codebase-snapshot -- --preset react-vite --yes
@@ -22,5 +24,24 @@ npm create codebase-snapshot -- --preset react-vite --yes
 | `--minimal` | Write only the settings that differ from defaults |
 | `--force` | Overwrite an existing config |
 
+## What it writes
+
+| Path | Notes |
+| :--- | :--- |
+| `snapshot.config.ts` / `snapshot.config.mjs` | Every setting at its default. `.ts` needs an ES-module `package.json` and Node ≥ 22.6; `.mjs` is used otherwise, because a `.ts` config is loaded with the enclosing package's module type. |
+| `package.json` → `scripts.snapshot`, `scripts.snapshot:validate` | Skipped when there is no `package.json` to hold them. |
+| `package.json` → `devDependencies` | `@ankurhalder/codebase-snapshot` at the range this scaffolder shipped with. |
+| `.gitignore` | `snapshot/`, `snapshot.tmp/`. |
+
+The generated scripts run `npx @ankurhalder/codebase-snapshot …`, and `npx` uses the
+local `devDependencies` copy when there is one — so the version is pinned by your
+lockfile instead of drifting to `@latest`. Until you run `npm install`, `npx` would
+fall back to downloading the newest release, which is why the printed next step is
+`npm install && npm run snapshot`. Nothing is installed, and no network is used,
+while scaffolding.
+
+Without a `package.json` the scripts cannot be added, and the printed next step is
+`npx @ankurhalder/codebase-snapshot generate` instead.
+
 This package is a shim: the wizard itself lives in the main package, so
 `npx @ankurhalder/codebase-snapshot init` does exactly the same thing.

package/index.mjs

@@ -1,4 +1,7 @@
 #!/usr/bin/env node
+import * as fs from "node:fs";
+import { createRequire } from "node:module";
+import * as path from "node:path";
 import { PromptCancelled, runInit } from "@ankurhalder/codebase-snapshot";
 
 /**
@@ -10,6 +13,126 @@ import { PromptCancelled, runInit } from "@ankurhalder/codebase-snapshot";
  * `npm create <x>` is the convention developers reach for first.
  */
 
+const PACKAGE_NAME = "@ankurhalder/codebase-snapshot";
+
+const require = createRequire(import.meta.url);
+
+/** The range this shim was published against, read from its own manifest. */
+function dependencyRange() {
+  try {
+    const manifest = require("./package.json");
+    const range = manifest?.dependencies?.[PACKAGE_NAME];
+    return typeof range === "string" ? range : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Keeps the file's own indentation and trailing newline when rewriting JSON. */
+function serializePackageJson(raw, value) {
+  const indent = /^[{[]\r?\n([ \t]+)/.exec(raw)?.[1];
+  const spacing = raw.includes("\n") ? (indent ?? "  ") : undefined;
+  const body = JSON.stringify(value, null, spacing);
+  return `${body}${raw.endsWith("\n") ? "\n" : ""}`;
+}
+
+/**
+ * Records the runtime dependency the generated scripts need.
+ *
+ * The wizard writes `npx @ankurhalder/codebase-snapshot generate`, which resolves
+ * the *latest* release when nothing is installed locally: the first run silently
+ * downloaded @latest (observed pulling an older minor), failed behind a proxy and
+ * could cross a major version. Naming the package in `devDependencies` makes
+ * `npx` prefer that local copy, so the scripts become version-locked once the
+ * project is installed — without this shim ever touching the network itself.
+ */
+function recordDependency(written) {
+  if (!written) return { added: false };
+
+  const range = dependencyRange();
+  if (!range) {
+    return {
+      added: false,
+      note: `Could not read ${PACKAGE_NAME}'s version from this package, so it was not added to devDependencies.`,
+    };
+  }
+
+  const pkgPath = path.join(process.cwd(), "package.json");
+  if (!fs.existsSync(pkgPath)) return { added: false };
+
+  let raw;
+  try {
+    raw = fs.readFileSync(pkgPath, "utf8");
+  } catch {
+    return {
+      added: false,
+      note: `package.json could not be read, so ${PACKAGE_NAME} was not added to devDependencies.`,
+    };
+  }
+
+  let pkg;
+  try {
+    pkg = JSON.parse(raw);
+  } catch {
+    return {
+      added: false,
+      note: `package.json could not be parsed, so ${PACKAGE_NAME} was not added to devDependencies.`,
+    };
+  }
+
+  const declared = ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"].some(
+    (field) => pkg?.[field] && typeof pkg[field] === "object" && PACKAGE_NAME in pkg[field]
+  );
+  if (declared) return { added: false, range };
+
+  pkg.devDependencies = { ...(pkg.devDependencies ?? {}), [PACKAGE_NAME]: range };
+  try {
+    fs.writeFileSync(pkgPath, serializePackageJson(raw, pkg));
+  } catch {
+    return {
+      added: false,
+      note: `package.json could not be written, so ${PACKAGE_NAME} was not added to devDependencies.`,
+    };
+  }
+  return { added: true, range };
+}
+
+/** True when the package's own binary is already installed in the project. */
+function hasLocalBinary() {
+  const names =
+    process.platform === "win32"
+      ? ["codebase-snapshot.cmd", "codebase-snapshot"]
+      : ["codebase-snapshot"];
+  return names.some((name) =>
+    fs.existsSync(path.join(process.cwd(), "node_modules", ".bin", name))
+  );
+}
+
+/** True when the project's package.json already carries the `snapshot` script. */
+function hasSnapshotScript() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(process.cwd(), "package.json"), "utf8"));
+    return typeof pkg?.scripts?.snapshot === "string";
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The command the developer should run next.
+ *
+ * `npm run snapshot` is only meaningful when the project has that script, which
+ * needs a `package.json`: the old text promised it unconditionally, so the
+ * documented next step failed with ENOENT in exactly the case that needs help
+ * most. A pre-existing script counts even when this run added nothing, hence the
+ * check is against `package.json` rather than against what the wizard wrote. The
+ * remaining forms are executable as printed.
+ */
+function nextStep() {
+  if (!hasSnapshotScript()) return `npx ${PACKAGE_NAME} generate`;
+  return hasLocalBinary() ? "npm run snapshot" : "npm install && npm run snapshot";
+}
+
 const argv = process.argv.slice(2);
 
 if (argv.includes("--help") || argv.includes("-h")) {
@@ -60,8 +183,16 @@ try {
   if (result.gitignoreEntries.length > 0) {
     process.stderr.write(`   Added to .gitignore: ${result.gitignoreEntries.join(", ")}\n`);
   }
+
+  const dependency = recordDependency(result.written);
+  if (dependency.added) {
+    process.stderr.write(`   Added devDependency: ${PACKAGE_NAME} ${dependency.range}\n`);
+  } else if (dependency.note) {
+    process.stderr.write(`   ⚠ ${dependency.note}\n`);
+  }
+
   for (const note of result.notes) process.stderr.write(`   ⚠ ${note}\n`);
-  process.stderr.write("\n   Next:  npm run snapshot\n\n");
+  process.stderr.write(`\n   Next:  ${nextStep()}\n\n`);
 } catch (err) {
   if (err instanceof PromptCancelled) {
     process.stderr.write("\n❌ Cancelled.\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-codebase-snapshot",
-  "version": "4.0.6",
+  "version": "4.1.0",
   "description": "Set up @ankurhalder/codebase-snapshot in a repository",
   "license": "MIT",
   "author": "Ankur Halder <ankur.halder12345@gmail.com>",
@@ -22,7 +22,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@ankurhalder/codebase-snapshot": "^4.0.6"
+    "@ankurhalder/codebase-snapshot": "^4.1.0"
   },
   "engines": {
     "node": ">=18.0.0"