@happyvertical/smrt-planner 0.0.0-stage → 0.0.2

package/dist/overviews/validate.js

@@ -0,0 +1,91 @@
+/**
+ * The cookbook's `overviews` field: one sparse smrt-svelte `OverviewOverride`
+ * per overview id. A stored override is untrusted data. Each one is checked
+ * with `checkOverviewOverride` against its page's definition; what fails (an
+ * unknown or disallowed widget type, options outside the widget's schema, an
+ * unknown overview id, a malformed entry) is dropped and reported, never
+ * rendered or loaded, and only the canonical override is kept.
+ */
+import { checkOverviewOverride, parseOverviewOverride, } from '@happyvertical/smrt-svelte/overview';
+import { isOverviewId, sectionOverview } from "./definitions.js";
+import { overviewRegistry } from "./registry.js";
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+function describe(id, issue) {
+    const what = issue.widgetId
+        ? `widget ${issue.widgetId}${issue.type ? ` (${issue.type})` : ''}`
+        : 'an entry';
+    const options = issue.options?.length
+        ? `: ${issue.options.map((o) => `${o.key} ${o.code}`).join(', ')}`
+        : '';
+    return `Overview ${id}: ${what} was dropped (${issue.code}${options}).`;
+}
+/**
+ * The override without the parts an issue names: an added widget or a change
+ * to a default widget with that id. The rest of the visitor's edits survive.
+ */
+function without(override, ids) {
+    const next = { ...override };
+    if (override.added) {
+        next.added = override.added.filter((widget) => !ids.has(widget.id));
+    }
+    if (override.changed) {
+        next.changed = Object.fromEntries(Object.entries(override.changed).filter(([id]) => !ids.has(id)));
+    }
+    return next;
+}
+/**
+ * Check one stored override. `checkOverviewOverride` is strict (any issue
+ * rejects); when it rejects, the offending widgets are taken out and the rest
+ * checked again, so one bad widget does not cost the visitor the others.
+ */
+export function checkStoredOverride(id, raw) {
+    const definition = sectionOverview(id);
+    if (!definition) {
+        return {
+            override: null,
+            issues: [
+                {
+                    widgetId: null,
+                    type: null,
+                    code: 'malformed',
+                    message: 'not an overview id',
+                },
+            ],
+        };
+    }
+    const first = checkOverviewOverride(definition, raw, overviewRegistry);
+    if (first.ok)
+        return { override: first.override, issues: [] };
+    const parsed = parseOverviewOverride(raw);
+    const bad = new Set(first.issues.flatMap((issue) => (issue.widgetId ? [issue.widgetId] : [])));
+    if (!parsed.override)
+        return { override: null, issues: first.issues };
+    const second = checkOverviewOverride(definition, without(parsed.override, bad), overviewRegistry);
+    return second.ok
+        ? { override: second.override, issues: first.issues }
+        : { override: null, issues: [...first.issues, ...second.issues] };
+}
+/**
+ * Read a cookbook's `overviews` value. `null` when it is not an object (the
+ * caller rejects the file, as for any malformed field); otherwise every entry
+ * is checked and what fails is dropped and reported.
+ */
+export function parseOverviews(input, layout) {
+    if (!isObject(input))
+        return null;
+    const entries = [];
+    const dropped = [];
+    for (const id of Object.keys(input).sort()) {
+        if (!isOverviewId(id, layout)) {
+            dropped.push(`Overview ${id} is not a page in this app and was dropped.`);
+            continue;
+        }
+        const { override, issues } = checkStoredOverride(id, input[id]);
+        for (const issue of issues)
+            dropped.push(describe(id, issue));
+        if (override)
+            entries.push([id, override]);
+    }
+    // fromEntries defines own keys, so a "__proto__" id cannot touch the prototype.
+    return { overviews: Object.fromEntries(entries), dropped };
+}

package/dist/planner/Planner.svelte

@@ -0,0 +1,204 @@
+<script lang="ts">
+import { Provider, tryGetAppStateContext } from '@happyvertical/smrt-svelte';
+import {
+  ShellLayoutController,
+  ShellLayoutEditor,
+  useShellLayout,
+} from '@happyvertical/smrt-svelte/workspace';
+import { Tabs } from '@happyvertical/smrt-ui';
+import { onMount, untrack } from 'svelte';
+import CookbooksPanel from '../components/CookbooksPanel.svelte';
+import ExportPanel from '../components/ExportPanel.svelte';
+import FeaturesPanel from '../components/FeaturesPanel.svelte';
+import RecipeCards from '../components/RecipeCards.svelte';
+import SettingsPanel from '../components/SettingsPanel.svelte';
+import { browserStorage } from '../cookbook/storage.js';
+import { cookbookStore } from '../cookbook/store.svelte.js';
+import { provideDataSource, tryUseDataSource } from '../data/context.js';
+import { createPlannerDataSource } from '../data/planner-source.js';
+import { cookbookNavGroups } from '../library/menu.js';
+import { libraryState } from '../library/state.svelte.js';
+import { recipeState } from '../recipes/state.svelte.js';
+import { setBasePath } from './app.svelte.js';
+import { createPlannerAssistant } from './assistant.js';
+import { PLANNER_TAB_IDS, type PlannerTabId } from './commands/index.js';
+import { plannerController, plannerRuntime } from './instance.js';
+import { plannerTab } from './tab.svelte.js';
+import type { PlannerProps } from './types.js';
+
+let {
+  controller = plannerController,
+  basePath,
+  inference,
+  layout = 'own',
+  persistence = 'self',
+  themeControls = false,
+  tabs = PLANNER_TAB_IDS,
+  onready,
+}: PlannerProps = $props();
+
+// Links to planner pages carry the base; set before anything renders them.
+$effect.pre(() => {
+  if (basePath !== undefined) setBasePath(basePath);
+});
+
+// Generated views and the Cookbooks tab read sample records from a data
+// source: use the host's, else make the planner's own.
+const dataSource =
+  tryUseDataSource() ?? provideDataSource(createPlannerDataSource());
+
+// smrt-svelte's inputs read the app state. Inside a host's own provider (or
+// the static app's AppShell) use that; otherwise the planner brings one.
+const hasAppState = tryGetAppStateContext() !== null;
+
+const labels: Record<PlannerTabId, string> = {
+  cookbooks: 'Cookbooks',
+  recipes: 'Recipes',
+  features: 'Features',
+  layout: 'Layout',
+  settings: 'Settings',
+  export: 'Export',
+};
+const shown = $derived(tabs.filter((id) => PLANNER_TAB_IDS.includes(id)));
+const items = $derived(shown.map((id) => ({ id, label: labels[id] })));
+const active = $derived(
+  shown.includes(plannerTab.active)
+    ? plannerTab.active
+    : (shown[0] ?? 'recipes'),
+);
+
+// The headless layout controller: the menu the cookbook generates, edited
+// through the cookbook store, with no AppShell around.
+// Fixed at mount: the two editors are different objects.
+const layoutMode = untrack(() => layout);
+const ownLayout =
+  layoutMode === 'own'
+    ? new ShellLayoutController({
+        nav: () => [],
+        groups: () =>
+          cookbookNavGroups({
+            recipes: recipeState.ids,
+            features: recipeState.features,
+          }),
+        panels: () => undefined,
+        layout: () => cookbookStore.layout,
+        editable: () => true,
+        commit: (next) => cookbookStore.setLayout(next),
+      })
+    : null;
+const shellLayout = layoutMode === 'shell' ? useShellLayout() : null;
+
+const select = (id: string) => {
+  const tab = PLANNER_TAB_IDS.find((t) => t === id);
+  if (tab) plannerTab.active = tab;
+};
+
+// The controller's focus -> the tab on screen, and back, each only on a
+// difference, so a foreign controller and the app's own both stay in step.
+onMount(() => {
+  const stop = controller.subscribe((snapshot) => {
+    const tab = snapshot.focus.tab;
+    if (tab && tab !== plannerTab.active) plannerTab.active = tab;
+  });
+  return stop;
+});
+$effect(() => {
+  const tab = plannerTab.active;
+  untrack(() => {
+    if (controller.snapshot().focus.tab !== tab) {
+      controller.run({ name: 'focus', input: { tab } });
+    }
+  });
+});
+
+// A library cookbook applied by a command regenerates the sample records.
+onMount(() => {
+  const previous = plannerRuntime.onReplaced;
+  plannerRuntime.onReplaced = () => dataSource.reset?.();
+  return () => {
+    plannerRuntime.onReplaced = previous;
+  };
+});
+
+// Saved in this browser, unless the host looks after it.
+onMount(() => {
+  if (persistence !== 'self') return;
+  if (!cookbookStore.loaded) {
+    libraryState.load();
+    cookbookStore.hydrate('', browserStorage());
+  }
+});
+$effect(() => {
+  if (persistence !== 'self') return;
+  // Reading it all (layout is deep) subscribes the effect to every part.
+  void JSON.stringify(cookbookStore.snapshot());
+  cookbookStore.scheduleSave();
+});
+
+onMount(() => {
+  const assistant = inference
+    ? createPlannerAssistant(controller, inference)
+    : undefined;
+  onready?.({ controller, ...(assistant ? { assistant } : {}) });
+});
+</script>
+
+<svelte:window onpagehide={() => persistence === 'self' && cookbookStore.flush()} />
+
+{#snippet view()}
+<div class="planner">
+  <Tabs tabs={items} {active} onchange={select} aria-label="Planner">
+    {#if shown.includes('cookbooks')}
+      <div hidden={active !== 'cookbooks'}><CookbooksPanel /></div>
+    {/if}
+    {#if shown.includes('recipes')}
+      <div hidden={active !== 'recipes'}><RecipeCards /></div>
+    {/if}
+    {#if shown.includes('features')}
+      <div hidden={active !== 'features'}><FeaturesPanel /></div>
+    {/if}
+    {#if shown.includes('layout')}
+      <div hidden={active !== 'layout'} class="pane">
+        <p class="meta">
+          Reorder, move or hide navigation entries and choose which panels show.
+          The layout is saved with the cookbook.
+        </p>
+        <ShellLayoutEditor controller={ownLayout ?? shellLayout ?? undefined} />
+      </div>
+    {/if}
+    {#if shown.includes('settings')}
+      <div hidden={active !== 'settings'}><SettingsPanel {themeControls} /></div>
+    {/if}
+    {#if shown.includes('export')}
+      <div hidden={active !== 'export'}><ExportPanel /></div>
+    {/if}
+  </Tabs>
+</div>
+{/snippet}
+
+{#if hasAppState}
+  {@render view()}
+{:else}
+  <Provider>{@render view()}</Provider>
+{/if}
+
+<style>
+  .planner :global(.tab-panel) {
+    padding-top: var(--smrt-spacing-4);
+  }
+
+  .pane {
+    display: grid;
+    gap: var(--smrt-spacing-3);
+  }
+
+  /* `display: grid` would otherwise override the inactive pane's `hidden`. */
+  .pane[hidden] {
+    display: none;
+  }
+
+  .meta {
+    margin: 0;
+    color: var(--smrt-color-on-surface-variant);
+  }
+</style>

package/dist/planner/Planner.svelte.d.ts

@@ -0,0 +1,4 @@
+import type { PlannerProps } from './types.ts';
+declare const Planner: import("svelte").Component<PlannerProps, {}, "">;
+type Planner = ReturnType<typeof Planner>;
+export default Planner;

package/dist/planner/app.svelte.d.ts

@@ -0,0 +1,6 @@
+export declare function setBasePath(path: string): void;
+export declare function getBasePath(): string;
+/** The query string carrying the shareable URL state (the package selection). */
+export declare function appQuery(): string;
+/** An in-app path (`/m/commerce/Order/`) carrying the current app state. */
+export declare function appHref(path: string): string;

package/dist/planner/app.svelte.js

@@ -0,0 +1,23 @@
+import { composeQuery } from "./query.js";
+import { selection } from "./selection.svelte.js";
+/**
+ * Where the planner's pages live: `''` at the site root, `/planner` under a
+ * sub-path. The static app sets it from SvelteKit's `base`; a host that mounts
+ * the `Planner` component passes its own `basePath`. Kept here, not read from
+ * `$app/paths`, so the planner needs no SvelteKit router to build its links.
+ */
+let basePath = '';
+export function setBasePath(path) {
+    basePath = path.replace(/\/+$/, '');
+}
+export function getBasePath() {
+    return basePath;
+}
+/** The query string carrying the shareable URL state (the package selection). */
+export function appQuery() {
+    return composeQuery({ packages: selection.ids });
+}
+/** An in-app path (`/m/commerce/Order/`) carrying the current app state. */
+export function appHref(path) {
+    return `${basePath}${path}${appQuery()}`;
+}

package/dist/planner/assistant.d.ts

@@ -0,0 +1,46 @@
+import { ThemeUndos } from '../assistant/theme-undo.svelte.ts';
+import { type BrowserAssistantTransport, type ChatModel } from '../assistant/transport.ts';
+import { type InferenceConfig } from '../inference/config.ts';
+import type { PlannerController } from './commands/index.ts';
+/**
+ * Give the planner a model yourself: anything that implements `message()`
+ * (the browser's WebLLM, an API provider behind your server, a test double).
+ * Choosing and loading it is the host's job; the planner only asks it for one
+ * structured reply per turn.
+ */
+export interface PlannerChatInference {
+    /** The model, or a function returning it (null until one is loaded). */
+    chat: ChatModel | (() => ChatModel | null);
+    /** Called with each reply the model wrote, e.g. to read it aloud. */
+    onReply?: (text: string) => void;
+}
+/**
+ * Or name an inference mode, the same shape as `planner.config.json`'s
+ * `inference` (it overrides the file):
+ * - `host`: POST to `host.endpoint` (see `docs/inference-host.md`).
+ * - `byo`: the OpenAI-compatible endpoint the visitor connected in this
+ *   browser; none until they have.
+ * - `browser`: no model of its own; pass `chat` to supply one.
+ * An invalid config falls back to `browser`, reported as `assistant.notice`.
+ */
+export type PlannerConfigInference = InferenceConfig & {
+    onReply?: (text: string) => void;
+};
+export type PlannerInference = PlannerChatInference | PlannerConfigInference;
+export interface PlannerAssistant {
+    /** For smrt-chat's `AssistantDock` (`transport`). */
+    transport: BrowserAssistantTransport;
+    /** The theme changes it made, each undoable; render with `toolCallData`. */
+    themeUndos: ThemeUndos;
+    /** The mode in use. */
+    mode: InferenceConfig['mode'];
+    /** Why the given `inference` was replaced by `browser`, when it was. */
+    notice?: string;
+}
+/**
+ * The planner's assistant for any controller: a chat transport whose every
+ * change is a command on `controller`, so it works against a host's own mount
+ * as well as the static app. Cookbook proposals are not offered here (they
+ * need a confirmation card the host would render); everything else is.
+ */
+export declare function createPlannerAssistant(controller: PlannerController, inference: PlannerInference): PlannerAssistant;

package/dist/planner/assistant.js

@@ -0,0 +1,122 @@
+import { ThemeUndos } from "../assistant/theme-undo.svelte.js";
+import { createBrowserAssistantTransport, } from "../assistant/transport.js";
+import { browserStorage } from "../cookbook/storage.js";
+import { savedByoChat } from "../inference/byo.svelte.js";
+import { configFromProp } from "../inference/config.js";
+import { createHostChat } from "../inference/host.js";
+import { recipes } from "../recipes/index.js";
+/** The controller's recipes as the store the assistant reads. Changes are commands. */
+function recipeStoreOf(controller) {
+    return {
+        get ids() {
+            return controller.snapshot().recipes.map((recipe) => recipe.id);
+        },
+        add: (...ids) => void controller.run({ name: 'add_recipes', input: { ids } }),
+        remove: (...ids) => void controller.run({ name: 'remove_recipes', input: { ids } }),
+    };
+}
+function settingsStoreOf(controller) {
+    return {
+        read: () => {
+            const { currency, taxRate, paymentTerms } = controller.snapshot().settings;
+            return {
+                currency,
+                taxRate: Number((taxRate / 100).toFixed(6)),
+                paymentTerms,
+            };
+        },
+        write: (settings) => {
+            void controller.run({
+                name: 'set_settings',
+                input: {
+                    currency: settings.currency,
+                    taxRate: Number((settings.taxRate * 100).toFixed(4)),
+                    ...(settings.paymentTerms
+                        ? { paymentTerms: settings.paymentTerms }
+                        : {}),
+                },
+            });
+        },
+    };
+}
+function themeStoreOf(controller) {
+    return {
+        read: () => {
+            const { preset, primary, colorScheme } = controller.snapshot().theme;
+            const theme = {};
+            if (preset)
+                theme.preset = preset;
+            if (primary)
+                theme.custom = { primary };
+            if (colorScheme !== 'system') {
+                theme.colorScheme = colorScheme;
+            }
+            return Object.keys(theme).length ? theme : undefined;
+        },
+        write: (theme) => {
+            if (!theme) {
+                void controller.run({ name: 'reset_theme', input: {} });
+                return;
+            }
+            void controller.run({ name: 'reset_theme', input: {} });
+            void controller.run({
+                name: 'set_theme',
+                input: {
+                    ...(theme.preset ? { preset: theme.preset } : {}),
+                    ...(theme.custom ? { primary: theme.custom.primary } : {}),
+                    ...(theme.colorScheme ? { colorScheme: theme.colorScheme } : {}),
+                },
+            });
+        },
+    };
+}
+/**
+ * The planner's assistant for any controller: a chat transport whose every
+ * change is a command on `controller`, so it works against a host's own mount
+ * as well as the static app. Cookbook proposals are not offered here (they
+ * need a confirmation card the host would render); everything else is.
+ */
+export function createPlannerAssistant(controller, inference) {
+    const theme = themeStoreOf(controller);
+    let mode = 'browser';
+    let notice;
+    let chat = () => null;
+    if ('chat' in inference) {
+        const given = inference.chat;
+        chat = () => (typeof given === 'function' ? given() : given);
+    }
+    else {
+        const result = configFromProp(inference);
+        notice = result.notice;
+        mode = result.config.mode;
+        if (result.config.mode === 'host' && result.config.host) {
+            const host = createHostChat({
+                endpoint: result.config.host.endpoint,
+                snapshot: () => controller.snapshot(),
+            });
+            chat = () => host;
+        }
+        else if (result.config.mode === 'byo') {
+            const presets = result.config.byo?.presets;
+            chat = () => savedByoChat(browserStorage(), presets, undefined, result.config.credentialPersistence);
+        }
+    }
+    const themeUndos = new ThemeUndos(theme, controller);
+    const transport = createBrowserAssistantTransport({
+        model: chat,
+        acceptCommands: mode === 'host',
+        unavailable: mode === 'byo'
+            ? 'Connect your model on the AI page first, then I can help.'
+            : 'No model is connected yet, so I cannot help. The planner works without one.',
+        store: recipeStoreOf(controller),
+        recipes,
+        // No cookbook proposals: they need a confirmation card the host renders.
+        cookbooks: [],
+        settings: settingsStoreOf(controller),
+        theme,
+        themeUndos,
+        controller,
+        onReply: inference.onReply,
+    });
+    return { transport, themeUndos, mode, ...(notice ? { notice } : {}) };
+}

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

@@ -0,0 +1,121 @@
+import { type CookbookEngine, type EngineCatalog, type EngineState } from '@happyvertical/smrt-core/cookbook/engine';
+import type { Cookbook, CookbookResult } from '../../cookbook/types.ts';
+import { toolsFor } from './schemas.ts';
+import { type BatchResult, type CommandResult, type PlannerCommand, type PlannerTabId, type PlanSnapshot, type RunOptions } from './types.ts';
+/** How the controller reads and moves the planner's own view. */
+export interface PlannerNavigation {
+    getTab(): PlannerTabId | null;
+    setTab(tab: PlannerTabId): void;
+    /** Open a menu section's page; the host decides what that means. */
+    setSection?(sectionId: string): void;
+}
+export interface PlannerControllerOptions {
+    /** The planner tab, so `focus` and the snapshot follow the real UI. */
+    navigation?: PlannerNavigation;
+    /**
+     * Called after a library cookbook was applied, so the app can regenerate its
+     * sample records (they are not part of a cookbook), as the Cookbooks tab does.
+     */
+    onReplaced?: () => void;
+}
+/** Where the app keeps the document the engine edits. */
+export interface PlannerPort {
+    /**
+     * The app's current document. Give it when something other than the engine
+     * (the UI) can change the document: it is compared on every call, and a
+     * difference is adopted as one manual edit.
+     */
+    read?(): unknown;
+    /** The library cookbook the app was last set up from, if the app tracks it. */
+    applied?(): string | null;
+    /** The engine changed the document: put it where the app keeps it. */
+    write?(cookbook: Cookbook, change: {
+        /** The commands that ran (a batch lists each; an undo is `undo`). */
+        commands: readonly string[];
+        /**
+         * A whole-app command ran (`apply_cookbook`, `import_cookbook`): take
+         * everything from `cookbook`, page customisations included. Otherwise
+         * the app's own page customisations are kept.
+         */
+        replaced: boolean;
+        /** The library cookbook the engine records the plan as set up from. */
+        applied: string | null;
+        /** A library cookbook was just set up: select it and reset sample data. */
+        libraryApplied: boolean;
+    }): void;
+    /** The app's own check of an imported document (it may migrate or trim it). */
+    prepareImport?(document: unknown): CookbookResult;
+}
+/** A value read and written by the adapter; reactive in the browser. */
+export interface Cell<T> {
+    get(): T;
+    set(value: T): void;
+}
+/** A plain cell. */
+export declare function cell<T>(initial: T): Cell<T>;
+/** What differs between the browser controller and plain Node. All optional. */
+export interface AdapterEnv {
+    /** Cells for state a snapshot shows; the browser passes `$state` ones. */
+    section?: Cell<string | null>;
+    tab?: Cell<PlannerTabId | null>;
+    /** The first listener arrived / the last one left (the browser starts effects). */
+    watch?: {
+        start(): void;
+        stop(): void;
+    };
+}
+/**
+ * The planner as a headless object: typed commands in, a compact snapshot
+ * out. The planner's own assistant, a host page, an MCP server and the CLI
+ * all drive the app through this one seam.
+ */
+export interface PlannerController {
+    /**
+     * Run one command. Never throws: a bad command, unknown id or refused edit
+     * comes back as `{ ok: false, error }` and leaves the app unchanged.
+     */
+    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;
+    /**
+     * Run several commands all-or-nothing (the engine's `batch`): any failure
+     * leaves the plan exactly as it was.
+     */
+    batch(batch: unknown): BatchResult;
+    /** The current plan, read-only and compact. */
+    snapshot(): PlanSnapshot;
+    /**
+     * Call `listener` with the current snapshot now and after every change,
+     * whether a command or a manual edit made it. Returns the unsubscribe.
+     */
+    subscribe(listener: (snapshot: PlanSnapshot) => void): () => void;
+}
+/** The adapter plus the hooks the browser wrapper's effects need. */
+export interface PlannerAdapter extends PlannerController {
+    /** The plan as a cookbook document. */
+    cookbook(): Cookbook;
+    /** Undo the most recent undoable change; `not_found` when there is none. */
+    undo(): CommandResult;
+    /** The engine's state, to persist and resume from. */
+    state(): EngineState;
+    /** The tool definitions this plan validates against, `focus` included. */
+    readonly tools: ReturnType<typeof toolsFor>;
+    /** The atomic-batch tool definition. */
+    readonly batchTool: CookbookEngine['batchTool'];
+    /**
+     * Build the snapshot and return its signature. Reading it subscribes an
+     * effect to every store it is built from; it does not notify.
+     */
+    observe(): string;
+    /** Tell listeners about the current snapshot if it changed since they heard. */
+    deliver(): void;
+}
+export interface PlannerAdapterOptions {
+    catalog: EngineCatalog;
+    /** Start from this document (strictly checked; the call throws if invalid). */
+    cookbook?: unknown;
+    port?: PlannerPort;
+    options?: PlannerControllerOptions;
+    env?: AdapterEnv;
+}
+export declare function createPlannerAdapter(config: PlannerAdapterOptions): PlannerAdapter;