@cosmicdrift/kumiko-framework 0.348.1 → 0.349.0

package/dist/engine/boot-validator/screens.js

@@ -1746,6 +1746,33 @@ function validateDashboardStatGroupPanel(featureName, screenId, panel, addPanelI
         if (stat.valueField.length === 0) {
             throw new Error(`[Feature ${featureName}] Screen "${screenId}" (dashboard) stat-group "${panel.id}" child "${stat.id}" has empty valueField.`);
         }
+        validateDashboardValueFormat(featureName, screenId, stat.id, stat.valueFormat);
+    }
+}
+function validateDashboardChartDisplay(featureName, screenId, panel) {
+    validateDashboardValueFormat(featureName, screenId, panel.id, panel.valueFormat);
+    const where = `[Feature ${featureName}] Screen "${screenId}" (dashboard) chart-panel "${panel.id}"`;
+    if (panel.scrollable !== undefined && typeof panel.scrollable !== "boolean") {
+        throw new Error(`${where} has a non-boolean scrollable.`);
+    }
+    if (panel.scrollable === true && panel.chart !== "stacked-area") {
+        throw new Error(`${where} sets scrollable on chart "${panel.chart}" — only "stacked-area" supports it.`);
+    }
+}
+const CURRENCY_CODE_RE = /^[A-Z]{3}$/;
+const MAX_VALUE_FORMAT_FRACTION_DIGITS = 4;
+function validateDashboardValueFormat(featureName, screenId, panelId, valueFormat) {
+    // skip: valueFormat is optional, nothing to validate without it
+    if (valueFormat === undefined)
+        return;
+    const where = `[Feature ${featureName}] Screen "${screenId}" (dashboard) panel "${panelId}" valueFormat`;
+    if (!CURRENCY_CODE_RE.test(valueFormat.currency)) {
+        throw new Error(`${where}.currency "${String(valueFormat.currency)}" must be a 3-letter uppercase ISO currency code.`);
+    }
+    const digits = valueFormat.fractionDigits;
+    if (digits !== undefined &&
+        (!Number.isInteger(digits) || digits < 0 || digits > MAX_VALUE_FORMAT_FRACTION_DIGITS)) {
+        throw new Error(`${where}.fractionDigits "${String(digits)}" must be an integer from 0 to ${MAX_VALUE_FORMAT_FRACTION_DIGITS}.`);
     }
 }
 export function validateDashboardCustomPanel(featureName, screenId, panel) {
@@ -1764,9 +1791,14 @@ function validateDashboardQueryPanel(featureName, screenId, panel, featureMap) {
         panel.span !== "full") {
         throw new Error(`[Feature ${featureName}] Screen "${screenId}" (dashboard) panel "${panel.id}" has span "${String(panel.span)}" — expected "half" or "full".`);
     }
-    if (panel.kind === "stat" && panel.valueField.length === 0) {
-        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (dashboard) stat-panel "${panel.id}" has empty valueField.`);
+    if (panel.kind === "stat") {
+        if (panel.valueField.length === 0) {
+            throw new Error(`[Feature ${featureName}] Screen "${screenId}" (dashboard) stat-panel "${panel.id}" has empty valueField.`);
+        }
+        validateDashboardValueFormat(featureName, screenId, panel.id, panel.valueFormat);
     }
+    if (panel.kind === "chart")
+        validateDashboardChartDisplay(featureName, screenId, panel);
     if (panel.kind === "list") {
         if (panel.columns.length === 0) {
             throw new Error(`[Feature ${featureName}] Screen "${screenId}" (dashboard) list-panel "${panel.id}" has an empty columns list.`);

package/dist/engine/index.d.ts

@@ -74,7 +74,7 @@ export { WORKFLOW_SYSTEM_EVENT_DEFS } from "./steps/workflow-system-events.js";
 export { ANONYMOUS_ROLE, ANONYMOUS_USER_ID, createAnonymousUser, createSystemUser, SYSTEM_ROLE, SYSTEM_USER_ID, } from "./system-user.js";
 export { type EffectiveFeaturesResolver, findTierResolverUsage, isTierResolverPlugin, TENANT_TIER_RESOLVER_EXT, type TierResolverPlugin, type TrialGate, } from "./tier-resolver-extension.js";
 export { isSystemTenant, isUuid, parseTenantId, SYSTEM_TENANT_ID } from "./types/identifiers.js";
-export type { AccessRule, ActionFormScreenDefinition, ActiveMembership, ActiveMembershipRejection, ActiveMembershipResult, AgentExposure, AgentHandlerHints, AgentRisk, AppContext, AppendEventArgs, AppendEventFn, AuthClaimsContext, AuthClaimsFn, AuthClaimsHookDef, BelongsToRelation, BigIntFieldDef, BooleanFieldDef, CamelToKebab, ChatSendFailureCode, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyJsType, ClaimKeyType, ConcurrencyMode, ConfigAccessor, ConfigAccessorFactory, ConfigBacking, ConfigCascade, ConfigCascadeLevel, ConfigDefinition, ConfigEditScreenDefinition, ConfigKeyAccess, ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigMask, ConfigResolver, ConfigScope, ConfigSecretsReader, ConfigSeedDef, ConfigStoredRow, ConfigStoredRowWithSource, ConfigValidateContext, ConfigValidateFn, ConfigValue, ConfigValueSource, ConfigValueWithSource, ContentCollectionDefinition, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions, CustomScreenDefinition, CustomScreenRoute, DashboardChartPanel, DashboardCustomPanel, DashboardFeedPanel, DashboardFilterDefinition, DashboardListPanel, DashboardPanelDefinition, DashboardPanelVisibility, DashboardProgressListPanel, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DateFieldDef, DecimalFieldDef, DeleteContext, DeliveryErrorCode, DeliveryFailureCode, DeliverySkipReason, DeriveContext, DerivedFieldDef, DerivedFieldsMap, DerivedValueType, EditExtensionSection, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EntityDefinition, EntityEditScreenDefinition, EntityId, EntityListExpandableRow, EntityListScreenDefinition, EntityRef, EntityRelations, EscapeHatchAuditSink, EscapeHatchDeclaration, EscapeHatchKind, EscapeHatchReporter, EscapeHatchTarget, EscapeHatchUseEvent, EventDef, ExtensionOptionsArgs, ExtensionOptionsFor, FeatureDefinition, FeatureRegistrar, FieldAccess, FieldCondition, FieldDefinition, FieldFormatRegistry, FieldIconKey, FieldRenderer, FileFieldDef, FilesFieldDef, Findability, FormatSpec, FormWidth, HandlerContext, HasManyRelation, HookMap, ImageFieldDef, ImagesFieldDef, JobBackoff, JobBackoffStrategy, JobContext, JobDefinition, JobHandlerFn, JobTrigger, JobTriggerEvent, JsonbFieldDef, KumikoEntityTypeMap, KumikoEventTypeMap, KumikoExtensionOptionsMap, KumikoHandlerPayloadMap, KumikoHandlerResultMap, LifecycleHookType, ListColumnSpec, ListFacetSpec, ListPaginationMode, ListSortDir, ListSortSpec, LongTextFindability, ManyToManyRelation, MemberReader, MetricNavigate, MetricSpec, MspErrorMode, MspErrorPolicy, MultiSelectFieldDef, MultiStreamApplyFn, MultiStreamProjectionDefinition, NameOrRef, NavDefinition, NavIconKey, NotificationDataFn, NotificationDefinition, NotificationRecipientFn, NotificationTemplateFn, NotifyDelivery, NotifyDeliveryStatus, NotifyFactory, NotifyFn, NotifyJobDispatcher, NotifyOptions, NotifyPriority, NotifyResult, NumberFieldDef, OnDeleteStrategy, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, ParentRefDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, PersonalSubject, PlatformComponent, PluralForms, PostDeleteHookFn, PostSaveHookFn, PreDeleteHookFn, PreQueryHookFn, PreSaveHookFn, ProjectionDefinition, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, ProjectionTable, QualifiedEventName, QueryEvent, QueryHandlerDef, QueryHandlerFn, RateLimitPer, RecordHeaderSpec, RecordHeaderSubtitlePart, ReferenceDataDef, Registry, RelationDefinition, ResolvedPiiFlags, RetentionDef, RoleAccessPersonalData, RoleAccessRule, RowAction, RowActionNavigate, RowActionNavigateBase, RowActionWriteHandler, RowFieldExtractor, SaveContext, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenNavSugar, ScreenSlots, SecretKeyDefinition, SecretKeyHandle, SecretMintConfirmStep, SecretMintScreenDefinition, SecretNamespaceDefinition, SecretNamespaceHandle, SecretNamespaceOptions, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, SelectFieldDef, SessionUser, SessionUserOrigin, StreamHandlerDef, StreamHandlerFn, Subscribe, TargetRef, TenantId, TextFieldDef, ToolbarAction, TranslationEntry, TranslationKeys, TranslationsDef, TranslationValue, TreeAction, TreeActionDef, TreeActionsHandle, TreeChildrenSubscribe, TreeNode, TreeNodeState, UnitKey, UnsafeAppendEventFn, ValidationError, ValidationHookFn, WorkspaceDefinition, WriteEvent, WriteHandlerDef, WriteHandlerFn, WriteResult, } from "./types/index.js";
+export type { AccessRule, ActionFormScreenDefinition, ActiveMembership, ActiveMembershipRejection, ActiveMembershipResult, AgentExposure, AgentHandlerHints, AgentRisk, AppContext, AppendEventArgs, AppendEventFn, AuthClaimsContext, AuthClaimsFn, AuthClaimsHookDef, BelongsToRelation, BigIntFieldDef, BooleanFieldDef, CamelToKebab, ChatSendFailureCode, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyJsType, ClaimKeyType, ConcurrencyMode, ConfigAccessor, ConfigAccessorFactory, ConfigBacking, ConfigCascade, ConfigCascadeLevel, ConfigDefinition, ConfigEditScreenDefinition, ConfigKeyAccess, ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigMask, ConfigResolver, ConfigScope, ConfigSecretsReader, ConfigSeedDef, ConfigStoredRow, ConfigStoredRowWithSource, ConfigValidateContext, ConfigValidateFn, ConfigValue, ConfigValueSource, ConfigValueWithSource, ContentCollectionDefinition, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions, CustomScreenDefinition, CustomScreenRoute, DashboardChartPanel, DashboardCustomPanel, DashboardDateParam, DashboardFeedPanel, DashboardFilterDefinition, DashboardI18nText, DashboardListPanel, DashboardMoneyParam, DashboardPanelDefinition, DashboardPanelVisibility, DashboardProgressListPanel, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DashboardText, DashboardTextParam, DashboardValueFormat, DateFieldDef, DecimalFieldDef, DeleteContext, DeliveryErrorCode, DeliveryFailureCode, DeliverySkipReason, DeriveContext, DerivedFieldDef, DerivedFieldsMap, DerivedValueType, EditExtensionSection, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EntityDefinition, EntityEditScreenDefinition, EntityId, EntityListExpandableRow, EntityListScreenDefinition, EntityRef, EntityRelations, EscapeHatchAuditSink, EscapeHatchDeclaration, EscapeHatchKind, EscapeHatchReporter, EscapeHatchTarget, EscapeHatchUseEvent, EventDef, ExtensionOptionsArgs, ExtensionOptionsFor, FeatureDefinition, FeatureRegistrar, FieldAccess, FieldCondition, FieldDefinition, FieldFormatRegistry, FieldIconKey, FieldRenderer, FileFieldDef, FilesFieldDef, Findability, FormatSpec, FormWidth, HandlerContext, HasManyRelation, HookMap, ImageFieldDef, ImagesFieldDef, JobBackoff, JobBackoffStrategy, JobContext, JobDefinition, JobHandlerFn, JobTrigger, JobTriggerEvent, JsonbFieldDef, KumikoEntityTypeMap, KumikoEventTypeMap, KumikoExtensionOptionsMap, KumikoHandlerPayloadMap, KumikoHandlerResultMap, LifecycleHookType, ListColumnSpec, ListFacetSpec, ListPaginationMode, ListSortDir, ListSortSpec, LongTextFindability, ManyToManyRelation, MemberReader, MetricNavigate, MetricSpec, MspErrorMode, MspErrorPolicy, MultiSelectFieldDef, MultiStreamApplyFn, MultiStreamProjectionDefinition, NameOrRef, NavDefinition, NavIconKey, NotificationDataFn, NotificationDefinition, NotificationRecipientFn, NotificationTemplateFn, NotifyDelivery, NotifyDeliveryStatus, NotifyFactory, NotifyFn, NotifyJobDispatcher, NotifyOptions, NotifyPriority, NotifyResult, NumberFieldDef, OnDeleteStrategy, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, ParentRefDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, PersonalSubject, PlatformComponent, PluralForms, PostDeleteHookFn, PostSaveHookFn, PreDeleteHookFn, PreQueryHookFn, PreSaveHookFn, ProjectionDefinition, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, ProjectionTable, QualifiedEventName, QueryEvent, QueryHandlerDef, QueryHandlerFn, RateLimitPer, RecordHeaderSpec, RecordHeaderSubtitlePart, ReferenceDataDef, Registry, RelationDefinition, ResolvedPiiFlags, RetentionDef, RoleAccessPersonalData, RoleAccessRule, RowAction, RowActionNavigate, RowActionNavigateBase, RowActionWriteHandler, RowFieldExtractor, SaveContext, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenNavSugar, ScreenSlots, SecretKeyDefinition, SecretKeyHandle, SecretMintConfirmStep, SecretMintScreenDefinition, SecretNamespaceDefinition, SecretNamespaceHandle, SecretNamespaceOptions, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, SelectFieldDef, SessionUser, SessionUserOrigin, StreamHandlerDef, StreamHandlerFn, Subscribe, TargetRef, TenantId, TextFieldDef, ToolbarAction, TranslationEntry, TranslationKeys, TranslationsDef, TranslationValue, TreeAction, TreeActionDef, TreeActionsHandle, TreeChildrenSubscribe, TreeNode, TreeNodeState, UnitKey, UnsafeAppendEventFn, ValidationError, ValidationHookFn, WorkspaceDefinition, WriteEvent, WriteHandlerDef, WriteHandlerFn, WriteResult, } from "./types/index.js";
 export { DEFAULT_CURRENCIES, DEFAULT_LOCALES, DELIVERY_FAILURE_CODES, DELIVERY_SKIP_REASONS, HookPhases, HTTP_ERROR_CODE_PATTERN, isAgentVisibleScreen, isDeliveryErrorCode, isOpenToAllGranted, resolveAgentExposure, } from "./types/index.js";
 export type { AwaitedEventType, PipelineBuildCtx, PipelineCtx, PipelineDef, StepBuilder, StepDef, StepFailureStrategy, StepInstance, StepKind, StepNamespace, StepResolver, } from "./types/step.js";
 export { runValidation } from "./validation.js";

package/dist/engine/types/index.d.ts

@@ -17,7 +17,7 @@ export type { ContentCollectionDefinition, NavDefinition, NavIconKey, } from "@c
 export type { FromRule, FromRuleKind, OwnershipClause, OwnershipMap, OwnershipRef, OwnershipRule, SqlFragment, WhereRule, WhereRuleContext, } from "@cosmicdrift/kumiko-types/ownership";
 export type { EntityProjectionExtension, MspErrorMode, MspErrorPolicy, MultiStreamApplyFn, MultiStreamProjectionDefinition, ProjectionDefinition, ProjectionRowIdOf, ProjectionTable, SingleStreamApplyFn, } from "@cosmicdrift/kumiko-types/projection";
 export type { BelongsToRelation, EntityRelations, HasManyRelation, ManyToManyRelation, RelationDefinition, } from "@cosmicdrift/kumiko-types/relations";
-export type { ActionFormScreenDefinition, ConfigEditScreenDefinition, CustomScreenDefinition, CustomScreenRoute, DashboardChartPanel, DashboardCustomPanel, DashboardFeedPanel, DashboardFilterDefinition, DashboardListPanel, DashboardPanelDefinition, DashboardPanelVisibility, DashboardProgressListPanel, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, EditExtensionSection, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EditWriteFormSection, EntityEditScreenDefinition, EntityListExpandableRow, EntityListScreenDefinition, FieldCondition, FieldFormatRegistry, FieldRenderer, FormatSpec, FormWidth, ListColumnSpec, ListFacetSpec, ListPaginationMode, ListSortDir, ListSortSpec, MetricNavigate, MetricSpec, PlatformComponent, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, RecordHeaderSpec, RecordHeaderSubtitlePart, RowAction, RowActionNavigate, RowActionNavigateBase, RowActionWriteHandler, RowFieldExtractor, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenNavSugar, ScreenSlots, SecretMintConfirmStep, SecretMintScreenDefinition, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, ToolbarAction, UnitKey, } from "@cosmicdrift/kumiko-types/screen";
+export type { ActionFormScreenDefinition, ConfigEditScreenDefinition, CustomScreenDefinition, CustomScreenRoute, DashboardChartPanel, DashboardCustomPanel, DashboardDateParam, DashboardFeedPanel, DashboardFilterDefinition, DashboardI18nText, DashboardListPanel, DashboardMoneyParam, DashboardPanelDefinition, DashboardPanelVisibility, DashboardProgressListPanel, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DashboardText, DashboardTextParam, DashboardValueFormat, EditExtensionSection, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EditWriteFormSection, EntityEditScreenDefinition, EntityListExpandableRow, EntityListScreenDefinition, FieldCondition, FieldFormatRegistry, FieldRenderer, FormatSpec, FormWidth, ListColumnSpec, ListFacetSpec, ListPaginationMode, ListSortDir, ListSortSpec, MetricNavigate, MetricSpec, PlatformComponent, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, RecordHeaderSpec, RecordHeaderSubtitlePart, RowAction, RowActionNavigate, RowActionNavigateBase, RowActionWriteHandler, RowFieldExtractor, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenNavSugar, ScreenSlots, SecretMintConfirmStep, SecretMintScreenDefinition, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, ToolbarAction, UnitKey, } from "@cosmicdrift/kumiko-types/screen";
 export { metricField, relatedListGroupHeaderLabel, relatedListGroupKey, } from "@cosmicdrift/kumiko-types/screen";
 export type { TargetRef } from "@cosmicdrift/kumiko-types/target-ref";
 export type { Subscribe, TreeAction, TreeActionDef, TreeActionsHandle, TreeChildrenSubscribe, TreeNode, TreeNodeState, } from "@cosmicdrift/kumiko-types/tree-node";

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

@@ -9,7 +9,7 @@ export type { BooleanFieldDef, DateFieldDef, EmbeddedDerivedCellDef, EntityDefin
 export type { AccessRule, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, RoleAccessPersonalData, RoleAccessRule, } from "../engine/types/handlers.js";
 export { isOpenToAllGranted, isUiAccessGranted } from "../engine/types/handlers.js";
 export type { IconKey, NavDefinition, NavIconKey } from "../engine/types/nav.js";
-export type { ActionFormFooterAction, ActionFormRedirect, ActionFormScreenDefinition, ConfigEditScreenDefinition, CustomScreenDefinition, CustomScreenRoute, DashboardChartKind, DashboardChartPanel, DashboardChartTone, DashboardCustomPanel, DashboardFeedPanel, DashboardFilterDefinition, DashboardListPanel, DashboardPanelDefinition, DashboardPanelEmptyState, DashboardPanelQueryOptions, DashboardPanelSpan, DashboardPanelVisibility, DashboardProgressListPanel, DashboardScopeDefinition, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DashboardTimeRangeDefinition, EditExtensionSection, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EditWriteFormSection, EntityEditScreenDefinition, EntityListExpandableRow, EntityListFacetConfig, EntityListFacetExtraOption, EntityListScreenDefinition, FieldCondition, FieldIconKey, FieldRenderer, FormWidth, ListBadgeTone, ListColumnDisplay, ListColumnSpec, ListFacetSpec, ListSortSpec, MetricNavigate, MetricSpec, PlatformComponent, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, RecordHeaderSubtitlePart, RelatedListGroupBy, RelatedListRowTone, RelatedListToolbarAction, RowAction, RowActionDisplay, RowActionDrawer, RowActionMode, RowActionNavigate, RowActionWriteHandler, RowFieldExtractor, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenSlots, SecretMintConfirmStep, SecretMintScreenDefinition, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, ToolbarAction, } from "../engine/types/screen.js";
+export type { ActionFormFooterAction, ActionFormRedirect, ActionFormScreenDefinition, ConfigEditScreenDefinition, CustomScreenDefinition, CustomScreenRoute, DashboardChartKind, DashboardChartPanel, DashboardChartTone, DashboardCustomPanel, DashboardDateParam, DashboardFeedPanel, DashboardFilterDefinition, DashboardI18nText, DashboardListPanel, DashboardMoneyParam, DashboardPanelDefinition, DashboardPanelEmptyState, DashboardPanelQueryOptions, DashboardPanelSpan, DashboardPanelVisibility, DashboardProgressListPanel, DashboardScopeDefinition, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DashboardText, DashboardTextParam, DashboardTimeRangeDefinition, DashboardValueFormat, EditExtensionSection, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EditWriteFormSection, EntityEditScreenDefinition, EntityListExpandableRow, EntityListFacetConfig, EntityListFacetExtraOption, EntityListScreenDefinition, FieldCondition, FieldIconKey, FieldRenderer, FormWidth, ListBadgeTone, ListColumnDisplay, ListColumnSpec, ListFacetSpec, ListSortSpec, MetricNavigate, MetricSpec, PlatformComponent, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, RecordHeaderSubtitlePart, RelatedListGroupBy, RelatedListRowTone, RelatedListToolbarAction, RowAction, RowActionDisplay, RowActionDrawer, RowActionMode, RowActionNavigate, RowActionWriteHandler, RowFieldExtractor, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenSlots, SecretMintConfirmStep, SecretMintScreenDefinition, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, ToolbarAction, } from "../engine/types/screen.js";
 export { metricField, relatedListGroupHeaderLabel, relatedListGroupKey, } from "../engine/types/screen.js";
 export type { TargetRef } from "../engine/types/target-ref.js";
 export type { TreeAction, TreeNode, TreeNodeState } from "../engine/types/tree-node.js";

package/dist/upgrade-cli.d.ts

@@ -7,6 +7,18 @@ 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,3 +1,4 @@
+import { createHash } from "node:crypto";
 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";
@@ -259,71 +260,153 @@ async function runCodemodScript(scriptPath, targetDir, repoRoot, dryRun) {
 function hasCodemod(e) {
     return typeof e.codemod === "string" && e.codemod.length > 0;
 }
+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}`;
+}
+function toMarkerManual(entry) {
+    return {
+        id: manualEntryId(entry.version, entry.title),
+        version: entry.version,
+        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));
+    const pendingManual = dedupeManualById([...previous.pendingManual, ...newManual]).filter((entry) => !resolvedIds.has(entry.id));
+    return {
+        ...(pendingManual.length > 0 && { pendingManual }),
+        ...(previous.resolvedManual.length > 0 && { resolvedManual: previous.resolvedManual }),
+    };
+}
 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: [] };
+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` (fw#2299); 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 readMarkerVersion(targetDir) {
+function readMarker(targetDir) {
     const markerPath = join(targetDir, ".kumiko", "upgrade-state.json");
     if (!existsSync(markerPath))
         return { kind: "missing" };
     try {
-        const parsed = JSON.parse(readFileSync(markerPath, "utf-8"));
-        return typeof parsed.version === "string" && SEMVER_RE.test(parsed.version)
-            ? { kind: "ok", version: parsed.version }
-            : { kind: "invalid" };
+        const marker = parseStoredMarker(JSON.parse(readFileSync(markerPath, "utf-8")));
+        return marker === null ? { kind: "invalid" } : { kind: "ok", version: marker.version, marker };
     }
     catch {
         return { kind: "invalid" };
     }
 }
-/** 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 carryOf(read) {
+    return read.kind === "ok" ? read.marker : NO_CARRY;
+}
+// The marker file is editable repo content; a tampered title must not reach
+// the terminal as an escape sequence.
+function printable(text) {
+    return text.replace(/\p{Cc}/gu, "");
 }
-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.`);
+function logOpenManual(out, open) {
+    // 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)}`);
     }
+    out.log('  Migrate them by hand, then mark them done: kumiko-upgrade --resolve <id|version> --reason "<what you did>" [--not-applicable]');
 }
 // 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) {
+function writePartialMarker(out, targetDir, pending, manualEntries, failedVersion, ran, previous) {
     // skip: no codemod wrote files before the failure, nothing to resume after
     if (ran.length === 0)
         return;
-    const doneBeforeFailure = pending.filter((e) => compareVersions(e.version, failedVersion) < 0);
-    const version = markerVersionForPending(doneBeforeFailure, manualEntries, "");
+    const versionsBeforeFailure = pending
+        .map((e) => e.version)
+        .filter((version) => compareVersions(version, failedVersion) < 0);
+    const version = versionsBeforeFailure.reduce((max, candidate) => (max === null || compareVersions(candidate, max) > 0 ? candidate : max), null);
     // skip: no pending entry completed before the failure, so no marker version to record
-    if (version === "")
+    if (version === null)
         return;
-    const pendingManual = manualEntries.map((e) => ({ version: e.version, title: e.title }));
     writeUpgradeMarker(targetDir, {
         version,
         appliedAt: Temporal.Now.instant().toString(),
         codemods: ran,
-        ...(pendingManual.length > 0 && { pendingManual }),
+        ...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.`);
 }
@@ -338,16 +421,19 @@ 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) {
+markerVersion, previous) {
     if (pending.length === 0) {
         out.log("  ✓ Nothing new since your version.");
         if (!dryRun) {
+            const carried = carryOverManual(previous, []);
             writeUpgradeMarker(targetDir, {
                 version: markerVersion,
                 appliedAt: Temporal.Now.instant().toString(),
                 codemods: [],
+                ...carried,
             });
             out.log(`  ✓ Applied 0 codemod(s). Wrote ${join(targetDir, ".kumiko/upgrade-state.json")}`);
+            logOpenManual(out, carried.pendingManual ?? []);
         }
         return 0;
     }
@@ -364,16 +450,15 @@ markerVersion) {
             ? "  No automatable codemods among the pending breaking changes."
             : "  ✓ No breaking changes pending.");
         if (!dryRun) {
-            const markerVer = markerVersionForPending(pending, manualEntries, markerVersion);
-            const pendingManual = manualEntries.map((e) => ({ version: e.version, title: e.title }));
+            const carried = carryOverManual(previous, manualEntries.map(toMarkerManual));
             writeUpgradeMarker(targetDir, {
-                version: markerVer,
+                version: markerVersion,
                 appliedAt: Temporal.Now.instant().toString(),
                 codemods: [],
-                ...(pendingManual.length > 0 && { pendingManual }),
+                ...carried,
             });
             out.log(`  ✓ Applied 0 codemod(s). Wrote ${join(targetDir, ".kumiko/upgrade-state.json")}`);
-            logManualMarkerOutcome(out, manualEntries, markerVer);
+            logOpenManual(out, carried.pendingManual ?? []);
         }
         return 0;
     }
@@ -388,7 +473,7 @@ markerVersion) {
         if (!scriptPath) {
             out.err(`  ✗ ${e.version} · ${e.title} — invalid codemod path "${e.codemod}"`);
             if (!dryRun)
-                writePartialMarker(out, targetDir, pending, manualEntries, e.version, ran);
+                writePartialMarker(out, targetDir, pending, manualEntries, e.version, ran, previous);
             return 1;
         }
         out.log(`  → ${e.version} · running ${e.codemod}${dryRun ? " (dry-run)" : ""}`);
@@ -398,7 +483,7 @@ markerVersion) {
         if (!result.ok) {
             out.err(`  ✗ ${e.version} · ${e.codemod} failed`);
             if (!dryRun)
-                writePartialMarker(out, targetDir, pending, manualEntries, e.version, ran);
+                writePartialMarker(out, targetDir, pending, manualEntries, e.version, ran, previous);
             return 1;
         }
         ran.push({ version: e.version, codemod: e.codemod, title: e.title });
@@ -407,28 +492,114 @@ markerVersion) {
         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 }));
+    const carried = carryOverManual(previous, manualEntries.map(toMarkerManual));
     writeUpgradeMarker(targetDir, {
-        version: latestVersion,
+        version: markerVersion,
         appliedAt: Temporal.Now.instant().toString(),
         codemods: ran,
-        ...(pendingManual.length > 0 && { pendingManual }),
+        ...carried,
     });
     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.`);
+    logOpenManual(out, carried.pendingManual ?? []);
+    return 0;
+}
+function parseResolveInput(args) {
+    if (getFlag(args, "apply"))
+        return { error: "--resolve cannot be combined with --apply." };
+    const refs = (getStringFlag(args, "resolve") ?? "")
+        .split(",")
+        .map((ref) => ref.trim())
+        .filter((ref) => ref.length > 0);
+    if (refs.length === 0)
+        return { error: "--resolve needs at least one id or version." };
+    const reason = getStringFlag(args, "reason")?.trim() ?? "";
+    if (reason.length === 0)
+        return { error: '--resolve requires --reason "<text>".' };
+    if (reason.length > MAX_RESOLVE_REASON_LENGTH) {
+        return { error: `--reason is too long (max ${MAX_RESOLVE_REASON_LENGTH} characters).` };
+    }
+    return { refs, reason };
+}
+function matchManualRefs(open, refs) {
+    const resolvedIds = new Set();
+    const errors = [];
+    for (const ref of refs) {
+        const byId = open.find((entry) => entry.id === ref);
+        const byVersion = open.filter((entry) => entry.version === ref);
+        if (byId !== undefined) {
+            resolvedIds.add(byId.id);
+        }
+        else if (byVersion.length === 1 && byVersion[0] !== undefined) {
+            resolvedIds.add(byVersion[0].id);
+        }
+        else if (byVersion.length > 1) {
+            errors.push(`"${ref}" matches ${byVersion.length} open entries, pass one of: ${byVersion.map((entry) => entry.id).join(", ")}`);
+        }
+        else {
+            errors.push(`"${ref}" matches no open manual migration`);
+        }
+    }
+    return { resolvedIds, errors };
+}
+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);
+    const read = readMarker(targetDir);
+    if (read.kind === "missing") {
+        return fail(`No .kumiko/upgrade-state.json under ${targetDir}, nothing to resolve.`);
+    }
+    if (read.kind === "invalid")
+        return fail("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.");
+    const { reason } = input;
+    const notApplicableFlag = args.flags.get("not-applicable");
+    const resolution = notApplicableFlag !== undefined && notApplicableFlag !== false ? "not-applicable" : "migrated";
+    const resolvedAt = Temporal.Now.instant().toString();
+    const newlyResolved = open
+        .filter((entry) => resolvedIds.has(entry.id))
+        .map((entry) => ({ ...entry, resolution, reason, resolvedAt }));
+    const remaining = open.filter((entry) => !resolvedIds.has(entry.id));
+    const resolvedManual = dedupeManualById([...read.marker.resolvedManual, ...newlyResolved]);
+    writeUpgradeMarker(targetDir, {
+        version: read.marker.version,
+        appliedAt: read.marker.appliedAt,
+        codemods: read.marker.codemods,
+        ...(remaining.length > 0 && { pendingManual: remaining }),
+        resolvedManual,
+    });
+    out.log("");
+    out.log(`  ✓ Marked ${newlyResolved.length} manual migration(s) as ${resolution}:`);
+    for (const entry of newlyResolved) {
+        out.log(`    ${printable(entry.id)} · ${printable(entry.title)}`);
     }
-    logManualMarkerOutcome(out, manualEntries, latestVersion);
+    if (remaining.length > 0)
+        logOpenManual(out, remaining);
+    out.log("");
     return 0;
 }
 const UPGRADE_USAGE = `kumiko-upgrade [--from <version>] [--dir <path>] [--json] [--verbose] [--apply [--dry-run]]
+kumiko-upgrade --resolve <id|version>[,<id|version>...] --reason "<text>" [--not-applicable] [--dir <path>]
 
   --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
+                     (one run moves the marker to the installed version; manual migrations stay listed as open)
+  --resolve <refs>   mark open manual migrations as done; ref = full id or a version with exactly one open entry
+  --reason <text>    required with --resolve, max 500 characters
+  --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
@@ -454,6 +625,9 @@ export async function runUpgradeCli(argv, cwd, out, options) {
         out.err("");
         return 1;
     }
+    if (args.flags.has("resolve")) {
+        return resolveManualMigrations(out, args, targetDir);
+    }
     // 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);
@@ -465,7 +639,8 @@ export async function runUpgradeCli(argv, cwd, out, options) {
     // 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 marker = fromFlag === undefined ? readMarkerVersion(targetDir) : { kind: "missing" };
+    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>");
@@ -516,23 +691,26 @@ export async function runUpgradeCli(argv, cwd, out, options) {
             return 1;
         }
         out.log("");
-        const code = await applyCodemods(out, pending, repoRoot, targetDir, dryRun, markerVersion ?? currentVersion);
+        const code = await applyCodemods(out, pending, repoRoot, targetDir, dryRun, markerVersion ?? currentVersion, carryOf(markerRead));
         out.log("");
         return code;
     }
     if (jsonMode) {
-        out.log(JSON.stringify({ currentVersion, installedVersion, pending }, null, 2));
+        const { pendingManual } = carryOf(markerRead);
+        out.log(JSON.stringify({ currentVersion, installedVersion, pending, pendingManual }, 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");
+    const openManual = carryOf(markerRead).pendingManual;
     out.log("");
     out.log(`  Upgrade: ${currentVersion} → latest`);
     out.log("");
     if (pending.length === 0) {
         out.log("  ✓ Nothing new since your version.");
         out.log("");
+        logOpenManual(out, openManual);
         return 0;
     }
     if (breaking.length > 0) {
@@ -576,5 +754,6 @@ export async function runUpgradeCli(argv, cwd, out, options) {
         out.log("  Run with --verbose for full migration details.");
         out.log("");
     }
+    logOpenManual(out, openManual);
     return 0;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.348.1",
+  "version": "0.349.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>",
@@ -206,8 +206,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.348.1",
-    "@cosmicdrift/kumiko-types": "0.348.1",
+    "@cosmicdrift/kumiko-http": "0.349.0",
+    "@cosmicdrift/kumiko-types": "0.349.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -223,7 +223,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.348.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.349.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.349.0",
+    "type": "improvement",
+    "title": "kumiko-upgrade advances in one --apply run, tracks open manual migrations with ids and resolves them via --resolve",
+    "detail": "kumiko-upgrade: one --apply run advances, manual items are resolved with --resolve\n`--apply` now moves the marker to the installed version in a single run. Breaking changes without a codemod stay in the marker as `pendingManual` with a stable id (`<version>:<8-char title hash>`) and are listed after every run; the upgrade guard no longer fails on them. `--resolve <id|version>[,...] --reason \"<text>\" [--not-applicable]` moves entries to `resolvedManual` (version must match exactly one open entry; unknown refs write nothing). Resolved ids do not come back. The plain report lists open entries, and `--json` carries them as `pendingManual`.",
+    "migration": "If you relied on a second --apply to acknowledge manual migrations, run kumiko-upgrade --resolve <id> --reason \"<text>\" instead."
+  },
   {
     "version": "0.348.0",
     "type": "improvement",