@cosmicdrift/kumiko-framework 0.374.0 → 0.377.0

package/dist/upgrade-cli.js

@@ -4,6 +4,7 @@ import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { getFlag, getStringFlag, parseArgs } from "./arg-parser.js";
 import { compareVersions, filterEntriesAfter, parseFeatureChangelog, sortEntries, } from "./engine/index.js";
 import { ensureTemporalPolyfill } from "./time/index.js";
+import { mergeUpgradeSection } from "./upgrade-changelog.js";
 const SEMVER_RE = /^\d+\.\d+\.\d+$/;
 const SEMVER_CORE_RE = /^(\d+\.\d+\.\d+)(?:-[0-9A-Za-z.-]+)?$/;
 const CODEMOD_SUBDIR = "scripts/codemod";
@@ -340,12 +341,24 @@ function carryOverManual(previous, newManual) {
         ...(previous.resolvedManual.length > 0 && { resolvedManual: previous.resolvedManual }),
     };
 }
+// The marker records every codemod ever applied, not just the last bump's, so the
+// CI guard and a resumed run see the whole history.
+function accumulateCodemods(previous, ran) {
+    const seen = new Set();
+    return [...previous, ...ran].filter((entry) => {
+        const key = `${entry.version}\0${entry.codemod}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
 function writeUpgradeMarker(targetDir, marker) {
     const dir = join(targetDir, ".kumiko");
     mkdirSync(dir, { recursive: true });
     writeFileSync(join(dir, "upgrade-state.json"), `${JSON.stringify(marker, null, 2)}\n`, "utf-8");
 }
-const NO_CARRY = { pendingManual: [], resolvedManual: [] };
+const NO_CARRY = { codemods: [], pendingManual: [], resolvedManual: [] };
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -427,16 +440,52 @@ function carryOf(read) {
 function printable(text) {
     return text.replace(/\p{Cc}/gu, "");
 }
-function logOpenManual(out, open) {
+function manualDetailsOf(entries) {
+    return new Map(entries.map((entry) => [
+        manualEntryId(entry.version, entry.title),
+        { detail: entry.detail, migration: entry.migration },
+    ]));
+}
+function logOpenManual(out, open, details) {
     // skip: no open manual migrations, nothing to report
     if (open.length === 0)
         return;
     out.log(`  ⚠ ${open.length} manual migration(s) still open:`);
     for (const entry of open) {
         out.log(`    ${printable(entry.id)} · ${printable(entry.version)} · ${printable(entry.title)}`);
+        const entryDetails = details?.get(entry.id);
+        if (entryDetails?.detail)
+            out.log(`      ${printable(entryDetails.detail.replace(/\s*\n\s*/g, " "))}`);
+        if (entryDetails?.migration)
+            out.log(`      → Migration: ${printable(entryDetails.migration)}`);
     }
     out.log('  Migrate them by hand, then mark them done: kumiko-upgrade --resolve <id|version> --reason "<what you did>" [--not-applicable]');
 }
+function manualWithStatus(manualEntries, previous) {
+    return manualEntries.map((entry) => {
+        const id = manualEntryId(entry.version, entry.title);
+        const resolved = previous.resolvedManual.find((candidate) => candidate.id === id);
+        return {
+            id,
+            version: entry.version,
+            title: entry.title,
+            status: resolved === undefined ? "open" : resolved.resolution,
+        };
+    });
+}
+// Runs only for a real bump: an app that is already current keeps its CHANGELOG.md untouched.
+function writeUpgradeChangelog(targetDir, bump) {
+    const path = join(targetDir, "CHANGELOG.md");
+    const existing = existsSync(path) ? readFileSync(path, "utf-8") : undefined;
+    writeFileSync(path, mergeUpgradeSection(existing, {
+        from: bump.from,
+        to: bump.to,
+        date: Temporal.Now.instant().toString().slice(0, 10),
+        breaking: bump.pending.filter((entry) => entry.type === "breaking"),
+        manual: manualWithStatus(bump.manualEntries, bump.previous),
+        codemods: bump.ran,
+    }), "utf-8");
+}
 // Records the codemods that already wrote files before a later one failed, so
 // a re-run resumes after them instead of replaying non-idempotent codemods.
 function writePartialMarker(out, targetDir, pending, manualEntries, failedVersion, ran, previous) {
@@ -453,7 +502,7 @@ function writePartialMarker(out, targetDir, pending, manualEntries, failedVersio
     writeUpgradeMarker(targetDir, {
         version,
         appliedAt: Temporal.Now.instant().toString(),
-        codemods: ran,
+        codemods: accumulateCodemods(previous.codemods, ran),
         ...carryOverManual(previous, manualEntries.map(toMarkerManual)),
     });
     out.err(`  ⚠ ${ran.length} codemod(s) already applied; wrote marker at ${version} so a re-run resumes at the failed one.`);
@@ -469,7 +518,7 @@ async function applyCodemods(out, pending, repoRoot, targetDir, dryRun,
 // Installed version for the zero-pending bootstrap marker — never a
 // `--from` filter override (that would permanently skip real pending
 // codemods once the CI guard compares against the fake marker).
-markerVersion, previous) {
+markerVersion, previous, fromVersion, manualDetails) {
     if (pending.length === 0) {
         out.log("  ✓ Nothing new since your version.");
         if (!dryRun) {
@@ -477,11 +526,11 @@ markerVersion, previous) {
             writeUpgradeMarker(targetDir, {
                 version: markerVersion,
                 appliedAt: Temporal.Now.instant().toString(),
-                codemods: [],
+                codemods: previous.codemods,
                 ...carried,
             });
             out.log(`  ✓ Applied 0 codemod(s). Wrote ${join(targetDir, ".kumiko/upgrade-state.json")}`);
-            logOpenManual(out, carried.pendingManual ?? []);
+            logOpenManual(out, carried.pendingManual ?? [], manualDetails);
         }
         return 0;
     }
@@ -504,11 +553,19 @@ markerVersion, previous) {
             writeUpgradeMarker(targetDir, {
                 version: markerVersion,
                 appliedAt: Temporal.Now.instant().toString(),
-                codemods: [],
+                codemods: previous.codemods,
                 ...carried,
             });
+            writeUpgradeChangelog(targetDir, {
+                from: fromVersion,
+                to: markerVersion,
+                pending,
+                manualEntries,
+                ran: [],
+                previous,
+            });
             out.log(`  ✓ Applied 0 codemod(s). Wrote ${join(targetDir, ".kumiko/upgrade-state.json")}`);
-            logOpenManual(out, carried.pendingManual ?? []);
+            logOpenManual(out, carried.pendingManual ?? [], manualDetails);
         }
         return 0;
     }
@@ -546,11 +603,19 @@ markerVersion, previous) {
     writeUpgradeMarker(targetDir, {
         version: markerVersion,
         appliedAt: Temporal.Now.instant().toString(),
-        codemods: ran,
+        codemods: accumulateCodemods(previous.codemods, ran),
         ...carried,
     });
+    writeUpgradeChangelog(targetDir, {
+        from: fromVersion,
+        to: markerVersion,
+        pending,
+        manualEntries,
+        ran,
+        previous,
+    });
     out.log(`  ✓ Applied ${ran.length} codemod(s). Wrote ${join(targetDir, ".kumiko/upgrade-state.json")}`);
-    logOpenManual(out, carried.pendingManual ?? []);
+    logOpenManual(out, carried.pendingManual ?? [], manualDetails);
     return 0;
 }
 function parseResolveInput(args) {
@@ -751,7 +816,7 @@ export async function runUpgradeCli(argv, cwd, out, options) {
             return 1;
         }
         out.log("");
-        const code = await applyCodemods(out, pending, repoRoot, targetDir, dryRun, markerVersion ?? currentVersion, carryOf(markerRead));
+        const code = await applyCodemods(out, pending, repoRoot, targetDir, dryRun, markerVersion ?? currentVersion, carryOf(markerRead), currentVersion, verbose ? manualDetailsOf(allEntries) : undefined);
         out.log("");
         return code;
     }
@@ -774,7 +839,7 @@ export async function runUpgradeCli(argv, cwd, out, options) {
     if (pending.length === 0) {
         out.log("  ✓ Nothing new since your version.");
         out.log("");
-        logOpenManual(out, openManual);
+        logOpenManual(out, openManual, verbose ? manualDetailsOf(allEntries) : undefined);
         return 0;
     }
     if (breaking.length > 0) {
@@ -819,6 +884,6 @@ export async function runUpgradeCli(argv, cwd, out, options) {
         out.log("  Run with --verbose for full migration details.");
         out.log("");
     }
-    logOpenManual(out, openManual);
+    logOpenManual(out, openManual, verbose ? manualDetailsOf(allEntries) : undefined);
     return 0;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.374.0",
+  "version": "0.377.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -199,8 +199,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.374.0",
-    "@cosmicdrift/kumiko-types": "0.374.0",
+    "@cosmicdrift/kumiko-types": "0.377.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -216,8 +215,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.374.0",
-    "@cosmicdrift/kumiko-testing": "0.374.0",
+    "@cosmicdrift/kumiko-testing": "0.377.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/presets/biome-app.json

@@ -62,6 +62,14 @@
     }
   },
   "overrides": [
+    {
+      "includes": ["bin/**", "scripts/**", "**/bin/**", "**/scripts/**"],
+      "linter": {
+        "rules": {
+          "suspicious": { "noConsole": "off" }
+        }
+      }
+    },
     {
       "includes": [
         "**/*.test.ts",

package/src/changes.json

@@ -1,4 +1,75 @@
 [
+  {
+    "version": "0.377.0",
+    "type": "improvement",
+    "title": "design decisions log",
+    "detail": "docs/reference/decisions.md records lasting design decisions with their reasons. It is documentation only and changes no behavior."
+  },
+  {
+    "version": "0.377.0",
+    "type": "improvement",
+    "title": "Env hint links to the infra deploy runbook",
+    "detail": "The boot env report ends with a link to docs/runbooks/standard-deploy-app.md in the infra repo instead of a path in kumiko-platform that no longer exists."
+  },
+  {
+    "version": "0.377.0",
+    "type": "improvement",
+    "title": "Replay parser and migration splitter cover dollar quotes, RENAME, CREATE TABLE AS and DO",
+    "detail": "splitSqlStatements keeps dollar-quoted bodies whole and throws on an unterminated one. The replay parser follows RENAME TO, RENAME COLUMN, CREATE TABLE AS and DO blocks; tables with columns it cannot derive are skipped in the schema diff. The Bun.SQL wording in db/query.ts errors and logger names now says postgres-js."
+  },
+  {
+    "version": "0.377.0",
+    "type": "improvement",
+    "title": "providerPluginContextFromHandler and providerPluginContextFromJob",
+    "detail": "Build a ProviderPluginContext from a HandlerContext or JobContext (jobs use the system user and have no dbOutsideTransaction)."
+  },
+  {
+    "version": "0.377.0",
+    "type": "improvement",
+    "title": "hasOutsideTransactionDb and requireOutsideTransactionDb",
+    "detail": "Public helpers in the db barrel. hasOutsideTransactionDb(ctx) narrows ctx.dbOutsideTransaction to TenantDb; requireOutsideTransactionDb(ctx) returns it or throws an InternalError."
+  },
+  {
+    "version": "0.377.0",
+    "type": "breaking",
+    "title": "Provider contexts expose auditUserId instead of _userId",
+    "detail": "FileProviderContext, MailTransportContext, InboundMailContext and the context read by requireSecretsContext name the audit identity auditUserId. The old underscore field is gone.",
+    "migration": "Rename _userId to auditUserId wherever a provider context is built by hand (tests, custom resolvers, worker wiring). requireSecretsContext still falls back to ctx.user.id when it is unset."
+  },
+  {
+    "version": "0.377.0",
+    "type": "improvement",
+    "title": "Boot always sets configAccessorFactory and overrides an app value",
+    "detail": "addConfigAccessorFactory writes configAccessorFactory and the _configAccessorFactory alias from the effective configResolver, replacing any app-supplied factory. The replay parser also rejects DO blocks without a dollar-quoted body and accepts tags like $do1$."
+  },
+  {
+    "version": "0.377.0",
+    "type": "improvement",
+    "title": "http moved into framework",
+    "detail": "egress(), the host policy helpers and their errors are implemented in @cosmicdrift/kumiko-framework/http. @cosmicdrift/kumiko-http now only re-exports that subpath and is removed after the consumer pass of wave 4.",
+    "migration": "Run bun kumiko-upgrade --apply, or bun kumiko codemod package-merge . --write. It rewrites imports of @cosmicdrift/kumiko-http to @cosmicdrift/kumiko-framework/http and replaces the kumiko-http dependency in package.json with kumiko-framework.",
+    "codemod": "scripts/codemod/package-merge.ts"
+  },
+  {
+    "version": "0.377.0",
+    "type": "improvement",
+    "title": "package-merge codemod covers headless and dispatcher-live",
+    "detail": "The mapping table of the package-merge codemod gained the headless and dispatcher-live moves into kumiko-renderer.",
+    "codemod": "scripts/codemod/package-merge.ts"
+  },
+  {
+    "version": "0.377.0",
+    "type": "improvement",
+    "title": "package-merge codemod covers renderer-web and CSS files",
+    "detail": "The mapping table of the package-merge codemod gained the renderer-web move into kumiko-renderer/web, and the codemod now also rewrites .css files (@import, @plugin, @config). A @source path into the old package is reported for manual follow-up.",
+    "codemod": "scripts/codemod/package-merge.ts"
+  },
+  {
+    "version": "0.376.0",
+    "type": "improvement",
+    "title": "kumiko-upgrade writes CHANGELOG.md and shows manual entries with --verbose",
+    "detail": "--apply adds one section per bump to CHANGELOG.md in the app (changed packages, breaking titles, manual migrations with status, codemods applied); a re-run of the same bump replaces its section. --verbose prints detail and migration of the open manual entries. A second --apply keeps the codemods already recorded in the marker. The biome-app preset allows console in bin and scripts. AppConfig takes an optional includeBundled flag that the managed kumiko/schema.ts uses to compose the bundled auth features."
+  },
   {
     "version": "0.374.0",
     "type": "improvement",

package/src/scripts/codemod/README.md

@@ -140,3 +140,28 @@ bun node_modules/@cosmicdrift/kumiko-framework/src/scripts/codemod/remove-engine
 
 Runs via `bun kumiko-upgrade --apply`. Without a mode flag it writes, then formats the changed files
 with Biome. `--check` exits 1 while any rewritable or manual site is left.
+
+## package-merge.ts
+
+Packages folded into another package stay as re-export shims for one wave. The codemod rewrites
+imports, re-exports, `import("…")` and `mock.module` specifiers (including subpaths) of the old
+package to the new one, and in `package.json` replaces the old dependency with the target package
+(same version range, same block, skipped when the block already lists it). The moves are the rows
+of `PACKAGE_MERGE_MAPPINGS`: `@cosmicdrift/kumiko-http` to `@cosmicdrift/kumiko-framework/http`,
+`@cosmicdrift/kumiko-repo-manifest` to `@cosmicdrift/kumiko-guards/repo-manifest`,
+`@cosmicdrift/kumiko-headless` to `@cosmicdrift/kumiko-renderer/headless` (subpaths keep their name),
+`@cosmicdrift/kumiko-dispatcher-live` to `@cosmicdrift/kumiko-renderer/live`,
+`@cosmicdrift/kumiko-renderer-web` to `@cosmicdrift/kumiko-renderer/web` (so
+`@import "@cosmicdrift/kumiko-renderer-web/styles.css"` becomes
+`@import "@cosmicdrift/kumiko-renderer/web/styles.css"`).
+
+`.css` files are covered too: the specifier of `@import`, `@plugin` and `@config` is rewritten like
+an import. A `@source` path into `node_modules/<old package>/…` has no mechanical target and is
+reported as manual.
+
+```bash
+bun node_modules/@cosmicdrift/kumiko-framework/src/scripts/codemod/package-merge.ts <dir> [--check | --dry-run | --write] [--no-format]
+```
+
+Runs via `bun kumiko-upgrade --apply`. Without a mode flag it writes. `--check` exits 1 while any
+site is left. Run your package manager's install afterwards to refresh the lockfile.

package/src/scripts/codemod/codemod-support.ts

@@ -1,6 +1,12 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
-import { type ImportDeclaration, type ImportSpecifier, Node, type SourceFile } from "ts-morph";
+import {
+  type ImportDeclaration,
+  type ImportSpecifier,
+  Node,
+  type SourceFile,
+  SyntaxKind,
+} from "ts-morph";
 import { collectSourceFiles } from "./collect-source-files.ts";
 
 export interface CodemodSite {
@@ -48,6 +54,47 @@ export function relativeSpecifier(
   return `${path.startsWith(".") ? path : `./${path}`}${extension}`;
 }
 
+function stringLiteralOf(node: Node | undefined): Node | undefined {
+  return node !== undefined && Node.isStringLiteral(node) ? node : undefined;
+}
+
+export interface TextEdit {
+  readonly start: number;
+  readonly end: number;
+  readonly text: string;
+}
+
+export function applyEdits(source: string, edits: readonly TextEdit[]): string {
+  let output = source;
+  for (const edit of [...edits].sort((x, y) => y.start - x.start)) {
+    output = output.slice(0, edit.start) + edit.text + output.slice(edit.end);
+  }
+  return output;
+}
+
+export function moduleSpecifierLiterals(sourceFile: SourceFile): Node[] {
+  const literals: Node[] = [];
+  for (const declaration of [
+    ...sourceFile.getImportDeclarations(),
+    ...sourceFile.getExportDeclarations(),
+  ]) {
+    const literal = declaration.getModuleSpecifier();
+    if (literal !== undefined) literals.push(literal);
+  }
+  for (const importType of sourceFile.getDescendantsOfKind(SyntaxKind.ImportType)) {
+    const argument = importType.getArgument();
+    if (Node.isLiteralTypeNode(argument)) literals.push(argument.getLiteral());
+  }
+  for (const call of sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+    const callee = call.getExpression();
+    const isModuleLoad =
+      callee.getKind() === SyntaxKind.ImportKeyword || callee.getText() === "mock.module";
+    const literal = stringLiteralOf(call.getArguments()[0]);
+    if (isModuleLoad && literal !== undefined) literals.push(literal);
+  }
+  return literals;
+}
+
 export function isPlainNamedImport(declaration: Node): boolean {
   return (
     Node.isImportDeclaration(declaration) &&
@@ -202,7 +249,7 @@ function parseArgs(argv: readonly string[]): CliOptions {
   return { mode: mode ?? "write", format, paths };
 }
 
-function isMigratableFile(name: string): boolean {
+function isSourceFileName(name: string): boolean {
   return /\.(ts|tsx)$/.test(name) && !name.endsWith(".d.ts");
 }
 
@@ -215,6 +262,10 @@ export interface CodemodCliConfig {
   readonly name: string;
   readonly transform: (source: string, filePath: string) => CodemodResult;
   readonly isSkippedPath: (file: string) => boolean;
+  // Exact file names (e.g. package.json) handed to transform next to the .ts/.tsx sources.
+  readonly extraFileNames?: readonly string[];
+  // File extensions (e.g. ".css") handed to transform next to the .ts/.tsx sources.
+  readonly extraExtensions?: readonly string[];
 }
 
 function parseArgsOrExit(codemodName: string, argv: readonly string[]): CliOptions {
@@ -262,15 +313,22 @@ export async function runCodemodCli(
   argv: readonly string[],
 ): Promise<void> {
   const options = parseArgsOrExit(config.name, argv);
-  const files = collectSourceFiles(options.paths, { isMigratableFile }).filter(
-    (file) => !(file.includes("/__tests__/fixtures/") || config.isSkippedPath(file)),
-  );
+  const files = collectSourceFiles(options.paths, {
+    isMigratableFile: (name) =>
+      isSourceFileName(name) ||
+      (config.extraFileNames?.includes(name) ?? false) ||
+      (config.extraExtensions?.some((extension) => name.endsWith(extension)) ?? false),
+  }).filter((file) => !(file.includes("/__tests__/fixtures/") || config.isSkippedPath(file)));
   const { rewrites, manual, changedFiles } = transformFiles(config, files, options.mode);
   console.log(
     `\n[${config.name}] ${options.mode === "write" ? "rewritten" : "rewritable"}: ${rewrites.length} site(s) in ${new Set(rewrites.map((site) => site.file)).size} file(s); manual: ${manual.length}`,
   );
   if (options.mode === "write" && options.format && changedFiles.length > 0) {
-    await formatWithBiome(config.name, changedFiles, resolve(options.paths[0] ?? "."));
+    await formatWithBiome(
+      config.name,
+      changedFiles.filter((file) => isSourceFileName(file)),
+      resolve(options.paths[0] ?? "."),
+    );
   }
   process.exit(options.mode === "check" && rewrites.length + manual.length > 0 ? 1 : 0);
 }