@happyvertical/smrt-app-shell 0.0.0-stage → 0.60.16

package/dist/engine/host.d.ts

@@ -0,0 +1,153 @@
+import { EventEmitter } from 'node:events';
+import { type Command, type ExecuteOptions, type Plan, type Template } from './commands.ts';
+import { type AppDefinition } from './definition.ts';
+import type { VersionStore } from './store.ts';
+type Row = Record<string, unknown>;
+export interface HostOptions {
+    store: VersionStore;
+    /** The worker entry. Defaults to `./app-worker.ts` or `.js` next to this module. */
+    workerUrl?: URL | string;
+}
+export interface ChangeResult {
+    version: number;
+    summary: string;
+    statements: string[];
+    snapshot: string | null;
+    appRestartMs: number;
+    affectedMethods?: string[];
+    converted?: number;
+    emptied?: number;
+    undid?: string;
+}
+export interface CleanUpResult {
+    purgedVersions: number[];
+    values: number;
+    tables: number;
+    /** Old migration/schema snapshot files removed. */
+    snapshots: number;
+}
+export type ExecuteResult = ChangeResult | CleanUpResult | Template;
+export interface MethodResult {
+    result: unknown;
+    writes: unknown[];
+    applied: number;
+    snapshot: string | null;
+}
+export interface ToolResult {
+    content: unknown;
+    isError: boolean;
+    structuredContent?: unknown;
+}
+export interface RestResult {
+    status: number;
+    contentType: string;
+    body: string;
+}
+export interface VersionSummary {
+    version: number;
+    parent: number | null;
+    author: string;
+    summary: string;
+    createdAt: string;
+    purged: boolean;
+    current: boolean;
+}
+export declare class AppHost extends EventEmitter {
+    def: AppDefinition;
+    version: number;
+    readonly dataDir: string;
+    lastSwapMs: number;
+    private store;
+    private workerUrl;
+    private app;
+    private closed;
+    /** Changes are applied one at a time. Work inside the queue must not wait on it. */
+    private queue;
+    private constructor();
+    static open(dataDir: string, opts: HostOptions): Promise<AppHost>;
+    private boot;
+    private spawn;
+    private run;
+    /**
+     * Start an app runtime on `def`; swap it in only if it comes up. With a
+     * migration the old runtime is stopped first, so nothing writes while tables
+     * change; if the new one fails, the migration rolled back and the old
+     * definition is started again.
+     */
+    private swap;
+    /**
+     * Swap to `next`, then persist. If persisting fails the app is put back
+     * where the store still says it is.
+     */
+    private transition;
+    /** Validate, start the new app runtime, record the version. Every change takes this path. */
+    private applyChange;
+    /** What a command would do, without changing anything. */
+    plan(cmd: Command): Promise<Plan>;
+    /**
+     * Apply a command. A risky one throws {@link ApprovalRequiredError} unless
+     * `approved` is true, and then nothing has changed.
+     */
+    execute(cmd: Command, opts: ExecuteOptions): Promise<ExecuteResult>;
+    private clone;
+    private model;
+    /** Where an own field of `model` is stored. */
+    private storage;
+    /** Methods (of any model) whose code mentions `name`; their code is not rewritten. */
+    private methodsMentioning;
+    private analyse;
+    private assertValid;
+    private analyseUndo;
+    /** The model and field stored in `table.column` under `def`. */
+    private locate;
+    /** The chain from the current version back to the root, newest first. */
+    private chain;
+    private analyseCleanUp;
+    private exportTemplate;
+    private analyseImport;
+    /** Talk to the app. Callers inside the change queue use this; others use onApp. */
+    private callApp;
+    private onApp;
+    list(model: string, limit?: number): Promise<Row[]>;
+    get(model: string, id: string): Promise<Row>;
+    create(model: string, data: Row): Promise<Row>;
+    update(model: string, id: string, data: Row): Promise<Row>;
+    remove(model: string, id: string): Promise<{
+        deleted: string;
+    }>;
+    runMethod(model: string, method: string, id?: string | null, params?: Row): Promise<MethodResult>;
+    /** The app's own generated MCP tools. */
+    appTools(): Promise<{
+        name: string;
+        description?: string;
+        inputSchema?: unknown;
+    }[]>;
+    /** Call one of the app's generated tools. A delete needs `approved: true`. */
+    callAppTool(name: string, args?: Row, opts?: {
+        approved?: boolean;
+    }): Promise<ToolResult>;
+    /** The worker's generated REST routes, passed through. A DELETE needs `approved: true`. */
+    rest(req: {
+        method: string;
+        url: string;
+        body?: string;
+    }, opts?: {
+        approved?: boolean;
+    }): Promise<RestResult>;
+    describe(): {
+        name: string;
+        version: number;
+        recipes: string[];
+        models: Record<string, import("./definition.ts").DescribedModel>;
+    };
+    versions(): Promise<VersionSummary[]>;
+    /** Restart the app runtime on the same definition (e.g. after a crash). */
+    restartApp(): Promise<{
+        appRestartMs: number;
+    }>;
+    /** Stop the app thread as a crash would. For tests and for the shell's own watchdogs. */
+    killApp(): Promise<void>;
+    get appAlive(): boolean;
+    close(): Promise<void>;
+}
+export {};