stitchkit 0.80.1 → 0.82.0

package/dist/upgrade-cli.d.ts

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+export interface UpgradeCliResult {
+    /** What to write to stdout. */
+    readonly output: string;
+    /** Process exit code — 0 when the plan (or "nothing to do") was produced. */
+    readonly code: number;
+}
+/**
+ * The whole command as a function of its arguments and the filesystem, so the
+ * gate can exercise the paths that matter — a project with no stitchkit
+ * installed, a range that runs backwards, a changelog the package did not ship.
+ */
+export declare function runUpgradeCli(argv: readonly string[]): UpgradeCliResult;
+/**
+ * Was this file executed as a program, rather than imported?
+ *
+ * Through the real install path that is a **symlink** question, not a string
+ * one: npm and bun link `node_modules/.bin/stitchkit` at the built file, Node
+ * keeps the link in `argv[1]` and resolves `import.meta.url` to its target. A
+ * direct comparison of the two is therefore false for every consumer, and the
+ * binary becomes a silent no-op — exit 0, no output, nothing to notice — while
+ * running the same file in place works perfectly. Both arguments are passed in
+ * so this is decidable without launching a process: under Bun `argv[1]` is
+ * already resolved, so a spawned symlink proves nothing about Node.
+ */
+export declare function isDirectInvocation(invoked: string | undefined, self: string): boolean;
+//# sourceMappingURL=upgrade-cli.d.ts.map

package/dist/upgrade-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade-cli.d.ts","sourceRoot":"","sources":["../src/upgrade-cli.ts"],"names":[],"mappings":";AA4DA,MAAM,WAAW,gBAAgB;IAC/B,+BAA+B;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,gBAAgB,CAqCvE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CASrF"}

package/dist/upgrade-cli.js

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+
+// src/upgrade-cli.ts
+import { readFileSync, realpathSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+// src/internal/upgrade-plan.ts
+function semverParts(version) {
+  const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(version);
+  if (!match)
+    throw new Error(`Expected an exact semver, received "${version}"`);
+  const [, major, minor, patch] = match;
+  if (major === undefined || minor === undefined || patch === undefined) {
+    throw new Error(`Expected an exact semver, received "${version}"`);
+  }
+  return [Number(major), Number(minor), Number(patch)];
+}
+function compareSemver(left, right) {
+  const a = semverParts(left);
+  const b = semverParts(right);
+  for (const index of [0, 1, 2]) {
+    const difference = a[index] - b[index];
+    if (difference !== 0)
+      return difference;
+  }
+  return 0;
+}
+function planUpgrade(changelog, from, to) {
+  semverParts(from);
+  semverParts(to);
+  if (compareSemver(from, to) >= 0) {
+    throw new Error(`Upgrade range must increase: ${from} → ${to}`);
+  }
+  const releases = [...changelog.matchAll(/^## \[(\d+\.\d+\.\d+)\].*$/gm)];
+  const changes = [];
+  for (const [index, release] of releases.entries()) {
+    const version = release[1];
+    if (version === undefined)
+      continue;
+    if (compareSemver(version, from) <= 0 || compareSemver(version, to) > 0)
+      continue;
+    const bodyStart = (release.index ?? 0) + release[0].length;
+    const bodyEnd = releases[index + 1]?.index ?? changelog.length;
+    const body = changelog.slice(bodyStart, bodyEnd);
+    const breakingHeader = /^### ⚠️ Breaking changes\s*$/m.exec(body);
+    if (!breakingHeader)
+      continue;
+    const breakingStart = (breakingHeader.index ?? 0) + breakingHeader[0].length;
+    const afterHeader = body.slice(breakingStart);
+    const nextSection = /^### /m.exec(afterHeader);
+    const markdown = afterHeader.slice(0, nextSection?.index ?? afterHeader.length).trim();
+    const who = /^\*\*Who must act:\*\*\s*([\s\S]*?)(?=\n\s*\n|\n[-*] )/m.exec(markdown);
+    changes.push({
+      version,
+      whoMustAct: who?.[1]?.replace(/\s+/g, " ").trim() ?? "Not declared in this legacy changelog section.",
+      markdown
+    });
+  }
+  return changes.sort((left, right) => compareSemver(left.version, right.version));
+}
+function renderUpgradePlan(changes, from, to) {
+  const header = `# Stitchkit upgrade ${from} → ${to}`;
+  if (changes.length === 0)
+    return `${header}
+
+No breaking sections in this range.
+`;
+  return `${header}
+
+${changes.map((change) => `## ${change.version}
+
+**Who must act:** ${change.whoMustAct}
+
+${change.markdown.replace(/^\*\*Who must act:\*\*[\s\S]*?(?=\n\s*\n|\n[-*] )/m, "").trim()}`).join(`
+
+`)}
+`;
+}
+
+// src/upgrade-cli.ts
+var USAGE = `stitchkit upgrade — print every breaking change between the installed version and this one
+
+  bunx stitchkit@latest upgrade            in a project that depends on stitchkit
+  npx stitchkit@latest upgrade
+
+Options
+  --from <version>     installed version (default: the stitchkit in ./node_modules)
+  --to <version>       target version (default: the version of this package)
+  --cwd <dir>          project to read the installed version from (default: .)
+  --changelog <path>   changelog to plan from (default: the one in this package)
+`;
+function option(argv, name) {
+  const index = argv.indexOf(`--${name}`);
+  if (index < 0)
+    return;
+  const value = argv[index + 1];
+  if (value === undefined || value.startsWith("--")) {
+    throw new Error(`--${name} needs a value`);
+  }
+  return value;
+}
+function packageRoot() {
+  return resolve(dirname(fileURLToPath(import.meta.url)), "..");
+}
+function versionOf(packageJsonPath) {
+  let text;
+  try {
+    text = readFileSync(packageJsonPath, "utf8");
+  } catch {
+    return;
+  }
+  const parsed = JSON.parse(text);
+  if (typeof parsed !== "object" || parsed === null || !("version" in parsed))
+    return;
+  const { version } = parsed;
+  return typeof version === "string" ? version : undefined;
+}
+function runUpgradeCli(argv) {
+  if (argv.includes("--help") || argv.includes("-h") || argv.length === 0) {
+    return { output: USAGE, code: 0 };
+  }
+  const [command] = argv;
+  if (command !== "upgrade") {
+    return { output: `Unknown command "${command}".
+
+${USAGE}`, code: 1 };
+  }
+  const root = packageRoot();
+  const to = option(argv, "to") ?? versionOf(join(root, "package.json"));
+  if (to === undefined) {
+    throw new Error(`Cannot read the version of the stitchkit at ${root}`);
+  }
+  const cwd = resolve(option(argv, "cwd") ?? process.cwd());
+  const from = option(argv, "from") ?? versionOf(join(cwd, "node_modules", "stitchkit", "package.json"));
+  if (from === undefined) {
+    throw new Error(`No stitchkit found in ${join(cwd, "node_modules")} — run this in the project that depends on it, or pass --from <installed version>`);
+  }
+  if (from === to) {
+    return { output: `Already on ${to}. Nothing to upgrade.
+`, code: 0 };
+  }
+  const changelogPath = option(argv, "changelog") ?? join(root, "CHANGELOG.md");
+  let changelog;
+  try {
+    changelog = readFileSync(changelogPath, "utf8");
+  } catch {
+    throw new Error(`Cannot read the changelog at ${changelogPath}`);
+  }
+  return { output: renderUpgradePlan(planUpgrade(changelog, from, to), from, to), code: 0 };
+}
+function isDirectInvocation(invoked, self) {
+  if (invoked === undefined)
+    return false;
+  if (invoked === self || pathToFileURL(invoked).href === pathToFileURL(self).href)
+    return true;
+  try {
+    return realpathSync(invoked) === realpathSync(self);
+  } catch {
+    return false;
+  }
+}
+if (isDirectInvocation(process.argv[1], fileURLToPath(import.meta.url))) {
+  try {
+    const { output, code } = runUpgradeCli(process.argv.slice(2));
+    process.stdout.write(output);
+    process.exit(code);
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`);
+    process.exit(1);
+  }
+}
+export {
+  runUpgradeCli,
+  isDirectInvocation
+};