@happyvertical/smrt-app-shell 0.60.18 → 0.61.0

package/dist/lib/server/host.js

@@ -1,21 +1,32 @@
 // Process-wide holders: where the shell gets its database, its data root and
-// the one `AppHost` (the user app's runtime). Everything server-side reaches
+// the app hosts (the user app's runtime). Everything server-side reaches
 // them through here, so tests can configure a temp directory and a SQLite
 // database without SvelteKit.
 //
-// Data layout: the host's `dataDir` is `<data root>/user-app`, a plain
+// Data layout: the live host's `dataDir` is `<data root>/user-app`, a plain
 // directory inside the app-runtime data root, so the encrypted backup that
-// seals the root also seals app.db, snapshots and archives. No symlinks.
+// seals the root also seals app.db, snapshots and archives. No symlinks. An
+// open draft is a second host over `<data root>/user-app-draft`, made and
+// removed only by the engine (`forkDraft` / `discard`).
+//
+// TWO holders, never a "current" one: `getHost()` is the LIVE host, always;
+// the draft host is reachable only through `hostFor('draft')` /
+// `getDraftSlot()`, which callers reach by naming the copy (see target.ts).
 import { existsSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { AppHost } from "../../engine/index.js";
+import { AppHost, discardDraftDirectory, EngineError, } from "../../engine/index.js";
+import { AppDraftCollection } from "../objects/AppDraft.js";
 import { publish } from "./events.js";
-import { ShellVersionStore } from "./version-store.js";
+import { DraftVersionStore, ShellVersionStore } from "./version-store.js";
+/** Where the open draft's copy lives under the data root. */
+export const DRAFT_DIRNAME = 'user-app-draft';
 let context = null;
 let syncDb = null;
 let hostPromise = null;
 let hostRef = null;
+let storeRef = null;
+let slotRef = null;
 let shutdownHooked = false;
 export function configureShell(next) {
     context = next;
@@ -30,6 +41,11 @@ export async function getShellDb() {
     syncDb = db;
     return db;
 }
+/** The runtime's secrets master key, or null when it supplies none. */
+export async function getShellSecretMasterKey() {
+    const provide = requireContext().secretMasterKey;
+    return provide ? provide() : null;
+}
 /** The shell database once `getShellDb()` has resolved. For sync thunks. */
 export function shellDbSync() {
     if (!syncDb)
@@ -50,18 +66,112 @@ function workerUrl() {
         return local;
     return new URL(import.meta.resolve('@happyvertical/smrt-app-shell/engine/worker'));
 }
-/** The one AppHost, opened on first use. */
+/** Republish a host's events on the bus, tagged with the copy they came from. */
+export function wireHostEvents(host, target) {
+    host.on('changed', (e) => publish({
+        type: 'changed',
+        target,
+        version: e.version,
+        summary: e.summary,
+    }));
+    host.on('records', (e) => publish({ type: 'records', target, model: e.model }));
+}
+/**
+ * Open a draft's host. `autoApprove` (risky changes need no approval) is the
+ * draft's alone: the engine refuses it unless `dir` holds its draft marker, so
+ * this call can never hand it to the live host.
+ */
+export function openDraftHost(db, id, dir) {
+    return AppHost.open(dir, {
+        store: new DraftVersionStore(db, id),
+        workerUrl: workerUrl(),
+        autoApprove: true,
+    });
+}
+/**
+ * After the live host is open: settle drafts a restart interrupted, and if one
+ * is open, FREEZE live structure again (the freeze is not persisted) and
+ * reopen the draft host. A draft whose copy cannot be opened still counts as
+ * open (live stays frozen) with `problem` saying why; the owner discards it.
+ */
+async function adoptDraft(db, live, root) {
+    const dir = join(root, DRAFT_DIRNAME);
+    const drafts = await AppDraftCollection.create({ db });
+    const now = new Date().toISOString();
+    const rows = await drafts.list({ limit: 1000 });
+    for (const row of rows.filter((r) => r.status === 'starting')) {
+        row.status = 'discarded';
+        row.note = 'the start did not finish';
+        row.endedAt = now;
+        await row.save();
+    }
+    const open = rows
+        .filter((r) => r.status === 'open')
+        .sort((a, b) => (String(a.createdAt) < String(b.createdAt) ? 1 : -1));
+    for (const extra of open.slice(1)) {
+        extra.status = 'discarded';
+        extra.note = 'another draft was open';
+        extra.endedAt = now;
+        await extra.save();
+    }
+    const row = open[0];
+    if (!row) {
+        // A copy nothing refers to any more (a crash after a publish or discard
+        // was recorded): the engine removes it, and only if it is one of its own.
+        if (existsSync(dir))
+            try {
+                discardDraftDirectory(dir);
+            }
+            catch {
+                // not removable (no marker, a symlink): left alone, never forced
+            }
+        return;
+    }
+    live.setFrozen(true);
+    const slot = {
+        id: row.id,
+        name: row.name,
+        dir,
+        host: null,
+        problem: null,
+    };
+    slotRef = slot;
+    if (!existsSync(join(dir, 'app.db'))) {
+        slot.problem = 'the draft copy is missing from the data folder';
+        return;
+    }
+    try {
+        slot.host = await openDraftHost(db, slot.id, dir);
+        wireHostEvents(slot.host, 'draft');
+    }
+    catch (e) {
+        slot.problem = `the draft cannot be opened: ${e instanceof Error ? e.message : String(e)}`;
+    }
+}
+/** The LIVE host, opened on first use. It is never the draft. */
 export function getHost() {
     hostPromise ??= (async () => {
         const db = await getShellDb();
-        const dir = join(await dataRoot(), 'user-app');
+        const root = await dataRoot();
+        const dir = join(root, 'user-app');
         mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const store = new ShellVersionStore(db);
         const host = await AppHost.open(dir, {
-            store: new ShellVersionStore(db),
+            store,
             workerUrl: workerUrl(),
         });
-        host.on('changed', (e) => publish({ type: 'changed', version: e.version, summary: e.summary }));
-        host.on('records', (e) => publish({ type: 'records', model: e.model }));
+        wireHostEvents(host, 'live');
+        try {
+            await adoptDraft(db, host, root);
+        }
+        catch (e) {
+            // Never serve live thawed when we could not tell whether a draft is
+            // open: fail the open; the next call retries.
+            slotRef = null;
+            await host.close().catch(() => { });
+            throw e;
+        }
+        storeRef = store;
         hostRef = host;
         if (!shutdownHooked) {
             shutdownHooked = true;
@@ -77,14 +187,48 @@ export function getHost() {
     });
     return hostPromise;
 }
-/** The host if it is already open (sync, for list_changed wiring). */
+/** The live host's version store (a publish names its draft on it). */
+export async function getLiveStore() {
+    await getHost();
+    return storeRef;
+}
+/** The live host if it is already open (sync, for list_changed wiring). */
 export function openHost() {
     return hostRef;
 }
+/** The open draft (live is open too), or null when there is none. */
+export async function getDraftSlot() {
+    await getHost();
+    return slotRef;
+}
+/** drafts.ts only: record the draft that just opened, or null once it is gone. */
+export function setDraftSlot(slot) {
+    slotRef = slot;
+}
+/**
+ * The host for a copy the REQUEST named. `live` is always the live host;
+ * `draft` is the draft host or a clear refusal, never live.
+ */
+export async function hostFor(target) {
+    const live = await getHost();
+    if (target === 'live')
+        return live;
+    const slot = slotRef;
+    if (!slot)
+        throw new EngineError('there is no draft open; start a draft first (or use the live app)', 'not_found');
+    if (!slot.host)
+        throw new EngineError(`the draft "${slot.name}" cannot be used: ${slot.problem ?? 'it is not open'}. Discard it to carry on.`, 'refused');
+    return slot.host;
+}
 export async function closeHost() {
     const pending = hostPromise;
+    const slot = slotRef;
     hostPromise = null;
     hostRef = null;
+    storeRef = null;
+    slotRef = null;
+    if (slot?.host)
+        await slot.host.close().catch(() => { });
     if (pending)
         await (await pending.catch(() => null))?.close();
 }

package/dist/lib/server/results.d.ts

@@ -0,0 +1,6 @@
+import type { ExecuteResult } from '../../engine/index.ts';
+type PublicResult<T> = T extends unknown ? Omit<T, 'snapshot'> : never;
+export type PublicExecuteResult = PublicResult<ExecuteResult>;
+/** Snapshot files are engine recovery state, never part of a browser response. */
+export declare function publicChangeResult<T>(value: T): PublicResult<T>;
+export {};

package/dist/lib/server/results.js

@@ -0,0 +1,8 @@
+/** Snapshot files are engine recovery state, never part of a browser response. */
+export function publicChangeResult(value) {
+    if (value && typeof value === 'object' && 'snapshot' in value) {
+        const { snapshot: _snapshot, ...shown } = value;
+        return shown;
+    }
+    return value;
+}

package/dist/lib/server/target.d.ts

@@ -0,0 +1,24 @@
+export declare const TARGETS: readonly ["live", "draft"];
+export type Target = (typeof TARGETS)[number];
+export declare function isTarget(value: unknown): value is Target;
+export interface CallScope {
+    /** Copy for record operations: app tools, app REST, record routes. */
+    records: Target;
+    /** Copy for builder operations: define/add/remove/undo/describe/history. */
+    structure: Target;
+}
+export declare const LIVE_SCOPE: Readonly<CallScope>;
+/** Both halves on one copy. */
+export declare function scopeFor(target: Target): CallScope;
+/**
+ * A request's target value: absent means `live`; anything but `live` or
+ * `draft` is a 400, never a silent fallback to some other copy.
+ */
+export declare function parseTarget(value: unknown): Target;
+/** Which scope one /mcp URL asks for: `?target=live|draft`, `?scope=assistant`, or none (live). */
+export type McpScopeKey = Target | 'assistant';
+export declare function mcpScopeKey(params: URLSearchParams): McpScopeKey;
+/** Run `fn` with `scope` for the App model's builder methods. */
+export declare function withScope<T>(scope: CallScope, fn: () => Promise<T>): Promise<T>;
+/** The scope entered by the request entry, or all-live. */
+export declare function currentScope(): CallScope;

package/dist/lib/server/target.js

@@ -0,0 +1,64 @@
+// Which copy of the app a request is about: `live` or `draft`.
+//
+// There is NO ambient "current host". Every entry (a REST route, an MCP
+// request, an assistant tool call) reads the copy from the request itself,
+// builds a {@link CallScope} and passes it down. The default is `live`, the
+// strict side: the approval gate is on, and while a draft is open its
+// structure is frozen. Only `hostFor('draft')` can reach the draft host, and
+// only a request that said `draft` gets there.
+//
+// A scope has two halves because the person may look at the live records while
+// the assistant builds in the draft: `records` is the copy for record
+// operations (app tools, app REST, reports, record routes), `structure` the
+// copy for builder operations (define, add, remove, undo, describe, history).
+//
+// The one piece of async-scoped state is the scope handed to the App model's
+// builder methods (they are static methods with fixed signatures that smrt
+// generates REST and MCP from). It is entered only by `withScope`, at the
+// request entries, and reads as `live` when nothing entered it.
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { EngineError } from "../../engine/index.js";
+export const TARGETS = ['live', 'draft'];
+export function isTarget(value) {
+    return value === 'live' || value === 'draft';
+}
+export const LIVE_SCOPE = Object.freeze({
+    records: 'live',
+    structure: 'live',
+});
+/** Both halves on one copy. */
+export function scopeFor(target) {
+    return { records: target, structure: target };
+}
+/**
+ * A request's target value: absent means `live`; anything but `live` or
+ * `draft` is a 400, never a silent fallback to some other copy.
+ */
+export function parseTarget(value) {
+    if (value === undefined || value === null || value === '')
+        return 'live';
+    if (isTarget(value))
+        return value;
+    throw new EngineError("target must be 'live' or 'draft'", 'invalid');
+}
+export function mcpScopeKey(params) {
+    const scope = params.get('scope');
+    const target = params.get('target');
+    if (scope !== null && target !== null)
+        throw new EngineError('send either scope or target, not both', 'invalid');
+    if (scope !== null) {
+        if (scope !== 'assistant')
+            throw new EngineError("scope must be 'assistant'", 'invalid');
+        return 'assistant';
+    }
+    return parseTarget(target);
+}
+const scopeStore = new AsyncLocalStorage();
+/** Run `fn` with `scope` for the App model's builder methods. */
+export function withScope(scope, fn) {
+    return scopeStore.run({ ...scope }, fn);
+}
+/** The scope entered by the request entry, or all-live. */
+export function currentScope() {
+    return scopeStore.getStore() ?? LIVE_SCOPE;
+}

package/dist/lib/server/version-store.d.ts

@@ -2,14 +2,53 @@ import type { DatabaseInterface } from '@happyvertical/sql';
 import type { VersionRecord, VersionStore } from '../../engine/index.ts';
 import { type App } from '../objects/App.ts';
 export declare const APP_SLUG = "app";
+/**
+ * Set on the live store for the duration of one publish: the draft whose
+ * `published` mark rides in `commit`'s transaction.
+ */
+export interface PublishMark {
+    draftId: string;
+}
 export declare class ShellVersionStore implements VersionStore {
     private readonly db;
+    /** The draft the next `commit` publishes (see {@link PublishMark}); drafts.ts sets and clears it. */
+    publishing: PublishMark | null;
     constructor(db: DatabaseInterface);
     private versions;
     private apps;
     private row;
     /** The singleton App row, created on first use. */
-    appRow(): Promise<App>;
+    appRow(db?: DatabaseInterface): Promise<App>;
+    current(): Promise<number | null>;
+    private point;
+    setCurrent(version: number): Promise<void>;
+    get(version: number): Promise<VersionRecord | null>;
+    list(): Promise<VersionRecord[]>;
+    private insert;
+    append(record: VersionRecord): Promise<void>;
+    /**
+     * Append `records` and point at `current` in ONE transaction. Any failure
+     * (a version that already exists, a missing target, a write error) rolls all
+     * of it back, so a publish that fails here leaves no orphan versions and the
+     * pointer where it was. When a publish names its draft ({@link publishing}),
+     * the draft's `published` mark is in the same transaction.
+     */
+    commit(records: VersionRecord[], current: number): Promise<void>;
+    markPurged(version: number): Promise<void>;
+    maxVersion(): Promise<number>;
+}
+/**
+ * One draft's versions. The draft host only ever reads and appends; its own
+ * pointer is the `AppDraft` row's `currentVersion`. The row must exist before
+ * the host starts.
+ */
+export declare class DraftVersionStore implements VersionStore {
+    private readonly db;
+    readonly draftId: string;
+    constructor(db: DatabaseInterface, draftId: string);
+    private versions;
+    private draftRow;
+    private row;
     current(): Promise<number | null>;
     setCurrent(version: number): Promise<void>;
     get(version: number): Promise<VersionRecord | null>;

package/dist/lib/server/version-store.js

@@ -1,4 +1,6 @@
 import { AppCollection } from "../objects/App.js";
+import { AppDraftCollection } from "../objects/AppDraft.js";
+import { AppDraftVersionCollection, } from "../objects/AppDraftVersion.js";
 import { AppVersionCollection, } from "../objects/AppVersion.js";
 export const APP_SLUG = 'app';
 function toRecord(row) {
@@ -20,27 +22,55 @@ function toRecord(row) {
             : String(row.createdAt),
     };
 }
+/** The columns every version row shares, from an engine record. */
+function columnsOf(record) {
+    return {
+        version: record.version,
+        parent: record.parent ?? -1,
+        author: record.author,
+        summary: record.summary,
+        definition: JSON.stringify(record.definition),
+        migration: record.migration ? JSON.stringify(record.migration) : '',
+        createdAt: record.createdAt,
+        purged: !!record.migration?.purged,
+    };
+}
+/** Mark a row's migration purged (shared by both stores). */
+async function markRowPurged(row) {
+    if (!row)
+        return;
+    row.purged = true;
+    if (row.migration) {
+        row.migration = JSON.stringify({
+            ...JSON.parse(row.migration),
+            purged: true,
+        });
+    }
+    await row.save();
+}
 export class ShellVersionStore {
     db;
+    /** The draft the next `commit` publishes (see {@link PublishMark}); drafts.ts sets and clears it. */
+    publishing = null;
     constructor(db) {
         this.db = db;
     }
-    versions() {
-        return AppVersionCollection.create({ db: this.db });
+    versions(db = this.db) {
+        return AppVersionCollection.create({ db });
     }
-    apps() {
-        return AppCollection.create({ db: this.db });
+    apps(db = this.db) {
+        return AppCollection.create({ db });
     }
-    async row(version) {
-        const rows = await (await this.versions()).list({
+    async row(version, db = this.db) {
+        const rows = await (await this.versions(db)).list({
             where: { version },
             limit: 1,
         });
         return rows[0] ?? null;
     }
     /** The singleton App row, created on first use. */
-    async appRow() {
-        const apps = await this.apps();
+    async appRow(db = this.db) {
+        const apps = await this.apps(db);
         const rows = await apps.list({ where: { slug: APP_SLUG }, limit: 1 });
         if (rows[0])
             return rows[0];
@@ -57,11 +87,11 @@ export class ShellVersionStore {
         const v = Number((await this.appRow()).currentVersion);
         return v < 0 ? null : v;
     }
-    async setCurrent(version) {
-        const rec = await this.row(version);
+    async point(version, db) {
+        const rec = await this.row(version, db);
         if (!rec)
             throw new Error(`version ${version} is not stored`);
-        const app = await this.appRow();
+        const app = await this.appRow(db);
         app.currentVersion = version;
         app.definition = rec.definition;
         try {
@@ -72,6 +102,9 @@ export class ShellVersionStore {
         }
         await app.save();
     }
+    async setCurrent(version) {
+        await this.point(version, this.db);
+    }
     async get(version) {
         const row = await this.row(version);
         return row ? toRecord(row) : null;
@@ -80,36 +113,115 @@ export class ShellVersionStore {
         const rows = await (await this.versions()).list({ limit: 100000 });
         return rows.map(toRecord).sort((a, b) => a.version - b.version);
     }
+    async insert(record, db) {
+        if (await this.row(record.version, db))
+            throw new Error(`version ${record.version} already exists`);
+        const created = await (await this.versions(db)).create(columnsOf(record));
+        await created.save();
+    }
+    async append(record) {
+        await this.insert(record, this.db);
+    }
+    /**
+     * Append `records` and point at `current` in ONE transaction. Any failure
+     * (a version that already exists, a missing target, a write error) rolls all
+     * of it back, so a publish that fails here leaves no orphan versions and the
+     * pointer where it was. When a publish names its draft ({@link publishing}),
+     * the draft's `published` mark is in the same transaction.
+     */
+    async commit(records, current) {
+        const db = this.db;
+        if (typeof db.transaction !== 'function')
+            throw new Error('the shell database cannot run transactions');
+        const mark = this.publishing;
+        await db.transaction(async (tx) => {
+            const txDb = tx;
+            for (const r of records)
+                await this.insert(r, txDb);
+            await this.point(current, txDb);
+            if (mark) {
+                const draft = await (await AppDraftCollection.create({ db: txDb })).get(mark.draftId);
+                if (draft?.status !== 'open')
+                    throw new Error('the draft is no longer open');
+                draft.status = 'published';
+                draft.endedAt = new Date().toISOString();
+                draft.publishedVersions = JSON.stringify(records.map((r) => r.version));
+                await draft.save();
+            }
+        });
+    }
+    async markPurged(version) {
+        await markRowPurged(await this.row(version));
+    }
+    async maxVersion() {
+        const rows = await (await this.versions()).list({ limit: 100000 });
+        return rows.length ? Math.max(...rows.map((r) => Number(r.version))) : -1;
+    }
+}
+/**
+ * One draft's versions. The draft host only ever reads and appends; its own
+ * pointer is the `AppDraft` row's `currentVersion`. The row must exist before
+ * the host starts.
+ */
+export class DraftVersionStore {
+    db;
+    draftId;
+    constructor(db, draftId) {
+        this.db = db;
+        this.draftId = draftId;
+    }
+    versions() {
+        return AppDraftVersionCollection.create({ db: this.db });
+    }
+    async draftRow() {
+        const row = await (await AppDraftCollection.create({ db: this.db })).get(this.draftId);
+        if (!row)
+            throw new Error('the draft is not stored');
+        return row;
+    }
+    async row(version) {
+        const rows = await (await this.versions()).list({
+            where: { draftId: this.draftId, version },
+            limit: 1,
+        });
+        return rows[0] ?? null;
+    }
+    async current() {
+        const v = Number((await this.draftRow()).currentVersion);
+        return v < 0 ? null : v;
+    }
+    async setCurrent(version) {
+        if (!(await this.row(version)))
+            throw new Error(`version ${version} is not stored`);
+        const draft = await this.draftRow();
+        draft.currentVersion = version;
+        await draft.save();
+    }
+    async get(version) {
+        const row = await this.row(version);
+        return row ? toRecord(row) : null;
+    }
+    async list() {
+        const rows = await (await this.versions()).list({
+            where: { draftId: this.draftId },
+            limit: 100000,
+        });
+        return rows.map(toRecord).sort((a, b) => a.version - b.version);
+    }
     async append(record) {
         if (await this.row(record.version))
             throw new Error(`version ${record.version} already exists`);
         const created = await (await this.versions()).create({
-            version: record.version,
-            parent: record.parent ?? -1,
-            author: record.author,
-            summary: record.summary,
-            definition: JSON.stringify(record.definition),
-            migration: record.migration ? JSON.stringify(record.migration) : '',
-            createdAt: record.createdAt,
-            purged: !!record.migration?.purged,
+            draftId: this.draftId,
+            ...columnsOf(record),
         });
         await created.save();
     }
     async markPurged(version) {
-        const row = await this.row(version);
-        if (!row)
-            return;
-        row.purged = true;
-        if (row.migration) {
-            row.migration = JSON.stringify({
-                ...JSON.parse(row.migration),
-                purged: true,
-            });
-        }
-        await row.save();
+        await markRowPurged(await this.row(version));
     }
     async maxVersion() {
-        const rows = await (await this.versions()).list({ limit: 100000 });
-        return rows.length ? Math.max(...rows.map((r) => Number(r.version))) : -1;
+        const rows = await this.list();
+        return rows.length ? Math.max(...rows.map((r) => r.version)) : -1;
     }
 }