@happyvertical/smrt-app-shell 0.0.0-stage → 0.60.16

package/dist/engine/commands.d.ts

@@ -0,0 +1,94 @@
+import type { AppDefinition, FieldDef, MethodDef } from './definition.ts';
+export type Command = {
+    type: 'defineModel';
+    name: string;
+    label?: string;
+    fields?: Record<string, FieldDef>;
+} | {
+    type: 'addField';
+    model: string;
+    field: string;
+    definition: FieldDef;
+} | {
+    type: 'hideField';
+    model: string;
+    field: string;
+} | {
+    type: 'renameField';
+    model: string;
+    from: string;
+    to: string;
+} | {
+    type: 'removeField';
+    model: string;
+    field: string;
+} | {
+    type: 'changeFieldType';
+    model: string;
+    field: string;
+    to: FieldDef;
+} | {
+    type: 'removeModel';
+    model: string;
+} | {
+    type: 'addMethod';
+    model: string;
+    name: string;
+    method: MethodDef;
+} | {
+    type: 'enableRecipe';
+    recipe: string;
+}
+/**
+ * Undo the current version. `version` (optional) pins which version the
+ * caller means; the host refuses if the app has moved on since.
+ */
+ | {
+    type: 'undo';
+    version?: number;
+} | {
+    type: 'cleanUp';
+    keep: number;
+} | {
+    type: 'exportTemplate';
+    includeRecords?: boolean;
+} | {
+    type: 'importTemplate';
+    data: Template;
+};
+export type CommandType = Command['type'];
+export interface Plan {
+    summary: string;
+    risky: boolean;
+    /** Counts of values to archive, values that will not convert, rows in a removed model. */
+    preview?: Record<string, unknown>;
+    /** Methods whose code mentions a renamed field; their code is not rewritten. */
+    affectedMethods?: string[];
+}
+export interface ExecuteOptions {
+    author: string;
+    approved?: boolean;
+}
+/** A template: the definition (and optionally the records) of an app. */
+export interface Template {
+    format: 1;
+    exportedAt?: string;
+    definition: AppDefinition;
+    records?: Record<string, Record<string, unknown>[]>;
+}
+/**
+ * Commands that must be approved. `importTemplate` is risky only when the
+ * template carries method code (see {@link isRiskyCommand}); `undo` is risky
+ * only when the stored version being undone has a `convertColumn` step, which
+ * the host decides from the stored version (never from the caller), so it is
+ * not in this set.
+ */
+export declare const RISKY_COMMANDS: ReadonlySet<CommandType>;
+/** A migration step whose down path overwrites newer data with archived originals. */
+export declare function overwritesOnUndo(step: {
+    op: string;
+}): boolean;
+/** Static risk of a command. `undo` is decided by the host from the stored version. */
+export declare function isRiskyCommand(cmd: Command): boolean;
+/** Generated app tools that delete records need approval. */
+export declare function isRiskyTool(name: string): boolean;

package/dist/engine/commands.js

@@ -0,0 +1,30 @@
+/**
+ * Commands that must be approved. `importTemplate` is risky only when the
+ * template carries method code (see {@link isRiskyCommand}); `undo` is risky
+ * only when the stored version being undone has a `convertColumn` step, which
+ * the host decides from the stored version (never from the caller), so it is
+ * not in this set.
+ */
+export const RISKY_COMMANDS = new Set([
+    'addMethod',
+    'removeField',
+    'removeModel',
+    'changeFieldType',
+    'cleanUp',
+]);
+/** A migration step whose down path overwrites newer data with archived originals. */
+export function overwritesOnUndo(step) {
+    return step.op === 'convertColumn';
+}
+/** Static risk of a command. `undo` is decided by the host from the stored version. */
+export function isRiskyCommand(cmd) {
+    if (RISKY_COMMANDS.has(cmd.type))
+        return true;
+    if (cmd.type === 'importTemplate')
+        return Object.values(cmd.data?.definition?.models ?? {}).some((m) => Object.keys(m?.methods ?? {}).length > 0);
+    return false;
+}
+/** Generated app tools that delete records need approval. */
+export function isRiskyTool(name) {
+    return /_delete$/.test(name);
+}

package/dist/engine/definition.d.ts

@@ -0,0 +1,192 @@
+import type { RuntimeFieldType, RuntimeModelDefinition } from '@happyvertical/smrt-core';
+export declare const USER_PKG = "@local/app";
+export declare const FORMAT = 1;
+export type FieldType = 'text' | 'number' | 'integer' | 'boolean' | 'date' | 'money' | 'choice' | 'reference' | 'json';
+export interface FieldDef {
+    type: FieldType;
+    label?: string;
+    required?: boolean;
+    choices?: string[];
+    /** For `reference`: the name of another model of the app. */
+    ref?: string;
+    hidden?: boolean;
+}
+export interface MethodParamDef {
+    type: FieldType;
+    required?: boolean;
+}
+export interface MethodDef {
+    description: string;
+    params?: Record<string, MethodParamDef>;
+    /**
+     * JavaScript body of `function ({ record, params, data, app })`. Return a
+     * result; call `app.create/update/delete` to propose writes.
+     */
+    code: string;
+}
+export interface ModelDef {
+    label?: string;
+    /**
+     * Qualified name of a shipped model this app model extends (the app-subclass
+     * rule: `Profile` extends `@happyvertical/smrt-profiles:Profile`). The
+     * model's fields become nullable columns on the parent's table.
+     */
+    extends?: string;
+    fields: Record<string, FieldDef>;
+    methods?: Record<string, MethodDef>;
+}
+export interface AppDefinition {
+    format: 1;
+    name: string;
+    /** Shipped SMRT packages turned on. Only `profiles` for now. */
+    recipes: string[];
+    models: Record<string, ModelDef>;
+}
+export declare const EMPTY_APP: AppDefinition;
+export interface RecipeModel {
+    /** Qualified name of the shipped parent class. */
+    parent: string;
+    /** The parent's (shared, STI) table. */
+    table: string;
+    /**
+     * Class name the app subclass is registered under. It cannot be `Profile`
+     * yet: a second class named `Profile` makes the real package's own
+     * `Person`/`Organization` subclasses lose their STI base in the registry
+     * (see AGENTS.md, "Known core gap"). Flip this to the model name when core
+     * resolves a parent by qualified name.
+     */
+    className: string;
+    /** Fields the parent already has, in app terms. */
+    builtIn: Record<string, FieldDef>;
+}
+export interface Recipe {
+    /** Shipped classes whose tables are created first. */
+    tables: string[];
+    models: Record<string, RecipeModel>;
+}
+export declare const RECIPES: Record<string, Recipe>;
+/** The recipe model an app model extends, if it does. */
+export declare function recipeModelFor(model: string, md: ModelDef | undefined): RecipeModel | undefined;
+export declare const MAX_CODE_LENGTH = 20000;
+export declare const MAX_MODELS = 100;
+export declare const MAX_FIELDS = 200;
+export declare const MAX_METHODS = 50;
+export declare const MAX_PARAMS = 20;
+export declare const MAX_CHOICES = 200;
+export declare const FIELD_TYPES: readonly FieldType[];
+/** The regular expression field and method names must match (camelCase). */
+export declare const FIELD_NAME_PATTERN: string;
+/** A legal camelCase spelling of a rejected name, e.g. `due_date` -> `dueDate`. */
+export declare function suggestFieldName(name: string): string | undefined;
+export declare const snake: (s: string) => string;
+export declare function isValidModelName(s: string): boolean;
+export declare function isValidFieldName(s: string): boolean;
+export declare function tableFor(model: string, md?: ModelDef): string;
+/** Class name a model is registered under (generated tools use it). */
+export declare function classNameFor(model: string, md?: ModelDef): string;
+/** Route segment of the generated REST collection. */
+export declare function routeFor(model: string, md?: ModelDef): string;
+/**
+ * Whether a REST request may be served: only `/api/<route>` and
+ * `/api/<route>/<id or action>` of the app's own models. Core's generated
+ * handler also serves reserved endpoints (`sync/apply`, whose `delete` op
+ * deletes records, `_changes`, `_events`, ...) and any shipped class it can
+ * find in its registry; none of those belong to the app.
+ */
+export declare function restRouteAllowed(def: AppDefinition, rawUrl: string): boolean;
+/** Names of the generated tools: `<class>_list`, ... and one per method. */
+export declare function toolNamesFor(model: string, md: ModelDef): string[];
+/** Shipped (built-in) fields of an app model. */
+export declare function builtInFields(model: string, md: ModelDef | undefined): Record<string, FieldDef>;
+export declare function visible(fields: Record<string, FieldDef>): {
+    [k: string]: FieldDef;
+};
+export declare const sqlType: (t: FieldType) => string;
+export declare const runtimeType: (t: FieldType) => RuntimeFieldType;
+/** Storage family of a declared SQLite column type, to compare columns. */
+export declare function storageFamily(declared: string): string;
+/** Check a whole definition. Returns problems; empty means valid. */
+export declare function validate(def: unknown): string[];
+/** Changes that cannot be applied by only adding things. */
+export declare function refuseChanges(prev: AppDefinition, next: AppDefinition, converting?: Set<string>): string[];
+/** What the app looks like to the assistant and the page. */
+export declare function describeApp(def: AppDefinition, version: number): {
+    name: string;
+    version: number;
+    recipes: string[];
+    models: Record<string, DescribedModel>;
+};
+export interface DescribedModel {
+    kind: 'app' | 'shipped-subclass';
+    label: string;
+    table: string;
+    className: string;
+    extends: string | null;
+    fields: Record<string, FieldDef>;
+    ownFields: string[];
+    methods: Record<string, {
+        description: string;
+        params: Record<string, MethodParamDef>;
+    }>;
+}
+/** A model as core's `registerRuntimeModel` wants it (hidden fields left out). */
+export declare function toRuntimeModel(model: string, md: ModelDef): RuntimeModelDefinition;
+/**
+ * One database step of a definition change that is not purely additive. Each
+ * has an inverse, which undo runs. Additive changes (new tables and columns)
+ * need no step: the app runtime adds what the definition lacks.
+ */
+export type Step = {
+    op: 'renameColumn';
+    table: string;
+    from: string;
+    to: string;
+}
+/** Values are archived first, so undo can put them back. */
+ | {
+    op: 'dropColumn';
+    table: string;
+    key: string;
+    column: string;
+    type: FieldType;
+}
+/** Original values are archived; rows that do not convert become null. */
+ | {
+    op: 'convertColumn';
+    table: string;
+    key: string;
+    column: string;
+    from: FieldDef;
+    to: FieldDef;
+}
+/** The table is renamed out of the way, not dropped. */
+ | {
+    op: 'archiveTable';
+    table: string;
+    archivedAs: string;
+};
+export interface Migration {
+    steps: Step[];
+    /** 'up' applies steps; 'down' undoes them in reverse order. */
+    direction: 'up' | 'down';
+    /** The version whose steps these are (archives are keyed by it). */
+    version: number;
+}
+/** Convert one stored value to a field type. */
+export declare function convertValue(v: unknown, to: FieldDef): {
+    ok: boolean;
+    value: unknown;
+};
+export type Coerced = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Check a value against a field and convert it for storage. Shared by record
+ * writes and by the writes a method proposes, so both are held to one rule.
+ * References are only checked for shape here; the runtime checks the target.
+ */
+export declare function coerceValue(fd: FieldDef, v: unknown): Coerced;