@cosmicdrift/kumiko-framework 0.328.0 → 0.329.0

package/dist/upgrade-cli.js

@@ -0,0 +1,532 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync, } from "node:fs";
+import { 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";
+const SEMVER_RE = /^\d+\.\d+\.\d+$/;
+const CODEMOD_SUBDIR = "scripts/codemod";
+function readPackageVersion(cwd, pkgName, repoLocalPath) {
+    // Walk up from cwd to find node_modules/@cosmicdrift/<pkgName>/package.json
+    // (handles bun workspace hoisting where packages live in parent node_modules)
+    let dir = cwd;
+    for (let i = 0; i < 10; i++) {
+        const nmPath = join(dir, `node_modules/@cosmicdrift/${pkgName}/package.json`);
+        if (existsSync(nmPath)) {
+            try {
+                const pkg = JSON.parse(readFileSync(nmPath, "utf-8"));
+                return pkg.version ?? null;
+            }
+            catch {
+                return null;
+            }
+        }
+        const parent = join(dir, "..");
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    // Fallback: repo-local package root
+    const repoPath = join(cwd, repoLocalPath);
+    if (existsSync(repoPath)) {
+        try {
+            const pkg = JSON.parse(readFileSync(repoPath, "utf-8"));
+            return pkg.version ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+// Changelog entries come from @cosmicdrift/kumiko-bundled-features (see
+// findFeaturesDirs); comparing against the framework version instead
+// compares unrelated packages once the two stop being versioned in lockstep.
+function readCurrentVersion(cwd) {
+    return (readPackageVersion(cwd, "kumiko-bundled-features", "packages/bundled-features/package.json") ??
+        readPackageVersion(cwd, "kumiko-framework", "packages/framework/package.json"));
+}
+function readChangelogFile(filePath) {
+    if (!existsSync(filePath))
+        return [];
+    try {
+        return [...(parseFeatureChangelog(readFileSync(filePath, "utf-8"), filePath)?.entries ?? [])];
+    }
+    catch {
+        // Skip malformed files
+        return [];
+    }
+}
+function collectChangelogs(featuresDir) {
+    if (!existsSync(featuresDir))
+        return [];
+    const entries = [];
+    const features = readdirSync(featuresDir, { withFileTypes: true })
+        .filter((d) => d.isDirectory())
+        .map((d) => d.name);
+    for (const name of features) {
+        // 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).
+        const srcLayout = join(featuresDir, name, "src", "changes.json");
+        const flatLayout = join(featuresDir, name, "changes.json");
+        const changelogPath = existsSync(srcLayout) ? srcLayout : flatLayout;
+        entries.push(...readChangelogFile(changelogPath));
+    }
+    return entries;
+}
+// bundled-features is excluded: findFeaturesDirs collects it per feature
+// (src/<feature>/changes.json), every other package has one src/changes.json.
+export function findPackageChangelogFiles(cwd) {
+    const isFrameworkRepo = existsSync(join(cwd, "packages/framework"));
+    if (isFrameworkRepo) {
+        const packagesDir = join(cwd, "packages");
+        return readdirSync(packagesDir, { withFileTypes: true })
+            .filter((d) => d.isDirectory() && d.name !== "bundled-features")
+            .map((d) => join(packagesDir, d.name, "src", "changes.json"))
+            .filter((p) => existsSync(p));
+    }
+    // Consumer/app repo: walk up (same 10-level cap as the other node_modules
+    // walks) collecting every hoisted @cosmicdrift package's changes.json.
+    // Dedupe by package dir name — the nearest node_modules to cwd wins, same
+    // precedence as findCodemodScriptsRoot/readPackageVersion. realpath also
+    // dedupes a workspace symlink that resolves to an already-collected file.
+    const files = [];
+    const seenNames = new Set();
+    const seenRealPaths = new Set();
+    let dir = cwd;
+    for (let i = 0; i < 10; i++) {
+        const scopeDir = join(dir, "node_modules/@cosmicdrift");
+        if (existsSync(scopeDir)) {
+            const pkgNames = readdirSync(scopeDir, { withFileTypes: true })
+                .filter((d) => d.isDirectory() && d.name !== "kumiko-bundled-features")
+                .map((d) => d.name);
+            for (const name of pkgNames) {
+                if (seenNames.has(name))
+                    continue;
+                const changelogPath = join(scopeDir, name, "src", "changes.json");
+                if (!existsSync(changelogPath))
+                    continue;
+                seenNames.add(name);
+                const realPath = realpathSync(changelogPath);
+                if (seenRealPaths.has(realPath))
+                    continue;
+                seenRealPaths.add(realPath);
+                files.push(changelogPath);
+            }
+        }
+        const parent = join(dir, "..");
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return files;
+}
+export function findFeaturesDirs(cwd) {
+    const dirs = [];
+    // Framework repo: packages/bundled-features/src
+    const fwDir = join(cwd, "packages/bundled-features/src");
+    if (existsSync(fwDir))
+        dirs.push(fwDir);
+    // 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
+    // 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.
+    const isFrameworkRepo = existsSync(join(cwd, "packages/framework"));
+    const entDir = join(cwd, "packages");
+    if (!isFrameworkRepo && existsSync(entDir)) {
+        const hasEntPkgs = readdirSync(entDir, { withFileTypes: true }).some((d) => d.isDirectory() &&
+            (existsSync(join(entDir, d.name, "changes.json")) ||
+                existsSync(join(entDir, d.name, "src", "changes.json"))));
+        if (hasEntPkgs)
+            dirs.push(entDir);
+    }
+    // App repos: walk up to find bundled-features in hoisted node_modules.
+    // Skipped inside the framework repo — the workspace symlink points back at
+    // the dir already collected above and would duplicate every entry.
+    if (dirs.includes(fwDir))
+        return dirs;
+    let dir = cwd;
+    for (let i = 0; i < 10; i++) {
+        const nmDir = join(dir, "node_modules/@cosmicdrift/kumiko-bundled-features/src");
+        if (existsSync(nmDir)) {
+            dirs.push(nmDir);
+            break;
+        }
+        const parent = join(dir, "..");
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return dirs;
+}
+// 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).
+export function findCodemodScriptsRoot(repoRoot) {
+    const local = join(repoRoot, "packages/framework/src");
+    if (existsSync(join(local, CODEMOD_SUBDIR))) {
+        // If package.json exists, require it to be kumiko-framework so a generic
+        // monorepo `packages/framework` cannot shadow the installed package.
+        // Missing package.json (test fixtures / incomplete trees) keeps prior behavior.
+        const pkgPath = join(repoRoot, "packages/framework/package.json");
+        if (existsSync(pkgPath)) {
+            try {
+                const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+                if (pkg.name === "@cosmicdrift/kumiko-framework")
+                    return local;
+                // wrong name → fall through
+            }
+            catch {
+                // unreadable → fall through
+            }
+        }
+        else {
+            return local;
+        }
+    }
+    let dir = repoRoot;
+    for (let i = 0; i < 10; i++) {
+        const nmSrc = join(dir, "node_modules/@cosmicdrift/kumiko-framework/src");
+        if (existsSync(join(nmSrc, CODEMOD_SUBDIR)))
+            return nmSrc;
+        const parent = join(dir, "..");
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+// Resolves a changes.json `codemod` field to an absolute script path,
+// refusing anything that would escape scripts/codemod/ (path traversal,
+// 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).
+function resolveCodemodScriptAt(codemodScriptsRoot, codemodField) {
+    if (!codemodField)
+        return null;
+    if (codemodField.includes("\0") || codemodField.startsWith("/") || !codemodField.endsWith(".ts"))
+        return null;
+    const scriptsRoot = join(codemodScriptsRoot, CODEMOD_SUBDIR);
+    const resolved = join(codemodScriptsRoot, codemodField);
+    const rel = relative(scriptsRoot, resolved);
+    if (rel === "" || rel.startsWith("..") || isAbsolute(rel))
+        return null;
+    if (!existsSync(resolved))
+        return null;
+    try {
+        const realResolved = realpathSync(resolved);
+        const realScriptsRoot = realpathSync(scriptsRoot);
+        const realRel = relative(realScriptsRoot, realResolved);
+        if (realRel.startsWith("..") || isAbsolute(realRel))
+            return null;
+    }
+    catch {
+        return null;
+    }
+    return resolved;
+}
+export function resolveCodemodScript(repoRoot, codemodField) {
+    const scriptsRoot = findCodemodScriptsRoot(repoRoot);
+    if (!scriptsRoot)
+        return null;
+    return resolveCodemodScriptAt(scriptsRoot, codemodField);
+}
+// Array-form argv only — never a shell string. The script itself decides
+// what to touch inside targetDir; this just invokes it as a subprocess.
+async function runCodemodScript(scriptPath, targetDir, repoRoot, dryRun) {
+    const cmd = ["bun", scriptPath, targetDir, ...(dryRun ? ["--dry-run"] : [])];
+    const proc = Bun.spawn({ cmd, cwd: repoRoot, stdout: "pipe", stderr: "pipe" });
+    const [stdout, stderr, exitCode] = await Promise.all([
+        new Response(proc.stdout).text(),
+        new Response(proc.stderr).text(),
+        proc.exited,
+    ]);
+    return { ok: exitCode === 0, output: `${stdout}${stderr}`.trim() };
+}
+function hasCodemod(e) {
+    return typeof e.codemod === "string" && e.codemod.length > 0;
+}
+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");
+}
+// Missing, unreadable, or invalid marker means no baseline was ever recorded
+// — most commonly a bootstrap app that never ran `--apply` (fw#2299) — so
+// this reports "no marker" instead of throwing.
+function readMarkerVersion(targetDir) {
+    const markerPath = join(targetDir, ".kumiko", "upgrade-state.json");
+    if (!existsSync(markerPath))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(markerPath, "utf-8"));
+        return typeof parsed.version === "string" && SEMVER_RE.test(parsed.version)
+            ? parsed.version
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Highest pending version strictly below the earliest open manual breaking
+ *  entry (no codemod). Falls back to highest non-breaking pending when every
+ *  pending version is at/after that manual. If only manuals remain, returns
+ *  `fallbackInstalled` so the marker stamp moves without claiming manuals done. */
+function markerVersionForPending(pending, manualEntries, fallbackInstalled) {
+    const earliestManual = [...manualEntries].sort((a, b) => compareVersions(a.version, b.version))[0];
+    const eligible = pending.filter((e) => earliestManual === undefined || compareVersions(e.version, earliestManual.version) < 0);
+    const headEligible = eligible[0];
+    if (headEligible !== undefined) {
+        return eligible.reduce((max, e) => (compareVersions(e.version, max) > 0 ? e.version : max), headEligible.version);
+    }
+    const nonBreaking = pending.filter((e) => e.type !== "breaking");
+    const headNonBreaking = nonBreaking[0];
+    if (headNonBreaking !== undefined) {
+        return nonBreaking.reduce((max, e) => (compareVersions(e.version, max) > 0 ? e.version : max), headNonBreaking.version);
+    }
+    return fallbackInstalled;
+}
+function logManualMarkerOutcome(out, manualEntries, markerVersion) {
+    if (manualEntries.length > 0) {
+        const markerHeldBack = manualEntries.some((e) => compareVersions(e.version, markerVersion) > 0);
+        out.log(markerHeldBack
+            ? `  ⚠ Marker stays at ${markerVersion}, so the upgrade guard keeps listing the manual change(s) above. Migrate them by hand, then run --apply again to acknowledge them.`
+            : `  ⚠ Marker moved past the manual change(s) above to ${markerVersion}; the upgrade guard no longer lists them, so make sure they are migrated.`);
+    }
+}
+// Runs every pending breaking entry's codemod, oldest version first (so a
+// later codemod can assume an earlier one already ran). Stops on the first
+// failure — no 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).
+// 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
+// `--from` filter override (that would permanently skip real pending
+// codemods once the CI guard compares against the fake marker).
+markerVersion) {
+    if (pending.length === 0) {
+        out.log("  ✓ Nothing new since your version.");
+        if (!dryRun) {
+            writeUpgradeMarker(targetDir, {
+                version: markerVersion,
+                appliedAt: Temporal.Now.instant().toString(),
+                codemods: [],
+            });
+            out.log(`  ✓ Applied 0 codemod(s). Wrote ${join(targetDir, ".kumiko/upgrade-state.json")}`);
+        }
+        return 0;
+    }
+    const breaking = pending.filter((e) => e.type === "breaking");
+    const codemodEntries = breaking
+        .filter(hasCodemod)
+        .sort((a, b) => compareVersions(a.version, b.version));
+    const manualEntries = breaking.filter((e) => !hasCodemod(e));
+    for (const e of manualEntries) {
+        out.log(`  ⚠ ${e.version} · ${e.title} — no codemod, manual migration required`);
+    }
+    if (codemodEntries.length === 0) {
+        out.log(breaking.length > 0
+            ? "  No automatable codemods among the pending breaking changes."
+            : "  ✓ No breaking changes pending.");
+        if (!dryRun) {
+            const markerVer = markerVersionForPending(pending, manualEntries, markerVersion);
+            writeUpgradeMarker(targetDir, {
+                version: markerVer,
+                appliedAt: Temporal.Now.instant().toString(),
+                codemods: [],
+            });
+            out.log(`  ✓ Applied 0 codemod(s). Wrote ${join(targetDir, ".kumiko/upgrade-state.json")}`);
+            logManualMarkerOutcome(out, manualEntries, markerVer);
+        }
+        return 0;
+    }
+    const codemodScriptsRoot = findCodemodScriptsRoot(repoRoot);
+    if (codemodScriptsRoot === null) {
+        out.err(`  ✗ could not locate @cosmicdrift/kumiko-framework/src/scripts/codemod — is the framework installed? searched from ${repoRoot} upward`);
+        return 1;
+    }
+    const ran = [];
+    for (const e of codemodEntries) {
+        const scriptPath = resolveCodemodScript(repoRoot, e.codemod);
+        if (!scriptPath) {
+            out.err(`  ✗ ${e.version} · ${e.title} — invalid codemod path "${e.codemod}"`);
+            return 1;
+        }
+        out.log(`  → ${e.version} · running ${e.codemod}${dryRun ? " (dry-run)" : ""}`);
+        const result = await runCodemodScript(scriptPath, targetDir, repoRoot, dryRun);
+        if (result.output)
+            out.log(result.output);
+        if (!result.ok) {
+            out.err(`  ✗ ${e.version} · ${e.codemod} failed`);
+            return 1;
+        }
+        ran.push({ version: e.version, codemod: e.codemod, title: e.title });
+    }
+    if (dryRun) {
+        out.log(`  ✓ Dry-run: ${ran.length} codemod(s) would run. Nothing written.`);
+        return 0;
+    }
+    const latestVersion = markerVersionForPending(pending, manualEntries, markerVersion);
+    const pendingManual = manualEntries.map((e) => ({ version: e.version, title: e.title }));
+    writeUpgradeMarker(targetDir, {
+        version: latestVersion,
+        appliedAt: Temporal.Now.instant().toString(),
+        codemods: ran,
+        ...(pendingManual.length > 0 && { pendingManual }),
+    });
+    out.log(`  ✓ Applied ${ran.length} codemod(s). Wrote ${join(targetDir, ".kumiko/upgrade-state.json")}`);
+    if (pendingManual.length > 0) {
+        out.log(`  ⚠ ${pendingManual.length} breaking change(s) still need manual migration.`);
+    }
+    logManualMarkerOutcome(out, manualEntries, latestVersion);
+    return 0;
+}
+const UPGRADE_USAGE = `kumiko-upgrade [--from <version>] [--dir <path>] [--json] [--verbose] [--apply [--dry-run]]
+
+  --from <version>   filter baseline version (default: last applied marker, or the installed version)
+  --dir <path>       target directory to check/apply against (default: cwd)
+  --json             machine-readable output
+  --verbose          include full migration details for each pending entry
+  --apply            run codemods for pending breaking changes and write the upgrade marker
+  --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;
+    }
+    // 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
+    // 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
+    // version, hiding breaking changes the marker never actually saw.
+    const currentVersion = fromFlag ?? readMarkerVersion(targetDir) ?? 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;
+    }
+    if (!SEMVER_RE.test(currentVersion)) {
+        out.err("");
+        out.err(`  Invalid version format: "${currentVersion}" — expected x.y.z`);
+        out.err("");
+        return 1;
+    }
+    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;
+    }
+    const allEntries = [];
+    for (const dir of featuresDirs) {
+        allEntries.push(...collectChangelogs(dir));
+    }
+    for (const changelogFile of packageChangelogFiles) {
+        allEntries.push(...readChangelogFile(changelogFile));
+    }
+    const pending = sortEntries(filterEntriesAfter(allEntries, 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 = (dirFlag ? readCurrentVersion(targetDir) : null) ?? installedVersion ?? currentVersion;
+        const dryRun = getFlag(args, "dry-run");
+        out.log("");
+        const code = await applyCodemods(out, pending, repoRoot, targetDir, dryRun, markerVersion);
+        out.log("");
+        return code;
+    }
+    if (jsonMode) {
+        out.log(JSON.stringify({ currentVersion, installedVersion, pending }, null, 2));
+        return 0;
+    }
+    const breaking = pending.filter((e) => e.type === "breaking");
+    const improvements = pending.filter((e) => e.type === "improvement");
+    const fixes = pending.filter((e) => e.type === "fix");
+    out.log("");
+    out.log(`  Upgrade: ${currentVersion} → latest`);
+    out.log("");
+    if (pending.length === 0) {
+        out.log("  ✓ Nothing new since your version.");
+        out.log("");
+        return 0;
+    }
+    if (breaking.length > 0) {
+        out.log(`  ⚠ BREAKING (${breaking.length})`);
+        out.log("");
+        for (const e of breaking) {
+            out.log(`    ${e.version} · ${e.title}`);
+            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("");
+    }
+    if (breaking.length > 0) {
+        out.log("  ⚠ Review breaking changes above before upgrading.");
+        out.log("  Run with --verbose for full migration details.");
+        out.log("");
+    }
+    return 0;
+}

package/dist/utils/assert.d.ts

@@ -0,0 +1 @@
+export declare function assertUnreachable(value: never, kind: string): never;

package/dist/utils/assert.js

@@ -0,0 +1,18 @@
+// Exhaustiveness-check helper for switch statements over union types.
+// Dropping a new member into the union triggers a compile-time error in
+// the call site unless a matching case is added — keeps switches honest
+// through future enum growth.
+//
+//   switch (status) {
+//     case "open": return ...;
+//     case "closed": return ...;
+//     default: assertUnreachable(status, "status");
+//   }
+//
+// The `never` parameter makes TS flag any code path that still has a
+// live value (e.g. a new union case was added and the switch missed it).
+// Runtime also throws so a production surprise surfaces loudly instead
+// of silently falling through.
+export function assertUnreachable(value, kind) {
+    throw new Error(`[Kumiko] unhandled ${kind}: ${String(value)}`);
+}

package/dist/utils/case.d.ts

@@ -0,0 +1 @@
+export declare function toSnakeCase(str: string): string;

package/dist/utils/case.js

@@ -0,0 +1,6 @@
+// Accepts both camelCase (`tenantMembership`) and kebab-case (`tenant-membership`)
+// names. Kebab is canonical for new multi-word identifiers; camelCase remains
+// supported for shipped code.
+export function toSnakeCase(str) {
+    return str.replace(/-/g, "_").replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+}

package/dist/utils/compare.d.ts

@@ -0,0 +1 @@
+export declare function compareByCodepoint(a: string, b: string): number;

package/dist/utils/compare.js

@@ -0,0 +1,10 @@
+// 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
+// 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.
+export function compareByCodepoint(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}

package/dist/utils/env-parse.d.ts

@@ -0,0 +1 @@
+export declare function readPositiveIntEnv(env: Readonly<Record<string, string | undefined>>, name: string): number | undefined;

package/dist/utils/env-parse.js

@@ -0,0 +1,13 @@
+// Strict env-var parsers. Misconfig at boot is loud: every helper throws
+// with the offending variable name + value so ops sees exactly what's
+// wrong instead of a cascading timeout downstream.
+export function readPositiveIntEnv(env, name) {
+    const raw = env[name];
+    if (raw === undefined || raw === "")
+        return undefined;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < 0 || !Number.isInteger(n)) {
+        throw new Error(`[env] ${name}="${raw}" must be a non-negative integer`);
+    }
+    return n;
+}

package/dist/utils/ids.d.ts

@@ -0,0 +1,2 @@
+export declare function generateId(): string;
+export declare function generateDeterministicId(namespace: string, key: string): string;

package/dist/utils/ids.js

@@ -0,0 +1,23 @@
+import { v5, v7 } from "uuid";
+// Non-secret identifiers for DB rows, event streams, correlation/request
+// IDs, SSE connections, distributed locks. UUIDv7: first 48 bits are a
+// Unix-ms timestamp, remaining 74 bits are random. Lexicographic order
+// matches chronological order, so B-Tree indexes stay dense on insert
+// and time-range queries ("events for stream X since T") read sequential
+// pages. Universal-safe — uses the `uuid` npm package, not `node:crypto`,
+// so the same call works in Bun, Node, Metro/RN, and Expo-Web bundles.
+//
+// Do NOT use this for security tokens (CSRF, session, API keys). The
+// timestamp prefix leaks creation time and shrinks unpredictable
+// entropy from 122 to 74 bits — use `generateToken` from api/tokens.ts.
+// @wrapper-known semantic-alias
+export function generateId() {
+    return v7();
+}
+// Derived from a DNS name (RFC 4122 §4.3) so the namespace is reproducible, not a hand-picked constant.
+const DETERMINISTIC_ID_NAMESPACE = v5("kumiko.rocks", v5.DNS);
+// Same (namespace, key) → same id, so a redelivered event hits the same row. Ids are
+// unique per table, not per tenant: fold the tenant id into `key` or tenants collide.
+export function generateDeterministicId(namespace, key) {
+    return v5(`${namespace}:${key}`, DETERMINISTIC_ID_NAMESPACE);
+}

package/dist/utils/index.d.ts

@@ -0,0 +1,9 @@
+export { assertUnreachable } from "./assert.js";
+export { toSnakeCase } from "./case.js";
+export { compareByCodepoint } from "./compare.js";
+export { readPositiveIntEnv } from "./env-parse.js";
+export { generateDeterministicId, generateId } from "./ids.js";
+export { isPlainObject } from "./is-plain-object.js";
+export { parseStringArrayJson } from "./parse-string-array-json.js";
+export { parseJsonOrThrow, parseJsonSafe, stringifyJson } from "./safe-json.js";
+export { parseRoles } from "./serialization.js";

package/dist/utils/index.js

@@ -0,0 +1,9 @@
+export { assertUnreachable } from "./assert.js";
+export { toSnakeCase } from "./case.js";
+export { compareByCodepoint } from "./compare.js";
+export { readPositiveIntEnv } from "./env-parse.js";
+export { generateDeterministicId, generateId } from "./ids.js";
+export { isPlainObject } from "./is-plain-object.js";
+export { parseStringArrayJson } from "./parse-string-array-json.js";
+export { parseJsonOrThrow, parseJsonSafe, stringifyJson } from "./safe-json.js";
+export { parseRoles } from "./serialization.js";

package/dist/utils/is-plain-object.d.ts

@@ -0,0 +1,2 @@
+/** Non-null object that is not an array — shared guard for deep-merge and AST extractors. */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;

package/dist/utils/is-plain-object.js

@@ -0,0 +1,4 @@
+/** Non-null object that is not an array — shared guard for deep-merge and AST extractors. */
+export function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/utils/parse-string-array-json.d.ts

@@ -0,0 +1,2 @@
+/** Parses a JSON-encoded string array from DB/cache columns; returns fallback on invalid input. */
+export declare function parseStringArrayJson(raw: string, fallback?: readonly string[]): readonly string[];