@cosmicdrift/kumiko-framework 0.374.0 → 0.377.0

package/dist/http/policy.d.ts

@@ -0,0 +1,30 @@
+import { lookup } from "node:dns/promises";
+export type EgressPolicy = {
+    readonly kind: "external";
+} | {
+    readonly kind: "internal";
+    readonly allowHosts?: readonly string[];
+    readonly allowOrigins?: readonly string[];
+} | {
+    readonly kind: "tenant-supplied";
+};
+export declare function isBlockedIp(ip: string): boolean;
+export declare function assertHttpScheme(url: URL): void;
+export interface ResolvedHost {
+    readonly address: string;
+    readonly family: 4 | 6;
+}
+export declare class BlockedHostError extends Error {
+    constructor(message: string);
+}
+export declare class HostResolutionError extends Error {
+    constructor(message: string);
+}
+export declare function resolvePublicHostname(rawHost: string, lookupFn?: typeof lookup): Promise<ResolvedHost>;
+export declare function resolvePublicHost(url: URL, lookupFn?: typeof lookup): Promise<ResolvedHost>;
+export declare function isPublicHost(raw: string, lookupFn?: typeof lookup): Promise<boolean>;
+export type InternalEgressPolicy = Extract<EgressPolicy, {
+    kind: "internal";
+}>;
+export declare function assertValidInternalPolicy(policy: InternalEgressPolicy): void;
+export declare function assertAllowedTarget(url: URL, policy: InternalEgressPolicy): void;

package/dist/http/policy.js

@@ -0,0 +1,299 @@
+// Egress trust boundary. `EgressPolicy` and the checks below back the single
+// exported way to speak outward, `egress()` in ./egress.ts. Only `isPublicHost`
+// reaches the package's public barrel (index.ts), as a boolean pre-check for
+// create-time validation — call sites otherwise bind a policy once via
+// `egress(policy)` and never see the range table or the allowlist check
+// directly.
+//
+// `external` and `tenant-supplied` resolve to the identical set of checks
+// below (deny private/reserved/link-local + no redirects). They stay
+// separate policy kinds because they carry different trust semantics — a
+// tenant-controlled URL is adversary-input in a way a hardcoded external
+// endpoint is not.
+//
+// DNS-rebinding protection: `resolvePublicHost` resolves the hostname
+// exactly once, validates every returned address, and hands back the one
+// address ./egress.ts connects to directly (fetch-by-IP, with the original
+// hostname preserved for the Host header and TLS SNI/cert validation).
+// There is no second resolution for an attacker-controlled DNS answer to
+// swap in between check and connect — see `resolvePublicHost` below for the
+// mechanism and ../__tests__/egress.test.ts / policy.test.ts for the tests
+// pinning it.
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+export function isBlockedIp(ip) {
+    const kind = isIP(ip);
+    if (kind === 4)
+        return isBlockedV4(ip);
+    if (kind === 6)
+        return isBlockedV6(ip);
+    return true; // not parseable as an IP -> fail closed
+}
+function inRange(n, [min, max]) {
+    return n >= min && n <= max;
+}
+// Each entry: first-octet range, an optional second-octet range for ranges
+// narrower than a full /8, and an optional third-octet range for the one
+// entry (192.0.0.0/24) narrower than a full /16. Table form keeps the range
+// list scannable as data rather than as a chain of near-identical `if`s.
+const BLOCKED_V4_RANGES = [
+    { a: [0, 0] }, // 0.0.0.0/8 "this host"
+    { a: [10, 10] }, // 10/8 private
+    { a: [127, 127] }, // loopback
+    { a: [169, 169], b: [254, 254] }, // link-local + cloud metadata (169.254.169.254)
+    { a: [172, 172], b: [16, 31] }, // 172.16/12 private
+    { a: [192, 192], b: [0, 0], c: [0, 0] }, // 192.0.0.0/24 IETF protocol assignments
+    { a: [192, 192], b: [168, 168] }, // 192.168/16 private
+    { a: [198, 198], b: [18, 19] }, // 198.18.0.0/15 benchmarking (RFC 2544)
+    { a: [100, 100], b: [64, 127] }, // 100.64/10 CGNAT
+    { a: [224, 255] }, // multicast/reserved — also covers 240.0.0.0/4 and the broadcast address
+];
+function isBlockedV4(ip) {
+    const [a = 0, b = 0, c = 0] = ip.split(".").map(Number);
+    return BLOCKED_V4_RANGES.some((range) => inRange(a, range.a) &&
+        (range.b === undefined || inRange(b, range.b)) &&
+        (range.c === undefined || inRange(c, range.c)));
+}
+// WHATWG URL host-parsing always serializes IPv6 into the canonical
+// compressed lowercase form (RFC 5952) regardless of the input shape —
+// uncompressed groups, embedded IPv4-dotted notation, mixed case all collapse
+// to one string. isBlockedV6 below only has to handle that one shape, so any
+// caller-supplied IPv6 literal is normalized through `new URL()` first.
+function canonicalIPv6(ip) {
+    try {
+        return new URL(`http://[${ip}]/`).hostname.replace(/^\[/, "").replace(/\]$/, "");
+    }
+    catch {
+        return ip; // unparsable — falls through to the (fail-closed) checks below
+    }
+}
+const HEX_GROUP_RE = /^[0-9a-f]{1,4}$/;
+// Expands a canonicalized (RFC 5952) IPv6 literal into its 8 explicit
+// 16-bit groups. Compression ("::") swallows a variable number of the
+// trailing zero groups an embedded IPv4 address produces — e.g.
+// `64:ff9b::0.0.0.1` canonicalizes to `64:ff9b::1` (one group, not two) —
+// so matching by regex on the compressed string misses those forms.
+// Expanding first lets every embedded-v4 check below match by fixed group
+// *position* regardless of how much of the address compressed away.
+// Returns null for anything that isn't well-formed hex-group IPv6 (e.g. a
+// zone id), which isBlockedV6 treats as fail-closed.
+function expandGroups(ip) {
+    const parts = ip.split("::");
+    if (parts.length > 2)
+        return null;
+    const toGroups = (segment) => (segment ? segment.split(":") : []);
+    const head = toGroups(parts[0]);
+    if (parts.length === 1) {
+        if (head.length !== 8 || !head.every((g) => HEX_GROUP_RE.test(g)))
+            return null;
+        return head.map((g) => Number.parseInt(g, 16));
+    }
+    const tail = toGroups(parts[1]);
+    const missing = 8 - head.length - tail.length;
+    if (missing < 0 || ![...head, ...tail].every((g) => HEX_GROUP_RE.test(g)))
+        return null;
+    return [...head, ...Array(missing).fill("0"), ...tail].map((g) => Number.parseInt(g, 16));
+}
+// Decodes the two 16-bit groups at `at`/`at+1` back into dotted-decimal, for
+// the v4 range rules.
+function decodeEmbeddedV4(groups, at) {
+    const hi = groups[at] ?? 0;
+    const lo = groups[at + 1] ?? 0;
+    return `${hi >>> 8}.${hi & 0xff}.${lo >>> 8}.${lo & 0xff}`;
+}
+// Every "IPv4-in-IPv6" encoding a URL literal can carry, as the fixed
+// leading groups (in expanded, 8-group form) and the group index the
+// embedded IPv4 address starts at. Matching by expanded position instead of
+// regex on the compressed string is what makes a single-group-compressed
+// embed (see expandGroups above) match the same as an uncompressed one.
+const EMBEDDED_V4_FORMS = [
+    { prefix: [0, 0, 0, 0, 0, 0], at: 6 }, // ::a.b.c.d — deprecated IPv4-compatible (RFC 4291)
+    { prefix: [0, 0, 0, 0, 0, 0xffff], at: 6 }, // ::ffff:a.b.c.d — IPv4-mapped (RFC 4291)
+    { prefix: [0, 0, 0, 0, 0xffff, 0], at: 6 }, // ::ffff:0:a.b.c.d — IPv4-translated (RFC 8215)
+    { prefix: [0x64, 0xff9b, 0, 0, 0, 0], at: 6 }, // 64:ff9b::a.b.c.d — NAT64 well-known prefix (RFC 6052)
+    { prefix: [0x64, 0xff9b, 1], at: 6 }, // 64:ff9b:1::a.b.c.d — NAT64 local-use prefix (RFC 8215)
+    { prefix: [0x2002], at: 1 }, // 2002:a.b.c.d:: — 6to4 (RFC 3056)
+];
+function matchesPrefix(groups, prefix) {
+    return prefix.every((value, index) => groups[index] === value);
+}
+const BLOCKED_V6_EXACT = new Set(["::1", "::"]); // loopback / unspecified
+// All three ranges expressed on the first 16-bit group ("head"), so they
+// share one table instead of three near-identical `if`s:
+//   fc00::/7   unique-local           -> head 0xfc00-0xfdff
+//   fe80::/10  link-local             -> head 0xfe80-0xfebf
+//   fec0::/10  deprecated site-local (RFC 3879, 2004) — no DNS server hands
+//              this out today, but this is an exported security boundary,
+//              so block it rather than lean on the deprecation.
+const BLOCKED_V6_HEAD_RANGES = [
+    [0xfc00, 0xfdff],
+    [0xfe80, 0xfebf],
+    [0xfec0, 0xfeff],
+];
+function isBlockedV6(ip) {
+    const lower = canonicalIPv6(ip.toLowerCase());
+    if (BLOCKED_V6_EXACT.has(lower))
+        return true;
+    const groups = expandGroups(lower);
+    if (!groups)
+        return true; // not well-formed IPv6 -> fail closed
+    const embedded = EMBEDDED_V4_FORMS.find((form) => matchesPrefix(groups, form.prefix));
+    if (embedded)
+        return isBlockedV4(decodeEmbeddedV4(groups, embedded.at));
+    const head = groups[0] ?? 0;
+    return BLOCKED_V6_HEAD_RANGES.some((range) => inRange(head, range));
+}
+function stripBrackets(host) {
+    return host.replace(/^\[/, "").replace(/\]$/, "");
+}
+export function assertHttpScheme(url) {
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new Error(`egress: unsupported scheme ${url.protocol}`);
+    }
+}
+// Denies private/reserved/link-local ranges for `external` and
+// `tenant-supplied`, and pins the exact address ./egress.ts must connect to.
+// Resolves the hostname's A/AAAA records (or reads the literal IP directly),
+// rejects if ANY resolved address falls in a denied range — a host with one
+// public and one private record must not pass — and returns ONE validated
+// address from that same resolution. Reusing that address for the connect,
+// instead of letting `fetch()` resolve the hostname again, is what closes
+// the DNS-rebinding window: there is no second lookup left for an
+// attacker-controlled DNS server to answer differently.
+//
+// Thrown for a host that is itself a blocked IP-literal, or that resolves to
+// one — a policy verdict, not a network condition. Retrying will not help;
+// callers should surface this as a rejected configuration.
+export class BlockedHostError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "BlockedHostError";
+    }
+}
+// Thrown when the resolver itself failed or returned nothing — a network
+// condition, not a policy verdict. Callers that retry (e.g. an inbound-mail
+// poll) should treat this as transient, unlike BlockedHostError.
+export class HostResolutionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "HostResolutionError";
+    }
+}
+// Resolves a bare hostname or IP-literal (no scheme, no URL parsing) exactly
+// once and returns the single validated address the caller must connect to
+// — the same DNS-rebinding-closing mechanism as resolvePublicHost below,
+// factored out for callers that only ever have a host (SMTP/IMAP tenant
+// config), never a full URL.
+//
+// `lookupFn` defaults to the real resolver and exists only so tests can pin
+// deterministic, network-free answers — production call sites never pass it.
+export async function resolvePublicHostname(rawHost, lookupFn = lookup) {
+    const host = stripBrackets(rawHost);
+    const ipVersion = isIP(host);
+    if (ipVersion !== 0) {
+        if (isBlockedIp(host))
+            throw new BlockedHostError(`egress: host is not a public address: ${host}`);
+        return { address: host, family: ipVersion === 6 ? 6 : 4 };
+    }
+    let addresses;
+    try {
+        addresses = await lookupFn(host, { all: true });
+    }
+    catch {
+        throw new HostResolutionError(`egress: DNS resolution failed for host: ${host}`);
+    }
+    if (addresses.length === 0) {
+        throw new HostResolutionError(`egress: DNS resolution returned no records for host: ${host}`);
+    }
+    const blocked = addresses.find((a) => isBlockedIp(a.address));
+    if (blocked) {
+        throw new BlockedHostError(`egress: host resolves to a non-public address: ${host} -> ${blocked.address}`);
+    }
+    // IPv4 first: hosts and runners without an IPv6 route would otherwise get an unreachable pinned address.
+    const chosen = addresses.find((address) => address.family === 4) ?? addresses[0];
+    if (!chosen) {
+        throw new HostResolutionError(`egress: DNS resolution returned no records for host: ${host}`);
+    }
+    return { address: chosen.address, family: chosen.family === 6 ? 6 : 4 };
+}
+export async function resolvePublicHost(url, lookupFn = lookup) {
+    if (url.username || url.password) {
+        throw new Error("egress: URLs with embedded credentials are not supported");
+    }
+    return resolvePublicHostname(url.hostname, lookupFn);
+}
+// Create-time validation for tenant-supplied URLs (e.g. webhook registration)
+// where rejecting at registration is better UX than failing later at fetch
+// time. Runs the same resolution as `egress()` without connecting anywhere,
+// and never throws — bad input (unparsable URL, non-http(s) scheme, embedded
+// credentials, DNS failure, blocked range) all just resolve to `false`.
+//
+// A `true` only holds at the moment of the check: DNS can change afterwards,
+// so this is a UX pre-check, not a substitute for the fetch-time check.
+// Outbound requests to tenant-supplied URLs MUST still go through
+// `egress({ kind: "tenant-supplied" })`, never a plain `fetch()`.
+export async function isPublicHost(raw, lookupFn = lookup) {
+    try {
+        const url = new URL(raw);
+        assertHttpScheme(url);
+        await resolvePublicHost(url, lookupFn);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isHostEntryWellFormed(entry) {
+    if (entry.includes("/") || entry.includes("@") || entry.includes("://"))
+        return false;
+    if (!entry.includes(":"))
+        return true;
+    return isIP(stripBrackets(entry)) === 6;
+}
+function isOriginEntryWellFormed(entry) {
+    let parsed;
+    try {
+        parsed = new URL(entry);
+    }
+    catch {
+        return false;
+    }
+    return ((parsed.protocol === "http:" || parsed.protocol === "https:") &&
+        !parsed.username &&
+        !parsed.password &&
+        parsed.pathname === "/" &&
+        !parsed.search &&
+        !parsed.hash);
+}
+// Runs once at bind time so a misconfigured allowlist fails at startup, not
+// on the first request.
+export function assertValidInternalPolicy(policy) {
+    const allowHosts = policy.allowHosts ?? [];
+    const allowOrigins = policy.allowOrigins ?? [];
+    if (allowHosts.length === 0 && allowOrigins.length === 0) {
+        throw new Error("egress(internal): allowHosts or allowOrigins must list at least one entry");
+    }
+    for (const entry of allowHosts) {
+        if (!isHostEntryWellFormed(entry)) {
+            throw new Error(`egress(internal): allowHosts entry must be a bare hostname, got "${entry}" (use allowOrigins to pin scheme and port)`);
+        }
+    }
+    // The entry is named by index only: it may carry credentials that must not reach startup logs.
+    allowOrigins.forEach((entry, index) => {
+        if (!isOriginEntryWellFormed(entry)) {
+            throw new Error(`egress(internal): allowOrigins[${index}] must be an http(s) origin like "https://host:port" without path, query or credentials`);
+        }
+    });
+}
+// Explicit allowlist check for `internal` — no range check, since `internal`
+// targets are deliberately private/cluster-local. The hostname (not the
+// resolved IP) must match `allowHosts` (any port/scheme) or the full origin
+// (scheme + host + port) must match `allowOrigins`.
+export function assertAllowedTarget(url, policy) {
+    const host = stripBrackets(url.hostname).toLowerCase();
+    const hostAllowed = (policy.allowHosts ?? []).some((entry) => stripBrackets(entry).toLowerCase() === host);
+    const originAllowed = (policy.allowOrigins ?? []).some((entry) => new URL(entry).origin === url.origin);
+    if (!hostAllowed && !originAllowed) {
+        throw new Error(`egress: target not in allowlist: ${url.origin}`);
+    }
+}

package/dist/i18n/required-surface-keys.js

@@ -304,6 +304,8 @@ export function requiredKeysFromScreen(featureName, screen, options = {}) {
                 pushKey(out, action.label);
             for (const link of form.successLinks ?? [])
                 pushKey(out, link.label);
+            for (const fact of form.successFacts ?? [])
+                pushKey(out, fact.label);
             for (const fieldName of Object.keys(form.fields)) {
                 const override = form.fieldLabels?.[fieldName];
                 if (override !== undefined)

package/dist/jobs/job-runner.js

@@ -15,6 +15,7 @@ import { isKumikoError } from "../errors/kumiko-error.js";
 import { createTenantFileContext } from "../files/file-handle.js";
 import { createFallbackLogger } from "../logging/index.js";
 import { createEscapeHatchProcessDedup, createEscapeHatchReporter, createEscapeHatchReportWindow, createMetricsForFactory, emitJobLastSuccess, emitJobQueueDepth, flushEscapeHatchAudits, getFallbackTracer, registerStandardMetrics, withEscapeHatchAuditScope, } from "../observability/index.js";
+import { configAccessorFactoryOf } from "../pipeline/config-accessor-factory.js";
 import { createDistributedLock } from "../pipeline/distributed-lock.js";
 import { RedisKeys } from "../pipeline/redis-keys.js";
 import { createGatedIdentitySwitch } from "../pipeline/system-identity-switch.js";
@@ -967,8 +968,9 @@ export function createJobRunner(options) {
         const crossTenantReads = tenantScopedDb && crossTenantReadsReason !== undefined
             ? createCrossTenantReads(tenantScopedDb, crossTenantReadsReason, reportEscapeHatch)
             : undefined;
-        const config = context._configAccessorFactory && tenantScopedDb
-            ? context._configAccessorFactory({
+        const configFactory = configAccessorFactoryOf(context);
+        const config = configFactory && tenantScopedDb
+            ? configFactory({
                 user: { id: jobSystemUser.id, tenantId },
                 db: tenantScopedDb,
                 secrets: context.secrets,

package/dist/pipeline/config-accessor-factory.d.ts

@@ -0,0 +1,3 @@
+import type { ConfigAccessorFactory } from "@cosmicdrift/kumiko-types/config";
+import type { AppContext } from "@cosmicdrift/kumiko-types/handlers";
+export declare function configAccessorFactoryOf(context: Pick<AppContext, "configAccessorFactory" | "_configAccessorFactory">): ConfigAccessorFactory | undefined;

package/dist/pipeline/config-accessor-factory.js

@@ -0,0 +1,3 @@
+export function configAccessorFactoryOf(context) {
+    return context.configAccessorFactory ?? context._configAccessorFactory;
+}

package/dist/pipeline/dispatch-shared.js

@@ -22,6 +22,7 @@ import { isPlainObject } from "../utils/is-plain-object.js";
 import { INTERACTIVE_SIGN_IN_POLICY, resolveActiveMembershipFn } from "./active-membership.js";
 import { appendDomainEventCore } from "./append-event-core.js";
 import { resolveAuthClaims as runAuthClaimsResolver } from "./auth-claims-resolver.js";
+import { configAccessorFactoryOf } from "./config-accessor-factory.js";
 import { runBatch, unwrapSingle } from "./dispatch-batch.js";
 import { executeQuery } from "./dispatch-query.js";
 import { executeWrite } from "./dispatch-write.js";
@@ -393,8 +394,9 @@ readOnlyForTenant = false) {
         });
     }
     // Mirror notify: only built when the config feature wired its factory.
-    const config = context._configAccessorFactory && db
-        ? context._configAccessorFactory({
+    const configFactory = configAccessorFactoryOf(context);
+    const config = configFactory && db
+        ? configFactory({
             user: { id: user.id, tenantId: user.tenantId },
             db,
             secrets: context.secrets,
@@ -404,7 +406,6 @@ readOnlyForTenant = false) {
     // identity is the target tenant's system user so the caller's own user-scope
     // values never resolve into another tenant's config; the db is tenant-mode
     // scoped to the target.
-    const configFactory = context._configAccessorFactory;
     const configFor = configFactory && dbSource
         ? (targetTenantId) => {
             if (targetTenantId === user.tenantId && config)
@@ -1268,8 +1269,9 @@ function buildAuthClaimsContext(ctx, user) {
             projectionRegistry: ctx.registry,
         },
     });
-    const configAccessor = context._configAccessorFactory
-        ? context._configAccessorFactory({
+    const authClaimsConfigFactory = configAccessorFactoryOf(context);
+    const configAccessor = authClaimsConfigFactory
+        ? authClaimsConfigFactory({
             user: { id: user.id, tenantId: user.tenantId },
             db,
             secrets: context.secrets,

package/dist/pipeline/index.d.ts

@@ -41,3 +41,4 @@ export type { ProjectionStatus } from "./projection-state.ts";
 export { createProjectionStateTable, ProjectionStatuses, projectionStateTable, } from "./projection-state.ts";
 export { runProjectionsForEvent } from "./projections-runner.ts";
 export { ACCESS_INVALIDATION_CONSUMER_NAME, createAccessInvalidationEventConsumer, createSearchEventConsumer, createSseBroadcastEventConsumer, SEARCH_CONSUMER_NAME, SSE_BROADCAST_CONSUMER_NAME, } from "./system-hooks.ts";
+export { TENANT_TIMEZONE_CONFIG_KEY } from "./tenant-timezone-config-key.ts";

package/dist/pipeline/index.js

@@ -23,3 +23,4 @@ export { getAllProjectionProgress, getProjectionState, listProjectionsWithState,
 export { createProjectionStateTable, ProjectionStatuses, projectionStateTable, } from "./projection-state.js";
 export { runProjectionsForEvent } from "./projections-runner.js";
 export { ACCESS_INVALIDATION_CONSUMER_NAME, createAccessInvalidationEventConsumer, createSearchEventConsumer, createSseBroadcastEventConsumer, SEARCH_CONSUMER_NAME, SSE_BROADCAST_CONSUMER_NAME, } from "./system-hooks.js";
+export { TENANT_TIMEZONE_CONFIG_KEY } from "./tenant-timezone-config-key.js";

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.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, 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 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 { metricField, 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";

package/dist/upgrade-changelog.d.ts

@@ -0,0 +1,25 @@
+export type UpgradeChangelogManual = {
+    readonly id: string;
+    readonly version: string;
+    readonly title: string;
+    readonly status: "open" | "migrated" | "not-applicable";
+};
+export type UpgradeChangelogSection = {
+    readonly from: string;
+    readonly to: string;
+    /** YYYY-MM-DD. */
+    readonly date: string;
+    readonly breaking: readonly {
+        readonly version: string;
+        readonly title: string;
+    }[];
+    readonly manual: readonly UpgradeChangelogManual[];
+    readonly codemods: readonly {
+        readonly version: string;
+        readonly codemod: string;
+        readonly title: string;
+    }[];
+};
+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;

package/dist/upgrade-changelog.js

@@ -0,0 +1,48 @@
+const CHANGELOG_HEADER = `# Changelog
+
+Kumiko upgrades of this app, written by \`kumiko-upgrade --apply\`. Newest first.
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+`;
+const SECTION_START = /^## \[/;
+const PACKAGES_LABEL = "@cosmicdrift/kumiko-*";
+function printableLine(text) {
+    return text.replace(/\p{Cc}/gu, " ");
+}
+function bulletList(title, lines) {
+    return lines.length === 0 ? [] : ["", `### ${title}`, "", ...lines.map((line) => `- ${line}`)];
+}
+export function renderUpgradeSection(section) {
+    return [
+        `## [${section.to}] - ${section.date}`,
+        ...bulletList("Changed", [`${PACKAGES_LABEL}: ${section.from} → ${section.to}`]),
+        ...bulletList("Breaking", section.breaking.map((entry) => `${entry.version} · ${printableLine(entry.title)}`)),
+        ...bulletList("Manual migrations", section.manual.map((entry) => `[${entry.status}] ${entry.id} · ${entry.version} · ${printableLine(entry.title)}`)),
+        ...bulletList("Codemods applied", section.codemods.map((entry) => `${entry.version} · ${entry.codemod} · ${printableLine(entry.title)}`)),
+        "",
+    ].join("\n");
+}
+function splitSections(content) {
+    const lines = content.split("\n");
+    const firstSection = lines.findIndex((line) => SECTION_START.test(line));
+    if (firstSection === -1)
+        return { header: content.replace(/\n*$/, "\n"), sections: [] };
+    const header = lines.slice(0, firstSection).join("\n").replace(/\n*$/, "\n");
+    const sections = [];
+    let current = [];
+    for (const line of lines.slice(firstSection)) {
+        if (SECTION_START.test(line) && current.length > 0) {
+            sections.push(current.join("\n").replace(/\n*$/, "\n"));
+            current = [];
+        }
+        current.push(line);
+    }
+    sections.push(current.join("\n").replace(/\n*$/, "\n"));
+    return { header, sections };
+}
+/** Puts the section on top; a section for the same target version is replaced, so a re-run stays idempotent. */
+export function mergeUpgradeSection(existing, section) {
+    const { header, sections } = splitSections(existing ?? CHANGELOG_HEADER);
+    const prefix = `## [${section.to}]`;
+    const others = sections.filter((candidate) => !candidate.startsWith(prefix));
+    return [header, renderUpgradeSection(section), ...others].join("\n");
+}