@happyvertical/smrt-core 0.55.9 → 0.55.11

package/dist/cookbook/engine/types.d.ts

@@ -0,0 +1,331 @@
+/**
+ * Cookbook command engine, contract v1 (#3753).
+ *
+ * Plain data in, plain data out: no SvelteKit, browser storage, planner
+ * singleton or inference dependency, and no Node imports, so the same engine
+ * runs in a browser planner, a CLI, an MCP server or a website. Adapters own
+ * navigation/focus, persistence and transport; the engine owns the document.
+ */
+import type { Cookbook, RecipeDefinition } from '@happyvertical/smrt-types';
+/**
+ * The command set version. A change an older client could not send or read
+ * bumps it; adding a command or an optional field does not.
+ */
+export declare const COOKBOOK_COMMANDS_VERSION = 1;
+/** The part of a manifest recipe the engine reads (a `RecipeDefinition` fits). */
+export type EngineRecipe = Pick<RecipeDefinition, 'id' | 'label' | 'models' | 'nav' | 'requires'> & Partial<Pick<RecipeDefinition, 'requiresAny' | 'group' | 'section' | 'options'>>;
+/** One field of a catalog model, for `set_policy` and settings defaults. */
+export interface EngineField {
+    name: string;
+    /** System fields (id, timestamps) cannot be given a policy. */
+    system?: boolean;
+    /** The field's own starting value, so a setting equal to it writes no row. */
+    default?: unknown;
+}
+/** One catalog model. Same shape as smrt-svelte's `CookbookModelInfo`, plus fields. */
+export interface EngineModel {
+    /** Qualified name, `@scope/pkg:Class`. */
+    id: string;
+    name: string;
+    /** Package id used in item ids: `commerce` for `@happyvertical/smrt-commerce`. */
+    packageId: string;
+    description?: string;
+    /** Has an API, MCP or CLI surface; only exposed models can be added as features. */
+    exposed?: boolean;
+    /** When given, `set_policy` rejects a field not listed. */
+    fields?: readonly EngineField[];
+}
+/** A ready-made cookbook the catalog offers (a library entry). */
+export interface EngineLibraryCookbook {
+    id: string;
+    name: string;
+    document: Cookbook;
+}
+/** Which model fields each app setting is the default of. */
+export type SettingTargets = Record<'currency' | 'taxRate' | 'paymentTerms', readonly {
+    model: string;
+    field: string;
+}[]>;
+/**
+ * Everything the engine resolves ids against, as data: recipes and models from
+ * published manifests, optionally a library of cookbooks. Nothing here is
+ * bundled with the engine.
+ */
+export interface EngineCatalog {
+    recipes: readonly EngineRecipe[];
+    models: readonly EngineModel[];
+    cookbooks?: readonly EngineLibraryCookbook[];
+    /** Theme preset names; default {@link DEFAULT_THEME_PRESETS}. */
+    themePresets?: readonly string[];
+    /** ISO 4217 codes; default any three capital letters. */
+    currencies?: readonly string[];
+    /** Default {@link COMMERCE_SETTING_TARGETS}. */
+    settingTargets?: SettingTargets;
+}
+/** Input of each command, keyed by the command's (tool) name. */
+export interface CommandInputs {
+    /** Switch recipes on, with everything they `require`. */
+    add_recipes: {
+        ids: string[];
+    };
+    /** Switch recipes off; ones another recipe needs are kept (and reported). */
+    remove_recipes: {
+        ids: string[];
+    };
+    /** Add models no recipe covers, by qualified name. */
+    add_features: {
+        ids: string[];
+    };
+    remove_features: {
+        ids: string[];
+    };
+    /** Add the recipes and features of a library cookbook to what is there. */
+    add_cookbook: {
+        id: string;
+    };
+    /** Remove what a library cookbook added (recipes others need are kept). */
+    remove_cookbook: {
+        id: string;
+    };
+    /** Select a library cookbook, replacing the app (needs `replace` if non-empty). */
+    apply_cookbook: {
+        id: string;
+        replace?: boolean;
+    };
+    /** Import a cookbook document, replacing the app (needs `replace` if non-empty). */
+    import_cookbook: {
+        document: unknown;
+        replace?: boolean;
+    };
+    /** App settings; tax rate in percent, 0 to 100. */
+    set_settings: {
+        currency?: string;
+        taxRate?: number;
+        paymentTerms?: string;
+    };
+    /** Set (or clear with null) one field's policy row. App scope. */
+    set_policy: {
+        model: string;
+        field: string;
+        defaultValue?: unknown;
+        visibility?: 'basic' | 'advanced' | 'hidden' | null;
+        label?: string | null;
+        help?: string | null;
+    };
+    set_theme: {
+        preset?: string;
+        primary?: string;
+        colorScheme?: 'light' | 'dark' | 'system';
+    };
+    reset_theme: Record<string, never>;
+    /** Name (and describe) the app; null clears. */
+    set_name: {
+        name?: string | null;
+        description?: string | null;
+    };
+    rename_section: {
+        id: string;
+        label: string;
+    };
+    /** `null` restores the entry's own name. */
+    rename_item: {
+        id: string;
+        label: string | null;
+    };
+    hide: {
+        id: string;
+    };
+    show: {
+        id: string;
+    };
+    /** Check the current document and report typed diagnostics. Changes nothing. */
+    validate: Record<string, never>;
+    /** The cookbook as `<name>.cookbook.json` text. Changes nothing. */
+    export_cookbook: {
+        name?: string;
+    };
+    /** Undo an earlier change by the `undoId` its receipt carried. */
+    undo: {
+        undoId: string;
+        force?: boolean;
+    };
+}
+export type CommandName = keyof CommandInputs;
+/** A command as a client sends it. */
+export type CookbookCommand = {
+    [N in CommandName]: {
+        name: N;
+        input: CommandInputs[N];
+        /** Retry key: a repeated id returns the first receipt and applies nothing. */
+        id?: string;
+        /** Refuse with `conflict` unless the plan is still at this revision. */
+        expectedRevision?: number;
+    };
+}[CommandName];
+/** Stable strings a client can switch on. */
+export type CommandErrorCode = 'unknown_command' | 'invalid_input' | 'not_found'
+/** A destructive command needs `replace: true` (or `force: true`). */
+ | 'confirmation_required'
+/** The plan moved on since the caller looked (`expectedRevision`, undo). */
+ | 'conflict'
+/** A command id was reused with a different command. */
+ | 'id_reuse'
+/** An atomic batch failed; `details.index` names the command, nothing applied. */
+ | 'batch_failed' | 'failed';
+export interface CommandError {
+    code: CommandErrorCode;
+    message: string;
+    /** Where the problem is, as a path into the input (`input.ids[1]`). */
+    path?: string;
+    details?: Record<string, unknown>;
+}
+/** What a recipe/feature command did, after `requires` ran. */
+export interface RecipeChanges {
+    added: string[];
+    removed: string[];
+    /** Asked to remove, but another recipe still needs them. */
+    kept: string[];
+}
+export interface PlanSnapshot {
+    version: typeof COOKBOOK_COMMANDS_VERSION;
+    /** Counts applied changes; equal histories give equal revisions. */
+    revision: number;
+    app: {
+        name: string;
+        description: string | null;
+        cookbook: string | null;
+    };
+    recipes: {
+        id: string;
+        label: string;
+    }[];
+    features: string[];
+    /** Recipe and feature ids this catalog lacks; kept on export. */
+    unavailable: string[];
+    settings: {
+        currency: string;
+        taxRate: number;
+        paymentTerms: string;
+    };
+    theme: {
+        text: string;
+        preset: string | null;
+        primary: string | null;
+        colorScheme: string;
+    };
+    sections: {
+        id: string;
+        label: string;
+        hidden: boolean;
+        items: {
+            id: string;
+            label: string;
+            hidden: boolean;
+        }[];
+    }[];
+    policies: number;
+    /** Undo ids still available, newest last. */
+    undo: string[];
+}
+export interface CommandReceipt {
+    name: CommandName;
+    /** The command id, when one was sent. */
+    id?: string;
+    summary: string;
+    changed: boolean;
+    revisionBefore: number;
+    revisionAfter: number;
+    undoId?: string;
+    changes?: RecipeChanges;
+    /** Non-fatal notes (an import's legacy `$schema` migration). */
+    warnings?: string[];
+}
+export type CommandResult = {
+    ok: true;
+    id?: string;
+    /** True when this is the stored result of an earlier run of the same id. */
+    replayed?: boolean;
+    snapshot: PlanSnapshot;
+    receipt: CommandReceipt;
+    data?: unknown;
+} | {
+    ok: false;
+    id?: string;
+    replayed?: boolean;
+    error: CommandError;
+};
+export interface RunOptions {
+    expectedRevision?: number;
+}
+/** Several commands applied all-or-nothing. */
+export interface CommandBatch {
+    id?: string;
+    commands: readonly unknown[];
+    expectedRevision?: number;
+}
+export type BatchResult = {
+    ok: true;
+    id?: string;
+    replayed?: boolean;
+    snapshot: PlanSnapshot;
+    receipt: {
+        id?: string;
+        count: number;
+        changed: boolean;
+        revisionBefore: number;
+        revisionAfter: number;
+        undoId?: string;
+    };
+    /** One result per command, in order. */
+    results: Extract<CommandResult, {
+        ok: true;
+    }>[];
+} | {
+    ok: false;
+    id?: string;
+    replayed?: boolean;
+    error: CommandError;
+    /** The state is exactly as before the batch. */
+    snapshot: PlanSnapshot;
+};
+/** One diagnostic from `validate`. */
+export interface Diagnostic {
+    severity: 'error' | 'warning';
+    code: string;
+    path: string;
+    message: string;
+}
+export interface ValidateData {
+    ok: boolean;
+    diagnostics: Diagnostic[];
+}
+export interface ExportData {
+    fileName: string;
+    text: string;
+    cookbook: Cookbook;
+}
+/** A journal row: enough to answer a retry of `id` after a restart. */
+export interface JournalEntry {
+    id: string;
+    fingerprint: string;
+    result: CommandResult | BatchResult;
+}
+/** The engine's whole state as plain JSON, to persist and resume from. */
+export interface EngineState {
+    version: typeof COOKBOOK_COMMANDS_VERSION;
+    revision: number;
+    /** The library cookbook the plan was last set up from, if any. */
+    applied: string | null;
+    cookbook: Cookbook;
+    journal: JournalEntry[];
+}
+export interface JsonSchema {
+    [key: string]: unknown;
+}
+/** One command as an LLM or MCP tool definition. */
+export interface CommandTool {
+    name: CommandName;
+    description: string;
+    inputSchema: JsonSchema;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/cookbook/engine/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/cookbook/engine/types.ts"],"names":[],"mappings":"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"}

package/dist/cookbook/engine/types.js

@@ -0,0 +1,10 @@
+//#region src/cookbook/engine/types.ts
+/**
+* The command set version. A change an older client could not send or read
+* bumps it; adding a command or an optional field does not.
+*/
+var COOKBOOK_COMMANDS_VERSION = 1;
+//#endregion
+export { COOKBOOK_COMMANDS_VERSION };
+
+//# sourceMappingURL=types.js.map

package/dist/cookbook/engine/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","names":[],"sources":["../../../src/cookbook/engine/types.ts"],"sourcesContent":["/**\n * Cookbook command engine, contract v1 (#3753).\n *\n * Plain data in, plain data out: no SvelteKit, browser storage, planner\n * singleton or inference dependency, and no Node imports, so the same engine\n * runs in a browser planner, a CLI, an MCP server or a website. Adapters own\n * navigation/focus, persistence and transport; the engine owns the document.\n */\nimport type { Cookbook, RecipeDefinition } from '@happyvertical/smrt-types';\n\n/**\n * The command set version. A change an older client could not send or read\n * bumps it; adding a command or an optional field does not.\n */\nexport const COOKBOOK_COMMANDS_VERSION = 1;\n\n/** The part of a manifest recipe the engine reads (a `RecipeDefinition` fits). */\nexport type EngineRecipe = Pick<\n  RecipeDefinition,\n  'id' | 'label' | 'models' | 'nav' | 'requires'\n> &\n  Partial<\n    Pick<RecipeDefinition, 'requiresAny' | 'group' | 'section' | 'options'>\n  >;\n\n/** One field of a catalog model, for `set_policy` and settings defaults. */\nexport interface EngineField {\n  name: string;\n  /** System fields (id, timestamps) cannot be given a policy. */\n  system?: boolean;\n  /** The field's own starting value, so a setting equal to it writes no row. */\n  default?: unknown;\n}\n\n/** One catalog model. Same shape as smrt-svelte's `CookbookModelInfo`, plus fields. */\nexport interface EngineModel {\n  /** Qualified name, `@scope/pkg:Class`. */\n  id: string;\n  name: string;\n  /** Package id used in item ids: `commerce` for `@happyvertical/smrt-commerce`. */\n  packageId: string;\n  description?: string;\n  /** Has an API, MCP or CLI surface; only exposed models can be added as features. */\n  exposed?: boolean;\n  /** When given, `set_policy` rejects a field not listed. */\n  fields?: readonly EngineField[];\n}\n\n/** A ready-made cookbook the catalog offers (a library entry). */\nexport interface EngineLibraryCookbook {\n  id: string;\n  name: string;\n  document: Cookbook;\n}\n\n/** Which model fields each app setting is the default of. */\nexport type SettingTargets = Record<\n  'currency' | 'taxRate' | 'paymentTerms',\n  readonly { model: string; field: string }[]\n>;\n\n/**\n * Everything the engine resolves ids against, as data: recipes and models from\n * published manifests, optionally a library of cookbooks. Nothing here is\n * bundled with the engine.\n */\nexport interface EngineCatalog {\n  recipes: readonly EngineRecipe[];\n  models: readonly EngineModel[];\n  cookbooks?: readonly EngineLibraryCookbook[];\n  /** Theme preset names; default {@link DEFAULT_THEME_PRESETS}. */\n  themePresets?: readonly string[];\n  /** ISO 4217 codes; default any three capital letters. */\n  currencies?: readonly string[];\n  /** Default {@link COMMERCE_SETTING_TARGETS}. */\n  settingTargets?: SettingTargets;\n}\n\n/** Input of each command, keyed by the command's (tool) name. */\nexport interface CommandInputs {\n  /** Switch recipes on, with everything they `require`. */\n  add_recipes: { ids: string[] };\n  /** Switch recipes off; ones another recipe needs are kept (and reported). */\n  remove_recipes: { ids: string[] };\n  /** Add models no recipe covers, by qualified name. */\n  add_features: { ids: string[] };\n  remove_features: { ids: string[] };\n  /** Add the recipes and features of a library cookbook to what is there. */\n  add_cookbook: { id: string };\n  /** Remove what a library cookbook added (recipes others need are kept). */\n  remove_cookbook: { id: string };\n  /** Select a library cookbook, replacing the app (needs `replace` if non-empty). */\n  apply_cookbook: { id: string; replace?: boolean };\n  /** Import a cookbook document, replacing the app (needs `replace` if non-empty). */\n  import_cookbook: { document: unknown; replace?: boolean };\n  /** App settings; tax rate in percent, 0 to 100. */\n  set_settings: { currency?: string; taxRate?: number; paymentTerms?: string };\n  /** Set (or clear with null) one field's policy row. App scope. */\n  set_policy: {\n    model: string;\n    field: string;\n    defaultValue?: unknown;\n    visibility?: 'basic' | 'advanced' | 'hidden' | null;\n    label?: string | null;\n    help?: string | null;\n  };\n  set_theme: {\n    preset?: string;\n    primary?: string;\n    colorScheme?: 'light' | 'dark' | 'system';\n  };\n  reset_theme: Record<string, never>;\n  /** Name (and describe) the app; null clears. */\n  set_name: { name?: string | null; description?: string | null };\n  rename_section: { id: string; label: string };\n  /** `null` restores the entry's own name. */\n  rename_item: { id: string; label: string | null };\n  hide: { id: string };\n  show: { id: string };\n  /** Check the current document and report typed diagnostics. Changes nothing. */\n  validate: Record<string, never>;\n  /** The cookbook as `<name>.cookbook.json` text. Changes nothing. */\n  export_cookbook: { name?: string };\n  /** Undo an earlier change by the `undoId` its receipt carried. */\n  undo: { undoId: string; force?: boolean };\n}\n\nexport type CommandName = keyof CommandInputs;\n\n/** A command as a client sends it. */\nexport type CookbookCommand = {\n  [N in CommandName]: {\n    name: N;\n    input: CommandInputs[N];\n    /** Retry key: a repeated id returns the first receipt and applies nothing. */\n    id?: string;\n    /** Refuse with `conflict` unless the plan is still at this revision. */\n    expectedRevision?: number;\n  };\n}[CommandName];\n\n/** Stable strings a client can switch on. */\nexport type CommandErrorCode =\n  | 'unknown_command'\n  | 'invalid_input'\n  | 'not_found'\n  /** A destructive command needs `replace: true` (or `force: true`). */\n  | 'confirmation_required'\n  /** The plan moved on since the caller looked (`expectedRevision`, undo). */\n  | 'conflict'\n  /** A command id was reused with a different command. */\n  | 'id_reuse'\n  /** An atomic batch failed; `details.index` names the command, nothing applied. */\n  | 'batch_failed'\n  | 'failed';\n\nexport interface CommandError {\n  code: CommandErrorCode;\n  message: string;\n  /** Where the problem is, as a path into the input (`input.ids[1]`). */\n  path?: string;\n  details?: Record<string, unknown>;\n}\n\n/** What a recipe/feature command did, after `requires` ran. */\nexport interface RecipeChanges {\n  added: string[];\n  removed: string[];\n  /** Asked to remove, but another recipe still needs them. */\n  kept: string[];\n}\n\nexport interface PlanSnapshot {\n  version: typeof COOKBOOK_COMMANDS_VERSION;\n  /** Counts applied changes; equal histories give equal revisions. */\n  revision: number;\n  app: { name: string; description: string | null; cookbook: string | null };\n  recipes: { id: string; label: string }[];\n  features: string[];\n  /** Recipe and feature ids this catalog lacks; kept on export. */\n  unavailable: string[];\n  settings: { currency: string; taxRate: number; paymentTerms: string };\n  theme: {\n    text: string;\n    preset: string | null;\n    primary: string | null;\n    colorScheme: string;\n  };\n  sections: {\n    id: string;\n    label: string;\n    hidden: boolean;\n    items: { id: string; label: string; hidden: boolean }[];\n  }[];\n  policies: number;\n  /** Undo ids still available, newest last. */\n  undo: string[];\n}\n\nexport interface CommandReceipt {\n  name: CommandName;\n  /** The command id, when one was sent. */\n  id?: string;\n  summary: string;\n  changed: boolean;\n  revisionBefore: number;\n  revisionAfter: number;\n  undoId?: string;\n  changes?: RecipeChanges;\n  /** Non-fatal notes (an import's legacy `$schema` migration). */\n  warnings?: string[];\n}\n\nexport type CommandResult =\n  | {\n      ok: true;\n      id?: string;\n      /** True when this is the stored result of an earlier run of the same id. */\n      replayed?: boolean;\n      snapshot: PlanSnapshot;\n      receipt: CommandReceipt;\n      data?: unknown;\n    }\n  | { ok: false; id?: string; replayed?: boolean; error: CommandError };\n\nexport interface RunOptions {\n  expectedRevision?: number;\n}\n\n/** Several commands applied all-or-nothing. */\nexport interface CommandBatch {\n  id?: string;\n  commands: readonly unknown[];\n  expectedRevision?: number;\n}\n\nexport type BatchResult =\n  | {\n      ok: true;\n      id?: string;\n      replayed?: boolean;\n      snapshot: PlanSnapshot;\n      receipt: {\n        id?: string;\n        count: number;\n        changed: boolean;\n        revisionBefore: number;\n        revisionAfter: number;\n        undoId?: string;\n      };\n      /** One result per command, in order. */\n      results: Extract<CommandResult, { ok: true }>[];\n    }\n  | {\n      ok: false;\n      id?: string;\n      replayed?: boolean;\n      error: CommandError;\n      /** The state is exactly as before the batch. */\n      snapshot: PlanSnapshot;\n    };\n\n/** One diagnostic from `validate`. */\nexport interface Diagnostic {\n  severity: 'error' | 'warning';\n  code: string;\n  path: string;\n  message: string;\n}\n\nexport interface ValidateData {\n  ok: boolean;\n  diagnostics: Diagnostic[];\n}\n\nexport interface ExportData {\n  fileName: string;\n  text: string;\n  cookbook: Cookbook;\n}\n\n/** A journal row: enough to answer a retry of `id` after a restart. */\nexport interface JournalEntry {\n  id: string;\n  fingerprint: string;\n  result: CommandResult | BatchResult;\n}\n\n/** The engine's whole state as plain JSON, to persist and resume from. */\nexport interface EngineState {\n  version: typeof COOKBOOK_COMMANDS_VERSION;\n  revision: number;\n  /** The library cookbook the plan was last set up from, if any. */\n  applied: string | null;\n  cookbook: Cookbook;\n  journal: JournalEntry[];\n}\n\nexport interface JsonSchema {\n  [key: string]: unknown;\n}\n\n/** One command as an LLM or MCP tool definition. */\nexport interface CommandTool {\n  name: CommandName;\n  description: string;\n  inputSchema: JsonSchema;\n}\n"],"mappings":";;;;;AAcA,IAAa,4BAA4B"}

package/dist/cookbook/engine.d.ts

@@ -0,0 +1,2 @@
+export * from './engine/index.js';
+//# sourceMappingURL=engine.d.ts.map

package/dist/cookbook/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/cookbook/engine.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC"}

package/dist/cookbook/engine.js

@@ -0,0 +1,9 @@
+import { COMMERCE_SETTING_TARGETS, DEFAULT_APP_NAME, DEFAULT_COLOR_SCHEME, DEFAULT_PRESET, DEFAULT_THEME_PRESETS, MAX_TERMS_LENGTH } from "./engine/defaults.js";
+import { buildNav, navItemId } from "./engine/nav.js";
+import { canonical, diagnose, isEmptyCookbook } from "./engine/document.js";
+import { adopt, execute, exportFileName, fail, libraryName, serializeCookbook } from "./engine/commands.js";
+import { buildBatchTool, buildCommandTools, checkSchema, commandSchemas } from "./engine/schemas.js";
+import { COOKBOOK_COMMANDS_VERSION } from "./engine/types.js";
+import { createCookbookEngine } from "./engine/engine.js";
+import "./engine/index.js";
+export { COMMERCE_SETTING_TARGETS, COOKBOOK_COMMANDS_VERSION, DEFAULT_APP_NAME, DEFAULT_COLOR_SCHEME, DEFAULT_PRESET, DEFAULT_THEME_PRESETS, MAX_TERMS_LENGTH, adopt, buildBatchTool, buildCommandTools, buildNav, canonical, checkSchema, commandSchemas, createCookbookEngine, diagnose, execute, exportFileName, fail, isEmptyCookbook, libraryName, navItemId, serializeCookbook };

package/dist/cookbook/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Cookbook v1: parse, validate and migrate (browser-safe; no Node imports).
+ * Types live in `@happyvertical/smrt-types`; see `agents/cookbook.md`.
+ */
+export * from './validate.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cookbook/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cookbook/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,eAAe,CAAC"}

package/dist/cookbook/v1.schema.json

@@ -0,0 +1,131 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://s-m-r-t.dev/schemas/cookbook/v1.json",
+  "title": "SMRT cookbook v1",
+  "description": "What an app is made of: recipes, features, field policies, exposure, shell layout, theme and overview pages. New optional fields are added within v1; readers ignore unknown keys.",
+  "type": "object",
+  "required": ["version", "recipes", "policies"],
+  "properties": {
+    "$schema": {
+      "enum": [
+        "https://s-m-r-t.dev/schemas/cookbook/v1.json",
+        "https://s-m-r-t.dev/schemas/blueprint/v1.json"
+      ]
+    },
+    "version": { "const": 1 },
+    "name": { "type": "string" },
+    "description": { "type": "string" },
+    "recipes": { "type": "array", "items": { "type": "string" } },
+    "features": { "type": "array", "items": { "type": "string" } },
+    "policies": { "type": "array", "items": { "$ref": "#/$defs/policyRow" } },
+    "exposure": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "array",
+        "items": { "enum": ["api", "mcp", "cli"] }
+      }
+    },
+    "layout": { "$ref": "#/$defs/layout" },
+    "theme": { "$ref": "#/$defs/theme" },
+    "overviews": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#/$defs/overviewOverride" }
+    }
+  },
+  "additionalProperties": true,
+  "$defs": {
+    "stringList": { "type": "array", "items": { "type": "string" } },
+    "policyRow": {
+      "type": "object",
+      "required": ["objectRef", "fieldName", "scopeType"],
+      "properties": {
+        "objectRef": { "type": "string", "minLength": 1 },
+        "fieldName": { "type": "string", "minLength": 1 },
+        "scopeType": { "const": "app" },
+        "defaultValue": { "type": ["string", "null"] },
+        "visibility": { "enum": ["basic", "advanced", "hidden", null] },
+        "help": { "type": ["string", "null"] },
+        "label": { "type": ["string", "null"] },
+        "displayOrder": { "type": ["number", "null"] },
+        "locked": { "type": ["boolean", "null"] }
+      },
+      "additionalProperties": true
+    },
+    "layout": {
+      "type": "object",
+      "required": ["version"],
+      "properties": {
+        "version": { "const": 1 },
+        "sectionOrder": { "$ref": "#/$defs/stringList" },
+        "hidden": { "$ref": "#/$defs/stringList" },
+        "itemOrder": {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/stringList" }
+        },
+        "moved": {
+          "type": "object",
+          "additionalProperties": { "type": "string" }
+        },
+        "placements": {
+          "type": "object",
+          "additionalProperties": { "type": "string" }
+        },
+        "sections": {
+          "type": "object",
+          "additionalProperties": { "type": "object" }
+        },
+        "items": {
+          "type": "object",
+          "additionalProperties": { "type": "object" }
+        },
+        "panels": {
+          "type": "object",
+          "additionalProperties": { "type": "object" }
+        },
+        "customSections": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "label"],
+            "properties": {
+              "id": { "type": "string" },
+              "label": { "type": "string" }
+            }
+          }
+        }
+      },
+      "additionalProperties": true
+    },
+    "theme": {
+      "type": "object",
+      "properties": {
+        "preset": { "type": "string" },
+        "colorScheme": { "enum": ["light", "dark", "system"] },
+        "custom": {
+          "type": "object",
+          "required": ["primary"],
+          "properties": {
+            "primary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" },
+            "fontFamily": { "type": "string" }
+          }
+        }
+      },
+      "additionalProperties": true
+    },
+    "overviewOverride": {
+      "type": "object",
+      "required": ["version"],
+      "properties": {
+        "version": { "const": 1 },
+        "order": { "$ref": "#/$defs/stringList" },
+        "removed": { "$ref": "#/$defs/stringList" },
+        "added": { "type": "array", "items": { "type": "object" } },
+        "changed": {
+          "type": "object",
+          "additionalProperties": { "type": "object" }
+        }
+      },
+      "additionalProperties": true
+    }
+  }
+}

package/dist/cookbook/validate.d.ts

@@ -0,0 +1,37 @@
+import type { Cookbook } from '@happyvertical/smrt-types';
+export type { Cookbook } from '@happyvertical/smrt-types';
+/** What a v1 document carries in `$schema`. */
+export declare const COOKBOOK_SCHEMA_URL = "https://s-m-r-t.dev/schemas/cookbook/v1.json";
+/** Accepted on read (the document used to be called a blueprint); never written. */
+export declare const COOKBOOK_LEGACY_SCHEMA_URL = "https://s-m-r-t.dev/schemas/blueprint/v1.json";
+export declare const COOKBOOK_VERSION = 1;
+export interface CookbookValidateOptions {
+    /**
+     * The recipe ids that exist (from published manifests). When given, an id
+     * outside it is an error. When absent no existence check runs: that is the
+     * seam `smrt cookbook validate` fills.
+     */
+    recipes?: Iterable<string>;
+}
+export type CookbookValidation = {
+    ok: true;
+    cookbook: Cookbook;
+    warnings: string[];
+} | {
+    ok: false;
+    errors: string[];
+};
+/**
+ * Structural validation of an unknown value (parsed JSON). Returns the
+ * normalised document (legacy `$schema` rewritten, `features` defaulted,
+ * recipes sorted and unique) or every problem found, each a readable line
+ * naming the path. Unknown top-level keys are kept (additive fields in v1).
+ *
+ * Deep checks that need other packages (overview widgets against a page
+ * definition, nav ids against recipes, theme presets) are the consumer's job;
+ * recipe existence runs only when `options.recipes` is given.
+ */
+export declare function validateCookbook(input: unknown, options?: CookbookValidateOptions): CookbookValidation;
+/** Parse JSON text, then {@link validateCookbook} it. */
+export declare function parseCookbookText(text: string, options?: CookbookValidateOptions): CookbookValidation;
+//# sourceMappingURL=validate.d.ts.map

package/dist/cookbook/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/cookbook/validate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EAMT,MAAM,2BAA2B,CAAC;AAEnC,YAAY,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAE1D,+CAA+C;AAC/C,eAAO,MAAM,mBAAmB,iDACgB,CAAC;AACjD,oFAAoF;AACpF,eAAO,MAAM,0BAA0B,kDACU,CAAC;AAClD,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAElC,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CAC5B;AAED,MAAM,MAAM,kBAAkB,GAC1B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,GACpD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AA6IpC;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,uBAA4B,GACpC,kBAAkB,CAwHpB;AAED,yDAAyD;AACzD,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,uBAA4B,GACpC,kBAAkB,CAQpB"}