@happyvertical/smrt-planner 0.0.0-stage → 0.0.2

package/dist/cookbook/store.svelte.js

@@ -0,0 +1,231 @@
+import { isShellLayoutEmpty, } from '@happyvertical/smrt-svelte/workspace/layout';
+import { setSampleTaxRate } from "../data/packs.js";
+import { recipeState } from "../recipes/state.svelte.js";
+import { hasTaxRateRow, readSettings, writeSettings, } from "../settings/app-settings.js";
+import { compactTheme } from "../theme/theme.js";
+import { assembleCookbook } from "./assemble.js";
+import { cookbookFromLegacySearch, hasLegacyState } from "./legacy.js";
+import { BACKUP_KEY, browserStorage, loadCookbook, PREVIOUS_STORAGE_KEY, removeKey, saveCookbook, writeKey, } from "./storage.js";
+import { parseCookbookText } from "./validate.js";
+/** Where the planner's AppShell keeps its own settings (panel states, sizes). */
+export const SHELL_STORAGE_KEY = 'smrt-planner:shell';
+export const SAVE_DELAY_MS = 300;
+/**
+ * The single source of truth for what a visitor has built. Recipes and
+ * options stay in `recipeState` (the one store views read); this adds the
+ * `layout` field and the persistence around both. `snapshot()` is the
+ * Cookbook, whether it is saved, exported or compared.
+ */
+export class CookbookStore {
+    /** The shell layout, owned here and passed to `AppShell`. */
+    layout = $state();
+    /** The app's name and description (`set_name`); not shown in the UI yet. */
+    name = $state();
+    description = $state();
+    /** The app's theme; undefined is the default. The shell applies it live. */
+    theme = $state();
+    /**
+     * Customised overview pages by overview id, canonical overrides only. Each
+     * page's `createOverview` reads its entry and writes edits back here.
+     */
+    overviews = $state.raw({});
+    persist = $state('unknown');
+    /** False until the saved cookbook has been read; nothing saves before. */
+    loaded = $state(false);
+    /** Why the saved cookbook was not used, if it was not. */
+    loadNotice = $state('');
+    /**
+     * True when saving would destroy the only copy of something (an unreadable
+     * value that could not be kept aside, or a saved cookbook a legacy link
+     * replaced without a backup). Nothing is written until the visitor imports
+     * or resets.
+     */
+    saveBlocked = false;
+    /** A migrated legacy link whose data is not safely stored: keep the URL. */
+    keepLegacyUrl = $state(false);
+    /** A cookbook was chosen (cookbook, import) before the saved one was read. */
+    replacedBeforeLoad = false;
+    /** The pre-rename key still holds a backup; the next good save removes it. */
+    previousKept = false;
+    storage = null;
+    timer;
+    snapshot() {
+        return assembleCookbook(recipeState.data, {
+            layout: this.layout,
+            theme: $state.snapshot(this.theme),
+            overviews: this.overviews,
+            name: this.name,
+            description: this.description,
+        });
+    }
+    /** A page's stored override, or `null` when it is on its defaults. */
+    overview(id) {
+        return Object.hasOwn(this.overviews, id) ? this.overviews[id] : null;
+    }
+    /**
+     * An edit from an overview page: the controller's canonical override, or
+     * `null` (back to the defaults), which removes the page's key.
+     */
+    setOverview(id, override) {
+        const next = Object.fromEntries(Object.entries(this.overviews).filter(([key]) => key !== id));
+        if (override)
+            next[id] = override;
+        this.overviews = next;
+    }
+    /** An edit from the shell or its layout editor; an empty one clears it. */
+    setLayout(next) {
+        this.layout = isShellLayoutEmpty(next) ? undefined : next;
+    }
+    /** Replace everything from a validated cookbook. */
+    apply(cookbook) {
+        recipeState.load(cookbook);
+        this.layout = cookbook.layout;
+        this.theme = cookbook.theme;
+        this.name = cookbook.name;
+        this.description = cookbook.description;
+        this.overviews = { ...(cookbook.overviews ?? {}) };
+        setSampleTaxRate(hasTaxRateRow(cookbook) ? readSettings(cookbook).taxRate : undefined);
+    }
+    /**
+     * A sentence naming recipes and features the loaded cookbook has that this
+     * version does not know (they are kept, not applied), or ''.
+     */
+    get unavailableNotice() {
+        const ids = [
+            ...recipeState.unavailableRecipes,
+            ...recipeState.unavailableFeatures,
+        ];
+        if (!ids.length)
+            return '';
+        const n = ids.length;
+        return `${n} ${n === 1 ? 'recipe' : 'recipes'} in this cookbook ${n === 1 ? "isn't" : "aren't"} available in this version: ${ids.join(', ')}. They are kept when you save or export.`;
+    }
+    /** Remove the unavailable ids from the cookbook, on the visitor's say. */
+    removeUnavailable() {
+        recipeState.removeUnavailable();
+        this.scheduleSave();
+    }
+    /** Change the theme; the default (or an empty one) clears it. */
+    setTheme(next) {
+        this.theme = compactTheme(next);
+    }
+    /** The app settings (currency, tax rate, payment terms), read from the policy rows. */
+    settings() {
+        return readSettings(this.snapshot());
+    }
+    /** Write the settings as policy rows. Existing records are untouched. */
+    setSettings(settings) {
+        const next = writeSettings(this.snapshot(), settings);
+        recipeState.rows = next.policies.map((row) => ({ ...row }));
+        setSampleTaxRate(hasTaxRateRow(next) ? readSettings(next).taxRate : undefined);
+    }
+    /** Replace on the visitor's say-so (an import): saving is allowed again. */
+    replace(cookbook) {
+        this.apply(cookbook);
+        if (!this.loaded)
+            this.replacedBeforeLoad = true;
+        this.saveBlocked = false;
+        this.keepLegacyUrl = false;
+    }
+    /** Back to an empty cookbook, and the shell's own settings to defaults. */
+    reset() {
+        recipeState.clear();
+        this.layout = undefined;
+        this.theme = undefined;
+        this.name = undefined;
+        this.description = undefined;
+        this.overviews = {};
+        try {
+            globalThis.localStorage?.removeItem(SHELL_STORAGE_KEY);
+        }
+        catch {
+            // Storage may be unavailable (private mode); the cookbook still resets.
+        }
+        this.saveBlocked = false;
+        this.keepLegacyUrl = false;
+    }
+    /** Validate and apply JSON text, e.g. a chosen file. Applies nothing on failure. */
+    importText(text) {
+        const result = parseCookbookText(text);
+        if (result.ok)
+            this.replace(result.cookbook);
+        return result;
+    }
+    /**
+     * Read the saved cookbook, then migrate a legacy `?r=` / `?o=` link into it.
+     * Call once in the browser, before `loaded` lets saving start. Returns true
+     * when a legacy link was imported, so the caller can clean the URL.
+     */
+    hydrate(search, storage = browserStorage()) {
+        this.storage = storage;
+        const outcome = loadCookbook(storage);
+        if (outcome.status === 'loaded')
+            this.previousKept = outcome.previousKept;
+        // What the visitor chose a moment ago (before the first navigation settled)
+        // wins over what was saved; the next save keeps it.
+        if (outcome.status === 'loaded' && !this.replacedBeforeLoad) {
+            this.apply(outcome.cookbook);
+            if (outcome.dropped?.length) {
+                this.loadNotice = `Some saved page customisations could not be used and were removed: ${outcome.dropped.join(' ')}`;
+            }
+        }
+        else if (outcome.status === 'unreadable') {
+            this.saveBlocked = !outcome.keptAside;
+            this.loadNotice = outcome.keptAside
+                ? `The saved cookbook could not be read (${outcome.reason}) and was kept aside; starting empty.`
+                : `The saved cookbook could not be read (${outcome.reason}). Starting empty without overwriting it; import or reset to save again.`;
+        }
+        let migrated = false;
+        if (hasLegacyState(search)) {
+            // An explicit link wins, but what it replaces is backed up first.
+            if (outcome.status === 'loaded' &&
+                !writeKey(storage, BACKUP_KEY, JSON.stringify(outcome.cookbook))) {
+                this.saveBlocked = true;
+            }
+            this.apply(cookbookFromLegacySearch(search));
+            migrated = true;
+        }
+        this.persist = outcome.status === 'unavailable' ? 'memory' : 'unknown';
+        this.loaded = true;
+        // Persist a migration at once: the URL is about to lose its copy.
+        if (migrated) {
+            const saved = this.save();
+            // The URL held the only copy unless it is now safely stored.
+            this.keepLegacyUrl = !saved;
+        }
+        return migrated;
+    }
+    /** Save now. Falls back to memory-only (and says so) if storage refuses. */
+    save() {
+        clearTimeout(this.timer);
+        this.timer = undefined;
+        if (!this.loaded)
+            return false;
+        if (this.saveBlocked) {
+            this.persist = 'memory';
+            return false;
+        }
+        const saved = saveCookbook(this.storage, this.snapshot());
+        this.persist = saved ? 'ok' : 'memory';
+        if (saved && this.previousKept) {
+            this.previousKept = !removeKey(this.storage, PREVIOUS_STORAGE_KEY);
+        }
+        // Once stored, the legacy parameters are redundant and may be cleaned.
+        if (saved)
+            this.keepLegacyUrl = false;
+        return saved;
+    }
+    /** Save soon; many quick edits make one write. */
+    scheduleSave() {
+        if (!this.loaded)
+            return;
+        clearTimeout(this.timer);
+        this.timer = setTimeout(() => this.save(), SAVE_DELAY_MS);
+    }
+    /** Save any pending change now (page hide). */
+    flush() {
+        if (this.timer !== undefined)
+            this.save();
+    }
+}
+export const cookbookStore = new CookbookStore();

package/dist/cookbook/types.d.ts

@@ -0,0 +1,76 @@
+import type { OverviewOverride } from '@happyvertical/smrt-svelte/overview/server';
+import type { ShellLayout } from '@happyvertical/smrt-svelte/workspace/layout';
+import type { FieldPolicyRow } from '../recipes/policy.ts';
+import type { ExposureSurface } from '../recipes/types.ts';
+import type { ThemeSetting } from '../theme/theme.ts';
+/**
+ * Placeholder until happyvertical/smrt#3604 publishes the real schema URL.
+ * The planner writes it so a file says what it is; it does not fetch it.
+ */
+export declare const COOKBOOK_SCHEMA = "https://s-m-r-t.dev/schemas/cookbook/v1.json";
+/**
+ * The URL files carried while the document was called a blueprint. Import
+ * still accepts it; nothing writes it.
+ */
+export declare const PREVIOUS_SCHEMA = "https://s-m-r-t.dev/schemas/blueprint/v1.json";
+export declare const COOKBOOK_VERSION = 1;
+/**
+ * Everything a visitor builds, in one portable document. This is the first
+ * concrete instance of the format happyvertical/smrt#3604 will pin; the
+ * planner's saved state, its JSON export and the localStorage value are all
+ * this one shape.
+ *
+ * Sample or created records are NOT part of it: they are demo data the
+ * in-memory `DataSource` reseeds, not something that scaffolds an app.
+ */
+export interface Cookbook {
+    $schema: string;
+    version: typeof COOKBOOK_VERSION;
+    /** The app's name (`set_name`); absent means the applied cookbook's, else `my-app`. */
+    name?: string;
+    /** A line about the app (`set_name`). */
+    description?: string;
+    /** Added recipe ids, sorted; requirements are already included. */
+    recipes: string[];
+    /**
+     * Added feature models (qualified names), sorted and unique: exposed
+     * catalog models no recipe covers. Absent in older files, read as `[]`.
+     */
+    features: string[];
+    /** App-scope smrt-fields policy rows (the recipe options). */
+    policies: FieldPolicyRow[];
+    /**
+     * Surfaces switched off per model, keyed by qualified model name. Omitted
+     * when nothing is narrowed.
+     */
+    exposure?: Record<string, ExposureSurface[]>;
+    /** The shell layout (smrt-svelte `ShellLayout`), applied by `AppShell`. */
+    layout?: ShellLayout;
+    /**
+     * The app's look: a smrt-ui preset, colour scheme and optional brand colour.
+     * Absent in older files, read as the default theme.
+     */
+    theme?: ThemeSetting;
+    /**
+     * Customised overview pages (smrt#3727), keyed by overview id: a section
+     * page's id is its layout id (`section:sales`, `custom:shop-2`). Each value
+     * is smrt-svelte's sparse `OverviewOverride` exactly, stored canonical (as
+     * `checkOverviewOverride` returns it) and validated against the page's
+     * definition on every load and import. Omitted when no page is customised;
+     * a page on its defaults has no key. Additive in version 1: older readers
+     * ignore unknown keys.
+     */
+    overviews?: Record<string, OverviewOverride>;
+}
+export type CookbookResult = {
+    ok: true;
+    cookbook: Cookbook;
+    /**
+     * What was dropped while reading (an invalid or unknown overview
+     * widget), one sentence each. Absent when nothing was.
+     */
+    dropped?: string[];
+} | {
+    ok: false;
+    error: string;
+};

package/dist/cookbook/types.js

@@ -0,0 +1,11 @@
+/**
+ * Placeholder until happyvertical/smrt#3604 publishes the real schema URL.
+ * The planner writes it so a file says what it is; it does not fetch it.
+ */
+export const COOKBOOK_SCHEMA = 'https://s-m-r-t.dev/schemas/cookbook/v1.json';
+/**
+ * The URL files carried while the document was called a blueprint. Import
+ * still accepts it; nothing writes it.
+ */
+export const PREVIOUS_SCHEMA = 'https://s-m-r-t.dev/schemas/blueprint/v1.json';
+export const COOKBOOK_VERSION = 1;

package/dist/cookbook/validate.d.ts

@@ -0,0 +1,14 @@
+import { type ParseCookbookOptions } from './parse.ts';
+import type { CookbookResult } from './types.ts';
+/**
+ * Check an unknown value (a parsed file or stored JSON) and return a
+ * normalised cookbook, or one clear sentence saying why not. Strict on
+ * purpose: nothing is silently dropped, so a bad file never half-applies.
+ * Page customisations are checked against the planner's widget registry; a
+ * host without it uses `parseCookbookWith` (`./parse.ts`).
+ */
+export declare function parseCookbook(input: unknown, options?: Omit<ParseCookbookOptions, 'overviews'>): CookbookResult;
+/** Parse JSON text, then `parseCookbook` it. */
+export declare function parseCookbookText(text: string, options?: {
+    dropUnknownRecipes?: boolean;
+}): CookbookResult;

package/dist/cookbook/validate.js

@@ -0,0 +1,29 @@
+import { parseOverviews } from "../overviews/validate.js";
+import { parseCookbookWith } from "./parse.js";
+const fail = (error) => ({ ok: false, error });
+/**
+ * Check an unknown value (a parsed file or stored JSON) and return a
+ * normalised cookbook, or one clear sentence saying why not. Strict on
+ * purpose: nothing is silently dropped, so a bad file never half-applies.
+ * Page customisations are checked against the planner's widget registry; a
+ * host without it uses `parseCookbookWith` (`./parse.ts`).
+ */
+export function parseCookbook(input, options = {}) {
+    return parseCookbookWith(input, { ...options, overviews: parseOverviews });
+}
+/** Parse JSON text, then `parseCookbook` it. */
+export function parseCookbookText(text, options = {}) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        return fail('This file is not valid JSON.');
+    }
+    try {
+        return parseCookbook(value, options);
+    }
+    catch {
+        return fail('This file is not a valid cookbook.');
+    }
+}

package/dist/core/app.d.ts

@@ -0,0 +1,37 @@
+import type { InferenceConfig } from '../inference/config.ts';
+import type { KitchenEndpoint } from '../kitchen/client.ts';
+/**
+ * Absolute path of the root-built prerendered planner app inside this package.
+ * Node only; kept out of `./core` so that entry stays free of Node built-ins.
+ * Serve it at `/`, or use `materializeApp` for a supported subpath artifact.
+ */
+export declare const appDir: string;
+/** Absolute path of one packaged app file, e.g. `appFile('index.html')`. */
+export declare function appFile(relativePath: string): string;
+export interface PlannerAppConfig {
+    inference?: InferenceConfig;
+    kitchen?: KitchenEndpoint;
+}
+export interface MaterializeAppOptions {
+    /** New or empty directory that receives the app root. */
+    outDir: string;
+    /** Canonical mount prefix: leading slash, no trailing slash, e.g. `/plan`. */
+    basePath: string;
+    /** Written as `planner.config.json` after validation and normalization. */
+    config: PlannerAppConfig;
+}
+export interface MaterializedApp {
+    outDir: string;
+    configFile: string;
+    fallbackFile: string;
+}
+/** Validate and canonicalize a non-root app mount prefix. */
+export declare function normalizeAppBasePath(basePath: string): string;
+/** Validate config strictly enough for an immutable public artifact. */
+export declare function normalizePlannerAppConfig(config: PlannerAppConfig): PlannerAppConfig;
+/**
+ * Copy the published static app into a deterministic, prefix-safe deployment
+ * artifact. The copy is assembled beside `outDir` and renamed only after its
+ * fallback and config validate, so callers never receive a partial tree.
+ */
+export declare function materializeApp(options: MaterializeAppOptions): MaterializedApp;

package/dist/core/app.js

@@ -0,0 +1,119 @@
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, renameSync, rmdirSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { dirname, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { validateInferenceConfig } from "../inference/config.js";
+import { parseKitchenConfig } from "../kitchen/client.js";
+/**
+ * Absolute path of the root-built prerendered planner app inside this package.
+ * Node only; kept out of `./core` so that entry stays free of Node built-ins.
+ * Serve it at `/`, or use `materializeApp` for a supported subpath artifact.
+ */
+export const appDir = fileURLToPath(new URL('../../app/', import.meta.url));
+/** Absolute path of one packaged app file, e.g. `appFile('index.html')`. */
+export function appFile(relativePath) {
+    return fileURLToPath(new URL(relativePath, new URL('../../app/', import.meta.url)));
+}
+const sensitiveName = /^(?:api[-_]?key|key|token|authorization|secret|password)$/i;
+/** Validate and canonicalize a non-root app mount prefix. */
+export function normalizeAppBasePath(basePath) {
+    if (typeof basePath !== 'string' ||
+        !/^\/[A-Za-z0-9._~-]+(?:\/[A-Za-z0-9._~-]+)*$/.test(basePath) ||
+        basePath.split('/').some((segment) => segment === '.' || segment === '..')) {
+        throw new Error('basePath must start with /, contain URL-safe path segments, and have no trailing slash');
+    }
+    return basePath;
+}
+function assertCredentialFree(value, path = 'config') {
+    if (!value || typeof value !== 'object')
+        return;
+    if (Array.isArray(value)) {
+        value.forEach((entry, index) => {
+            assertCredentialFree(entry, `${path}[${index}]`);
+        });
+        return;
+    }
+    for (const [name, entry] of Object.entries(value)) {
+        if (sensitiveName.test(name)) {
+            throw new Error(`${path}.${name} is a credential field and cannot be built into the app`);
+        }
+        assertCredentialFree(entry, `${path}.${name}`);
+    }
+}
+/** Validate config strictly enough for an immutable public artifact. */
+export function normalizePlannerAppConfig(config) {
+    if (!config || typeof config !== 'object' || Array.isArray(config)) {
+        throw new Error('config must be an object');
+    }
+    const unknown = Object.keys(config).filter((name) => name !== 'inference' && name !== 'kitchen');
+    if (unknown.length)
+        throw new Error(`unknown app config field: ${unknown[0]}`);
+    assertCredentialFree(config);
+    const inference = validateInferenceConfig({
+        inference: config.inference,
+    });
+    if (inference.notice)
+        throw new Error(inference.notice);
+    let kitchen;
+    if (config.kitchen !== undefined) {
+        kitchen = parseKitchenConfig(config.kitchen);
+        if (!kitchen) {
+            throw new Error('kitchen.endpoint must be a usable http(s) URL');
+        }
+    }
+    return {
+        inference: inference.config,
+        ...(kitchen ? { kitchen } : {}),
+    };
+}
+function patchFallback(file, basePath) {
+    const source = readFileSync(file, 'utf8');
+    if (!source.includes('/_app/') || !/base:\s*""/.test(source)) {
+        throw new Error('packaged 404.html does not match the supported root fallback');
+    }
+    const patched = source
+        .replaceAll('/_app/', `${basePath}/_app/`)
+        .replace(/base:\s*""/, `base: ${JSON.stringify(basePath)}`);
+    if (patched.includes('"/_app/') || /base:\s*""/.test(patched)) {
+        throw new Error('could not make the fallback prefix-safe');
+    }
+    writeFileSync(file, patched);
+}
+/**
+ * Copy the published static app into a deterministic, prefix-safe deployment
+ * artifact. The copy is assembled beside `outDir` and renamed only after its
+ * fallback and config validate, so callers never receive a partial tree.
+ */
+export function materializeApp(options) {
+    const basePath = normalizeAppBasePath(options.basePath);
+    const config = normalizePlannerAppConfig(options.config);
+    const outDir = resolve(options.outDir);
+    const source = resolve(appDir);
+    const relation = relative(source, outDir);
+    if (!relation || (!relation.startsWith(`..${sep}`) && relation !== '..')) {
+        throw new Error('outDir must be outside the packaged app directory');
+    }
+    if (existsSync(outDir)) {
+        if (!statSync(outDir).isDirectory() || readdirSync(outDir).length > 0) {
+            throw new Error('outDir must be new or empty');
+        }
+    }
+    mkdirSync(dirname(outDir), { recursive: true });
+    const temporary = mkdtempSync(resolve(dirname(outDir), '.smrt-planner-'));
+    try {
+        cpSync(source, temporary, { recursive: true });
+        patchFallback(resolve(temporary, '404.html'), basePath);
+        writeFileSync(resolve(temporary, 'planner.config.json'), `${JSON.stringify(config, null, 2)}\n`);
+        if (existsSync(outDir))
+            rmdirSync(outDir);
+        renameSync(temporary, outDir);
+    }
+    catch (error) {
+        rmSync(temporary, { recursive: true, force: true });
+        throw error;
+    }
+    return {
+        outDir,
+        configFile: resolve(outDir, 'planner.config.json'),
+        fallbackFile: resolve(outDir, '404.html'),
+    };
+}

package/dist/core/catalog.d.ts

@@ -0,0 +1,19 @@
+import type { CookbookBrief } from '../assistant/prompt.ts';
+import type { Recipe } from '../recipes/types.ts';
+/**
+ * What the assistant's prompt and reply schema are built from: the recipes it
+ * may add and the cookbooks it may offer. A host with its own subset passes
+ * one to `buildHostPrompt` / `buildReplySchema`; the default is the planner's
+ * own library.
+ */
+export interface PromptCatalog {
+    recipes: readonly Recipe[];
+    cookbooks: readonly CookbookBrief[];
+}
+/** Every recipe and every library cookbook, as the browser assistant sees them. */
+export declare const defaultCatalog: PromptCatalog;
+export type { CookbookBrief } from '../assistant/prompt.ts';
+export { getLibraryCookbook, libraryCookbooks } from '../library/index.ts';
+export type { LibraryCookbook } from '../library/types.ts';
+export { getRecipe, recipes, recipesById } from '../recipes/index.ts';
+export type { Recipe } from '../recipes/types.ts';

package/dist/core/catalog.js

@@ -0,0 +1,9 @@
+import { libraryCookbooks } from "../library/index.js";
+import { recipes } from "../recipes/index.js";
+/** Every recipe and every library cookbook, as the browser assistant sees them. */
+export const defaultCatalog = {
+    recipes,
+    cookbooks: libraryCookbooks,
+};
+export { getLibraryCookbook, libraryCookbooks } from "../library/index.js";
+export { getRecipe, recipes, recipesById } from "../recipes/index.js";

package/dist/core/headless.d.ts

@@ -0,0 +1,52 @@
+import type { Cookbook } from '../cookbook/types.ts';
+import type { CommandTool } from '../planner/commands/schemas.ts';
+import type { BatchResult, CommandResult, PlannerCommand, PlanSnapshot, RunOptions } from '../planner/commands/types.ts';
+import type { PromptCatalog } from './catalog.ts';
+export interface HeadlessPlannerOptions {
+    /**
+     * Restrict the recipes and library cookbooks this plan may name (the same
+     * shape `buildHostPrompt` takes). Ids outside it fail validation as
+     * `invalid_input`, exactly as a bad enum value does. Default: the whole
+     * library.
+     */
+    catalog?: PromptCatalog;
+}
+/**
+ * One plan held in plain objects, driven by the same commands as the browser
+ * planner. Runs in plain Node; any number may coexist.
+ */
+export interface HeadlessPlanner {
+    /**
+     * Run one command: same names, input schemas, validation, error codes and
+     * receipts as the browser controller. Never throws.
+     */
+    run(command: PlannerCommand, options?: RunOptions): CommandResult;
+    /** Untyped form for commands that arrive as data (a model's tool call). */
+    run(command: unknown, options?: RunOptions): CommandResult;
+    /** Several commands, all or nothing (the engine's `batch`). */
+    batch(batch: unknown): BatchResult;
+    /** The current plan, read-only and compact. */
+    snapshot(): PlanSnapshot;
+    /** The plan as a cookbook document (what `export_cookbook` writes). */
+    cookbook(): Cookbook;
+    /**
+     * Undo the most recent undoable change. `not_found` when there is none; the
+     * command `undo` with an explicit `undoId` is available through `run`.
+     */
+    undo(): CommandResult;
+    /** Call `listener` with the snapshot now and after every command. */
+    subscribe(listener: (snapshot: PlanSnapshot) => void): () => void;
+    /** The command tools this plan validates against (a restricted catalog narrows the enums). */
+    readonly tools: readonly CommandTool[];
+}
+/**
+ * A planner with no UI, no runes and no module state: the command set over a
+ * plain-object plan, for a Node server (an MCP server holds one per plan id).
+ * It is smrt's cookbook command engine (`createCookbookEngine`) behind the
+ * planner's names, plus `focus`.
+ *
+ * `cookbook` is the starting document; it goes through the strict import
+ * check and the call throws on a document that fails it. Everything after that
+ * reports errors through `run`'s result instead.
+ */
+export declare function createHeadlessPlanner(cookbook?: Cookbook, options?: HeadlessPlannerOptions): HeadlessPlanner;

package/dist/core/headless.js

@@ -0,0 +1,39 @@
+import { parseCookbookWith } from "../cookbook/parse.js";
+import { createPlannerAdapter, } from "../planner/commands/adapter.js";
+import { engineCatalog, restrictCatalog } from "../planner/commands/catalog.js";
+/**
+ * A planner with no UI, no runes and no module state: the command set over a
+ * plain-object plan, for a Node server (an MCP server holds one per plan id).
+ * It is smrt's cookbook command engine (`createCookbookEngine`) behind the
+ * planner's names, plus `focus`.
+ *
+ * `cookbook` is the starting document; it goes through the strict import
+ * check and the call throws on a document that fails it. Everything after that
+ * reports errors through `run`'s result instead.
+ */
+export function createHeadlessPlanner(cookbook, options = {}) {
+    let initial;
+    if (cookbook !== undefined) {
+        const parsed = parseCookbookWith(cookbook);
+        if (!parsed.ok)
+            throw new Error(parsed.error);
+        initial = parsed.cookbook;
+    }
+    const base = engineCatalog();
+    const adapter = createPlannerAdapter({
+        catalog: options.catalog ? restrictCatalog(base, options.catalog) : base,
+        cookbook: initial,
+        port: { prepareImport: (document) => parseCookbookWith(document) },
+    });
+    return {
+        run: adapter.run,
+        batch: adapter.batch,
+        snapshot: adapter.snapshot,
+        subscribe: adapter.subscribe,
+        cookbook: adapter.cookbook,
+        undo: adapter.undo,
+        get tools() {
+            return adapter.tools;
+        },
+    };
+}