@happyvertical/smrt-app-shell 0.60.18 → 0.61.0

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

@@ -0,0 +1,100 @@
+import { type AppHost, type PublishPreview, type PublishResult } from '../../engine/index.ts';
+import { type PendingApproval } from './approvals.ts';
+import type { Target } from './target.ts';
+/** What the UI and tools see of the open draft. */
+export interface DraftInfo {
+    id: string;
+    name: string;
+    status: 'open';
+    /** The live version the draft was copied from. */
+    baseVersion: number;
+    /** The draft's current version (null when its copy cannot be opened). */
+    version: number | null;
+    /** Changes made in the draft (its versions after the base). */
+    changes: number;
+    createdAt: string;
+    createdBy: string;
+    /** The live version now. */
+    liveVersion: number;
+    /** Live structure is frozen while a draft is open. */
+    liveFrozen: boolean;
+    /** False when it cannot be published (see `problem`); discard is always offered. */
+    publishable: boolean;
+    problem: string | null;
+    /** What opening the draft's copy found: `rolled-back` = an interrupted publish was undone (publish again). */
+    recovery: 'none' | 'rolled-forward' | 'rolled-back';
+}
+export type DraftPublishResult = Omit<PublishResult, 'snapshot'> & {
+    draft: string;
+};
+/** The open draft, or null. Safe to call for any request. */
+export declare function draftInfo(): Promise<DraftInfo | null>;
+/** Start a draft. Live structure is frozen from here until it is published or discarded. */
+export declare function startDraft(name: unknown, ownerId: string): Promise<DraftInfo>;
+/**
+ * What publishing would do (a rehearsal on a copy of the CURRENT live data;
+ * live is only read). `preview.digest` pins the answer for the publish Approval.
+ */
+export declare function previewDraft(): Promise<{
+    draft: DraftInfo;
+    preview: PublishPreview;
+}>;
+/**
+ * Ask to publish: ALWAYS an Approval, pinned to the digest of a preview taken
+ * now. `expect`, when given, is the digest the person reviewed: a draft that
+ * changed since is refused (review it again), not published.
+ */
+export declare function requestPublish(expect: unknown, requestedBy: string): Promise<PendingApproval>;
+/**
+ * Apply an APPROVED publish. Called only from approvals.ts, which passes the
+ * engine call (it owns the `approved` flag). Refuses if this is not the open
+ * draft any more, or if the draft is not exactly what the approval was pinned
+ * to (the engine compares the digest against the chain as it is now).
+ */
+export declare function publishApproved(action: {
+    draftId: string;
+    digest: string;
+}, engine: (live: AppHost, draft: AppHost, options: {
+    expect: string;
+    draftName: string;
+}) => Promise<PublishResult>): Promise<DraftPublishResult>;
+/** Discard the open draft now: closes it, deletes its copy, thaws live. Owner's direct action. */
+export declare function discardNow(expectId?: string): Promise<{
+    discarded: string;
+}>;
+/** Ask to discard (a tool's way): an Approval. */
+export declare function requestDiscard(requestedBy: string): Promise<PendingApproval>;
+/**
+ * The app as one copy now: `{ mode, draft, frozen, ...describe }`. `mode` is
+ * the copy this describes; `draft` is the open draft (the same object whichever
+ * copy is described, so a view of live can show the draft strip); `frozen` is
+ * whether THIS copy's structure is frozen.
+ */
+export declare function describeCopy(target: Target): Promise<{
+    name: string;
+    version: number;
+    recipes: string[];
+    models: Record<string, import("../../engine/definition.ts").DescribedModel>;
+    mode: "live" | "draft";
+    draft: DraftInfo | null;
+    frozen: boolean;
+}>;
+/**
+ * The versions of one copy. Live: a published draft's versions carry
+ * `publish: { draftId, name }` so History groups them. Draft: the live
+ * version it was copied from (its base) is left out, it is not a change made
+ * there.
+ */
+export declare function historyFor(target: Target): Promise<{
+    publish: {
+        draftId: string;
+        name: string;
+    } | null;
+    version: number;
+    parent: number | null;
+    author: string;
+    summary: string;
+    createdAt: string;
+    purged: boolean;
+    current: boolean;
+}[]>;

package/dist/lib/server/drafts.js

@@ -0,0 +1,324 @@
+// The draft lifecycle: start, describe, preview, publish, discard.
+//
+// One draft at a time. The draft is a second app host over a COPY of the live
+// data (engine: `forkDraft`); live keeps serving records but its structure is
+// FROZEN while the draft is open (frozen again after every restart, in
+// host.ts). Publishing replays the draft's changes onto live and is ALWAYS an
+// Approval pinned to the preview's digest; discarding is a direct owner action
+// from the UI and an Approval when a tool asks. All lifecycle changes run one
+// at a time (`exclusive`), so a start cannot race a publish or a discard.
+import { existsSync, realpathSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { discardDraftDirectory, EngineError, } from "../../engine/index.js";
+import { AppDraftCollection } from "../objects/AppDraft.js";
+import { requestApproval, } from "./approvals.js";
+import { publish } from "./events.js";
+import { DRAFT_DIRNAME, dataRoot, getDraftSlot, getHost, getLiveStore, getShellDb, hostFor, setDraftSlot, wireHostEvents, } from "./host.js";
+import { DraftVersionStore } from "./version-store.js";
+let tail = Promise.resolve();
+/** Run lifecycle work one at a time. */
+function exclusive(fn) {
+    const run = tail.then(fn, fn);
+    tail = run.catch(() => { });
+    return run;
+}
+function clean(name) {
+    const text = typeof name === 'string'
+        ? Array.from(name)
+            .filter((ch) => ch.charCodeAt(0) >= 0x20 && ch !== '\u007f')
+            .join('')
+            .replace(/\s+/g, ' ')
+            .trim()
+        : '';
+    return text ? text.slice(0, 60) : 'Draft';
+}
+function realOf(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return resolve(path);
+    }
+}
+/** Why the open draft cannot be published, or null. */
+function unpublishable(slot, live) {
+    if (!slot.host)
+        return slot.problem ?? 'the draft copy is not open';
+    const marker = slot.host.draft;
+    if (!marker)
+        return 'the draft copy is not marked as a draft';
+    if (realOf(marker.liveDir) !== realOf(live.dataDir))
+        return 'the draft was made from another app or location (the data folder was restored or moved); it cannot be published. Discard it and start again';
+    return null;
+}
+/** The open draft, or null. Safe to call for any request. */
+export async function draftInfo() {
+    const live = await getHost();
+    const slot = await getDraftSlot();
+    if (!slot)
+        return null;
+    const row = await (await AppDraftCollection.create({ db: await getShellDb() })).get(slot.id);
+    let changes = 0;
+    if (slot.host) {
+        try {
+            changes = (await slot.host.draftChain()).versions.length;
+        }
+        catch {
+            changes = 0;
+        }
+    }
+    const problem = unpublishable(slot, live);
+    return {
+        id: slot.id,
+        name: slot.name,
+        status: 'open',
+        baseVersion: Number(row?.baseVersion ?? slot.host?.draft?.baseVersion ?? -1),
+        version: slot.host ? slot.host.version : null,
+        changes,
+        createdAt: String(row?.createdAt ?? ''),
+        createdBy: row?.createdBy ?? '',
+        liveVersion: live.version,
+        liveFrozen: live.frozen,
+        publishable: problem === null,
+        problem,
+        recovery: slot.host?.recovery ?? 'none',
+    };
+}
+/** Start a draft. Live structure is frozen from here until it is published or discarded. */
+export function startDraft(name, ownerId) {
+    return exclusive(async () => {
+        const live = await getHost();
+        const open = await getDraftSlot();
+        if (open)
+            throw new EngineError(`a draft is already open ("${open.name}"); publish or discard it first`, 'refused');
+        const db = await getShellDb();
+        const dir = join(await dataRoot(), DRAFT_DIRNAME);
+        // A leftover copy no row refers to (host.ts removes these at start): the
+        // engine only removes a directory that is one of its own drafts.
+        if (existsSync(dir))
+            discardDraftDirectory(dir);
+        const drafts = await AppDraftCollection.create({ db });
+        const row = await drafts.create({
+            name: clean(name),
+            status: 'starting',
+            createdBy: ownerId,
+            createdAt: new Date().toISOString(),
+        });
+        await row.save();
+        const id = row.id;
+        // Frozen BEFORE the copy: no structural change can land between the row
+        // and the copy (the copy itself runs in the live change queue).
+        live.setFrozen(true);
+        let host = null;
+        try {
+            host = await live.forkDraft(dir, {
+                store: new DraftVersionStore(db, id),
+            });
+            // The draft's store moved the row's pointer: re-read it before updating.
+            const fresh = (await drafts.get(id)) ?? row;
+            fresh.status = 'open';
+            fresh.baseVersion = host.draft?.baseVersion ?? live.version;
+            await fresh.save();
+        }
+        catch (e) {
+            live.setFrozen(false);
+            if (host)
+                await host.discard().catch(() => { });
+            const failed = await drafts.get(id).catch(() => null);
+            if (failed) {
+                failed.status = 'discarded';
+                failed.note = 'the start failed';
+                failed.endedAt = new Date().toISOString();
+                await failed.save().catch(() => { });
+            }
+            throw e;
+        }
+        wireHostEvents(host, 'draft');
+        setDraftSlot({ id, name: row.name, dir, host, problem: null });
+        publish({ type: 'draft', status: 'started', id, name: row.name });
+        return (await draftInfo());
+    });
+}
+async function usableSlot() {
+    const live = await getHost();
+    const slot = await getDraftSlot();
+    if (!slot)
+        throw new EngineError('there is no draft open', 'not_found');
+    const problem = unpublishable(slot, live);
+    if (problem || !slot.host)
+        throw new EngineError(problem ?? 'the draft cannot be used', 'refused');
+    return { slot, host: slot.host, live };
+}
+/**
+ * What publishing would do (a rehearsal on a copy of the CURRENT live data;
+ * live is only read). `preview.digest` pins the answer for the publish Approval.
+ */
+export async function previewDraft() {
+    const { host, live } = await usableSlot();
+    const preview = await live.previewPublish(host);
+    return { draft: (await draftInfo()), preview };
+}
+/**
+ * Ask to publish: ALWAYS an Approval, pinned to the digest of a preview taken
+ * now. `expect`, when given, is the digest the person reviewed: a draft that
+ * changed since is refused (review it again), not published.
+ */
+export async function requestPublish(expect, requestedBy) {
+    if (expect !== undefined && expect !== null && typeof expect !== 'string')
+        throw new EngineError('expect must be the digest of a preview', 'invalid');
+    const { draft, preview } = await previewDraft();
+    if (expect && expect !== preview.digest)
+        throw new EngineError('the draft changed since it was reviewed; review it again', 'refused');
+    const action = {
+        kind: 'publish-draft',
+        draftId: draft.id,
+        draftName: draft.name,
+        digest: preview.digest,
+    };
+    const n = preview.versions.length;
+    return requestApproval(action, {
+        summary: `Publish draft "${draft.name}": ${n} change${n === 1 ? '' : 's'} become live`,
+        risky: true,
+        preview: { draft: draft.name, ...preview },
+    }, requestedBy);
+}
+/**
+ * Apply an APPROVED publish. Called only from approvals.ts, which passes the
+ * engine call (it owns the `approved` flag). Refuses if this is not the open
+ * draft any more, or if the draft is not exactly what the approval was pinned
+ * to (the engine compares the digest against the chain as it is now).
+ */
+export function publishApproved(action, engine) {
+    return exclusive(async () => {
+        const { slot, host, live } = await usableSlot();
+        if (slot.id !== action.draftId)
+            throw new EngineError('this approval was for a draft that is no longer open', 'refused');
+        const store = await getLiveStore();
+        // The draft's `published` mark rides in the store commit's transaction.
+        store.publishing = { draftId: slot.id };
+        let result;
+        try {
+            result = await engine(live, host, {
+                expect: action.digest,
+                draftName: slot.name,
+            });
+        }
+        finally {
+            store.publishing = null;
+        }
+        // Final: live has the versions and the row says `published`.
+        setDraftSlot(null);
+        try {
+            await host.discard();
+        }
+        catch (e) {
+            // biome-ignore lint/suspicious/noConsole: message only; the stray copy is removed at the next start
+            console.error('draft copy not removed after publish:', e instanceof Error ? e.message : 'unknown error');
+        }
+        live.setFrozen(false);
+        publish({
+            type: 'draft',
+            status: 'published',
+            id: slot.id,
+            name: slot.name,
+        });
+        // The retained pre-publish copy's path stays on this machine.
+        const { snapshot: _kept, ...shown } = result;
+        return { ...shown, draft: slot.name };
+    });
+}
+/** Discard the open draft now: closes it, deletes its copy, thaws live. Owner's direct action. */
+export function discardNow(expectId) {
+    return exclusive(async () => {
+        const live = await getHost();
+        const slot = await getDraftSlot();
+        if (!slot)
+            throw new EngineError('there is no draft open', 'not_found');
+        if (expectId && expectId !== slot.id)
+            throw new EngineError('this is not the draft that was asked about', 'refused');
+        if (slot.host)
+            await slot.host.discard();
+        else if (existsSync(slot.dir))
+            discardDraftDirectory(slot.dir);
+        const row = await (await AppDraftCollection.create({ db: await getShellDb() })).get(slot.id);
+        if (row) {
+            row.status = 'discarded';
+            row.note = 'discarded';
+            row.endedAt = new Date().toISOString();
+            await row.save();
+        }
+        setDraftSlot(null);
+        live.setFrozen(false);
+        publish({
+            type: 'draft',
+            status: 'discarded',
+            id: slot.id,
+            name: slot.name,
+        });
+        return { discarded: slot.name };
+    });
+}
+/** Ask to discard (a tool's way): an Approval. */
+export async function requestDiscard(requestedBy) {
+    const draft = await draftInfo();
+    if (!draft)
+        throw new EngineError('there is no draft open', 'not_found');
+    return requestApproval({ kind: 'discard-draft', draftId: draft.id, draftName: draft.name }, {
+        summary: `Discard draft "${draft.name}" and everything built in it`,
+        risky: true,
+        preview: {
+            draft: draft.name,
+            changes: draft.changes,
+            note: 'The draft is thrown away. The live app is not changed.',
+        },
+    }, requestedBy);
+}
+/**
+ * The app as one copy now: `{ mode, draft, frozen, ...describe }`. `mode` is
+ * the copy this describes; `draft` is the open draft (the same object whichever
+ * copy is described, so a view of live can show the draft strip); `frozen` is
+ * whether THIS copy's structure is frozen.
+ */
+export async function describeCopy(target) {
+    const host = await hostFor(target);
+    return {
+        mode: target,
+        draft: await draftInfo(),
+        frozen: host.frozen,
+        ...host.describe(),
+    };
+}
+/**
+ * The versions of one copy. Live: a published draft's versions carry
+ * `publish: { draftId, name }` so History groups them. Draft: the live
+ * version it was copied from (its base) is left out, it is not a change made
+ * there.
+ */
+export async function historyFor(target) {
+    const host = await hostFor(target);
+    const versions = await host.versions();
+    if (target === 'draft') {
+        const base = host.draft?.baseVersion;
+        return versions
+            .filter((v) => v.version !== base)
+            .map((v) => ({ ...v, publish: null }));
+    }
+    const groups = new Map();
+    const drafts = await AppDraftCollection.create({ db: await getShellDb() });
+    for (const d of await drafts.list({
+        where: { status: 'published' },
+        limit: 1000,
+    })) {
+        try {
+            for (const n of JSON.parse(d.publishedVersions || '[]'))
+                groups.set(n, { draftId: d.id, name: d.name });
+        }
+        catch {
+            // an unreadable list just leaves that publish ungrouped
+        }
+    }
+    return versions.map((v) => ({
+        ...v,
+        publish: groups.get(v.version) ?? null,
+    }));
+}

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

@@ -1,15 +1,29 @@
+import type { Target } from './target.ts';
 export type ShellEvent = {
     type: 'changed';
+    target: Target;
     version: number;
     summary: string;
 } | {
     type: 'records';
+    target: Target;
     model: string | null;
 } | {
     type: 'approval';
     id: string;
     status: 'pending' | 'approved' | 'denied' | 'failed';
     summary: string;
+} | {
+    /**
+     * The draft's life changed. `started`: a draft is open (live structure
+     * is now frozen); `published`: its changes are live and it is gone;
+     * `discarded`: it is gone and live thawed; `unpublishable`: it was found
+     * open but cannot be published (see `describe().draft.problem`).
+     */
+    type: 'draft';
+    status: 'started' | 'published' | 'discarded' | 'unpublishable';
+    id: string;
+    name: string;
 };
 export declare function publish(event: ShellEvent): void;
 /** Subscribe; returns the unsubscribe function. */

package/dist/lib/server/events.js

@@ -1,6 +1,9 @@
 // A small in-process event bus for live updates. Host events ('changed',
 // 'records') and approval events are republished here; the SSE route
 // (`/api/events`) and the MCP route (list_changed) subscribe.
+//
+// Every definition/record event says WHICH COPY changed (`target`), so a view
+// of the live app never reloads for a draft's change and the reverse.
 import { EventEmitter } from 'node:events';
 const bus = new EventEmitter();
 bus.setMaxListeners(100);

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

@@ -1,22 +1,64 @@
 import type { DatabaseInterface } from '@happyvertical/sql';
 import { AppHost } from '../../engine/index.ts';
+import type { Target } from './target.ts';
+import { ShellVersionStore } from './version-store.ts';
+/** Where the open draft's copy lives under the data root. */
+export declare const DRAFT_DIRNAME = "user-app-draft";
+/** The open draft as the shell holds it. */
+export interface DraftSlot {
+    id: string;
+    name: string;
+    /** The draft's data directory. */
+    dir: string;
+    /** The draft host; null when it could not be opened (see `problem`). */
+    host: AppHost | null;
+    /** Why `host` is null, or null. */
+    problem: string | null;
+}
 export interface ShellContext {
     /** The shell's database (shell.db: users, App, AppVersion, Approval). */
     db: () => Promise<DatabaseInterface>;
     /** The app-runtime data root. */
     dataRoot: () => Promise<string>;
+    /**
+     * The runtime's secrets master key (created once on the local profile and
+     * kept in its vault key store; `SMRT_SECRET_MASTER_KEY` always wins). Never
+     * logged or sent anywhere.
+     */
+    secretMasterKey?: () => Promise<string | null>;
     /** Override the app worker entry (tests; defaults to the engine's own). */
     workerUrl?: URL | string;
 }
 export declare function configureShell(next: ShellContext): void;
 export declare function getShellDb(): Promise<DatabaseInterface>;
+/** The runtime's secrets master key, or null when it supplies none. */
+export declare function getShellSecretMasterKey(): Promise<string | null>;
 /** The shell database once `getShellDb()` has resolved. For sync thunks. */
 export declare function shellDbSync(): DatabaseInterface;
 export declare function dataRoot(): Promise<string>;
-/** The one AppHost, opened on first use. */
+/** Republish a host's events on the bus, tagged with the copy they came from. */
+export declare function wireHostEvents(host: AppHost, target: Target): void;
+/**
+ * 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 declare function openDraftHost(db: DatabaseInterface, id: string, dir: string): Promise<AppHost>;
+/** The LIVE host, opened on first use. It is never the draft. */
 export declare function getHost(): Promise<AppHost>;
-/** 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 declare function getLiveStore(): Promise<ShellVersionStore>;
+/** The live host if it is already open (sync, for list_changed wiring). */
 export declare function openHost(): AppHost | null;
+/** The open draft (live is open too), or null when there is none. */
+export declare function getDraftSlot(): Promise<DraftSlot | null>;
+/** drafts.ts only: record the draft that just opened, or null once it is gone. */
+export declare function setDraftSlot(slot: DraftSlot | null): void;
+/**
+ * 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 declare function hostFor(target: Target): Promise<AppHost>;
 export declare function closeHost(): Promise<void>;
 /** Tests: forget everything. */
 export declare function resetShell(): Promise<void>;