@cosmicdrift/kumiko-framework 0.387.0 → 0.389.0

package/dist/search/meilisearch-adapter.js

@@ -34,7 +34,8 @@ function isSubsetOf(stored, wanted) {
 }
 // A stored list that lies inside the current default and misses attributes is an
 // older default that gained fields since; anything with a foreign attribute is
-// an explicit configure() and stays untouched.
+// an explicit configure() and stays untouched. Known limit: an explicit configure() that
+// narrowed to a strict subset of the default is indistinguishable and gets widened again.
 function isOutdatedDefault(stored, wanted) {
     const pairs = [
         [stored.searchable, wanted.searchable],

package/dist/search/reindex-entity.js

@@ -6,7 +6,7 @@
 // existing row and indexes it, same as a live write would.
 import { resolveTableName } from "../db/entity-table-meta.js";
 import { executeRawQueryRead } from "../db/queries/raw-sql.js";
-import { withoutStatementTimeout } from "../db/statement-timeout.js";
+import { runInNewTransaction, runnerCanBeginTransaction } from "../db/query.js";
 import { buildSearchDocument, decryptSearchableSubjectFields, hasErasedSearchableSubjectField, } from "../pipeline/system-hooks.js";
 import { toSnakeCase } from "../utils/case.js";
 function quoteIdent(name) {
@@ -26,10 +26,20 @@ function rowToState(row, fieldNames) {
     }
     return state;
 }
-export function reindexEntity(db, registry, searchAdapter, entityName, tenantId, options = {}) {
-    return withoutStatementTimeout(db, (unboundedDb) => scanAndIndexEntity(unboundedDb, registry, searchAdapter, entityName, tenantId, options));
+// Server pools cap statement_timeout, and a batch scan over a large table can outlast it. The caller's
+// runner (often a gated proxy around the pool) is used as is, so the cap is lifted per batch
+// with a transaction-local set_config instead of moving the scan to an ungated sibling pool. A runner already inside a
+// transaction keeps the caller's setting rather than leaking ours into its remaining statements.
+async function readBatchWithoutStatementTimeout(db, sqlText, params) {
+    if (!runnerCanBeginTransaction(db)) {
+        return executeRawQueryRead(db, sqlText, params);
+    }
+    return runInNewTransaction(db, async (tx) => {
+        await executeRawQueryRead(tx, "SELECT set_config('statement_timeout', '0', true)", []);
+        return executeRawQueryRead(tx, sqlText, params);
+    });
 }
-async function scanAndIndexEntity(db, registry, searchAdapter, entityName, tenantId, options) {
+export async function reindexEntity(db, registry, searchAdapter, entityName, tenantId, options = {}) {
     const entity = registry.getEntity(entityName);
     if (!entity) {
         throw new Error(`reindexEntity: unknown entity "${entityName}"`);
@@ -61,7 +71,7 @@ async function scanAndIndexEntity(db, registry, searchAdapter, entityName, tenan
     for (;;) {
         // Keyset, not OFFSET: rows deleted or changed while the loop runs must not shift the window.
         const afterLastId = lastId === undefined ? "" : `AND ${quoteIdent("id")} > $3`;
-        const rows = await executeRawQueryRead(db, `SELECT * FROM ${quoteIdent(tableName)}
+        const rows = await readBatchWithoutStatementTimeout(db, `SELECT * FROM ${quoteIdent(tableName)}
         WHERE ${quoteIdent("tenant_id")} = $1 ${deletedFilter} ${afterLastId}
         ORDER BY ${quoteIdent("id")} ASC
         LIMIT $2`, lastId === undefined ? [tenantId, batchSize] : [tenantId, batchSize, lastId]);

package/dist/ui-types/index.d.ts

@@ -11,8 +11,8 @@ export type { BooleanFieldDef, DateFieldDef, EmbeddedDerivedCellDef, EntityDefin
 export type { AccessRule, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, RoleAccessPersonalData, RoleAccessRule, } from "../engine/types/handlers.ts";
 export { isOpenToAllGranted, isUiAccessGranted } from "../engine/types/handlers.ts";
 export type { IconKey, NavDefinition, NavIconKey } from "../engine/types/nav.ts";
-export type { ActionFormFooterAction, ActionFormLoad, ActionFormRedirect, ActionFormScreenDefinition, ActionFormSuccessFact, ActionFormSuccessLink, ConfigEditScreenDefinition, CustomScreenDefinition, CustomScreenRoute, DashboardChartKind, DashboardChartMarkerKind, DashboardChartPanel, DashboardChartRangeOption, DashboardChartRanges, DashboardChartTone, DashboardCurrencyFormat, DashboardCustomPanel, DashboardDateParam, DashboardFeedPanel, DashboardFilterDefinition, DashboardI18nText, DashboardListPanel, DashboardMoneyParam, DashboardPanelDefinition, DashboardPanelEmptyState, DashboardPanelGate, DashboardPanelQueryOptions, DashboardPanelSpan, DashboardPanelVisibility, DashboardProgressListPanel, DashboardProgressTone, DashboardRecordBinding, DashboardRefresh, DashboardRelativeTimeFormat, DashboardRelativeTimeParam, DashboardScopeDefinition, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DashboardText, DashboardTextBlock, DashboardTextPanel, DashboardTextParam, DashboardTimeRangeDefinition, DashboardValueFormat, EditExtensionSection, EditFieldPrefill, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EditWriteFormSection, EmbeddedListEditSpec, EntityEditAction, EntityEditActionPlacement, EntityEditScreenDefinition, EntityListExpandableRow, EntityListFacetConfig, EntityListFacetExtraOption, EntityListScreenDefinition, EntityWriteExcludedFields, FieldAffix, FieldCondition, FieldFillAction, FieldIconKey, FieldRenderer, FormWidth, ListBadgeTone, ListColumnDisplay, ListColumnSpec, ListEmptyStateSpec, ListFacetSpec, ListSortSpec, MetricNavigate, MetricSpec, PlatformComponent, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, RecordHeaderSubtitlePart, RelatedListGroupBy, RelatedListRowTone, RelatedListToolbarAction, RowAction, RowActionClientAction, RowActionDisplay, RowActionDrawer, RowActionMode, RowActionNavigate, RowActionWriteHandler, RowFieldExtractor, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenSlots, SecretMintConfirmStep, SecretMintScreenDefinition, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, ToolbarAction, } from "../engine/types/screen.ts";
-export { relatedListGroupHeaderLabel, relatedListGroupKey, } from "../engine/types/screen.ts";
+export type { ActionFormFooterAction, ActionFormLoad, ActionFormRedirect, ActionFormScreenDefinition, ActionFormSuccessFact, ActionFormSuccessLink, ConfigEditScreenDefinition, CustomScreenDefinition, CustomScreenRoute, DashboardChartKind, DashboardChartMarkerKind, DashboardChartPanel, DashboardChartRangeOption, DashboardChartRanges, DashboardChartTone, DashboardCurrencyFormat, DashboardCustomPanel, DashboardDateParam, DashboardFeedPanel, DashboardFilterDefinition, DashboardI18nText, DashboardListPanel, DashboardMoneyParam, DashboardPanelDefinition, DashboardPanelEmptyState, DashboardPanelGate, DashboardPanelQueryOptions, DashboardPanelSpan, DashboardPanelVisibility, DashboardProgressListPanel, DashboardProgressTone, DashboardRecordBinding, DashboardRefresh, DashboardRelativeTimeFormat, DashboardRelativeTimeParam, DashboardScopeDefinition, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DashboardText, DashboardTextBlock, DashboardTextPanel, DashboardTextParam, DashboardTimeRangeDefinition, DashboardValueFormat, EditExtensionSection, EditFieldPrefill, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EditWriteFormSection, EmbeddedListEditSpec, EntityEditAction, EntityEditActionPlacement, EntityEditScreenDefinition, EntityListExpandableRow, EntityListFacetConfig, EntityListFacetExtraOption, EntityListScreenDefinition, EntityWriteExcludedFields, ExpandableRowGrouping, FieldAffix, FieldCondition, FieldFillAction, FieldIconKey, FieldRenderer, FormWidth, ListBadgeTone, ListBulkAction, ListColumnDisplay, ListColumnSpec, ListEmptyStateSpec, ListFacetSpec, ListSortSpec, ListTableDensity, ListTableOptions, MetricNavigate, MetricSpec, PlatformComponent, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, RecordHeaderSubtitlePart, RelatedListRowTone, RelatedListToolbarAction, RowAction, RowActionClientAction, RowActionDisplay, RowActionDrawer, RowActionMode, RowActionNavigate, RowActionWriteHandler, RowFieldExtractor, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenSlots, SecretMintConfirmStep, SecretMintScreenDefinition, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, ToolbarAction, } from "../engine/types/screen.ts";
+export { MAX_BULK_SELECTION, relatedListGroupHeaderLabel, relatedListGroupKey, } from "../engine/types/screen.ts";
 export type { TargetRef } from "../engine/types/target-ref.ts";
 export type { TreeAction, TreeNode, TreeNodeState } from "../engine/types/tree-node.ts";
 export type { WorkspaceDefinition } from "../engine/types/workspace.ts";

package/dist/ui-types/index.js

@@ -25,7 +25,7 @@ export { applyFormDerivations, isFormDerivationInputMode, isUnusedFallbackOperan
 export { parseRefTarget } from "../engine/parse-ref-target.js";
 export { ACTION_FORM_PSEUDO_ENTITY, availableSelectOptions, evalFieldCondition, explicitListScreenId, findUnavailableSelectOptions, isExtensionEditSection, isFieldsEditSection, isFormatSpec, isRecordLocked, isUnchangedValue, isWriteFormEditSection, normalizeEditField, normalizeListColumn, resolveNavParentScreen, sectionFieldSpecs, } from "../engine/screen-helpers.js";
 export { isOpenToAllGranted, isUiAccessGranted } from "../engine/types/handlers.js";
-export { relatedListGroupHeaderLabel, relatedListGroupKey, } from "../engine/types/screen.js";
+export { MAX_BULK_SELECTION, relatedListGroupHeaderLabel, relatedListGroupKey, } from "../engine/types/screen.js";
 export { ACTION_FORM_ENTITY, handlerFieldLabelKey, handlerTitleKey, PROJECTION_DETAIL_ENTITY, WRITE_FORM_SECTION_ENTITY, } from "../i18n/required-surface-keys.js";
 export { CARD_META_MAX, cardColumnRoles, cardFileDisplayKind } from "./card-column-roles.js";
 export { formalLocaleTag } from "./formality.js";

package/dist/upgrade-changelog.d.ts

@@ -23,3 +23,5 @@ export type UpgradeChangelogSection = {
 export declare function renderUpgradeSection(section: UpgradeChangelogSection): string;
 /** Puts the section on top; a section for the same target version is replaced, so a re-run stays idempotent. */
 export declare function mergeUpgradeSection(existing: string | undefined, section: UpgradeChangelogSection): string;
+/** Pure string match on the rendered `- [open] <id> · ` prefix, in every section. */
+export declare function setManualStatusInChangelog(content: string, ids: ReadonlySet<string>, resolution: "migrated" | "not-applicable"): string;

package/dist/upgrade-changelog.js

@@ -46,3 +46,17 @@ export function mergeUpgradeSection(existing, section) {
     const others = sections.filter((candidate) => !candidate.startsWith(prefix));
     return [header, renderUpgradeSection(section), ...others].join("\n");
 }
+/** Pure string match on the rendered `- [open] <id> · ` prefix, in every section. */
+export function setManualStatusInChangelog(content, ids, resolution) {
+    return content
+        .split("\n")
+        .map((line) => {
+        for (const id of ids) {
+            const open = `- [open] ${id} · `;
+            if (line.startsWith(open))
+                return `- [${resolution}] ${id} · ${line.slice(open.length)}`;
+        }
+        return line;
+    })
+        .join("\n");
+}

package/dist/upgrade-cli.d.ts

@@ -1,3 +1,6 @@
+import { type ManualResolution, manualEntryId, type UpgradeMarkerManual, type UpgradeMarkerResolvedManual } from "./upgrade-marker-parse.ts";
+export type { ManualResolution, UpgradeMarkerManual, UpgradeMarkerResolvedManual };
+export { manualEntryId };
 export type UpgradeCliOut = {
     readonly log: (line: string) => void;
     readonly err: (line: string) => void;
@@ -7,18 +10,6 @@ export declare function findPackageChangelogFiles(cwd: string): string[];
 export declare function findFeaturesDirs(cwd: string): string[];
 export declare function findCodemodScriptsRoot(repoRoot: string): string | null;
 export declare function resolveCodemodScript(repoRoot: string, codemodField: string | undefined): string | null;
-export type UpgradeMarkerManual = {
-    readonly id: string;
-    readonly version: string;
-    readonly title: string;
-};
-export type ManualResolution = "migrated" | "not-applicable";
-export type UpgradeMarkerResolvedManual = UpgradeMarkerManual & {
-    readonly resolution: ManualResolution;
-    readonly reason: string;
-    readonly resolvedAt: string;
-};
-export declare function manualEntryId(version: string, title: string): string;
 export declare function runUpgradeCli(argv: readonly string[], cwd: string, out: UpgradeCliOut, options?: {
     readonly repoRoot?: string;
 }): Promise<number>;

package/dist/upgrade-cli.js

@@ -1,12 +1,12 @@
-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";
-import { mergeUpgradeSection } from "./upgrade-changelog.js";
-const SEMVER_RE = /^\d+\.\d+\.\d+$/;
+import { mergeUpgradeSection, setManualStatusInChangelog, } from "./upgrade-changelog.js";
+import { dedupeManualById, manualEntryId, parseStoredMarker, SEMVER_RE, } from "./upgrade-marker-parse.js";
+export { manualEntryId };
 const SEMVER_CORE_RE = /^(\d+\.\d+\.\d+)(?:-[0-9A-Za-z.-]+)?$/;
 const CODEMOD_SUBDIR = "scripts/codemod";
 function readPackageJsonVersion(packageJsonPath) {
@@ -304,13 +304,7 @@ function hasCodemod(e) {
 function needsManualMigration(e) {
     return !hasCodemod(e) || e.manualAfterCodemod === true;
 }
-const MANUAL_ID_HASH_LENGTH = 8;
 const MAX_RESOLVE_REASON_LENGTH = 500;
-// The hash tells apart entries that share a version (studio has several at 0.341.0).
-export function manualEntryId(version, title) {
-    const hash = createHash("sha256").update(title).digest("hex").slice(0, MANUAL_ID_HASH_LENGTH);
-    return `${version}:${hash}`;
-}
 // Breaking entries that need hand work carry the id `kumiko-upgrade --resolve` takes.
 function manualIdOf(entry) {
     return entry.type === "breaking" && needsManualMigration(entry)
@@ -324,15 +318,6 @@ function toMarkerManual(entry) {
         title: entry.title,
     };
 }
-function dedupeManualById(entries) {
-    const seen = new Set();
-    return entries.filter((entry) => {
-        if (seen.has(entry.id))
-            return false;
-        seen.add(entry.id);
-        return true;
-    });
-}
 // Open manual items survive every marker write until --resolve moves them.
 function carryOverManual(previous, newManual) {
     const resolvedIds = new Set(previous.resolvedManual.map((entry) => entry.id));
@@ -360,64 +345,6 @@ function writeUpgradeMarker(targetDir, marker) {
     writeFileSync(join(dir, "upgrade-state.json"), `${JSON.stringify(marker, null, 2)}\n`, "utf-8");
 }
 const NO_CARRY = { codemods: [], pendingManual: [], resolvedManual: [] };
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function parseManualEntry(value) {
-    if (!isRecord(value))
-        return null;
-    const { id, version, title } = value;
-    if (typeof version !== "string" || typeof title !== "string")
-        return null;
-    return {
-        id: typeof id === "string" && id.length > 0 ? id : manualEntryId(version, title),
-        version,
-        title,
-    };
-}
-function parseResolvedEntry(value) {
-    const base = parseManualEntry(value);
-    if (base === null || !isRecord(value))
-        return null;
-    const { resolution, reason, resolvedAt } = value;
-    if (resolution !== "migrated" && resolution !== "not-applicable")
-        return null;
-    if (typeof reason !== "string" || typeof resolvedAt !== "string")
-        return null;
-    return { ...base, resolution, reason, resolvedAt };
-}
-function parseList(value, parseEntry) {
-    if (value === undefined)
-        return [];
-    if (!Array.isArray(value))
-        return null;
-    const parsed = value.map(parseEntry);
-    return parsed.every((entry) => entry !== null) ? parsed : null;
-}
-function isMarkerCodemod(value) {
-    return (isRecord(value) &&
-        typeof value["version"] === "string" &&
-        typeof value["codemod"] === "string" &&
-        typeof value["title"] === "string");
-}
-function parseStoredMarker(raw) {
-    if (!isRecord(raw))
-        return null;
-    const { version, appliedAt, codemods } = raw;
-    if (typeof version !== "string" || !SEMVER_RE.test(version))
-        return null;
-    const pendingManual = parseList(raw["pendingManual"], parseManualEntry);
-    const resolvedManual = parseList(raw["resolvedManual"], parseResolvedEntry);
-    if (pendingManual === null || resolvedManual === null)
-        return null;
-    return {
-        version,
-        appliedAt: typeof appliedAt === "string" ? appliedAt : Temporal.Now.instant().toString(),
-        codemods: Array.isArray(codemods) ? codemods.filter(isMarkerCodemod) : [],
-        pendingManual: dedupeManualById(pendingManual),
-        resolvedManual: dedupeManualById(resolvedManual),
-    };
-}
 // 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.
@@ -659,27 +586,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"
@@ -697,6 +624,11 @@ function resolveManualMigrations(out, args, targetDir) {
         ...(remaining.length > 0 && { pendingManual: remaining }),
         resolvedManual,
     });
+    const changelogPath = join(targetDir, "CHANGELOG.md");
+    if (existsSync(changelogPath)) {
+        const content = readFileSync(changelogPath, "utf-8");
+        writeFileSync(changelogPath, setManualStatusInChangelog(content, resolvedIds, resolution), "utf-8");
+    }
     out.log("");
     out.log(`  ✓ Marked ${newlyResolved.length} manual migration(s) as ${resolution}:`);
     for (const entry of newlyResolved) {
@@ -721,32 +653,7 @@ 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);
@@ -761,33 +668,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) {
@@ -796,6 +710,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
@@ -804,87 +730,135 @@ 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 logApplyHint(out, plan) {
+    const { markerRead, targetInstalledVersion } = plan;
+    const markerBehindInstalled = markerRead.kind === "ok" &&
+        targetInstalledVersion !== null &&
+        compareVersions(markerRead.version, targetInstalledVersion) < 0;
+    // skip: nothing differs between marker and installed version, so there is nothing to record.
+    if (plan.pending.length === 0 && !markerBehindInstalled)
+        return;
+    out.log("  Nothing is recorded yet: the upgrade CHANGELOG and the marker are only");
+    out.log("  written by --apply (add --dry-run to preview without writing).");
+    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);
+        logApplyHint(out, plan);
+        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);
+    logApplyHint(out, plan);
+    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/upgrade-marker-parse.d.ts

@@ -0,0 +1,32 @@
+export declare const SEMVER_RE: RegExp;
+export type UpgradeMarkerCodemod = {
+    readonly version: string;
+    readonly codemod: string;
+    readonly title: string;
+};
+export type UpgradeMarkerManual = {
+    readonly id: string;
+    readonly version: string;
+    readonly title: string;
+};
+export type ManualResolution = "migrated" | "not-applicable";
+export type UpgradeMarkerResolvedManual = UpgradeMarkerManual & {
+    readonly resolution: ManualResolution;
+    readonly reason: string;
+    readonly resolvedAt: string;
+};
+export declare function manualEntryId(version: string, title: string): string;
+export declare function dedupeManualById<T extends {
+    readonly id: string;
+}>(entries: readonly T[]): readonly T[];
+export type MarkerCarry = {
+    readonly codemods: readonly UpgradeMarkerCodemod[];
+    readonly pendingManual: readonly UpgradeMarkerManual[];
+    readonly resolvedManual: readonly UpgradeMarkerResolvedManual[];
+};
+export type StoredMarker = MarkerCarry & {
+    readonly version: string;
+    readonly appliedAt: string;
+    readonly codemods: readonly UpgradeMarkerCodemod[];
+};
+export declare function parseStoredMarker(raw: unknown): StoredMarker | null;