/** * Phase 2 app-layer contract: the data-driven app definition schema. * * Every future app in kody-os is DATA matching these types, stored in * packageStorage() — never code. Adding an app writes its definition and state keys; it needs * no republish of the OS package and zero additional Kody packages. * * Identity follows the ReKindle registry pattern: `id` is the stable slug * (routes, storage keys), `name` is the display name, `label` the tile label. * `description` is the help text a human or agent reads to learn what the * app is for without reading its code. * * Browser-safe: this module has no imports at all (no kody:/node: imports), * so it can be shared between the Worker shell, MCP handlers, and any client. * * Kindle ceiling is ES2019: no ?. and no ?? anywhere in this file or its * importers (see the canonical ceiling in docs/scribe-limitations.md). */ export type FieldType = 'integer' | 'string' | 'boolean' | 'array' | 'object' export type ArgType = 'integer' | 'string' | 'boolean' /** Generic ops are `set` and `append`. `increment`, `toggle`, and `reset` are deprecated sugar kept until migration retires them. */ export type EffectOp = 'set' | 'append' | 'increment' | 'toggle' | 'reset' /** Deprecated allowlist value set for `UiDef.placements`. Kept only so old definitions still validate; it gates nothing. */ export type AppPlacement = 'page' | 'modal' | 'widget' /** How an app opens by default from the Apps page. A default, not a restriction: every app is allowed in every context. */ export type OpenAs = 'page' | 'modal' export interface StateFieldDef { type: FieldType /** Inclusive minimum (integer fields only). */ min?: number /** Inclusive maximum (integer fields only). */ max?: number /** Maximum string length (string fields only). */ maxLength?: number /** Element type (array fields only). Scalar element types, or 'object' for arrays of objects (schemaVersion 5); never nested arrays. */ items?: 'integer' | 'string' | 'boolean' | 'object' /** Maximum entry count (array fields only). */ maxItems?: number } /** A durable state value: scalars, arrays of scalars or objects, or a nested object (schemaVersion 5). Nested values must be JSON-serializable; see checkFieldValue in registry.ts for the depth and serializability rules. */ export type StateValue = number | string | boolean | Array> | Record export interface StateSchemaDef { type: 'object' /** Initial state written at add_app / import time. */ initial: Record /** Every key of `initial` must be declared here; no undeclared keys allowed. */ fields: Record } export interface ActionArgDef { type: ArgType required?: boolean default?: number | string | boolean /** Inclusive minimum (integer args only). */ min?: number /** Inclusive maximum (integer args only). */ max?: number /** Maximum string length (string args only). */ maxLength?: number } /** Deprecated sugar over `set`: prefer a `set` effect with a computed value. Kept until migration retires it. */ export interface IncrementEffect { op: 'increment' field: string /** Fixed step, or taken from an integer arg when `byArg` is set. */ by?: number byArg?: string } export interface SetEffect { op: 'set' field: string /** Fixed value, or taken from an arg when `fromArg` is set. In schemaVersion 5 the fixed value may be a nested object/array (JSON-serializable). */ value?: StateValue fromArg?: string } /** Deprecated sugar over `set`: prefer a `set` effect with a boolean value. Kept until migration retires it. */ export interface ToggleEffect { op: 'toggle' field: string } /** Deprecated sugar over `set`: prefer explicit `set` effects per field. Kept until migration retires it. */ export interface ResetEffect { op: 'reset' } export interface AppendEffect { op: 'append' /** Array field this entry is appended to. Must name a declared `array` state field. */ field: string /** Fixed entry value, or taken from an arg when `fromArg` is set. */ value?: number | string | boolean fromArg?: string /** Maximum entries kept after append (oldest entries drop first). */ cap?: number /** Maximum UTF-8 bytes per string entry. */ maxEntryBytes?: number } export type ActionEffect = SetEffect | AppendEffect | IncrementEffect | ToggleEffect | ResetEffect export interface ActionDef { description?: string args?: Record /** Legacy single effect (schemaVersion 3). Exactly one of `effect` / `effects` must be present. */ effect?: ActionEffect /** V2 sequence (schemaVersion 4): applied in order to a state copy, then validated + written once. */ effects?: ActionEffect[] } export interface UiActionDef { /** Action name this button submits. Must exist in `actions`. */ action: string label: string } export interface UiDef { title?: string /** Default open mode from the Apps page. Omitted means page. */ openAs?: OpenAs /** Deprecated: old allowlist. When present without `openAs`, it derives it (modal-only → modal, otherwise page); `openAs` wins on disagreement. */ placements?: AppPlacement[] /** Buttons the shell renders as plain forms. Empty = read-only app page. */ actions?: UiActionDef[] /** Visually hide the server-rendered state readout (stays in the DOM so bundle scripts can read initial state). Use when the bundle already displays state. */ hideState?: boolean /** Also show this app in the top menu bar when installed. Author-controlled, not a user toggle; hidden apps are excluded from the menu. Defaults to false. */ menuBar?: boolean /** Plain-text how-to-use text shown in the app-header help dialog (the `[?]` box left of expand). Never interpreted as HTML or markdown. Distinct from `description`, which is the "what this app is for" text shown on the app page body and as a tile tooltip. Absent means no help button. */ help?: string } export interface BundleManifest { /** Entry file. Must be 'index.html'. */ entry: string /** Bundle files, in one of two forms (never both — carrying both is an error): * - inline map (`Record`): the transport and stored form. * `add_app` carries contents inline (an agent can only pass JSON) and * installed definitions store contents inline, so the runtime, canonical, * and stored forms are always the map. * - manifest list (`string[]`): the on-disk authoring form. Each catalog * app directory holds `definition.json` (metadata plus this manifest) * alongside the real bundle files (`index.html` required, plus optional * `.js` / `.css`, flat next to `definition.json` and `RECIPE.md`). * Tooling (`scripts/build-catalog-index.ts`, the catalog harness, and * `assembleBundleFiles` in `registry.ts`) resolves the list to the * runtime map before validating references, fingerprinting, or storing. * Only .html/.js/.css, no '..', no absolute paths. */ files: Record | string[] } export interface FeedDecl { /** Feed slug used in the route: GET /feed//. Same slug rule as app ids. */ name: string /** Upstream feed URL. HTTPS only; validated at install and again at serve time. */ url: string /** Cache lifetime in seconds. Defaults to 3600. Range 60..86400. */ ttlSeconds?: number /** Maximum upstream body kept, in characters. Defaults to 65536. Range 1024..262144. */ maxBytes?: number } /** Generic upstream proxy entry, shaped like a feed declaration. * Route: GET /proxy//. The route never takes a URL from * the request: only a declared entry, matched by name against the * stored definition, is fetched. */ export interface ProxyDecl { /** Proxy slug used in the route: GET /proxy//. Same slug rule as app ids. */ name: string /** Upstream URL. HTTPS only; validated at install and again at serve time. */ url: string /** Cache lifetime in seconds. Defaults to 3600. Range 60..86400. */ ttlSeconds?: number /** Maximum upstream body kept, in characters. Defaults to 65536. Range 1024..262144. */ maxBytes?: number } /** Optional server-side capabilities an app declares. Apps remain data: the * package implements each capability generically; a definition only names * what it needs, never code. Declared capabilities are installer * disclosure (shown before install, and an update adding one requires * confirmation) plus a server-side allowlist for honest apps — not a * sandbox: bundle scripts run same-origin with session authority, so a * declaration does not stop a malicious bundle from calling a shell * route directly. See bundle-capabilities. */ export interface AppCapabilities { /** Allowlisted upstream feeds this app may read through GET /feed//. */ feeds?: FeedDecl[] /** True when the app may use the shell's app management API * (read store rows, install, update, restore from the catalog). * The API refuses callers whose stored definition does not declare * this, with the feed-style plain 404. */ manageApps?: boolean /** Allowlisted generic upstreams this app may read through * GET /proxy//. */ proxy?: ProxyDecl[] /** Shell theme access through GET /theme/: `view` allows the * read route, `set` allows set and reset. A definition with neither * flag true is treated as not declaring theme. */ theme?: { view: boolean; set: boolean } } /** Legacy helper kept for import compatibility. Every unified app carries a bundle manifest, so this returns true when a bundle manifest is present. */ export function isBundleDefinition(def: AppDefinition): boolean { if (!def) return false var rec = def as unknown as Record return rec['bundle'] !== undefined && rec['bundle'] !== null } /** * Definition schema version stamped into every installed app. Single source * of truth: bump it on any breaking definition change and ship a migration in * the same release (same pattern as the kody-os-app/1 to /2 importer). * * 1 = operator-only era (no bundle; `kind` discriminated the renderer) * 2 = bundle-kind era (bundle manifest, still `kind`-discriminated) * 3 = unified era (one shape: meta + bundle + stateSchema + actions, single `effect`) * 4 = v2 effects era (one shape with `effects[]` sequence; `ui.template` removed) * 5 = bridge era (JSON seed + bridge-owned store; nested/object state values allowed; `ui.template` still removed) */ export var DEFINITION_SCHEMA_VERSION = 5 export interface AppDefinition { /** Stable slug: ^[a-z0-9][a-z0-9-]{0,63}$ . Identity: routes, storage keys. */ id: string /** Human display name. */ name: string /** Tile label. Defaults to `name` when omitted. */ label?: string /** * Definition schema version this app was stamped with at install time. * Pre-version installs backfill on read; see DEFINITION_SCHEMA_VERSION * for the era history. */ schemaVersion: number /** * Catalog version: a positive integer, starting at 1 on the app's * first versioned catalog release, +1 on any change to its catalog * definition file. Distinct from schemaVersion (definition format * era) and from the package version. Required only for catalog * definitions (see validateCatalogDefinition); a generic add_app * definition without it stays valid, and a stored copy preserves * the value it was installed with. */ catalogVersion?: number /** * Install mode for a catalog app. Absent means `'json'`: unattended * install from the definition alone. Only an app with a non-trivial * recipe that MUST be installed via its recipe carries this field * (`'recipe-only'` — the Store shows the recipe prompt in place of * one-tap install; no current catalog app uses it). Excluded from * the definition fingerprint, like catalogVersion, so adding it * changes no installed app's status. */ installMode?: 'json' | 'recipe-only' /** * Minimum shell (package) version this app requires: an optional * `MAJOR.MINOR.PATCH` string (numeric parts, no pre-release, no * build metadata). Absent means no minimum. A present but malformed * value fails definition validation and nothing is installed. * Fingerprinted definition content (unlike `installMode`): adding * or changing it requires a `catalogVersion` +1 by the existing rule. */ minPackageVersion?: string /** * Tile icon: a plain-text glyph or short mark (system fonts only, never * emoji), OR an inline SVG starting with ` } export type AppState = Record export interface AppSummary { id: string name: string label: string /** Definition schema version, backfilled on read for pre-version installs. */ schemaVersion: number icon?: string category?: string description?: string /** Default open mode from the Apps page (always present; derived from deprecated `placements` for old stored definitions). */ openAs: OpenAs /** True when the definition carries `ui.menuBar: true`. Always present; false when the field is absent. */ menuBar: boolean } export interface ActOk { ok: true state: AppState } export interface ActErr { ok: false error: string } export type ActResult = ActOk | ActErr export interface AppExport { format: 'kody-os-app/2' exportedAt: string definition: AppDefinition /** State snapshot at export time; import restores it when present. */ state: AppState }