@happyvertical/smrt-planner 0.0.0-stage → 0.0.2

package/dist/planner/commands/adapter.js

@@ -0,0 +1,597 @@
+import { canonical, createCookbookEngine, isEmptyCookbook, } from '@happyvertical/smrt-core/cookbook/engine';
+import { checkSchema, toolsFor } from "./schemas.js";
+import { PLANNER_TAB_IDS, } from "./types.js";
+/** A plain cell. */
+export function cell(initial) {
+    let value = initial;
+    return {
+        get: () => value,
+        set: (next) => {
+            value = next;
+        },
+    };
+}
+const err = (code, message, extra = {}) => ({ code, message, ...extra });
+const fail = (error, id) => ({
+    ok: false,
+    ...(id !== undefined ? { id } : {}),
+    error,
+});
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const REPLACING = new Set(['apply_cookbook', 'import_cookbook']);
+const message = (cause) => cause instanceof Error ? cause.message : String(cause);
+/** The document without `overviews`: page edits are not plan changes. */
+function signature(doc, applied) {
+    if (!isObject(doc))
+        return JSON.stringify([applied, doc ?? null]);
+    const { overviews: _overviews, ...rest } = doc;
+    return JSON.stringify([applied, rest]);
+}
+export function createPlannerAdapter(config) {
+    const { catalog, port, options = {}, env = {} } = config;
+    const section = env.section ?? cell(null);
+    const tab = env.tab ?? cell(null);
+    const tools = toolsFor(catalog);
+    const schemaOf = (name) => tools.find((tool) => tool.name === name)?.inputSchema;
+    const focusSchema = schemaOf('focus');
+    const undoSchema = schemaOf('undo');
+    let engine;
+    let lastKey = '';
+    /** Why the app's document could not be adopted; commands fail until it can. */
+    let syncError = null;
+    /** Undo ids the outside has seen, by the engine's own id; closed on a new epoch. */
+    let outward = new Map();
+    let inward = new Map();
+    let undoCounter = 0;
+    const listeners = new Map();
+    const resolvedApplied = () => port?.applied?.() ?? null;
+    const currentTab = () => options.navigation?.getTab() ?? tab.get();
+    function start() {
+        if (!port?.read) {
+            // Headless: the given document is the plan, and a bad one is the caller's error.
+            engine = createCookbookEngine(config.cookbook === undefined
+                ? { catalog }
+                : {
+                    catalog,
+                    state: {
+                        version: 1,
+                        revision: 0,
+                        applied: null,
+                        cookbook: config.cookbook,
+                        journal: [],
+                    },
+                });
+            return;
+        }
+        const given = port.read();
+        lastKey = signature(given, resolvedApplied());
+        try {
+            engine = createCookbookEngine({
+                catalog,
+                state: {
+                    version: 1,
+                    revision: 0,
+                    applied: resolvedApplied(),
+                    cookbook: given,
+                    journal: [],
+                },
+            });
+        }
+        catch (cause) {
+            // The app's document is not one the engine accepts: start empty, say so.
+            engine = createCookbookEngine({ catalog });
+            syncError = message(cause);
+        }
+    }
+    start();
+    /** The app edited the document by hand: a new epoch, one revision on. */
+    function adoptManualEdit(doc, key) {
+        const state = engine.state();
+        try {
+            engine = createCookbookEngine({
+                catalog,
+                state: {
+                    version: 1,
+                    revision: state.revision + 1,
+                    applied: resolvedApplied(),
+                    cookbook: doc,
+                    journal: state.journal,
+                },
+            });
+            syncError = null;
+        }
+        catch (cause) {
+            // Keep the engine as it was; commands answer `failed` until the document is valid.
+            syncError = message(cause);
+        }
+        outward = new Map();
+        inward = new Map();
+        lastKey = key;
+    }
+    /** Compare the app's document with the engine's; adopt a difference. Never throws. */
+    function sync() {
+        if (!port?.read)
+            return;
+        try {
+            const doc = port.read();
+            const key = signature(doc, resolvedApplied());
+            if (key === lastKey)
+                return;
+            adoptManualEdit(doc, key);
+        }
+        catch (cause) {
+            syncError = message(cause);
+        }
+    }
+    const syncFailureError = () => err('failed', `The app's document is not one the planner can read (${syncError}). Fix it or reset the cookbook, then try again.`);
+    const syncFailure = (id) => fail(syncFailureError(), id);
+    function undoIdOut(inner) {
+        if (!inner)
+            return undefined;
+        let id = outward.get(inner);
+        if (!id) {
+            id = `undo-${++undoCounter}`;
+            outward.set(inner, id);
+            inward.set(id, inner);
+        }
+        return id;
+    }
+    /** Forget undo ids the engine no longer holds (used or past its cap). */
+    function pruneUndoIds(live) {
+        const keep = new Set(live);
+        for (const [inner, id] of outward) {
+            if (keep.has(inner))
+                continue;
+            outward.delete(inner);
+            inward.delete(id);
+        }
+    }
+    const withView = (base) => ({
+        ...base,
+        undo: base.undo.map((id) => undoIdOut(id)),
+        focus: { tab: currentTab(), section: section.get() },
+    });
+    function build() {
+        const base = engine.snapshot();
+        pruneUndoIds(base.undo);
+        return withView(base);
+    }
+    /** The engine's document with the app's live page customisations. */
+    function liveDocument(doc) {
+        if (!port?.read)
+            return doc;
+        try {
+            const live = port.read();
+            const overviews = isObject(live) ? live.overviews : undefined;
+            const { overviews: _stale, ...rest } = doc;
+            return canonical((isObject(overviews) && Object.keys(overviews).length
+                ? { ...rest, overviews }
+                : rest));
+        }
+        catch {
+            return doc;
+        }
+    }
+    function decorate(result) {
+        if (!result.ok)
+            return result;
+        const { receipt } = result;
+        // A replay answers an earlier epoch's change: its undo id may now name another.
+        const undoId = result.replayed ? undefined : undoIdOut(receipt.undoId);
+        const { undoId: _drop, ...rest } = receipt;
+        let data = result.data;
+        if (receipt.name === 'export_cookbook' &&
+            isObject(data) &&
+            !result.replayed) {
+            const cookbook = liveDocument(data.cookbook);
+            data = {
+                ...data,
+                cookbook,
+                text: `${JSON.stringify(cookbook, null, 2)}\n`,
+            };
+        }
+        return {
+            ...result,
+            ...(data !== undefined ? { data } : {}),
+            snapshot: build(),
+            receipt: { ...rest, ...(undoId ? { undoId } : {}) },
+        };
+    }
+    /** Hand the engine's document to the app after a change. */
+    function commit(commands, appliedBefore) {
+        if (!port?.write)
+            return;
+        const applied = engine.snapshot().app.cookbook;
+        const libraryApplied = commands.includes('apply_cookbook') ||
+            (applied !== null && applied !== appliedBefore);
+        port.write(engine.cookbook(), {
+            commands,
+            replaced: commands.some((name) => REPLACING.has(name)),
+            applied,
+            libraryApplied,
+        });
+        if (port.read)
+            lastKey = signature(port.read(), resolvedApplied());
+        if (libraryApplied)
+            options.onReplaced?.();
+    }
+    function deliver() {
+        if (!listeners.size)
+            return;
+        sync();
+        const current = build();
+        const full = JSON.stringify(current);
+        for (const [listener, last] of listeners) {
+            if (last === full)
+                continue;
+            listeners.set(listener, full);
+            listener(current);
+        }
+    }
+    /** `id`, `expectedRevision` and stray keys, checked as the engine checks them. */
+    function checkEnvelope(raw, runOptions) {
+        for (const key of Object.keys(raw)) {
+            if (!['name', 'input', 'id', 'expectedRevision'].includes(key)) {
+                return err('invalid_input', `${key} is not part of a command.`, {
+                    path: key,
+                });
+            }
+        }
+        const { id } = raw;
+        if (id !== undefined &&
+            !(typeof id === 'string' && id.length > 0 && id.length <= 200)) {
+            return err('invalid_input', 'id must be a non-empty string of at most 200 characters.', { path: 'id' });
+        }
+        const expected = raw.expectedRevision ?? runOptions.expectedRevision;
+        if (expected !== undefined &&
+            !(Number.isInteger(expected) && expected >= 0)) {
+            return err('invalid_input', 'expectedRevision must be a whole number.', {
+                path: 'expectedRevision',
+            });
+        }
+        return null;
+    }
+    function runFocus(raw, runOptions) {
+        const bad = checkEnvelope(raw, runOptions);
+        const id = typeof raw.id === 'string' ? raw.id : undefined;
+        if (bad)
+            return fail(bad, id);
+        const expected = raw.expectedRevision ?? runOptions.expectedRevision;
+        const input = (raw.input ?? {});
+        const problem = checkSchema(focusSchema, input);
+        if (problem)
+            return fail(err('invalid_input', problem, { path: 'input' }), id);
+        const revision = engine.snapshot().revision;
+        if (expected !== undefined && expected !== revision) {
+            return fail(err('conflict', `The plan is at revision ${revision}, not ${expected}. Read the snapshot and try again.`, {
+                details: { expectedRevision: expected, currentRevision: revision },
+            }), id);
+        }
+        if (input.section !== undefined) {
+            const known = build().sections.some((s) => s.id === input.section);
+            if (!known) {
+                return fail(err('not_found', `No menu section "${input.section}".`, {
+                    path: 'input.section',
+                }), id);
+            }
+        }
+        let changed = false;
+        if (input.tab && PLANNER_TAB_IDS.includes(input.tab)) {
+            changed ||= currentTab() !== input.tab;
+            tab.set(input.tab);
+            options.navigation?.setTab(input.tab);
+        }
+        if (input.section !== undefined) {
+            changed ||= section.get() !== input.section;
+            section.set(input.section);
+            options.navigation?.setSection?.(input.section);
+        }
+        const result = {
+            ok: true,
+            ...(id !== undefined ? { id } : {}),
+            snapshot: build(),
+            receipt: {
+                name: 'focus',
+                ...(id !== undefined ? { id } : {}),
+                summary: '',
+                changed,
+                revisionBefore: revision,
+                revisionAfter: revision,
+            },
+        };
+        deliver();
+        return result;
+    }
+    /** The planner's strict import check, before the engine's. */
+    function prepareImport(raw) {
+        const input = raw.input;
+        if (!port?.prepareImport || !isObject(input))
+            return { raw };
+        const checked = port.prepareImport(input.document);
+        if (!checked.ok) {
+            return fail(err('invalid_input', checked.error, { path: 'input.document' }), raw.id);
+        }
+        return {
+            raw: { ...raw, input: { ...input, document: checked.cookbook } },
+            dropped: checked.dropped,
+        };
+    }
+    /**
+     * Replacing a whole app needs `replace: true` unless the app holds nothing.
+     * The engine checks its own copy, which can lack page customisations the app
+     * has (they are edited outside the plan). Before such a command, if the app
+     * holds something the engine's copy does not, adopt the app's document (same
+     * revision) so the engine's own refusal, in its own order of checks, is right.
+     */
+    function alignForReplace(names) {
+        if (!port?.read ||
+            !names.some((n) => typeof n === 'string' && REPLACING.has(n))) {
+            return;
+        }
+        try {
+            const app = port.read();
+            if (isEmptyCookbook(engine.cookbook()) &&
+                !isEmptyCookbook(app)) {
+                const state = engine.state();
+                engine = createCookbookEngine({
+                    catalog,
+                    state: {
+                        version: 1,
+                        revision: state.revision,
+                        applied: resolvedApplied(),
+                        cookbook: app,
+                        journal: state.journal,
+                    },
+                });
+                outward = new Map();
+                inward = new Map();
+                lastKey = signature(app, resolvedApplied());
+            }
+        }
+        catch (cause) {
+            syncError = message(cause);
+        }
+    }
+    function run(command, runOptions = {}) {
+        try {
+            sync();
+            if (syncError) {
+                return syncFailure(isObject(command) && typeof command.id === 'string'
+                    ? command.id
+                    : undefined);
+            }
+            if (!isObject(command)) {
+                return decorate(engine.run(command, runOptions));
+            }
+            if (command.name === 'focus')
+                return runFocus(command, runOptions);
+            alignForReplace([command.name]);
+            if (syncError) {
+                return syncFailure(typeof command.id === 'string' ? command.id : undefined);
+            }
+            let raw = command;
+            let dropped;
+            if (command.name === 'import_cookbook') {
+                const prepared = prepareImport(command);
+                if ('ok' in prepared)
+                    return prepared;
+                raw = prepared.raw;
+                dropped = prepared.dropped;
+            }
+            const appliedBefore = engine.snapshot().app.cookbook;
+            const keepTheme = themeToKeep(raw);
+            const result = keepTheme
+                ? runKeepingTheme(raw, runOptions, keepTheme)
+                : decorate(engine.run(raw, runOptions));
+            if (!result.ok)
+                return result;
+            if (!result.replayed && result.receipt.changed) {
+                commit([String(raw.name)], appliedBefore);
+            }
+            let finished = result;
+            if (dropped?.length) {
+                finished = {
+                    ...result,
+                    receipt: {
+                        ...result.receipt,
+                        warnings: [
+                            ...(result.receipt.warnings ?? []),
+                            ...dropped.map((note) => `Not imported: ${note}`),
+                        ],
+                    },
+                };
+            }
+            deliver();
+            return finished.ok ? { ...finished, snapshot: build() } : finished;
+        }
+        catch (cause) {
+            return fail(err('failed', message(cause)));
+        }
+    }
+    /**
+     * Applying a library cookbook that sets no theme keeps the person's own look
+     * (as the Cookbooks tab does): the preset, brand colour and colour scheme
+     * (the font is not carried; `set_theme` has no font). Returns the patch.
+     */
+    function themeToKeep(raw) {
+        const input = raw.input;
+        if (raw.name !== 'apply_cookbook' || !isObject(input))
+            return undefined;
+        const book = catalog.cookbooks?.find((c) => c.id === input.id);
+        if (!book || book.document.theme)
+            return undefined;
+        const theme = engine.cookbook().theme;
+        if (!theme)
+            return undefined;
+        const patch = {};
+        if (theme.preset)
+            patch.preset = theme.preset;
+        if (theme.custom?.primary)
+            patch.primary = theme.custom.primary;
+        if (theme.colorScheme)
+            patch.colorScheme = theme.colorScheme;
+        return Object.keys(patch).length ? patch : undefined;
+    }
+    function runKeepingTheme(raw, runOptions, patch) {
+        const batch = engine.batch({
+            ...(raw.id !== undefined ? { id: raw.id } : {}),
+            expectedRevision: raw.expectedRevision ?? runOptions.expectedRevision,
+            commands: [raw, { name: 'set_theme', input: patch }].map(({ id: _id, expectedRevision: _rev, ...command }) => command),
+        });
+        if (!batch.ok) {
+            const cause = batch.error.details?.cause;
+            return fail(batch.error.code === 'batch_failed' && cause ? cause : batch.error, raw.id);
+        }
+        const first = batch.results[0];
+        const undoId = batch.replayed ? undefined : undoIdOut(batch.receipt.undoId);
+        return {
+            ...first,
+            ...(batch.id !== undefined ? { id: batch.id } : {}),
+            ...(batch.replayed ? { replayed: true } : {}),
+            snapshot: build(),
+            receipt: {
+                ...first.receipt,
+                ...(batch.id !== undefined ? { id: batch.id } : {}),
+                revisionBefore: batch.receipt.revisionBefore,
+                revisionAfter: batch.receipt.revisionAfter,
+                changed: batch.receipt.changed,
+                ...(undoId ? { undoId } : {}),
+            },
+        };
+    }
+    function batch(input) {
+        try {
+            sync();
+            if (syncError) {
+                return {
+                    ok: false,
+                    error: syncFailureError(),
+                    snapshot: build(),
+                };
+            }
+            const commands = isObject(input) && Array.isArray(input.commands) ? input.commands : [];
+            alignForReplace(commands.map((c) => (isObject(c) ? c.name : undefined)));
+            if (syncError) {
+                return { ok: false, error: syncFailureError(), snapshot: build() };
+            }
+            const appliedBefore = engine.snapshot().app.cookbook;
+            const result = engine.batch(input);
+            if (!result.ok) {
+                return { ...result, snapshot: build() };
+            }
+            if (!result.replayed && result.receipt.changed) {
+                commit(commands.map((c) => String(c?.name)), appliedBefore);
+            }
+            const undoId = result.replayed
+                ? undefined
+                : undoIdOut(result.receipt.undoId);
+            const { undoId: _drop, ...receipt } = result.receipt;
+            const current = build();
+            const out = {
+                ...result,
+                snapshot: current,
+                receipt: { ...receipt, ...(undoId ? { undoId } : {}) },
+                results: result.results.map((item) => ({
+                    ...item,
+                    snapshot: result.replayed ? current : withView(item.snapshot),
+                })),
+            };
+            deliver();
+            return out;
+        }
+        catch (cause) {
+            return {
+                ok: false,
+                error: err('failed', message(cause)),
+                snapshot: build(),
+            };
+        }
+    }
+    function untranslate(raw) {
+        if (!isObject(raw) || raw.name !== 'undo' || !isObject(raw.input))
+            return raw;
+        const id = raw.input.undoId;
+        if (typeof id !== 'string')
+            return raw;
+        return { ...raw, input: { ...raw.input, undoId: inward.get(id) ?? '' } };
+    }
+    /** The engine's refusal names its own undo id; say the one the caller sent. */
+    function reword(result, given) {
+        if (result.ok || result.error.code !== 'not_found')
+            return result;
+        const inner = inward.get(given);
+        return inner
+            ? {
+                ...result,
+                error: {
+                    ...result.error,
+                    message: result.error.message.replace(`"${inner}"`, `"${given}"`),
+                },
+            }
+            : result;
+    }
+    const runWithUndo = (command, runOptions) => {
+        // An undo id from an earlier epoch (or never issued) names nothing.
+        if (isObject(command) &&
+            command.name === 'undo' &&
+            isObject(command.input)) {
+            const given = command.input.undoId;
+            if (typeof given === 'string' &&
+                checkSchema(undoSchema, command.input) === null) {
+                sync();
+                build();
+                if (!inward.has(given)) {
+                    return fail(err('not_found', `Nothing to undo for "${given}".`, {
+                        path: 'input.undoId',
+                    }), command.id);
+                }
+                return reword(run(untranslate(command), runOptions), given);
+            }
+        }
+        return run(untranslate(command), runOptions);
+    };
+    return {
+        run: runWithUndo,
+        batch,
+        snapshot() {
+            sync();
+            return build();
+        },
+        cookbook() {
+            sync();
+            return liveDocument(engine.cookbook());
+        },
+        undo() {
+            sync();
+            const last = build().undo.at(-1);
+            if (!last) {
+                return fail(err('not_found', 'Nothing to undo.'));
+            }
+            return runWithUndo({ name: 'undo', input: { undoId: last } });
+        },
+        state: () => engine.state(),
+        get tools() {
+            return tools;
+        },
+        get batchTool() {
+            return engine.batchTool;
+        },
+        observe() {
+            sync();
+            return JSON.stringify(build());
+        },
+        deliver,
+        subscribe(listener) {
+            env.watch?.start();
+            sync();
+            const current = build();
+            listeners.set(listener, JSON.stringify(current));
+            listener(current);
+            return () => {
+                listeners.delete(listener);
+                if (!listeners.size)
+                    env.watch?.stop();
+            };
+        },
+    };
+}

package/dist/planner/commands/catalog.d.ts

@@ -0,0 +1,19 @@
+import type { EngineCatalog } from '@happyvertical/smrt-core/cookbook/engine';
+/**
+ * The planner's own data as the engine's catalog: the recipes (the published
+ * packages' plus the planner-local `forms`), every catalog model, the library
+ * cookbooks, the smrt-ui presets and the currencies. The engine bundles none of
+ * it; a host with a different catalog builds its own `EngineCatalog`.
+ */
+export declare function buildEngineCatalog(): EngineCatalog;
+/** The planner's engine catalog, built once. */
+export declare function engineCatalog(): EngineCatalog;
+/** The catalog narrowed to the given recipe and library cookbook ids. */
+export declare function restrictCatalog(base: EngineCatalog, allowed: {
+    recipes: readonly {
+        id: string;
+    }[];
+    cookbooks: readonly {
+        id: string;
+    }[];
+}): EngineCatalog;

package/dist/planner/commands/catalog.js

@@ -0,0 +1,54 @@
+import { catalog } from "../../catalog/index.js";
+import { libraryCookbooks } from "../../library/index.js";
+import { recipes } from "../../recipes/index.js";
+import { SETTING_TARGETS } from "../../settings/app-settings.js";
+import { CURRENCY_CODES } from "../../settings/currencies.js";
+import { THEME_PRESETS } from "../../theme/theme.js";
+/**
+ * The planner's own data as the engine's catalog: the recipes (the published
+ * packages' plus the planner-local `forms`), every catalog model, the library
+ * cookbooks, the smrt-ui presets and the currencies. The engine bundles none of
+ * it; a host with a different catalog builds its own `EngineCatalog`.
+ */
+export function buildEngineCatalog() {
+    const models = catalog.packages.flatMap((pkg) => pkg.models.map((model) => ({
+        id: model.id,
+        name: model.name,
+        packageId: pkg.id,
+        ...(model.description ? { description: model.description } : {}),
+        exposed: model.exposed,
+        fields: model.fields.map((field) => ({
+            name: field.name,
+            ...(field.system ? { system: true } : {}),
+            ...(field.default !== undefined ? { default: field.default } : {}),
+        })),
+    })));
+    return {
+        recipes,
+        models,
+        cookbooks: libraryCookbooks.map((cookbook) => ({
+            id: cookbook.id,
+            name: cookbook.name,
+            document: cookbook.document,
+        })),
+        themePresets: THEME_PRESETS,
+        currencies: [...CURRENCY_CODES],
+        settingTargets: SETTING_TARGETS,
+    };
+}
+let cached;
+/** The planner's engine catalog, built once. */
+export function engineCatalog() {
+    cached ??= buildEngineCatalog();
+    return cached;
+}
+/** The catalog narrowed to the given recipe and library cookbook ids. */
+export function restrictCatalog(base, allowed) {
+    const recipeIds = new Set(allowed.recipes.map((r) => r.id));
+    const cookbookIds = new Set(allowed.cookbooks.map((c) => c.id));
+    return {
+        ...base,
+        recipes: base.recipes.filter((r) => recipeIds.has(r.id)),
+        cookbooks: (base.cookbooks ?? []).filter((c) => cookbookIds.has(c.id)),
+    };
+}

package/dist/planner/commands/controller.svelte.d.ts

@@ -0,0 +1,13 @@
+import { type CookbookStore } from '../../cookbook/store.svelte.ts';
+import { type PlannerAdapter, type PlannerController, type PlannerControllerOptions, type PlannerPort } from './adapter.ts';
+export type { PlannerController, PlannerControllerOptions, PlannerNavigation, } from './adapter.ts';
+/** The app's stores as the engine's port: where the document is read and written. */
+export declare function portFromStore(store: CookbookStore): PlannerPort;
+/**
+ * The controller for the planner app over `store` (the app's is
+ * `cookbookStore`): smrt's cookbook engine behind the planner's command names,
+ * with the stores as its document and the planner tab and section as `focus`.
+ * Every UI path that changes the app is a command here, and the assistant, the
+ * palette, a host page and the MCP and CLI servers use the same ones.
+ */
+export declare function createPlannerController(store?: CookbookStore, options?: PlannerControllerOptions): PlannerController & Pick<PlannerAdapter, 'cookbook' | 'undo' | 'tools'>;