@cosmicdrift/kumiko-framework 0.388.0 → 0.390.0

package/dist/engine/feature-ast/patcher.d.ts

@@ -1,217 +0,0 @@
-import type { SourceFile } from "ts-morph";
-import type { LifecycleHookType } from "../constants.ts";
-import type { ConfigKeyDefinition, ConfigKeyType, JobDefinition, RunIn, TranslationKeys } from "../types/config.ts";
-import type { MetricOptions, SecretNamespaceOptions, SecretOptions } from "../types/feature.ts";
-import type { EntityDefinition } from "../types/fields.ts";
-import type { AccessRule, ClaimKeyType, EscapeHatchDeclaration, RateLimitOption } from "../types/handlers.ts";
-import type { HookPhase } from "../types/hooks.ts";
-import type { HttpRouteMethod } from "../types/http-route.ts";
-import type { NavDefinition } from "../types/nav.ts";
-import type { MspErrorMode } from "../types/projection.ts";
-import type { RelationDefinition } from "../types/relations.ts";
-import type { ScreenDefinition } from "../types/screen.ts";
-import type { WorkspaceDefinition } from "../types/workspace.ts";
-import { type PatternChange, type PatternId } from "./patch.ts";
-import type { FeaturePattern } from "./patterns.ts";
-import type { SourceLocation } from "./source-location.ts";
-export declare const SYNTHETIC_LOC: SourceLocation;
-export declare function rawLoc(raw: string): SourceLocation;
-export type AddEntityArgs = {
-    readonly name: string;
-    readonly definition: EntityDefinition;
-};
-export type AddRelationArgs = {
-    readonly entity: string;
-    readonly name: string;
-    readonly definition: RelationDefinition;
-};
-export type AddWriteHandlerArgs = {
-    readonly name: string;
-    /** Source text of the Zod schema, e.g. `"z.object({ title: z.string() })"`. */
-    readonly schemaSource: string;
-    /** Source text of the handler closure, e.g. `"async (event, ctx) => { ... }"`. */
-    readonly handlerSource: string;
-    readonly access?: AccessRule;
-    readonly rateLimit?: RateLimitOption;
-    readonly unsafeSkipTransitionGuard?: boolean;
-    readonly escapeHatch?: EscapeHatchDeclaration;
-};
-export type AddQueryHandlerArgs = {
-    readonly name: string;
-    readonly schemaSource: string;
-    readonly handlerSource: string;
-    readonly access?: AccessRule;
-    readonly rateLimit?: RateLimitOption;
-    readonly escapeHatch?: EscapeHatchDeclaration;
-};
-export type AddStreamHandlerArgs = {
-    readonly name: string;
-    readonly schemaSource: string;
-    readonly handlerSource: string;
-    readonly access?: AccessRule;
-    readonly rateLimit?: RateLimitOption;
-    readonly escapeHatch?: EscapeHatchDeclaration;
-};
-export type AddHookArgs = {
-    readonly type: LifecycleHookType | "validation";
-    readonly target: string | readonly string[] | {
-        readonly allOf: string;
-    };
-    /** Source text of the closure, e.g. `"async (event, ctx) => { ... }"`. */
-    readonly handlerSource: string;
-    readonly phase?: HookPhase;
-    readonly escapeHatch?: EscapeHatchDeclaration;
-};
-export type AddJobArgs = {
-    readonly name: string;
-    readonly options: Omit<JobDefinition, "name" | "handler">;
-    readonly handlerSource: string;
-};
-export type AddNotificationArgs = {
-    readonly name: string;
-    readonly trigger?: {
-        readonly on: string;
-    };
-    readonly recipientSource?: string;
-    readonly dataSource?: string;
-    readonly templates?: Readonly<Record<string, string>>;
-};
-export type AddHttpRouteArgs = {
-    readonly method: HttpRouteMethod;
-    readonly path: string;
-    readonly handlerSource: string;
-    readonly anonymous: boolean;
-};
-export type AddDefineEventArgs = {
-    readonly name: string;
-    readonly schemaSource: string;
-    readonly piiFieldsSource: string;
-    readonly version?: number;
-    readonly migrations?: Readonly<Record<string, string>>;
-};
-export type AddProjectionArgs = {
-    readonly name: string;
-    readonly sourceEntity: string | readonly string[];
-    /** Map of event-type → closure source for the apply handler. */
-    readonly applySources: Readonly<Record<string, string>>;
-};
-export type AddMultiStreamProjectionArgs = {
-    readonly name: string;
-    readonly applySources: Readonly<Record<string, string>>;
-    readonly errorMode?: MspErrorMode;
-    readonly runIn?: RunIn;
-    readonly delivery?: "shared" | "per-instance";
-};
-export type AddReferenceDataArgs = {
-    readonly entity: string;
-    readonly data: readonly Record<string, unknown>[];
-    readonly upsertKey?: string;
-};
-export type AddMetricArgs = {
-    readonly name: string;
-    readonly options: MetricOptions;
-};
-export type AddSecretArgs = {
-    readonly name: string;
-    readonly options: SecretOptions;
-};
-export type AddSecretNamespaceArgs = {
-    readonly name: string;
-    readonly options: SecretNamespaceOptions;
-};
-export type AddClaimKeyArgs = {
-    readonly name: string;
-    readonly type: ClaimKeyType;
-};
-export type AddUseExtensionArgs = {
-    readonly extension: string;
-    readonly entity: string;
-    readonly options?: Readonly<Record<string, unknown>>;
-};
-export type AddScreenArgs = {
-    readonly definition: ScreenDefinition;
-    /** Source spans for each closure-typed sub-property; keyed by JSON-path
-     *  inside the definition (e.g. `"rowActions.0.visible"`). Each entry's
-     *  raw is the closure source the renderer will splice in. */
-    readonly opaqueSources?: Readonly<Record<string, string>>;
-};
-export type AddRequiresArgs = {
-    readonly features: readonly string[];
-};
-export type AddOptionalRequiresArgs = {
-    readonly features: readonly string[];
-};
-export type AddReadsConfigArgs = {
-    readonly keys: readonly string[];
-};
-export type AddToggleableArgs = {
-    readonly default: boolean;
-};
-export type AddDescribeArgs = {
-    readonly text: string;
-};
-export type AddNavArgs = {
-    readonly definition: NavDefinition;
-};
-export type AddWorkspaceArgs = {
-    readonly definition: WorkspaceDefinition;
-};
-export type AddConfigArgs = {
-    readonly keys: Readonly<Record<string, ConfigKeyDefinition<ConfigKeyType>>>;
-};
-export type AddTranslationsArgs = {
-    readonly keys: TranslationKeys;
-};
-export type AddAuthClaimsArgs = {
-    /** Source text of the claims handler closure. */
-    readonly handlerSource: string;
-};
-export type FeaturePatcher = {
-    readonly addRequires: (args: AddRequiresArgs) => void;
-    readonly addOptionalRequires: (args: AddOptionalRequiresArgs) => void;
-    readonly addReadsConfig: (args: AddReadsConfigArgs) => void;
-    readonly addSystemScope: () => void;
-    readonly addToggleable: (args: AddToggleableArgs) => void;
-    readonly addDescribe: (args: AddDescribeArgs) => void;
-    readonly addEntity: (args: AddEntityArgs) => void;
-    readonly addRelation: (args: AddRelationArgs) => void;
-    readonly addNav: (args: AddNavArgs) => void;
-    readonly addWorkspace: (args: AddWorkspaceArgs) => void;
-    readonly addConfig: (args: AddConfigArgs) => void;
-    readonly addTranslations: (args: AddTranslationsArgs) => void;
-    readonly addMetric: (args: AddMetricArgs) => void;
-    readonly addSecret: (args: AddSecretArgs) => void;
-    readonly addSecretNamespace: (args: AddSecretNamespaceArgs) => void;
-    readonly addClaimKey: (args: AddClaimKeyArgs) => void;
-    readonly addReferenceData: (args: AddReferenceDataArgs) => void;
-    readonly addUseExtension: (args: AddUseExtensionArgs) => void;
-    readonly addScreen: (args: AddScreenArgs) => void;
-    readonly addWriteHandler: (args: AddWriteHandlerArgs) => void;
-    readonly addQueryHandler: (args: AddQueryHandlerArgs) => void;
-    readonly addStreamHandler: (args: AddStreamHandlerArgs) => void;
-    readonly addHook: (args: AddHookArgs) => void;
-    readonly addJob: (args: AddJobArgs) => void;
-    readonly addNotification: (args: AddNotificationArgs) => void;
-    readonly addAuthClaims: (args: AddAuthClaimsArgs) => void;
-    readonly addHttpRoute: (args: AddHttpRouteArgs) => void;
-    readonly addProjection: (args: AddProjectionArgs) => void;
-    readonly addMultiStreamProjection: (args: AddMultiStreamProjectionArgs) => void;
-    readonly addDefineEvent: (args: AddDefineEventArgs) => void;
-    readonly replace: (id: PatternId, pattern: FeaturePattern) => void;
-    readonly remove: (id: PatternId) => void;
-    readonly apply: (changes: readonly PatternChange[]) => void;
-    /**
-     * Escape hatch — directly add a hand-built pattern. The typed `add{Kind}`
-     * methods above cover every pattern in the catalogue and should be the
-     * default path; this method exists for migration tools, AST-replay
-     * scenarios, and the rare case where a future pattern-kind isn't yet
-     * exposed via a typed method.
-     */
-    readonly addPattern: (pattern: FeaturePattern) => void;
-};
-/**
- * Build a patcher bound to the given source file. All methods mutate the
- * file in place; saving is the caller's responsibility (e.g. via
- * `sourceFile.saveSync()`).
- */
-export declare function createFeaturePatcher(sourceFile: SourceFile): FeaturePatcher;

package/dist/engine/feature-ast/patcher.js

@@ -1,281 +0,0 @@
-// FeaturePatcher — imperative typed wrapper around the generic apply API.
-// Each `add{Kind}` method takes the natural arguments for that pattern
-// (no SourceLocation gymnastics, no FeaturePattern hand-crafting) and
-// dispatches through the renderer + addPattern under the hood.
-//
-// **Why this layer exists:**
-//   - **AI tool-use**: an LLM-with-tools picks methods by name. `addEntity`
-//     with typed args is a 1-shot tool-call; building a FeaturePattern
-//     literal in JSON would require teaching the model our internal
-//     discriminated-union shape (kind + source + entityName + definition).
-//   - **Designer forms**: form-submit handlers map directly to a single
-//     `patcher.addX(formData)` call — no intermediary translation step.
-//   - **Type narrowing**: each method's TypeScript signature locks the
-//     fields the caller must provide; missing required props fail at
-//     compile time, not at the parse step downstream.
-//
-// **What stays in the generic API:**
-//   - `replace(id, pattern)` / `remove(id)` — symmetric across kinds; the
-//     PatternId discriminator already names what to match.
-//   - `apply(changes)` — bulk operations, friendlier when the AI emits a
-//     change-list as a single JSON array.
-import { addPattern, applyChanges, removePattern, replacePattern, } from "./patch.js";
-// =============================================================================
-// Synthetic SourceLocation — for new patterns that don't have a real file
-// span yet. The renderer only reads `.raw` from body locations (handler/
-// schema/etc.), so for static patterns the synthetic value is a placeholder
-// that never reaches the output.
-// =============================================================================
-export const SYNTHETIC_LOC = {
-    file: "<patcher>",
-    start: { line: 1, column: 1 },
-    end: { line: 1, column: 1 },
-    raw: "",
-};
-export function rawLoc(raw) {
-    return { ...SYNTHETIC_LOC, raw };
-}
-/**
- * Build a patcher bound to the given source file. All methods mutate the
- * file in place; saving is the caller's responsibility (e.g. via
- * `sourceFile.saveSync()`).
- */
-export function createFeaturePatcher(sourceFile) {
-    function add(pattern) {
-        addPattern(sourceFile, pattern);
-    }
-    return {
-        addRequires({ features }) {
-            add({
-                kind: "requires",
-                source: SYNTHETIC_LOC,
-                featureNames: features,
-            });
-        },
-        addOptionalRequires({ features }) {
-            add({
-                kind: "optionalRequires",
-                source: SYNTHETIC_LOC,
-                featureNames: features,
-            });
-        },
-        addReadsConfig({ keys }) {
-            add({
-                kind: "readsConfig",
-                source: SYNTHETIC_LOC,
-                qualifiedKeys: keys,
-            });
-        },
-        addSystemScope() {
-            add({ kind: "systemScope", source: SYNTHETIC_LOC });
-        },
-        addToggleable({ default: defaultOn }) {
-            add({ kind: "toggleable", source: SYNTHETIC_LOC, default: defaultOn });
-        },
-        addDescribe({ text }) {
-            add({ kind: "describe", source: SYNTHETIC_LOC, text });
-        },
-        addEntity({ name, definition }) {
-            add({
-                kind: "entity",
-                source: SYNTHETIC_LOC,
-                entityName: name,
-                definition,
-            });
-        },
-        addRelation({ entity, name, definition }) {
-            add({
-                kind: "relation",
-                source: SYNTHETIC_LOC,
-                entityName: entity,
-                relationName: name,
-                definition,
-            });
-        },
-        addNav({ definition }) {
-            add({ kind: "nav", source: SYNTHETIC_LOC, definition });
-        },
-        addWorkspace({ definition }) {
-            add({ kind: "workspace", source: SYNTHETIC_LOC, definition });
-        },
-        addConfig({ keys }) {
-            add({ kind: "config", source: SYNTHETIC_LOC, keys });
-        },
-        addTranslations({ keys }) {
-            add({ kind: "translations", source: SYNTHETIC_LOC, keys });
-        },
-        addMetric({ name, options }) {
-            add({ kind: "metric", source: SYNTHETIC_LOC, shortName: name, options });
-        },
-        addSecret({ name, options }) {
-            add({ kind: "secret", source: SYNTHETIC_LOC, shortName: name, options });
-        },
-        addSecretNamespace({ name, options }) {
-            add({ kind: "secretNamespace", source: SYNTHETIC_LOC, shortName: name, options });
-        },
-        addClaimKey({ name, type }) {
-            add({ kind: "claimKey", source: SYNTHETIC_LOC, shortName: name, claimType: type });
-        },
-        addReferenceData({ entity, data, upsertKey }) {
-            add({
-                kind: "referenceData",
-                source: SYNTHETIC_LOC,
-                entityName: entity,
-                data,
-                ...(upsertKey !== undefined && { upsertKey }),
-            });
-        },
-        addUseExtension({ extension, entity, options }) {
-            add({
-                kind: "useExtension",
-                source: SYNTHETIC_LOC,
-                extensionName: extension,
-                entityName: entity,
-                ...(options !== undefined && { options }),
-            });
-        },
-        addScreen({ definition, opaqueSources }) {
-            const opaqueProps = opaqueSources
-                ? Object.fromEntries(Object.entries(opaqueSources).map(([k, v]) => [k, rawLoc(v)]))
-                : {};
-            add({ kind: "screen", source: SYNTHETIC_LOC, definition, opaqueProps });
-        },
-        addWriteHandler({ name, schemaSource, handlerSource, access, rateLimit, unsafeSkipTransitionGuard, escapeHatch, }) {
-            add({
-                kind: "writeHandler",
-                source: SYNTHETIC_LOC,
-                handlerName: name,
-                schemaSource: rawLoc(schemaSource),
-                handlerBody: rawLoc(handlerSource),
-                ...(access !== undefined && { access }),
-                ...(rateLimit !== undefined && { rateLimit }),
-                ...(unsafeSkipTransitionGuard === true && { unsafeSkipTransitionGuard: true }),
-                ...(escapeHatch !== undefined && { escapeHatch }),
-            });
-        },
-        addQueryHandler({ name, schemaSource, handlerSource, access, rateLimit, escapeHatch }) {
-            add({
-                kind: "queryHandler",
-                source: SYNTHETIC_LOC,
-                handlerName: name,
-                schemaSource: rawLoc(schemaSource),
-                handlerBody: rawLoc(handlerSource),
-                ...(access !== undefined && { access }),
-                ...(rateLimit !== undefined && { rateLimit }),
-                ...(escapeHatch !== undefined && { escapeHatch }),
-            });
-        },
-        addStreamHandler({ name, schemaSource, handlerSource, access, rateLimit, escapeHatch }) {
-            add({
-                kind: "streamHandler",
-                source: SYNTHETIC_LOC,
-                handlerName: name,
-                schemaSource: rawLoc(schemaSource),
-                handlerBody: rawLoc(handlerSource),
-                ...(access !== undefined && { access }),
-                ...(rateLimit !== undefined && { rateLimit }),
-                ...(escapeHatch !== undefined && { escapeHatch }),
-            });
-        },
-        addHook({ type, target, handlerSource, phase, escapeHatch }) {
-            add({
-                kind: "hook",
-                source: SYNTHETIC_LOC,
-                hookType: type,
-                target,
-                fnBody: rawLoc(handlerSource),
-                ...(phase !== undefined && { phase }),
-                ...(escapeHatch !== undefined && { escapeHatch }),
-            });
-        },
-        addJob({ name, options, handlerSource }) {
-            add({
-                kind: "job",
-                source: SYNTHETIC_LOC,
-                jobName: name,
-                options,
-                handlerBody: rawLoc(handlerSource),
-            });
-        },
-        addNotification({ name, trigger, recipientSource, dataSource, templates }) {
-            const templateLocs = templates
-                ? Object.fromEntries(Object.entries(templates).map(([k, v]) => [k, rawLoc(v)]))
-                : undefined;
-            add({
-                kind: "notification",
-                source: SYNTHETIC_LOC,
-                notificationName: name,
-                ...(trigger !== undefined && { trigger }),
-                ...(recipientSource !== undefined && { recipientBody: rawLoc(recipientSource) }),
-                ...(dataSource !== undefined && { dataBody: rawLoc(dataSource) }),
-                ...(templateLocs !== undefined && { templates: templateLocs }),
-            });
-        },
-        addAuthClaims({ handlerSource }) {
-            add({
-                kind: "authClaims",
-                source: SYNTHETIC_LOC,
-                fnBody: rawLoc(handlerSource),
-            });
-        },
-        addHttpRoute({ method, path, handlerSource, anonymous }) {
-            add({
-                kind: "httpRoute",
-                source: SYNTHETIC_LOC,
-                method,
-                path,
-                handlerBody: rawLoc(handlerSource),
-                anonymous,
-            });
-        },
-        addProjection({ name, sourceEntity, applySources }) {
-            const applyBodies = Object.fromEntries(Object.entries(applySources).map(([k, v]) => [k, rawLoc(v)]));
-            add({
-                kind: "projection",
-                source: SYNTHETIC_LOC,
-                name,
-                sourceEntity,
-                applyBodies,
-            });
-        },
-        addMultiStreamProjection({ name, applySources, errorMode, runIn, delivery }) {
-            const applyBodies = Object.fromEntries(Object.entries(applySources).map(([k, v]) => [k, rawLoc(v)]));
-            add({
-                kind: "multiStreamProjection",
-                source: SYNTHETIC_LOC,
-                name,
-                applyBodies,
-                ...(errorMode !== undefined && { errorMode }),
-                ...(runIn !== undefined && { runIn }),
-                ...(delivery !== undefined && { delivery }),
-            });
-        },
-        addDefineEvent({ name, schemaSource, piiFieldsSource, version, migrations }) {
-            const migrationLocs = migrations
-                ? Object.fromEntries(Object.entries(migrations).map(([fromVersion, source]) => [
-                    fromVersion,
-                    rawLoc(source),
-                ]))
-                : undefined;
-            add({
-                kind: "defineEvent",
-                source: SYNTHETIC_LOC,
-                eventName: name,
-                schemaSource: rawLoc(schemaSource),
-                piiFields: rawLoc(piiFieldsSource),
-                ...(version !== undefined && { version }),
-                ...(migrationLocs !== undefined && { migrations: migrationLocs }),
-            });
-        },
-        replace(id, pattern) {
-            replacePattern(sourceFile, id, pattern);
-        },
-        remove(id) {
-            removePattern(sourceFile, id);
-        },
-        apply(changes) {
-            applyChanges(sourceFile, changes);
-        },
-        addPattern: add,
-    };
-}