@cosmicdrift/kumiko-framework 0.386.0 → 0.388.0

package/dist/upgrade-cli.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync, } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { getFlag, getStringFlag, parseArgs } from "./arg-parser.js";
 import { compareVersions, filterEntriesAfter, parseFeatureChangelog, sortEntries, } from "./engine/index.js";
 import { ensureTemporalPolyfill } from "./time/index.js";
@@ -96,7 +97,7 @@ export function findFeatureChangelogFiles(featuresDir) {
         // Layout is detected per-package, not guessed from a naming convention:
         // enterprise packages keep changes.json under src/, framework's
         // bundled-features keep it flat. A name-prefix heuristic (e.g. "ai-*")
-        // silently drops packages that don't match it (fw#1605).
+        // silently drops packages that don't match it.
         const srcLayout = join(featuresDir, name, "src", "changes.json");
         const flatLayout = join(featuresDir, name, "changes.json");
         const changelogPath = existsSync(srcLayout) ? srcLayout : flatLayout;
@@ -167,7 +168,7 @@ export function findFeaturesDirs(cwd) {
     // Enterprise repo: packages/<name>/src/changes.json or packages/<name>/changes.json.
     // Detected by presence of changes.json, not a package-name prefix — a
     // prefix heuristic silently stops matching once packages are renamed or a
-    // differently-named package is added (fw#1605). Skipped inside the
+    // differently-named package is added. Skipped inside the
     // framework repo itself (packages/framework present): every package's own
     // changes.json is already collected via findPackageChangelogFiles, and
     // would otherwise get double-counted as one here.
@@ -202,7 +203,7 @@ export function findFeaturesDirs(cwd) {
 // Consumer-facing codemod scripts ship inside the published
 // @cosmicdrift/kumiko-framework package (src/scripts/codemod), not at the
 // git repo root — only the installed package path exists in a consumer's
-// node_modules after a plain npm/bun install (fw#2301).
+// node_modules after a plain npm/bun install.
 export function findCodemodScriptsRoot(repoRoot) {
     const local = join(repoRoot, "packages/framework/src");
     if (existsSync(join(local, CODEMOD_SUBDIR))) {
@@ -213,7 +214,7 @@ export function findCodemodScriptsRoot(repoRoot) {
         if (existsSync(pkgPath)) {
             try {
                 const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
-                if (pkg.name === "@cosmicdrift/kumiko-framework")
+                if (propertyOf(pkg, "name") === "@cosmicdrift/kumiko-framework")
                     return local;
                 // wrong name → fall through
             }
@@ -242,7 +243,7 @@ export function findCodemodScriptsRoot(repoRoot) {
 // absolute paths, symlinks pointing outward) or that isn't a real .ts file.
 // First arg is the consumer repo root (same as findCodemodScriptsRoot) —
 // not the scripts root — so out-of-tree callers keep compiling against the
-// public upgrade-cli subpath without silently resolving to null (fw#2341).
+// public upgrade-cli subpath without silently resolving to null.
 function resolveCodemodScriptAt(codemodScriptsRoot, codemodField) {
     if (!codemodField)
         return null;
@@ -417,7 +418,7 @@ function parseStoredMarker(raw) {
         resolvedManual: dedupeManualById(resolvedManual),
     };
 }
-// A missing marker is a bootstrap app that never ran `--apply` (fw#2299); an
+// A missing marker is a bootstrap app that never ran `--apply`; an
 // existing but unreadable one must not silently fall back to the installed
 // version, or a bare `--apply` would skip every codemod in between.
 function readMarker(targetDir) {
@@ -512,7 +513,7 @@ function writePartialMarker(out, targetDir, pending, manualEntries, failedVersio
 // failure; codemods that already ran are kept in a partial marker. Writes the
 // marker whenever dryRun is false —
 // even with zero pending entries, so an already-current app still gets a
-// bootstrap marker recording its installed version (fw#2299).
+// bootstrap marker recording its installed version.
 // kumiko-lint-ignore complexity-budget sequential codemod runner with zero-pending bootstrap marker
 async function applyCodemods(out, pending, repoRoot, targetDir, dryRun, 
 // Installed version for the zero-pending bootstrap marker — never a
@@ -658,27 +659,27 @@ function matchManualRefs(open, refs) {
     }
     return { resolvedIds, errors };
 }
+function failUpgrade(out, ...lines) {
+    out.err("");
+    for (const line of lines)
+        out.err(`  ${line}`);
+    out.err("");
+    return 1;
+}
 function resolveManualMigrations(out, args, targetDir) {
-    const fail = (...lines) => {
-        out.err("");
-        for (const line of lines)
-            out.err(`  ${line}`);
-        out.err("");
-        return 1;
-    };
     const input = parseResolveInput(args);
     if ("error" in input)
-        return fail(input.error);
+        return failUpgrade(out, input.error);
     const read = readMarker(targetDir);
     if (read.kind === "missing") {
-        return fail(`No .kumiko/upgrade-state.json under ${targetDir}, nothing to resolve.`);
+        return failUpgrade(out, `No .kumiko/upgrade-state.json under ${targetDir}, nothing to resolve.`);
     }
     if (read.kind === "invalid")
-        return fail("invalid .kumiko/upgrade-state.json, fix it first.");
+        return failUpgrade(out, "invalid .kumiko/upgrade-state.json, fix it first.");
     const open = read.marker.pendingManual;
     const { resolvedIds, errors } = matchManualRefs(open, input.refs);
     if (errors.length > 0)
-        return fail(...errors, "Nothing was written.");
+        return failUpgrade(out, ...errors, "Nothing was written.");
     const { reason } = input;
     const resolution = getFlag(args, "not-applicable")
         ? "not-applicable"
@@ -720,39 +721,14 @@ kumiko-upgrade --resolve <id|version>[,<id|version>...] --reason "<text>" [--not
   --not-applicable   with --resolve, record the entries as not applicable instead of migrated
   --dry-run          with --apply, report what would run without writing anything
   --help, -h         print this usage and exit`;
-// kumiko-lint-ignore complexity-budget CLI orchestration moved from bin/commands/upgrade.ts — same branching surface, shared by kumiko upgrade + published kumiko-upgrade bin
-export async function runUpgradeCli(argv, cwd, out, options) {
-    if (argv.includes("--help") || argv.includes("-h")) {
-        out.log(UPGRADE_USAGE);
-        return 0;
-    }
-    // Standalone CLI entry, not booted via runProdApp/runDevApp — Temporal needs an explicit polyfill here.
-    await ensureTemporalPolyfill();
-    const repoRoot = options?.repoRoot ?? cwd;
-    const args = parseArgs(argv);
-    const jsonMode = getFlag(args, "json");
-    const verbose = getFlag(args, "verbose");
-    const fromFlag = getStringFlag(args, "from");
-    // Resolved once here (not just inside --apply) so both the filter
-    // baseline below and the --apply codemod run target the same directory.
-    const dirFlag = getStringFlag(args, "dir");
-    const targetDir = dirFlag ? resolve(dirFlag) : cwd;
-    if (!existsSync(targetDir) || !statSync(targetDir).isDirectory()) {
-        out.err("");
-        out.err(`  --dir path is not a directory: ${targetDir}`);
-        out.err("");
-        return 1;
-    }
-    if (args.flags.has("resolve")) {
-        return resolveManualMigrations(out, args, targetDir);
-    }
+function resolveUpgradeBaseline(cwd, targetDir, fromFlag) {
     // Always resolve the actually installed version, even when --from is set,
     // so --json can report both the filter baseline and what's really there.
     const installedVersion = readCurrentVersion(cwd);
     // Filter baseline: explicit --from wins, otherwise the marker recorded
     // under targetDir (what was last actually applied there), falling back to
-    // the installed version only when no marker exists yet (bootstrap,
-    // fw#2299). Baselining on installedVersion here would silently treat every
+    // the installed version only when no marker exists yet (bootstrap).
+    // Baselining on installedVersion here would silently treat every
     // changelog entry up to the installed version as already handled, even
     // when the marker says otherwise — a bare `--apply` would then always
     // report "Nothing new" and bootstrap the marker onto the installed
@@ -760,33 +736,40 @@ export async function runUpgradeCli(argv, cwd, out, options) {
     const markerRead = readMarker(targetDir);
     const marker = fromFlag === undefined ? markerRead : { kind: "missing" };
     if (marker.kind === "invalid") {
-        out.err("");
-        out.err("  invalid .kumiko/upgrade-state.json, fix it or pass --from <version>");
-        out.err("");
-        return 1;
+        return {
+            kind: "error",
+            lines: ["invalid .kumiko/upgrade-state.json, fix it or pass --from <version>"],
+        };
     }
     const currentVersion = fromFlag ?? (marker.kind === "ok" ? marker.version : undefined) ?? installedVersion;
     if (!currentVersion) {
-        out.err("");
-        out.err("  Could not detect Kumiko version.");
-        out.err("  Run from an app directory with node_modules, or use --from <version>.");
-        out.err("");
-        return 1;
+        return {
+            kind: "error",
+            lines: [
+                "Could not detect Kumiko version.",
+                "Run from an app directory with node_modules, or use --from <version>.",
+            ],
+        };
     }
     if (!SEMVER_RE.test(currentVersion)) {
-        out.err("");
-        out.err(`  Invalid version format: "${currentVersion}" — expected x.y.z`);
-        out.err("");
-        return 1;
+        return {
+            kind: "error",
+            lines: [`Invalid version format: "${currentVersion}" — expected x.y.z`],
+        };
     }
+    return { kind: "ok", value: { currentVersion, installedVersion, markerRead } };
+}
+function collectAllChangelogEntries(cwd) {
     const featuresDirs = findFeaturesDirs(cwd);
     const packageChangelogFiles = findPackageChangelogFiles(cwd);
     if (featuresDirs.length === 0 && packageChangelogFiles.length === 0) {
-        out.err("");
-        out.err("  Could not find bundled-features directory.");
-        out.err("  Run from framework/enterprise repo or an app with node_modules.");
-        out.err("");
-        return 1;
+        return {
+            kind: "error",
+            lines: [
+                "Could not find bundled-features directory.",
+                "Run from framework/enterprise repo or an app with node_modules.",
+            ],
+        };
     }
     const allEntries = [];
     for (const dir of featuresDirs) {
@@ -795,6 +778,18 @@ export async function runUpgradeCli(argv, cwd, out, options) {
     for (const changelogFile of packageChangelogFiles) {
         allEntries.push(...readChangelogFile(changelogFile));
     }
+    return { kind: "ok", value: allEntries };
+}
+function planUpgrade(args, cwd, targetDir) {
+    const dirFlag = getStringFlag(args, "dir");
+    const baseline = resolveUpgradeBaseline(cwd, targetDir, getStringFlag(args, "from"));
+    if (baseline.kind === "error")
+        return baseline;
+    const entries = collectAllChangelogEntries(cwd);
+    if (entries.kind === "error")
+        return entries;
+    const { currentVersion, installedVersion } = baseline.value;
+    const allEntries = entries.value;
     // Installed version of the target the marker belongs to (cwd unless --dir).
     const targetInstalledVersion = dirFlag ? readCurrentVersion(targetDir) : installedVersion;
     // Changelogs can be found in a parent workspace's newer install. A change
@@ -803,87 +798,121 @@ export async function runUpgradeCli(argv, cwd, out, options) {
         ? allEntries
         : allEntries.filter((entry) => compareVersions(entry.version, targetInstalledVersion) <= 0);
     const pending = sortEntries(filterEntriesAfter(installedEntries, currentVersion));
-    if (getFlag(args, "apply")) {
-        // Marker must reflect what is actually installed under the target (or
-        // cwd), not the filter baseline above — otherwise CI stays green forever.
-        const markerVersion = targetInstalledVersion;
-        const dryRun = getFlag(args, "dry-run");
-        if (markerVersion === null && !dryRun) {
-            out.err("");
-            out.err(`  Could not detect the installed Kumiko version under ${targetDir}.`);
-            out.err("  Refusing to write an upgrade marker without it (--from is only a filter).");
-            out.err("");
-            return 1;
+    return {
+        kind: "ok",
+        value: { ...baseline.value, targetInstalledVersion, allEntries, pending },
+    };
+}
+async function applyPlannedUpgrade(out, args, plan, repoRoot, targetDir) {
+    // Marker must reflect what is actually installed under the target (or
+    // cwd), not the filter baseline above — otherwise CI stays green forever.
+    const markerVersion = plan.targetInstalledVersion;
+    const dryRun = getFlag(args, "dry-run");
+    if (markerVersion === null && !dryRun) {
+        return failUpgrade(out, `Could not detect the installed Kumiko version under ${targetDir}.`, "Refusing to write an upgrade marker without it (--from is only a filter).");
+    }
+    out.log("");
+    const code = await applyCodemods(out, plan.pending, repoRoot, targetDir, dryRun, markerVersion ?? plan.currentVersion, carryOf(plan.markerRead), plan.currentVersion, getFlag(args, "verbose") ? manualDetailsOf(plan.allEntries) : undefined);
+    out.log("");
+    return code;
+}
+function reportUpgradeJson(out, plan) {
+    const { currentVersion, installedVersion } = plan;
+    const { pendingManual } = carryOf(plan.markerRead);
+    const pendingWithManualId = plan.pending.map((entry) => {
+        const manualId = manualIdOf(entry);
+        return manualId === undefined ? entry : { ...entry, manualId };
+    });
+    out.log(JSON.stringify({ currentVersion, installedVersion, pending: pendingWithManualId, pendingManual }, null, 2));
+    return 0;
+}
+function logEntryDetail(out, entry, verbose) {
+    if (verbose && entry.detail) {
+        out.log(`      ${entry.detail}`);
+    }
+}
+function logBreakingSection(out, breaking, verbose) {
+    // skip: no breaking entries, the section is omitted
+    if (breaking.length === 0)
+        return;
+    out.log(`  ⚠ BREAKING (${breaking.length})`);
+    out.log("");
+    for (const e of breaking) {
+        const manualId = manualIdOf(e);
+        out.log(`    ${e.version} · ${e.title}${manualId === undefined ? "" : `  [${manualId}]`}`);
+        logEntryDetail(out, e, verbose);
+        if (e.migration) {
+            out.log(`      → Migration: ${e.migration}`);
         }
         out.log("");
-        const code = await applyCodemods(out, pending, repoRoot, targetDir, dryRun, markerVersion ?? currentVersion, carryOf(markerRead), currentVersion, verbose ? manualDetailsOf(allEntries) : undefined);
-        out.log("");
-        return code;
-    }
-    if (jsonMode) {
-        const { pendingManual } = carryOf(markerRead);
-        const pendingWithManualId = pending.map((entry) => {
-            const manualId = manualIdOf(entry);
-            return manualId === undefined ? entry : { ...entry, manualId };
-        });
-        out.log(JSON.stringify({ currentVersion, installedVersion, pending: pendingWithManualId, pendingManual }, null, 2));
-        return 0;
     }
+}
+function logNonBreakingSection(out, heading, entries, verbose, showCodemod) {
+    // skip: no entries of this type, the section is omitted
+    if (entries.length === 0)
+        return;
+    out.log(`  ✓ ${heading} (${entries.length})`);
+    out.log("");
+    for (const e of entries) {
+        out.log(`    ${e.version} · ${e.title}`);
+        logEntryDetail(out, e, verbose);
+        if (showCodemod && hasCodemod(e)) {
+            out.log(`      → codemod: ${e.codemod} (runs on --apply)`);
+        }
+    }
+    out.log("");
+}
+function reportUpgradeText(out, plan, verbose) {
+    const { pending } = plan;
     const breaking = pending.filter((e) => e.type === "breaking");
-    const improvements = pending.filter((e) => e.type === "improvement");
-    const fixes = pending.filter((e) => e.type === "fix");
-    const openManual = carryOf(markerRead).pendingManual;
+    const openManual = carryOf(plan.markerRead).pendingManual;
+    const manualDetails = verbose ? manualDetailsOf(plan.allEntries) : undefined;
     out.log("");
-    out.log(`  Upgrade: ${currentVersion} → latest`);
+    out.log(`  Upgrade: ${plan.currentVersion} → latest`);
     out.log("");
     if (pending.length === 0) {
         out.log("  ✓ Nothing new since your version.");
         out.log("");
-        logOpenManual(out, openManual, verbose ? manualDetailsOf(allEntries) : undefined);
+        logOpenManual(out, openManual, manualDetails);
         return 0;
     }
-    if (breaking.length > 0) {
-        out.log(`  ⚠ BREAKING (${breaking.length})`);
-        out.log("");
-        for (const e of breaking) {
-            const manualId = manualIdOf(e);
-            out.log(`    ${e.version} · ${e.title}${manualId === undefined ? "" : `  [${manualId}]`}`);
-            if (verbose && e.detail) {
-                out.log(`      ${e.detail}`);
-            }
-            if (e.migration) {
-                out.log(`      → Migration: ${e.migration}`);
-            }
-            out.log("");
-        }
-    }
-    if (improvements.length > 0) {
-        out.log(`  ✓ IMPROVEMENTS (${improvements.length})`);
-        out.log("");
-        for (const e of improvements) {
-            out.log(`    ${e.version} · ${e.title}`);
-            if (verbose && e.detail) {
-                out.log(`      ${e.detail}`);
-            }
-        }
-        out.log("");
-    }
-    if (fixes.length > 0) {
-        out.log(`  ✓ FIXES (${fixes.length})`);
-        out.log("");
-        for (const e of fixes) {
-            out.log(`    ${e.version} · ${e.title}`);
-            if (verbose && e.detail) {
-                out.log(`      ${e.detail}`);
-            }
-        }
-        out.log("");
-    }
+    logBreakingSection(out, breaking, verbose);
+    logNonBreakingSection(out, "IMPROVEMENTS", pending.filter((e) => e.type === "improvement"), verbose, true);
+    logNonBreakingSection(out, "FIXES", pending.filter((e) => e.type === "fix"), verbose, false);
     if (breaking.length > 0) {
         out.log("  ⚠ Review breaking changes above before upgrading.");
         out.log("  Run with --verbose for full migration details.");
         out.log("");
     }
-    logOpenManual(out, openManual, verbose ? manualDetailsOf(allEntries) : undefined);
+    logOpenManual(out, openManual, manualDetails);
     return 0;
 }
+// Shared by `kumiko upgrade` and the published kumiko-upgrade bin.
+export async function runUpgradeCli(argv, cwd, out, options) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        out.log(UPGRADE_USAGE);
+        return 0;
+    }
+    // Standalone CLI entry, not booted via runProdApp/runDevApp — Temporal needs an explicit polyfill here.
+    await ensureTemporalPolyfill();
+    const args = parseArgs(argv);
+    // Resolved once here (not just inside --apply) so both the filter
+    // baseline and the --apply codemod run target the same directory.
+    const dirFlag = getStringFlag(args, "dir");
+    const targetDir = dirFlag ? resolve(dirFlag) : cwd;
+    if (!existsSync(targetDir) || !statSync(targetDir).isDirectory()) {
+        return failUpgrade(out, `--dir path is not a directory: ${targetDir}`);
+    }
+    if (args.flags.has("resolve")) {
+        return resolveManualMigrations(out, args, targetDir);
+    }
+    const planned = planUpgrade(args, cwd, targetDir);
+    if (planned.kind === "error")
+        return failUpgrade(out, ...planned.lines);
+    if (getFlag(args, "apply")) {
+        return applyPlannedUpgrade(out, args, planned.value, options?.repoRoot ?? cwd, targetDir);
+    }
+    if (getFlag(args, "json"))
+        return reportUpgradeJson(out, planned.value);
+    return reportUpgradeText(out, planned.value, getFlag(args, "verbose"));
+}

package/dist/utils/compare.js

@@ -1,7 +1,7 @@
 // Locale-independent string ordering for sorts that feed byte-exact serialized
 // artifacts (manifest JSON, snapshot.json, generated migration SQL). Unlike
 // String.localeCompare — whose order depends on the runner's ICU locale and so
-// can drift between a macOS dev box and Linux CI (#330) — this compares by
+// can drift between a macOS dev box and Linux CI — this compares by
 // UTF-16 code unit, which is stable across machines and, for the BMP identifier
 // strings we sort here (table / column / feature / qualified names), equals
 // codepoint order.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.386.0",
+  "version": "0.388.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
-  "license": "BUSL-1.1",
+  "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
   "repository": {
     "type": "git",
@@ -199,7 +199,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.386.0",
+    "@cosmicdrift/kumiko-types": "0.388.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -208,14 +208,14 @@
     "jose": "^6.2.3",
     "meilisearch": "^0.58.0",
     "pino": "^10.3.1",
-    "postgres": "npm:@bender0oo0/postgres@3.4.9-kumiko.1",
+    "postgres": "npm:@bender0oo0/postgres@3.4.9-kumiko.2",
     "temporal-polyfill": "^0.3.2",
     "ts-morph": "^28.0.0",
     "uuid": "^14.0.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-testing": "0.386.0",
+    "@cosmicdrift/kumiko-testing": "0.388.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },