@happyvertical/smrt-planner 0.0.0-stage → 0.0.1

package/dist/catalog/generate/recipe-demo.d.ts

@@ -0,0 +1,11 @@
+import type { CatalogPackage } from '../types.ts';
+/**
+ * Adds `effectiveDemo` to every recipe whose browser-demo answer changes once
+ * what it requires is counted: the worst mode of its own `demo` and of every
+ * recipe it needs, across packages (smrt#3709). The rule is smrt-core's
+ * `effectiveRecipeDemo`, not a copy: it runs here, in the node-side
+ * generator, because core is not safe to import into the browser bundle. A
+ * recipe whose own `demo` already is its effective one gets no key, and a
+ * recipe with no `demo` gets none (nothing was measured).
+ */
+export declare function withEffectiveDemo(packages: readonly CatalogPackage[]): CatalogPackage[];

package/dist/catalog/generate/recipe-demo.js

@@ -0,0 +1,29 @@
+import { effectiveRecipeDemo } from '@happyvertical/smrt-core/recipe-demo';
+/**
+ * Adds `effectiveDemo` to every recipe whose browser-demo answer changes once
+ * what it requires is counted: the worst mode of its own `demo` and of every
+ * recipe it needs, across packages (smrt#3709). The rule is smrt-core's
+ * `effectiveRecipeDemo`, not a copy: it runs here, in the node-side
+ * generator, because core is not safe to import into the browser bundle. A
+ * recipe whose own `demo` already is its effective one gets no key, and a
+ * recipe with no `demo` gets none (nothing was measured).
+ */
+export function withEffectiveDemo(packages) {
+    const all = packages.flatMap((pkg) => pkg.recipes ?? []);
+    return packages.map((pkg) => {
+        if (!pkg.recipes)
+            return pkg;
+        return {
+            ...pkg,
+            recipes: pkg.recipes.map((recipe) => {
+                const effective = effectiveRecipeDemo(recipe.id, all);
+                if (!effective ||
+                    !recipe.demo ||
+                    JSON.stringify(effective) === JSON.stringify(recipe.demo)) {
+                    return recipe;
+                }
+                return { ...recipe, effectiveDemo: effective };
+            }),
+        };
+    });
+}

package/dist/catalog/generate/recipe-metadata.d.ts

@@ -0,0 +1,12 @@
+import type { PackageBrowserCapability, Recipe, RecipeDemo } from '../../recipes/types.ts';
+type Json = Record<string, unknown>;
+/** A recipe's `demo`; absent when the mode is not one of the four. */
+export declare function extractDemo(raw: unknown): RecipeDemo | undefined;
+/**
+ * The package-level `browser` capability, or undefined when the artifact has
+ * none (an unmeasured package, or a smrt that predates smrt#3709).
+ */
+export declare function extractBrowser(raw: unknown): PackageBrowserCapability | undefined;
+/** The validated non-model metadata of one raw recipe entry. */
+export declare function extractRecipeMetadata(raw: Json): Pick<Recipe, 'surfaces' | 'providers' | 'runtime' | 'demoSeed' | 'demo'>;
+export {};

package/dist/catalog/generate/recipe-metadata.js

@@ -0,0 +1,138 @@
+/**
+ * The non-model parts of a recipe entry (smrt#3708 surfaces, providers,
+ * runtime, demo seed; smrt#3709 `demo` and the package's `browser`), read from
+ * the manifest or knowledge artifact. Each is checked against the shape the
+ * Features catalogue renders and dropped when malformed, so a manifest from a
+ * newer or older smrt never reaches the UI half-typed. Values are copied as
+ * authored: nothing here derives, mocks or rewrites what smrt emitted.
+ */
+const DEMO_MODES = [
+    'live',
+    'mock',
+    'sample',
+    'server',
+];
+const RUNTIMES = ['browser', 'server', 'both'];
+const isObject = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const isString = (value) => typeof value === 'string' && value.length > 0;
+function strings(value) {
+    return Array.isArray(value) && value.every((v) => typeof v === 'string')
+        ? value
+        : undefined;
+}
+const isExportRef = (value) => isString(value) && value.includes('#') && !value.startsWith('#');
+/** A surface of a kind the catalogue knows, else undefined (dropped). */
+function surface(raw) {
+    if (!isObject(raw))
+        return undefined;
+    const { kind } = raw;
+    if (!isExportRef(raw.export))
+        return undefined;
+    const icon = isString(raw.icon) ? { icon: raw.icon } : {};
+    switch (kind) {
+        case 'shell-widget':
+            return isString(raw.slot) && isString(raw.label)
+                ? {
+                    kind,
+                    slot: raw.slot,
+                    export: raw.export,
+                    label: raw.label,
+                    ...icon,
+                }
+                : undefined;
+        case 'route':
+            return isString(raw.path) && isString(raw.label)
+                ? { kind, path: raw.path, export: raw.export, label: raw.label }
+                : undefined;
+        case 'settings-panel':
+            return isString(raw.label)
+                ? { kind, export: raw.export, label: raw.label }
+                : undefined;
+        case 'playground':
+            return {
+                kind,
+                export: raw.export,
+                ...(isString(raw.label) ? { label: raw.label } : {}),
+            };
+        case 'widget':
+            return isString(raw.type) && isString(raw.label)
+                ? { ...raw }
+                : undefined;
+        default:
+            return undefined;
+    }
+}
+function provider(raw) {
+    if (!isObject(raw) || !isString(raw.id) || !isString(raw.kind)) {
+        return undefined;
+    }
+    const options = strings(raw.options);
+    if (!options || typeof raw.required !== 'boolean')
+        return undefined;
+    const secrets = strings(raw.secrets);
+    const browserOptions = strings(raw.browserOptions);
+    return {
+        id: raw.id,
+        kind: raw.kind,
+        options,
+        required: raw.required,
+        ...(secrets?.length ? { secrets } : {}),
+        ...(browserOptions?.length ? { browserOptions } : {}),
+    };
+}
+function demoSeed(raw) {
+    if (!isObject(raw))
+        return undefined;
+    if (isExportRef(raw.export))
+        return { export: raw.export };
+    return 'data' in raw ? { data: raw.data } : undefined;
+}
+/** A recipe's `demo`; absent when the mode is not one of the four. */
+export function extractDemo(raw) {
+    if (!isObject(raw))
+        return undefined;
+    const mode = DEMO_MODES.find((m) => m === raw.mode);
+    const reasons = strings(raw.reasons);
+    if (!mode || !reasons)
+        return undefined;
+    const mocked = strings(raw.mocked);
+    return { mode, reasons, ...(mocked?.length ? { mocked } : {}) };
+}
+/**
+ * The package-level `browser` capability, or undefined when the artifact has
+ * none (an unmeasured package, or a smrt that predates smrt#3709).
+ */
+export function extractBrowser(raw) {
+    if (!isObject(raw))
+        return undefined;
+    if (raw.status !== 'browser-safe' && raw.status !== 'server-only') {
+        return undefined;
+    }
+    const issues = strings(raw.issues);
+    const via = strings(raw.via);
+    return {
+        status: raw.status,
+        ...(issues?.length ? { issues } : {}),
+        ...(isString(raw.reason) ? { reason: raw.reason } : {}),
+        ...(via?.length ? { via } : {}),
+    };
+}
+/** The validated non-model metadata of one raw recipe entry. */
+export function extractRecipeMetadata(raw) {
+    const surfaces = Array.isArray(raw.surfaces)
+        ? raw.surfaces.flatMap((s) => surface(s) ?? [])
+        : [];
+    const providers = Array.isArray(raw.providers)
+        ? raw.providers.flatMap((p) => provider(p) ?? [])
+        : [];
+    const runtime = RUNTIMES.find((r) => r === raw.runtime);
+    const seed = demoSeed(raw.demoSeed);
+    const demo = extractDemo(raw.demo);
+    return {
+        ...(surfaces.length ? { surfaces } : {}),
+        ...(providers.length ? { providers } : {}),
+        ...(runtime ? { runtime } : {}),
+        ...(seed ? { demoSeed: seed } : {}),
+        ...(demo ? { demo } : {}),
+    };
+}

package/dist/catalog/generate/registry.d.ts

@@ -0,0 +1,14 @@
+import type { RawPackage } from './extract.ts';
+export declare const DEFAULT_REGISTRY = "https://npm.happyvertical.com";
+/**
+ * Every `@happyvertical/smrt-*` package name the registry's search lists. The
+ * search index lags behind publishes, so it supplies names only; versions and
+ * contents come from each package's own packument.
+ */
+export declare function discoverPackageNames(registry: string): Promise<string[]>;
+/**
+ * Fetch a package's latest version and read its `./manifest.json` export and
+ * the `smrt-knowledge.json` beside it. Returns null for packages that export
+ * no manifest (tooling, runtime and UI libraries).
+ */
+export declare function fetchPackage(registry: string, packageName: string): Promise<RawPackage | null>;

package/dist/catalog/generate/registry.js

@@ -0,0 +1,83 @@
+import { execFile } from 'node:child_process';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { promisify } from 'node:util';
+import { PACKAGE_PREFIX } from "./exclusions.js";
+const run = promisify(execFile);
+export const DEFAULT_REGISTRY = 'https://npm.happyvertical.com';
+async function getJson(url) {
+    const response = await fetch(url);
+    if (!response.ok)
+        throw new Error(`GET ${url} -> ${response.status}`);
+    return (await response.json());
+}
+/**
+ * Every `@happyvertical/smrt-*` package name the registry's search lists. The
+ * search index lags behind publishes, so it supplies names only; versions and
+ * contents come from each package's own packument.
+ */
+export async function discoverPackageNames(registry) {
+    const names = new Set();
+    const size = 250;
+    for (let from = 0;; from += size) {
+        const page = await getJson(`${registry}/-/v1/search?text=${encodeURIComponent(PACKAGE_PREFIX)}&size=${size}&from=${from}`);
+        for (const { package: pkg } of page.objects) {
+            if (pkg.name.startsWith(PACKAGE_PREFIX))
+                names.add(pkg.name);
+        }
+        if (page.objects.length < size)
+            break;
+    }
+    return [...names].sort();
+}
+async function readJson(path) {
+    try {
+        return JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Fetch a package's latest version and read its `./manifest.json` export and
+ * the `smrt-knowledge.json` beside it. Returns null for packages that export
+ * no manifest (tooling, runtime and UI libraries).
+ */
+export async function fetchPackage(registry, packageName) {
+    const packument = await getJson(`${registry}/${packageName.replace('/', '%2f')}`);
+    const version = packument['dist-tags'].latest;
+    const meta = packument.versions[version];
+    const entry = meta.exports?.['./manifest.json'];
+    const manifestPath = typeof entry === 'string' ? entry : entry?.default;
+    if (!manifestPath)
+        return null;
+    const dir = await mkdtemp(join(tmpdir(), 'smrt-catalog-'));
+    try {
+        // Tarballs are served from the registry's own host regardless of the
+        // absolute URL the packument records.
+        const tarball = new URL(meta.dist.tarball);
+        const response = await fetch(`${registry}${tarball.pathname}`);
+        if (!response.ok) {
+            throw new Error(`GET ${tarball.pathname} -> ${response.status}`);
+        }
+        const archive = join(dir, 'package.tgz');
+        await writeFile(archive, Buffer.from(await response.arrayBuffer()));
+        await run('tar', ['-xzf', archive, '-C', dir]);
+        const manifestFile = join(dir, 'package', manifestPath);
+        const manifest = await readJson(manifestFile);
+        if (!manifest)
+            throw new Error(`${packageName}: unreadable ${manifestPath}`);
+        const knowledge = await readJson(join(dirname(manifestFile), 'smrt-knowledge.json'));
+        return {
+            packageName,
+            version,
+            description: meta.description ?? '',
+            manifest,
+            knowledge,
+        };
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+}

package/dist/catalog/index.d.ts

@@ -0,0 +1,21 @@
+import type { Catalog, CatalogModel, CatalogPackage } from './types.ts';
+export type * from './types.ts';
+/**
+ * The static catalog, generated by `pnpm catalog:generate` and committed, with
+ * the local stand-ins for enum values, widget hints and undeclared relations
+ * (`../upstream/`) applied. Delete the overlay when the manifests carry them.
+ */
+export declare const catalog: Catalog;
+export declare function getPackage(id: string): CatalogPackage | undefined;
+export declare function getModel(packageId: string, modelName: string): CatalogModel | undefined;
+/** Look a model up by its `@scope/pkg:Class` qualified name. */
+export declare function getModelByQualifiedName(qualified: string): {
+    pkg: CatalogPackage;
+    model: CatalogModel;
+} | undefined;
+/** The models of a package that get generated views (and nav entries). */
+export declare function exposedModels(pkg: CatalogPackage): CatalogModel[];
+/** Case-insensitive match on package id, description, model and field names. */
+export declare function searchPackages(packages: readonly CatalogPackage[], query: string): CatalogPackage[];
+/** Total number of generated surfaces (REST + MCP + CLI) for a package. */
+export declare function surfaceCount(pkg: CatalogPackage): number;

package/dist/catalog/index.js

@@ -0,0 +1,53 @@
+import { applyUpstreamOverlay } from "../upstream/overlay.js";
+import raw from './catalog.json' with { type: 'json' };
+/**
+ * The static catalog, generated by `pnpm catalog:generate` and committed, with
+ * the local stand-ins for enum values, widget hints and undeclared relations
+ * (`../upstream/`) applied. Delete the overlay when the manifests carry them.
+ */
+export const catalog = applyUpstreamOverlay(raw);
+const byId = new Map(catalog.packages.map((pkg) => [pkg.id, pkg]));
+export function getPackage(id) {
+    return byId.get(id);
+}
+export function getModel(packageId, modelName) {
+    return byId.get(packageId)?.models.find((m) => m.name === modelName);
+}
+/** Look a model up by its `@scope/pkg:Class` qualified name. */
+export function getModelByQualifiedName(qualified) {
+    const separator = qualified.lastIndexOf(':');
+    if (separator < 0)
+        return undefined;
+    const packageName = qualified.slice(0, separator);
+    const pkg = catalog.packages.find((p) => p.packageName === packageName);
+    const model = pkg?.models.find((m) => m.id === qualified);
+    return pkg && model ? { pkg, model } : undefined;
+}
+/** The models of a package that get generated views (and nav entries). */
+export function exposedModels(pkg) {
+    return pkg.models.filter((m) => m.exposed);
+}
+/** Case-insensitive match on package id, description, model and field names. */
+export function searchPackages(packages, query) {
+    const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+    if (terms.length === 0)
+        return [...packages];
+    return packages.filter((pkg) => {
+        const haystack = [
+            pkg.id,
+            pkg.description,
+            ...pkg.models.flatMap((m) => [
+                m.name,
+                m.collection,
+                ...m.fields.map((f) => f.name),
+            ]),
+        ]
+            .join(' ')
+            .toLowerCase();
+        return terms.every((term) => haystack.includes(term));
+    });
+}
+/** Total number of generated surfaces (REST + MCP + CLI) for a package. */
+export function surfaceCount(pkg) {
+    return pkg.models.reduce((sum, m) => sum + m.rest.length + m.mcp.length + m.cli.length, 0);
+}

package/dist/catalog/types.d.ts

@@ -0,0 +1,141 @@
+/**
+ * The static package catalog: the shape of `catalog.json`, which
+ * `pnpm catalog:generate` writes from the published `@happyvertical/smrt-*`
+ * packages' `manifest.json` (and `smrt-knowledge.json` where present).
+ *
+ * Everything the browser needs is here, so the app never loads a package.
+ */
+import type { PackageBrowserCapability, Recipe } from '../recipes/types.ts';
+/** Field types as the s-m-r-t manifest names them. */
+export type CatalogFieldType = 'text' | 'integer' | 'decimal' | 'boolean' | 'datetime' | 'json' | 'foreignKey' | 'crossPackageRef' | (string & {});
+/** A field's static UI hints, from `@field({ ui })` (`_meta.ui` in the manifest). */
+export interface CatalogFieldUI {
+    /** Seeds the field into the "basic" tier, shown before the advanced ones. */
+    basic?: boolean;
+    /** Grouping key for form sections. */
+    group?: string;
+    /** Relative sort order, ascending. */
+    order?: number;
+    /** Seeds the field's policy as locked. */
+    locked?: boolean;
+    /**
+     * Which input suits the field (`_meta.ui.widget`, happyvertical/smrt#3611).
+     * Published manifests do not carry it yet, so `upstream/widgets.ts` fills it
+     * in when the catalog loads; a value in the manifest always wins.
+     */
+    widget?: CatalogFieldWidget;
+}
+/** The widget hints of happyvertical/smrt#3599. */
+export type CatalogFieldWidget = 'textarea' | 'currency' | 'email' | 'url' | 'phone';
+export interface CatalogField {
+    name: string;
+    type: CatalogFieldType;
+    required: boolean;
+    /** Manifest default, when it is a plain JSON value. */
+    default?: string | number | boolean | null;
+    /** Referenced model (a class name in this package, or a qualified name). */
+    related?: string;
+    /** Allowed values, when the manifest declares an enumeration. */
+    enum?: string[];
+    /** `@field({ ui })` hints: `basic`, `group`, `order`, `locked`. */
+    ui?: CatalogFieldUI;
+    /**
+     * The user-facing description from `@field({ description })`, when the
+     * package declares one. It feeds the help glossary.
+     */
+    description?: string;
+    /**
+     * Framework-managed (tenant id, timestamps): shown in the catalog but never
+     * in generated forms.
+     */
+    system?: boolean;
+}
+export interface CatalogRoute {
+    method: string;
+    /** Path as the REST generator mounts it, without the `/api` prefix. */
+    path: string;
+}
+export interface CatalogOperation {
+    /** CRUD verb or method name this surface performs. */
+    operation: string;
+    /** Tool or command name. */
+    name: string;
+}
+export interface CatalogMethod {
+    name: string;
+    async: boolean;
+    /** `name: type` parameter strings, optional ones suffixed with `?`. */
+    parameters: string[];
+    returnType: string;
+    /** An MCP tool exists for this method, so an AI agent can call it. */
+    aiCallable: boolean;
+}
+export interface CatalogModel {
+    /** `@scope/pkg:Class` qualified name. */
+    id: string;
+    /** Class name, e.g. `Product`. */
+    name: string;
+    /** Collection (REST resource) name, e.g. `products`. */
+    collection: string;
+    /** Qualified name of the model this one extends, when it is an STI child. */
+    extends?: string;
+    /** The class's description from the manifest, when the scanner emits one. */
+    description?: string;
+    /**
+     * The manifest's `displayLabelField` (happyvertical/smrt#3611): the own
+     * field that labels a record in pickers. Undeclared means the first of `name`,
+     * `title`, `label`, `code`; see `data/display.ts`.
+     */
+    display?: {
+        label: string;
+    };
+    fields: CatalogField[];
+    /** Generated REST routes. */
+    rest: CatalogRoute[];
+    /** Generated MCP tools. */
+    mcp: CatalogOperation[];
+    /** Generated CLI commands. */
+    cli: CatalogOperation[];
+    /** Public methods, with whether an AI agent can call them. */
+    methods: CatalogMethod[];
+    /** Qualified names of the models this model's fields reference. */
+    references: string[];
+    /**
+     * False for internal models (junction tables and the like) that expose no
+     * REST, MCP or CLI surface; they are listed but get no generated views.
+     */
+    exposed: boolean;
+}
+export interface CatalogPackage {
+    /** Short name used in URLs and the selection, e.g. `products`. */
+    id: string;
+    /** Full npm name, e.g. `@happyvertical/smrt-products`. */
+    packageName: string;
+    version: string;
+    description: string;
+    models: CatalogModel[];
+    /** Ids of other catalog packages this one needs (manifest + model refs). */
+    dependencies: string[];
+    /** Where the surfaces came from: the knowledge artifact or the manifest. */
+    surfaceSource: 'knowledge' | 'manifest';
+    /**
+     * Whether the package builds for a browser, as the manifest states it
+     * (smrt#3709). Absent for packages smrt does not measure and for manifests
+     * that predate it.
+     */
+    browser?: PackageBrowserCapability;
+    /**
+     * Recipes the package declares (smrt#3604), in declaration order. Absent
+     * when it declares none. The planner overlays its local-only parts
+     * (`forms`, `extends`) in `src/lib/recipes`.
+     */
+    recipes?: Recipe[];
+}
+export interface Catalog {
+    /** Schema version of this file. */
+    schema: 1;
+    /** Registry the catalog was generated from. */
+    registry: string;
+    /** Sorted by id. */
+    packages: CatalogPackage[];
+}

package/dist/catalog/types.js

@@ -0,0 +1,8 @@
+/**
+ * The static package catalog: the shape of `catalog.json`, which
+ * `pnpm catalog:generate` writes from the published `@happyvertical/smrt-*`
+ * packages' `manifest.json` (and `smrt-knowledge.json` where present).
+ *
+ * Everything the browser needs is here, so the app never loads a package.
+ */
+export {};