/** * Reference implementation of the Phase 2 app-layer contract. * * Server-side only (uses storage.ts). Callable signatures for the MCP * interface from the handoff Phase 2 + clarification: * * list_apps() -> AppSummary[] * get_app_state(id) -> AppState * act(id, action, args?) -> { ok, state? | error? } * add_app(definition) -> definition/state write only, no republish * remove_app(id) -> uninstall definition + state + all reference lists * export_app(id) -> complete AppExport JSON * plus: get_app(id), import_app(json) — blank-install import without code changes * * Rules enforced: state lives in storage; every action is validated BEFORE * any mutation; a bad action returns { ok:false } and the stored state is * untouched (state is computed on a copy and written with a single set). * * Identity follows ReKindle: `id` is the stable slug (routes, storage keys), * `name` the display name. Export format is kody-os-app/2; v1 payloads and * bare definitions import with id derived from name. * * ES2019 ceiling: no ?. and no ?? in this file (see the canonical ceiling in docs/scribe-limitations.md). */ import type { ActionDef, ActResult, AppDefinition, AppExport, OpenAs, AppState, AppSummary, ProxyDecl, StateFieldDef, } from './types.ts' import { catalogGitHubRef, catalogLabelForBase, catalogTagLabel, devOverrideBase, get_catalog_definition, get_catalog_entry, list_catalog, normalizeCatalogBase, readCatalogManifest, get_catalog_source, folderUrlForBase } from './remote-catalog.ts' import { RECENT_CAP, createMemoryStore, defKey, deleteKey, readHidden, readHomepage, readJson, readPinned, readRecent, resolveStore, stateKey, writeHidden, writeHomepage, writeJson, writePinned, writeRecent, type KeyStore, } from './storage.ts' import { DEFINITION_SCHEMA_VERSION } from './types.ts' import { APPEND_CAP, APPEND_MAX_ENTRY_BYTES, backfillDefinition, byteLength, checkFieldValue, cloneState, coerceArg, capabilityAdditions, compileDefinition, comparePackageVersions, deriveOpenAs, fingerprintDefinition, isRecord, MIN_SUPPORTED_SCHEMA_VERSION, NAME_RE, summarizeCapabilities, parsePackageVersion, reqStr, validateDefinition, } from './definition.ts' export { APPEND_CAP, APPEND_MAX_ENTRY_BYTES, assembleBundleFiles, BUNDLE_CAP_BYTES, canonicalizeDefinition, capabilityAdditions, comparePackageVersions, deriveOpenAs, fingerprintDefinition, isSvgIcon, migrateAction, migrateDefinition, MIN_SUPPORTED_SCHEMA_VERSION, parsePackageVersion, summarizeCapabilities, SUPPORTED_SCHEMA_VERSIONS, validateBundleReferences, validateCatalogDefinition, validateDefinition, sanitizeSvgIcon, } from './definition.ts' export type { CapabilitySummary } from './definition.ts' import type { CapabilitySummary } from './definition.ts' var EXPORT_FORMAT = 'kody-os-app/2' var EXPORT_FORMAT_V1 = 'kody-os-app/1' /** * Catalog apps retired into built-in shell pages. An upgraded store that * still has one of these rows must not show a stale app beside the shell * page, so the row is pruned the next time the installed list is derived. */ var RETIRED_APP_IDS = ['help', 'about'] var DEF_PREFIX = 'kody-os.apps.def.' var runningPackageVersionPromise: Promise | null = null /** * Running shell (package) version: read from `pkg/package.json` via a * dynamic JSON import (the bundler inlines it when present), the same * source the status bar reads via `getPackageMeta()` in `src/app.ts`. * Falls back to `0.1.0` when the manifest is absent. `build` is ignored: * only `version` (`MAJOR.MINOR.PATCH`) is a compatibility signal. */ export function getRunningPackageVersion(): Promise { if (runningPackageVersionPromise !== null) return runningPackageVersionPromise try { // @ts-ignore optional manifest; the bundler inlines it when present. var req = import('../../package.json', { with: { type: 'json' } }) runningPackageVersionPromise = req.then( function (m: unknown): string { try { var rec = m as { default?: unknown } | null var body = rec && typeof rec === 'object' && 'default' in rec ? rec.default : m if (body && typeof body === 'object') { var v = (body as { version?: unknown }).version if (typeof v === 'string' && parsePackageVersion(v) !== null) return v } } catch (err) { } return '0.1.0' }, function (): string { return '0.1.0' } ) } catch (err) { runningPackageVersionPromise = Promise.resolve('0.1.0') } return runningPackageVersionPromise } function loadEntry( store: KeyStore, id: string, ): Promise<{ definition: AppDefinition; state: AppState } | { error: string }> { if (RETIRED_APP_IDS.indexOf(id) !== -1) return Promise.resolve({ error: 'unknown app "' + id + '"' }) return Promise.all([ readJson(store, defKey(id)), readJson(store, stateKey(id)), ]).then(function (pair): { definition: AppDefinition; state: AppState } | { error: string } { var definition = pair[0] var state = pair[1] if (!definition) return { error: 'unknown app "' + id + '"' } if (!state) return { error: 'app "' + id + '" has no state' } return { definition: backfillDefinition(definition), state: state } }) } export interface ListAppsOptions { includeHidden?: boolean } function isKeyStore(value: unknown): value is KeyStore { return value !== null && typeof value === 'object' && typeof (value as KeyStore).get === 'function' && typeof (value as KeyStore).set === 'function' } /** Read pinned ids in pin order. Missing keys read as empty. */ export function get_pinned(store?: KeyStore): Promise { return resolveStore(store).then(function (active: KeyStore) { return readPinned(active) }) } /** Read hidden ids. Missing keys read as empty. */ export function get_hidden(store?: KeyStore): Promise { return resolveStore(store).then(function (active: KeyStore) { return readHidden(active) }) } /** Read recent ids, most recent first. Missing keys read as empty. */ export function get_recent(store?: KeyStore): Promise { return resolveStore(store).then(function (active: KeyStore) { return readRecent(active) }) } /** Read homepage ids in dashboard order. Missing keys read as empty. */ export function get_homepage(store?: KeyStore): Promise { return resolveStore(store).then(function (active: KeyStore) { return readHomepage(active) }) } /** * Read the whole launcher state in one call, in stored order, missing * keys as []. Recency is read internally here and is NOT a separate * root export: recency stays internal by the 2026-10-30 direction, but * the aggregate still lets an agent verify a removal scrubbed every * list, recent included. Reads never write. */ export function get_launcher_state(store?: KeyStore): Promise<{ pinned: string[]; hidden: string[]; recent: string[]; homepage: string[] }> { return resolveStore(store).then(function (active: KeyStore) { return listInstalledIds(active).then(function (derived: string[]): Promise<{ pinned: string[]; hidden: string[]; recent: string[]; homepage: string[] }> { return pruneRetiredApps(derived, active).then(function (): Promise<{ pinned: string[]; hidden: string[]; recent: string[]; homepage: string[] }> { return Promise.all([readPinned(active), readHidden(active), readRecent(active), readHomepage(active)]).then(function (parts) { return { pinned: parts[0], hidden: parts[1], recent: parts[2], homepage: parts[3] } }) }) }) }) } /** Overwrite the homepage order list (order matters). */ export function set_homepage(ids: string[], store?: KeyStore): Promise { return resolveStore(store).then(function (active: KeyStore) { return writeHomepage(active, ids) }) } /** Set or clear one homepage entry. Keeps order (new entries append). */ export function set_home(id: string, want: boolean, store?: KeyStore): Promise { return resolveStore(store).then(function (active: KeyStore) { return readHomepage(active).then(function (ids: string[]): Promise { var at = ids.indexOf(id) if (want && at === -1) ids.push(id) if (!want && at !== -1) ids.splice(at, 1) return writeHomepage(active, ids).then(function (): string[] { return ids }) }) }) } /** Move one homepage entry up (-1) or down (+1). Single list write. */ export function move_home(id: string, delta: number, store?: KeyStore): Promise { return resolveStore(store).then(function (active: KeyStore) { return readHomepage(active).then(function (ids: string[]): Promise { var at = ids.indexOf(id) if (at === -1) return Promise.resolve(ids) var to = at + (delta < 0 ? -1 : 1) if (to < 0 || to >= ids.length) return Promise.resolve(ids) var next = ids.slice() next.splice(at, 1) next.splice(to, 0, id) return writeHomepage(active, next).then(function (): string[] { return next }) }) }) } /** Overwrite the pinned list (order matters). */ export function set_pinned(ids: string[], store?: KeyStore): Promise { return resolveStore(store).then(function (active: KeyStore) { return writePinned(active, ids) }) } /** Overwrite the hidden list. */ export function set_hidden(ids: string[], store?: KeyStore): Promise { return resolveStore(store).then(function (active: KeyStore) { return writeHidden(active, ids) }) } /** Empty the recency list without touching apps, pins, or hidden flags. */ export function clear_recent(store?: KeyStore): Promise { return resolveStore(store).then(function (active: KeyStore) { return writeRecent(active, []) }) } /** Move one app id to the front of recency (dedupe, capped). */ export function record_use(id: string, store?: KeyStore): Promise { return resolveStore(store).then(function (active: KeyStore) { return readRecent(active).then(function (ids: string[]): Promise { var next: string[] = [id] for (var i = 0; i < ids.length; i++) { if (ids[i] !== id) next.push(ids[i]) } next = next.slice(0, RECENT_CAP) return writeRecent(active, next).then(function (): string[] { return next }) }) }) } /** Set or clear one pin. Keeps pin order (new pins append). */ export function set_pin(id: string, want: boolean, store?: KeyStore): Promise { return resolveStore(store).then(function (active: KeyStore) { return readPinned(active).then(function (ids: string[]): Promise { var at = ids.indexOf(id) if (want && at === -1) ids.push(id) if (!want && at !== -1) ids.splice(at, 1) return writePinned(active, ids).then(function (): string[] { return ids }) }) }) } /** Set or clear one hidden flag. */ export function set_hide(id: string, want: boolean, store?: KeyStore): Promise { return resolveStore(store).then(function (active: KeyStore) { return readHidden(active).then(function (ids: string[]): Promise { var at = ids.indexOf(id) if (want && at === -1) ids.push(id) if (!want && at !== -1) ids.splice(at, 1) return writeHidden(active, ids).then(function (): string[] { return ids }) }) }) } /** * Installed ids, derived from definition keys: paginate * `list({ prefix: 'kody-os.apps.def.' })` to completion and return * the id suffix of each key, in key order (alphabetical by id). * A store without `list()` throws a clear error naming the store * instead of silently reporting an empty install. `pageSize` is * test-only; production uses the Kody default (250). */ export function listInstalledIds(store: KeyStore, pageSize?: number): Promise { if (typeof store.list !== 'function') return Promise.reject(new Error('listInstalledIds: this store has no list() method, so installed apps cannot be enumerated from definition keys')) var size = pageSize !== undefined ? pageSize : 250 var ids: string[] = [] function page(startAfter?: string): Promise { var options: { prefix: string; pageSize?: number; startAfter?: string } = { prefix: DEF_PREFIX, pageSize: size } if (startAfter !== undefined) options.startAfter = startAfter return Promise.resolve(store.list(options)).then(function (result) { for (var i = 0; i < result.entries.length; i++) { ids.push(result.entries[i].key.slice(DEF_PREFIX.length)) } if (result.truncated) { if (result.nextStartAfter === null) return Promise.reject(new Error('listInstalledIds: truncated page without nextStartAfter')) return page(result.nextStartAfter) } return ids }) } return page() } /** * Drop retired-app rows (and their state, snapshot, and launcher entries) * left installed before Help/About became shell pages. Filters the * derived installed ids, returning the survivors. A clean store is * read-only: no write happens when no retired id is present. */ function pruneRetiredApps(ids: string[], store: KeyStore): Promise { var retired: string[] = [] for (var i = 0; i < ids.length; i++) { if (RETIRED_APP_IDS.indexOf(ids[i]) !== -1) retired.push(ids[i]) } if (retired.length === 0) return Promise.resolve(ids) var kept = ids.filter(function (one: string): boolean { return RETIRED_APP_IDS.indexOf(one) === -1 }) var chain: Promise = Promise.resolve() for (var r = 0; r < retired.length; r++) { ;(function (id: string): void { chain = chain .then(function (): Promise { return deleteKey(store, defKey(id)) }) .then(function (): Promise { return deleteKey(store, stateKey(id)) }) .then(function (): Promise { return deleteInstallSnapshot(store, id) }) })(retired[r]) } return chain.then(function (): Promise { function clean(list: string[]): string[] { return list.filter(function (one: string): boolean { return RETIRED_APP_IDS.indexOf(one) === -1 }) } return Promise.all([readPinned(store), readHidden(store), readRecent(store), readHomepage(store)]).then(function (lists): Promise { return writePinned(store, clean(lists[0])) .then(function () { return writeHidden(store, clean(lists[1])) }) .then(function () { return writeRecent(store, clean(lists[2])) }) .then(function () { return writeHomepage(store, clean(lists[3])) }) .then(function (): string[] { return kept }) }) }) } /** List every installed app, in alphabetical-by-id (key) order. Read-only apart from retiring stale rows. */ export function list_apps(store?: KeyStore, opts?: ListAppsOptions): Promise { var activeStore: KeyStore | undefined = store var options: ListAppsOptions | undefined = opts if (store && !isKeyStore(store)) { options = store as unknown as ListAppsOptions activeStore = undefined } return resolveStore(activeStore).then(function (active: KeyStore): Promise { var hiddenP: Promise = options && options.includeHidden === false ? readHidden(active) : Promise.resolve([] as string[]) return hiddenP.then(function (hidden: string[]): Promise { return listInstalledIds(active).then(function (derived: string[]): Promise { return pruneRetiredApps(derived, active).then(function (ids: string[]): Promise { var out: AppSummary[] = [] var chain = Promise.resolve() for (var id of ids) { ;(function (want: string): void { chain = chain.then(function (): Promise { if (hidden.indexOf(want) !== -1) return Promise.resolve() return readJson(active, defKey(want)).then(function (raw): void { if (!raw) return var def = backfillDefinition(raw) out.push({ id: def.id, name: def.name, label: def.label || def.name, schemaVersion: def.schemaVersion, icon: def.icon, category: def.category, description: def.description, openAs: deriveOpenAs(def.ui), menuBar: def.ui.menuBar === true, }) }) }) })(id) } return chain.then(function (): AppSummary[] { return out }) }) }) }) }) } /** Read one app's definition plus live state. */ export function get_app( id: string, store?: KeyStore, ): Promise<{ definition: AppDefinition; state: AppState } | { error: string }> { return resolveStore(store).then(function (active: KeyStore) { return loadEntry(active, id) }) } /** Read one app's live state (UI refresh and MCP poll the same value). */ export function get_app_state(id: string, store?: KeyStore): Promise { return resolveStore(store).then(function (active: KeyStore) { return loadEntry(active, id).then(function (entry) { if ('error' in entry) return { error: entry.error } return entry.state }) }) } /** * Run one declarative action. Validates everything before mutating; writes the * new state with a single set. A bad action returns { ok:false } and the * stored state is untouched. */ export function act( id: string, action: string, args?: Record, store?: KeyStore, ): Promise { return resolveStore(store).then(function (active: KeyStore): Promise { return loadEntry(active, id).then(function (entry): Promise { if ('error' in entry) return Promise.resolve({ ok: false as const, error: entry.error }) var definition = entry.definition var state = entry.state // Unified shape: every app carries bundle files plus state plus actions, // so act() runs on all apps with no bundle refusal. (The legacy kind // discriminator and the /probe* routes are retired; the probe is a // unified bundle app that persists via act().) var actionTable: Record | undefined = definition.actions var actionDef: ActionDef | undefined = actionTable ? actionTable[action] : undefined if (!actionDef) { return Promise.resolve({ ok: false as const, error: 'unknown action "' + action + '" for app "' + id + '"' }) } // 1. Resolve + validate args against the action's arg schema. var resolved: Record = {} var argSchema = actionDef.args || {} for (var argName of Object.keys(argSchema)) { var argDef = argSchema[argName] var raw: unknown = args ? args[argName] : undefined if (raw === undefined) { if (argDef.required !== true && argDef.default !== undefined) { resolved[argName] = argDef.default continue } if (argDef.required === true) { return Promise.resolve({ ok: false as const, error: 'missing required arg "' + argName + '"' }) } continue } var coerced = coerceArg(argDef.type, raw) if (coerced.error || coerced.value === undefined) { return Promise.resolve({ ok: false as const, error: 'invalid arg "' + argName + '": ' + coerced.error }) } if (argDef.type === 'integer' && typeof coerced.value === 'number') { if (argDef.min !== undefined && coerced.value < argDef.min) { return Promise.resolve({ ok: false as const, error: 'arg "' + argName + '" must be >= ' + argDef.min }) } if (argDef.max !== undefined && coerced.value > argDef.max) { return Promise.resolve({ ok: false as const, error: 'arg "' + argName + '" must be <= ' + argDef.max }) } } if (argDef.type === 'string' && typeof coerced.value === 'string' && argDef.maxLength !== undefined && coerced.value.length > argDef.maxLength) { return Promise.resolve({ ok: false as const, error: 'arg "' + argName + '" must be at most ' + argDef.maxLength + ' characters', }) } resolved[argName] = coerced.value } // 2. Apply the declarative effects to a COPY — storage untouched so far. // v3 definitions carry single `effect`; v4 carries `effects[]`. var rawAction = actionDef as unknown as Record var seq: unknown[] = [] if (Array.isArray(rawAction['effects'])) seq = rawAction['effects'] as unknown[] else if (isRecord(rawAction['effect'])) seq = [rawAction['effect']] else { return Promise.resolve({ ok: false as const, error: 'action "' + action + '" has no effects' }) } var next = cloneState(state) var applyError: string | null = null for (var si = 0; si < seq.length; si++) { if (applyError) break var effect = seq[si] as import('./types.ts').ActionEffect if (effect.op === 'set') { var value: unknown = effect.fromArg !== undefined ? resolved[effect.fromArg] : effect.value if (value === undefined) { applyError = 'set action "' + action + '" has no value' break } next[effect.field] = value as number | string | boolean } else if (effect.op === 'append') { var entryValue: unknown = effect.fromArg !== undefined ? resolved[effect.fromArg] : effect.value if (entryValue === undefined) { applyError = 'append action "' + action + '" has no value' break } var list = next[effect.field] if (!Array.isArray(list)) { applyError = 'field "' + effect.field + '" is not an array' break } if (typeof entryValue === 'string') { var maxEntry = effect.maxEntryBytes !== undefined ? effect.maxEntryBytes : APPEND_MAX_ENTRY_BYTES if (byteLength(entryValue) > maxEntry) { applyError = 'append entry exceeds ' + maxEntry + ' bytes' break } } var grown = (list as Array).concat([entryValue as number | string | boolean]) var cap = effect.cap !== undefined ? effect.cap : APPEND_CAP if (grown.length > cap) grown = grown.slice(grown.length - cap) next[effect.field] = grown } else if (effect.op === 'increment') { // Deprecated sugar over set: computes the next integer and sets it. // Kept until migration retires it; prefer a set effect instead. var step: unknown = effect.byArg !== undefined ? resolved[effect.byArg] : effect.by !== undefined ? effect.by : 1 if (typeof step !== 'number' || !Number.isSafeInteger(step)) { applyError = 'increment step for "' + effect.field + '" is not a safe integer' break } var current = next[effect.field] if (typeof current !== 'number') { applyError = 'field "' + effect.field + '" is not an integer' break } next[effect.field] = current + step } else if (effect.op === 'toggle') { // Deprecated sugar over set: negates the boolean field via set. // Kept until migration retires it; prefer a set effect instead. var cur = next[effect.field] if (typeof cur !== 'boolean') { applyError = 'field "' + effect.field + '" is not a boolean' break } next[effect.field] = !cur } else if (effect.op === 'reset') { // Deprecated sugar over set: resets every field to its initial // value via set. Kept until migration retires it. var fresh = cloneState(definition.stateSchema.initial) for (var k of Object.keys(next)) delete next[k] for (var fk of Object.keys(fresh)) next[fk] = fresh[fk] } else { applyError = 'unknown effect op "' + String((effect as unknown as Record)['op']) + '"' break } } if (applyError) { return Promise.resolve({ ok: false as const, error: applyError }) } // 3. Validate the resulting state against the schema BEFORE writing. for (var field of Object.keys(definition.stateSchema.fields)) { var ferr = checkFieldValue(field, definition.stateSchema.fields[field], next[field]) if (ferr) { return Promise.resolve({ ok: false as const, error: 'action "' + action + '" rejected: ' + ferr }) } } // 4. Single write — the only mutation point. return writeJson(active, stateKey(id), next).then(function (): Promise { return record_use(id, active).then(function (): ActResult { return { ok: true, state: next } }) }) }) }) } export interface AddAppOptions { resetState?: boolean migrate?: Record } /** * Install a unified app definition. Validate-all-first, then a definition * write followed by a state write. A failed call writes * nothing: storage is byte-identical to before the call. * * Same-id overwrite preserves state by default (declared fields carried * forward, dropped fields reset to `initial`) and leaves * pins, hidden flags, homepage placement, and recent entries untouched. * `resetState: true` restores the legacy wipe; `migrate` maps old field * names to new ones with validator-checked values (unmappable aborts). */ export function add_app( definition: AppDefinition, store?: KeyStore | AddAppOptions, opts?: AddAppOptions, ): Promise<{ ok: true; id: string } | { ok: false; error: string }> { var activeStore: KeyStore | undefined = undefined var options: AddAppOptions = {} if (store && isKeyStore(store)) { activeStore = store if (opts) options = opts } else if (store && typeof store === 'object') { options = store as AddAppOptions } if (typeof definition.schemaVersion === 'number' && definition.schemaVersion < MIN_SUPPORTED_SCHEMA_VERSION) { return Promise.resolve({ ok: false as const, error: 'App "' + definition.id + '" requires schema version ' + MIN_SUPPORTED_SCHEMA_VERSION + ' (has ' + definition.schemaVersion + ')' }) } var compiled = compileDefinition(definition) if (!compiled.ok) return Promise.resolve({ ok: false as const, error: compiled.error }) var def: AppDefinition = compiled.definition return getRunningPackageVersion().then(function (running: string) { if (definition.minPackageVersion !== undefined) { var min = parsePackageVersion(definition.minPackageVersion) var run = parsePackageVersion(running) if (min !== null && run !== null && comparePackageVersions(run, min) < 0) { return { ok: false as const, error: 'App "' + definition.id + '" requires package version ' + definition.minPackageVersion + ' (running ' + running + ')' } } } return resolveStore(activeStore).then(function (active: KeyStore) { return Promise.all([ readJson(active, defKey(definition.id)), readJson(active, stateKey(definition.id)), ]).then(function (pair): Promise<{ ok: true; id: string } | { ok: false; error: string }> { var existing = pair[0] var existingState = pair[1] if (options.resetState === true && options.migrate !== undefined) { return Promise.resolve({ ok: false as const, error: 'add_app options resetState and migrate are mutually exclusive' }) } if (!existing && definition.schemaVersion !== DEFINITION_SCHEMA_VERSION) { return Promise.resolve({ ok: false as const, error: 'definition.schemaVersion ' + definition.schemaVersion + ' is stale for a new app; send the current version ' + DEFINITION_SCHEMA_VERSION + ' (re-adding an existing id restamps it)', }) } var candidate: AppState var freshInitial = cloneState(definition.stateSchema.initial as AppState) if (!existing) { candidate = freshInitial } else if (options.resetState === true) { candidate = freshInitial } else { candidate = cloneState(freshInitial) var newFields = definition.stateSchema.fields as Record var stored: AppState = existingState ? existingState : ({} as AppState) for (var fname of Object.keys(newFields)) { if (fname in stored) { var perr = checkFieldValue(fname, newFields[fname], stored[fname]) if (perr) { return Promise.resolve({ ok: false as const, error: 'preserved state invalid: ' + perr }) } candidate[fname] = stored[fname] } } if (options.migrate !== undefined) { if (!isRecord(options.migrate)) { return Promise.resolve({ ok: false as const, error: 'add_app migrate must be an object mapping old field names to new ones' }) } var mapping = options.migrate as Record for (var oldName of Object.keys(mapping)) { var newName = mapping[oldName] if (typeof newName !== 'string') { return Promise.resolve({ ok: false as const, error: 'migrate maps old field "' + oldName + '" to a non-string field name' }) } if (!(oldName in stored)) { return Promise.resolve({ ok: false as const, error: 'migrate maps unknown old field "' + oldName + '"' }) } if (!(newName in newFields)) { return Promise.resolve({ ok: false as const, error: 'migrate maps to unknown new field "' + newName + '"' }) } var merr = checkFieldValue(newName, newFields[newName], stored[oldName]) if (merr) { return Promise.resolve({ ok: false as const, error: 'migrate value invalid: ' + merr }) } candidate[newName] = stored[oldName] } } } for (var cfield of Object.keys(def.stateSchema.fields)) { var cerr = checkFieldValue(cfield, def.stateSchema.fields[cfield], candidate[cfield]) if (cerr) { return Promise.resolve({ ok: false as const, error: 'candidate state invalid: ' + cerr }) } } return writeJson(active, defKey(def.id), def) .then(function () { return writeJson(active, stateKey(def.id), candidate) }) .then(function (): { ok: true; id: string } { return { ok: true as const, id: def.id } }) }) }) }) } /** * Uninstall an app: delete its definition and state and scrub every reference * list (pinned, hidden, recent, homepage). Validation runs before any write: * an unknown id returns { ok:false } and storage is untouched. */ export function remove_app( id: string, store?: KeyStore, ): Promise<{ ok: true; id: string } | { ok: false; error: string }> { return resolveStore(store).then(function (active: KeyStore) { return readJson(active, defKey(id)).then(function (def) { if (!def) { return { ok: false as const, error: 'unknown app "' + id + '"' } } return Promise.all([readPinned(active), readHidden(active), readRecent(active), readHomepage(active)]).then(function (lists) { var pinned = lists[0].filter(function (one: string): boolean { return one !== id }) var hidden = lists[1].filter(function (one: string): boolean { return one !== id }) var recent = lists[2].filter(function (one: string): boolean { return one !== id }) var homepage = lists[3].filter(function (one: string): boolean { return one !== id }) return writePinned(active, pinned) .then(function () { return writeHidden(active, hidden) }) .then(function () { return writeRecent(active, recent) }) .then(function () { return writeHomepage(active, homepage) }) .then(function () { return deleteKey(active, stateKey(id)) }) .then(function () { return deleteKey(active, defKey(id)) }) .then(function () { return deleteInstallSnapshot(active, id) }) .then(function (): { ok: true; id: string } { return { ok: true as const, id: id } }) }) }) }) } /** * The catalog base a Store declares in its own definition: the `proxy` * entry named `catalog`. The shell fetches that Store's catalog only * from the declared base. Returns null when the definition declares * no `catalog` entry or the entry has no usable URL. */ export function declaredCatalogBase(def: AppDefinition | null | undefined): string | null { if (!def || !def.capabilities || !Array.isArray(def.capabilities.proxy)) return null var entries = def.capabilities.proxy for (var i = 0; i < entries.length; i++) { var entry = entries[i] if (entry && entry.name === 'catalog' && typeof entry.url === 'string' && entry.url !== '') return entry.url } return null } /** * The listing base a Store declares in its own definition: the proxy * entry named catalog-apps. Returns null when the definition declares * no such entry or the entry has no usable URL. Changing it is a * definition change (catalogVersion +1) like changing catalog. */ export function declaredCatalogAppsBase(def: AppDefinition | null | undefined): string | null { if (!def || !def.capabilities || !Array.isArray(def.capabilities.proxy)) return null var entries = def.capabilities.proxy for (var i = 0; i < entries.length; i++) { var entry = entries[i] if (entry && entry.name === 'catalog-apps' && typeof entry.url === 'string' && entry.url !== '') return entry.url } return null } /** * Storage-backed dev override for the catalog base (local catalog * development): a bare base URL string stored under exactly this key. * Consulted after the explicit param / env override slot, before any * installed Store's declared base. Never part of install payloads: * export_install never builds it, restore never wipes it (see * export_install / restore — install keys only), so a stored value * survives restore unchanged. No browser control sets or clears it; * only set_dev_catalog_base / clear_dev_catalog_base (agent/script). */ export var DEV_CATALOG_BASE_KEY = 'kody-os.dev.catalogBase' /** * Read the stored dev catalog override: a string check plus the * shared base allowlist (HTTPS, loopback http for dev). Any failure * (missing key, non-string, refused base) resolves to null (no * override), never a throw — resolution must stay total so callers * keep their existing no-source errors. */ function readDevCatalogBase(active: KeyStore): Promise { return readJson(active, DEV_CATALOG_BASE_KEY).then(function (raw): string | null { if (typeof raw !== 'string' || raw === '') return null try { return normalizeCatalogBase(raw) } catch (err) { return null } }) } /** * Set the stored dev catalog override to a base URL (validated with * the same base allowlist; a refused base writes nothing and reports * the refusal). Agent/script path for local catalog development. */ export function set_dev_catalog_base( base: string, store?: KeyStore, ): Promise<{ ok: true; baseUrl: string } | { ok: false; error: string }> { var normalized: string try { normalized = normalizeCatalogBase(base) } catch (err) { return Promise.resolve({ ok: false as const, error: 'dev catalog base refused: ' + (err instanceof Error ? err.message : String(err)) }) } return resolveStore(store).then(function (active: KeyStore) { return writeJson(active, DEV_CATALOG_BASE_KEY, normalized).then(function (): { ok: true; baseUrl: string } { return { ok: true as const, baseUrl: normalized } }) }) } /** * Clear the stored dev catalog override. Resolution falls back to * the installed Store's declared base (or no source when none is * installed). Never fails for a missing key. */ export function clear_dev_catalog_base(store?: KeyStore): Promise<{ ok: true }> { return resolveStore(store).then(function (active: KeyStore) { return deleteKey(active, DEV_CATALOG_BASE_KEY).then(function (): { ok: true } { return { ok: true as const } }) }) } /** Catalog base declared by one installed app (the Store driving the * call), or null when it declares none. Stored declarations were * HTTPS-validated at install; a stored base that no longer validates * is treated as no source rather than fetched. */ function actingCatalogBase(active: KeyStore, actingId: string): Promise { return readJson(active, defKey(actingId)).then(function (def) { var declared = declaredCatalogBase(def !== undefined ? def : null) if (declared === null) return null try { normalizeCatalogBase(declared) } catch (err) { return null } return declared }) } /** Catalog base declared by the installed App Store, or null when no * Store is installed or it declares none. */ function installedStoreCatalogBase(active: KeyStore): Promise { return actingCatalogBase(active, 'app-store') } /** Listing base declared by one installed app (the Store driving the * call), or null when it declares none. Same validation rule as * actingCatalogBase: a stored base that no longer validates is * treated as no source rather than fetched. */ function actingCatalogAppsBase(active: KeyStore, actingId: string): Promise { return readJson(active, defKey(actingId)).then(function (def) { var declared = declaredCatalogAppsBase(def !== undefined ? def : null) if (declared === null) return null try { normalizeCatalogBase(declared) } catch (err) { return null } return declared }) } /** Listing base declared by the installed App Store, or null when no * Store is installed or it declares none. */ function installedStoreCatalogAppsBase(active: KeyStore): Promise { return actingCatalogAppsBase(active, 'app-store') } /** * Resolve the base for a browser management call, by target: a Store * self-update (app-store) uses the discovery base (the acting * Store's catalog entry, main); every other app uses the listing base * (the acting Store's catalog-apps entry, pinned tag) when the acting * Store declares one, falling back to the discovery base when it * declares none. The dev override, when set, replaces both bases * (local verification uses one loopback base for everything). Null * means the acting Store declares no source. The management API takes * no explicit base parameter, so the override is the only thing that * beats a declaration; agent calls with an explicit base parameter * keep winning over the override via resolveAgentCatalogBase. The * resolved base is passed on as an explicit base, which the fetch * layer then uses as-is without re-applying the override. */ function resolveManagedBase(active: KeyStore, actingId: string, targetId?: string): Promise { var override: string | null = null try { override = devOverrideBase() } catch (err) { override = null } if (override !== null) return Promise.resolve(override) return readDevCatalogBase(active).then(function (stored) { if (stored !== null) return stored if (targetId === 'app-store') return actingCatalogBase(active, actingId) return actingCatalogAppsBase(active, actingId).then(function (listing) { if (listing !== null) return listing return actingCatalogBase(active, actingId) }) }) } /** Both bases for a management rows call: the discovery base (the * acting Store's catalog entry) and the listing base (its * catalog-apps entry, or the discovery base when it declares none). * The dev override, when set, is both. */ function resolveManagedBases(active: KeyStore, actingId: string): Promise<{ discovery: string | null; listing: string | null }> { var override: string | null = null try { override = devOverrideBase() } catch (err) { override = null } if (override !== null) return Promise.resolve({ discovery: override, listing: override }) return readDevCatalogBase(active).then(function (stored) { if (stored !== null) return { discovery: stored, listing: stored } return actingCatalogBase(active, actingId).then(function (discovery) { return actingCatalogAppsBase(active, actingId).then(function (listing) { return { discovery: discovery, listing: listing !== null ? listing : discovery } }) }) }) } function noCatalogSourceError(caller: string, id: string): string { return caller + ': no catalog source for "' + id + '" (supply catalogBase or install the App Store)' }/** Resolve the base for an agent catalog call: the explicit parameter * when supplied (validated — a refused base is an `{ ok: false }` * with no write), else the dev override when set (kept as-is: the * override replaces the installed-Store base), else the installed App * Store's declared base for that target (listing base for apps, * discovery base for the Store itself). Null means no source: refuse, * write nothing. * The resolved base is passed explicitly to the fetch layer, where an * explicitly passed base always wins over the override — so the * precedence here holds end to end. */ function resolveAgentCatalogBase(active: KeyStore, catalogBase: string | undefined, targetId?: string): Promise { if (catalogBase !== undefined) { try { return Promise.resolve(normalizeCatalogBase(catalogBase)) } catch (err) { return Promise.reject(err) } } var override: string | null = null try { override = devOverrideBase() } catch (err) { override = null } if (override !== null) return Promise.resolve(override) return readDevCatalogBase(active).then(function (stored) { if (stored !== null) return stored if (targetId === 'app-store') return installedStoreCatalogBase(active) return installedStoreCatalogAppsBase(active).then(function (listing) { if (listing !== null) return listing return installedStoreCatalogBase(active) }) }) } function installFromCatalogBase( id: string, active: KeyStore, base: string, ): Promise<{ ok: true; id: string } | { ok: false; error: string }> { return get_catalog_definition(id, base).then(function (def) { if (def === null) return { ok: false as const, error: 'unknown catalog app "' + id + '"' } return add_app(def, active) }) } /** * Install a shipped catalog app by id, through the validated `add_app` * path. Idempotent: re-installing an already-installed app preserves * its state and restamps it to the catalog definition (same as a * re-add). Unknown catalog ids return `{ ok: false }` naming the id * and write nothing. Never passes `resetState`, so state is never * wiped by an install. * * The catalog source is caller-supplied: an explicit `catalogBase` * when given, else the installed App Store's declared base for that target (listing base for apps, discovery base for the Store itself). With * neither, the call is refused naming that no catalog source was * given, and nothing is written. */ export function install_from_catalog( id: string, store?: KeyStore, catalogBase?: string, ): Promise<{ ok: true; id: string } | { ok: false; error: string }> { return resolveStore(store).then(function (active: KeyStore) { return resolveAgentCatalogBase(active, catalogBase, id).then(function (base) { if (base === null) return { ok: false as const, error: noCatalogSourceError('install_from_catalog', id) } return installFromCatalogBase(id, active, base) }, function (err) { return { ok: false as const, error: 'install_from_catalog: catalog base refused for "' + id + '": ' + (err instanceof Error ? err.message : String(err)) } }) }) } /** * Bring an already-installed app up to its shipped catalog definition, * preserving state (bundle and definition replaced, state carried * forward by `add_app`). Refuses to install: an id that is not * installed returns `{ ok: false }` directing the caller to * `install_from_catalog`, and an id that is not in the catalog * returns `{ ok: false }` naming the id. Nothing is written on * either failure. */ function updateFromCatalogBase( id: string, active: KeyStore, base: string, ): Promise<{ ok: true; id: string } | { ok: false; error: string }> { return get_catalog_definition(id, base).then(function (def) { if (def === null) return { ok: false as const, error: 'unknown catalog app "' + id + '"' } return get_app(id, active).then(function (entry) { if ('error' in entry) { return { ok: false as const, error: 'app "' + id + '" is not installed (use install_from_catalog to install it)' } } return add_app(def as AppDefinition, active) }) }) } export function update_from_catalog( id: string, store?: KeyStore, ): Promise<{ ok: true; id: string } | { ok: false; error: string }> { return resolveStore(store).then(function (active: KeyStore) { return resolveAgentCatalogBase(active, undefined, id).then(function (base) { if (base === null) return { ok: false as const, error: noCatalogSourceError('update_from_catalog', id) } return updateFromCatalogBase(id, active, base) }) }) } /** * Absorb an agent-merged definition for a modified catalog app, * keeping local customizations and recording the merged definition * as the new baseline. The merge itself is the agent's job (the * absorb prompt: backup first, compare export_app against * get_catalog_definition, show the merge plan, ask before * writing); this export is the thin "install this merged * definition and make it the baseline" primitive. Validates and * writes through add_app, then records a new snapshot at the * catalog version carrying the catalog fingerprint absorbed from. * Refuses with no write unless the app is installed, is in the * catalog, and its status is behind-modified, modified-current, * or absorbed-behind, and unless the merged definition's * catalogVersion equals the catalog's. Refuses when the merged * definition's id does not match the requested id. * * Signature mirrors install_from_catalog with the merged * definition inserted: (id, definition, store?, catalogBase?). * The third parameter also accepts a base URL string, so an MCP * caller passing (id, definition, catalogBase) works positionally. */ export function absorb_from_catalog( id: string, definition: AppDefinition, store?: KeyStore | string, catalogBase?: string, ): Promise<{ ok: true; id: string } | { ok: false; error: string }> { var activeStore: KeyStore | undefined = undefined var baseArg: string | undefined = catalogBase if (typeof store === 'string') { baseArg = store } else if (store) { activeStore = store } return resolveStore(activeStore).then(function (active: KeyStore) { return resolveAgentCatalogBase(active, baseArg, id).then(function (base) { if (base === null) return { ok: false as const, error: noCatalogSourceError('absorb_from_catalog', id) } return get_catalog_entry(id, base).then(function (entry) { if (entry === null) return { ok: false as const, error: 'absorb_from_catalog: unknown catalog app "' + id + '"' } return get_app_status(id, active, base).then(function (info) { if (!info.installed) return { ok: false as const, error: 'absorb_from_catalog: app "' + id + '" is not installed' } if (info.status !== 'behind-modified' && info.status !== 'modified-current' && info.status !== 'absorbed-behind') { return { ok: false as const, error: 'absorb_from_catalog: app "' + id + '" cannot be absorbed: status is "' + info.status + '"' } } if (definition.id !== id) return { ok: false as const, error: 'absorb_from_catalog: definition id "' + definition.id + '" does not match "' + id + '"' } if (definition.catalogVersion !== entry.catalogVersion) return { ok: false as const, error: 'absorb_from_catalog: merged definition catalogVersion ' + String(definition.catalogVersion) + ' does not match catalog version ' + String(entry.catalogVersion) } return add_app(definition, active).then(function (added) { if (!added.ok) return added return recordAbsorbSnapshot(active, id, entry.fingerprint).then(function (snap) { if (!snap.ok) return snap return { ok: true as const, id: id } }) }) }) }) }, function (err) { return { ok: false as const, error: 'absorb_from_catalog: catalog base refused for "' + id + '": ' + (err instanceof Error ? err.message : String(err)) } }) }) } /** * Install snapshot (app-store Decisions 8-11): recorded only by a store * install or store update, separate from the definition, holding the * catalogVersion at install time and the fingerprint of the definition * as actually stored (after add_app normalization). Generic add_app and * import_app never write it; remove_app deletes it; it is never part * of an export. A snapshot MAY also carry `catalogFingerprint`, the * fingerprint of the catalog definition absorbed from, set only by * `absorb_from_catalog`. Storage key: kody-os.apps.snapshot.. */ export interface InstallSnapshot { catalogVersion: number fingerprint: string /** Fingerprint of the catalog definition absorbed from; set only by absorb_from_catalog. */ catalogFingerprint?: string } var SNAPSHOT_PREFIX = 'kody-os.apps.snapshot.' function snapshotKey(id: string): string { return SNAPSHOT_PREFIX + id } export function readInstallSnapshot(store: KeyStore, id: string): Promise { return readJson(store, snapshotKey(id)).then(function (raw): InstallSnapshot | null { if (!raw || typeof raw.catalogVersion !== 'number' || typeof raw.fingerprint !== 'string') return null return raw }) } export function writeInstallSnapshot(store: KeyStore, id: string, snapshot: InstallSnapshot): Promise { return writeJson(store, snapshotKey(id), snapshot) } export function deleteInstallSnapshot(store: KeyStore, id: string): Promise { return deleteKey(store, snapshotKey(id)) } function recordInstallSnapshot(store: KeyStore, id: string): Promise<{ ok: true } | { ok: false; error: string }> { return readJson(store, defKey(id)).then(function (def): Promise<{ ok: true } | { ok: false; error: string }> { if (!def) return Promise.resolve({ ok: false as const, error: 'app "' + id + '" is not installed' }) if (typeof def.catalogVersion !== 'number') return Promise.resolve({ ok: false as const, error: 'app "' + id + '" has no catalogVersion to snapshot' }) return writeInstallSnapshot(store, id, { catalogVersion: def.catalogVersion, fingerprint: fingerprintDefinition(def) }).then(function (): { ok: true } { return { ok: true as const } }) }) } function recordAbsorbSnapshot(store: KeyStore, id: string, catalogFingerprint: string): Promise<{ ok: true } | { ok: false; error: string }> { return readJson(store, defKey(id)).then(function (def): Promise<{ ok: true } | { ok: false; error: string }> { if (!def) return Promise.resolve({ ok: false as const, error: 'app "' + id + '" is not installed' }) if (typeof def.catalogVersion !== 'number') return Promise.resolve({ ok: false as const, error: 'app "' + id + '" has no catalogVersion to snapshot' }) return writeInstallSnapshot(store, id, { catalogVersion: def.catalogVersion, fingerprint: fingerprintDefinition(def), catalogFingerprint: catalogFingerprint }).then(function (): { ok: true } { return { ok: true as const } }) }) } /** * Store install: install_from_catalog plus a snapshot write. Offered * only for not-installed ids by the store page; a re-install through * this path still records the new snapshot, matching "store install" * in the spec. Generic add_app callers never get a snapshot. */ export function store_install_from_catalog( id: string, store?: KeyStore, catalogBase?: string, ): Promise<{ ok: true; id: string } | { ok: false; error: string }> { return resolveStore(store).then(function (active: KeyStore) { return resolveAgentCatalogBase(active, catalogBase, id).then(function (base) { if (base === null) return { ok: false as const, error: noCatalogSourceError('store_install_from_catalog', id) } return installFromCatalogBase(id, active, base).then(function (result) { if (!result.ok) return result return recordInstallSnapshot(active, id).then(function (snap) { if (!snap.ok) return snap return result }) }) }, function (err) { return { ok: false as const, error: 'store_install_from_catalog: catalog base refused for "' + id + '": ' + (err instanceof Error ? err.message : String(err)) } }) }) } /** * Store update: update_from_catalog plus a snapshot replacement. * State is preserved by the add_app rule (surviving fields carry * forward, dropped fields reset); pins, hidden flags, homepage * placement, and recency are untouched by add_app. The store page, * not this function, owns the modified-app confirmation gate. */ export function store_update_from_catalog( id: string, store?: KeyStore, catalogBase?: string, ): Promise<{ ok: true; id: string } | { ok: false; error: string }> { return resolveStore(store).then(function (active: KeyStore) { return resolveAgentCatalogBase(active, catalogBase, id).then(function (base) { if (base === null) return { ok: false as const, error: noCatalogSourceError('store_update_from_catalog', id) } return updateFromCatalogBase(id, active, base).then(function (result) { if (!result.ok) return result return recordInstallSnapshot(active, id).then(function (snap) { if (!snap.ok) return snap return result }) }) }, function (err) { return { ok: false as const, error: 'store_update_from_catalog: catalog base refused for "' + id + '": ' + (err instanceof Error ? err.message : String(err)) } }) }) } /** * Bundle management API (data-only App Store). These functions are * the browser-facing management path: they reuse the store * install/update logic and snapshot rules, and they add the two * gates the shell Store page used to own — the manageApps * capability check, and the confirmation gate for modified apps * and for capability expansion. They are NOT MCP exports: agents * keep using install_from_catalog / update_from_catalog, and * the agent is the installer that surfaces capabilities before * calling them. The shell route translates a permission failure * into the feed-style plain 404; other failures keep their * error text so the bundle can render them. */ export type ManageResult = | { ok: true; id?: string; rows?: StoreRow[]; catalogRelease?: string; catalogCached?: boolean; catalogError?: string; storeSelf?: StoreSelfUpdate } | { ok: false; error: string; needsConfirmation?: boolean; additions?: string[]; permissionDenied?: boolean; catalogRelease?: string; catalogCached?: boolean } function checkManagePermission(active: KeyStore, actingId: string): Promise { return readJson(active, defKey(actingId)).then(function (def) { return def !== null && def !== undefined && def.capabilities !== undefined && def.capabilities.manageApps === true }) }/** * The App Store's own update state for the separate self-update * section above the apps list. The rows payload carries it so the * bundle needs no second endpoint. pinnedLabel is the tag ref of the * listing base (for example 4.1.11), the full base label for a * non-GitHub listing base, or null when the Store declares no listing * base and the list follows the discovery base. discoveryRef is the * GitHub ref of the discovery base (main), or null for a non-GitHub * base, where discoveryLabel carries the full base label instead. * latestCatalogVersion is the Store version on the discovery base, or * null when it could not be read; hasUpdate is true only when that * version is newer than the installed one and compatible with the * running shell. When the latest Store needs a newer shell, * needsNewerShell is true, hasUpdate is false, and the section shows * the requirement with Remove (the gated-row Remove behaviour). */ export interface StoreSelfUpdate { installedCatalogVersion: number pinnedLabel: string | null discoveryRef: string | null discoveryLabel: string | null runningVersion: string latestCatalogVersion: number | null latestMinPackageVersion?: string needsNewerShell: boolean hasUpdate: boolean error?: string } function catalogErrorDetail(err: unknown): string { var message = err instanceof Error ? err.message : String(err) return message === '' ? 'unknown error' : message } function getStoreSelfUpdate(active: KeyStore, actingId: string, discovery: string | null, listing: string | null): Promise { return Promise.all([ readJson(active, defKey(actingId)), getRunningPackageVersion(), ]).then(function (parts) { var installedDef = parts[0] var running = parts[1] var installedVersion = installedDef !== undefined && typeof installedDef.catalogVersion === 'number' ? installedDef.catalogVersion : 0 var pinnedLabel: string | null = null if (listing !== null && listing !== discovery) { var tag = catalogTagLabel(listing) pinnedLabel = tag !== null ? tag : catalogLabelForBase(listing) } var discoveryRef: string | null = discovery !== null ? catalogGitHubRef(discovery) : null var discoveryLabel: string | null = discovery !== null && discoveryRef === null ? catalogLabelForBase(discovery) : null var self: StoreSelfUpdate = { installedCatalogVersion: installedVersion, pinnedLabel: pinnedLabel, discoveryRef: discoveryRef, discoveryLabel: discoveryLabel, runningVersion: running, latestCatalogVersion: null, needsNewerShell: false, hasUpdate: false } if (discovery === null) { self.error = 'This Store declares no catalog source.' return self } return readCatalogManifest(discovery).then(function (manifest) { var latestEntry: { catalogVersion: number; minPackageVersion?: string } | null = null for (var i = 0; i < manifest.entries.length; i++) { if (manifest.entries[i].id === 'app-store') latestEntry = manifest.entries[i] } if (latestEntry === null) { self.error = 'Could not read the App Catalog from the discovery base.' return self } var latestVersion = latestEntry.catalogVersion var latestMin = latestEntry.minPackageVersion var gated = latestMin !== undefined ? rowNeedsNewerShell(latestMin, running) : false self.latestCatalogVersion = latestVersion if (latestMin !== undefined) self.latestMinPackageVersion = latestMin self.needsNewerShell = gated self.hasUpdate = latestVersion > installedVersion && !gated return self }, function (err) { self.error = 'Could not read the App Catalog from the discovery base. (' + catalogErrorDetail(err) + ')' return self }) }) } export function manage_rows(actingId: string, store?: KeyStore): Promise { return resolveStore(store).then(function (active: KeyStore) { return checkManagePermission(active, actingId).then(function (allowed) { if (!allowed) return { ok: false as const, error: 'management not permitted', permissionDenied: true } return resolveManagedBases(active, actingId).then(function (bases) { var base = bases.listing return get_store_rows(active, base !== null ? base : undefined).then(function (allRows) { // The App Store is not a row in its own list: its update // lives in the separate self-update section (storeSelf). var rows = allRows.filter(function (row) { return row.id !== 'app-store' }) return getStoreSelfUpdate(active, actingId, bases.discovery, bases.listing).then(function (self) { if (base === null) { return { ok: true as const, rows: rows, storeSelf: self, catalogRelease: '', catalogCached: false, catalogError: 'This Store declares no catalog source. Showing installed apps.' } } var useBase: string = base return readCatalogManifest(useBase).then(function (manifest) { var tag = catalogTagLabel(useBase) return { ok: true as const, rows: rows, storeSelf: self, catalogRelease: tag !== null ? tag : manifest.releaseLabel, catalogCached: manifest.cached } }, function (err) { var src = get_catalog_source(useBase) var tag = catalogTagLabel(useBase) return { ok: true as const, rows: rows, storeSelf: self, catalogRelease: tag !== null ? tag : src.releaseLabel, catalogCached: true, catalogError: 'Catalog could not be refreshed. Showing installed apps. Retry to refresh. (' + catalogErrorDetail(err) + ')' } }) }) }) }) }) }) } export function get_store_catalog_info(store?: KeyStore, catalogBase?: string): Promise<{ releaseLabel: string; cached: boolean; error?: string }> { void store var base: string | null = null if (catalogBase !== undefined) { try { base = normalizeCatalogBase(catalogBase) } catch (err) { var msg0 = err instanceof Error ? err.message : String(err) return Promise.resolve({ releaseLabel: '', cached: true, error: msg0 }) } } else { return Promise.resolve({ releaseLabel: '', cached: true, error: 'no catalog source given' }) } return readCatalogManifest(base).then(function (manifest) { return { releaseLabel: manifest.releaseLabel, cached: manifest.cached } }, function (err) { var src = get_catalog_source(base as string) var msg = err instanceof Error ? err.message : String(err) return { releaseLabel: src.releaseLabel, cached: true, error: msg } }) } export function manage_install(actingId: string, targetId: string, store?: KeyStore): Promise { return resolveStore(store).then(function (active: KeyStore) { return checkManagePermission(active, actingId).then(function (allowed) { if (!allowed) return { ok: false as const, error: 'management not permitted', permissionDenied: true } return resolveManagedBase(active, actingId, targetId).then(function (base) { return get_app_status(targetId, active, base !== null ? base : undefined).then(function (info) { if (info.installed) return { ok: false as const, error: 'App "' + targetId + '" is already installed.' } if (base === null) return { ok: false as const, error: 'manage_install: no catalog source for "' + targetId + '" (the calling Store declares no catalog)' } return store_install_from_catalog(targetId, active, base).then(function (result) { if (!result.ok) return result return { ok: true as const, id: targetId } }) }) }) }) }) } function manage_update_with_status( actingId: string, targetId: string, confirmed: boolean, store: KeyStore | undefined, kind: 'update' | 'restore', ): Promise { return resolveStore(store).then(function (active: KeyStore) { return checkManagePermission(active, actingId).then(function (allowed) { if (!allowed) return { ok: false as const, error: 'management not permitted', permissionDenied: true } return resolveManagedBase(active, actingId, targetId).then(function (base) { var useBase = base !== null ? base : undefined return get_app_status(targetId, active, useBase).then(function (info) { if (!info.installed || !info.inCatalog) { return { ok: false as const, error: 'App "' + targetId + '" cannot be ' + kind + 'd: it is not an installed catalog app.' } } if (kind === 'update') { if (info.status === 'modified-current' || info.status === 'modified-ahead') { return { ok: false as const, error: 'App "' + targetId + '" is modified: use Restore, not Overwrite.' } } if (info.status !== 'behind-clean' && info.status !== 'catalog-differing' && info.status !== 'behind-modified' && info.status !== 'absorbed-behind' && info.status !== 'snapshot-less') { return { ok: false as const, error: 'App "' + targetId + '" has no update available.' } } } else { if (info.status !== 'modified-current' && info.status !== 'modified-ahead') { return { ok: false as const, error: 'App "' + targetId + '" has nothing to restore.' } } } return Promise.all([ readJson(active, defKey(targetId)), useBase !== undefined ? get_catalog_definition(targetId, useBase) : Promise.resolve(null), ]).then(function (pair) { var installedDef = pair[0] var catalogDef = pair[1] var additions = capabilityAdditions(installedDef, catalogDef) var needsConfirm = info.status === 'behind-modified' || info.status === 'absorbed-behind' || info.status === 'snapshot-less' || additions.length > 0 if (kind === 'restore') needsConfirm = true if (needsConfirm && !confirmed) { return { ok: false as const, error: 'Confirmation required before ' + kind + 'ing "' + targetId + '".', needsConfirmation: true, additions: additions, } } if (useBase === undefined) { return { ok: false as const, error: 'manage_' + kind + ': no catalog source for "' + targetId + '" (the calling Store declares no catalog)' } } return store_update_from_catalog(targetId, active, useBase).then(function (result) { if (!result.ok) return result return { ok: true as const, id: targetId } }) }) }) }) }) }) } /** * Management remove: permission-checked remove_app for the browser * Store. Only the Store's own Remove button offers it, for up-to-date * rows, but the API itself removes any installed app: it deletes the * definition, state, and snapshot and scrubs every reference list, * exactly like the agent remove_app it wraps. Removal always requires * confirmation: without confirmed, nothing is written and the caller * gets needsConfirmation, which the bundle answers with its own * confirmation dialog. */ export function manage_remove(actingId: string, targetId: string, confirmed: boolean, store?: KeyStore): Promise { return resolveStore(store).then(function (active: KeyStore) { return checkManagePermission(active, actingId).then(function (allowed) { if (!allowed) return { ok: false as const, error: 'management not permitted', permissionDenied: true } return get_app_status(targetId, active).then(function (info) { if (!info.installed) { return { ok: false as const, error: 'App "' + targetId + '" is not installed.' } } if (!confirmed) { return { ok: false as const, error: 'Confirmation required before removing "' + targetId + '".', needsConfirmation: true, additions: [], } } return remove_app(targetId, active).then(function (result) { if (!result.ok) return result return { ok: true as const, id: targetId } }) }) }) }) } export function manage_update(actingId: string, targetId: string, confirmed: boolean, store?: KeyStore): Promise { return manage_update_with_status(actingId, targetId, confirmed, store, 'update') } export function manage_restore(actingId: string, targetId: string, confirmed: boolean, store?: KeyStore): Promise { return manage_update_with_status(actingId, targetId, confirmed, store, 'restore') } export type AppStoreStatus = | 'not-installed' | 'up-to-date' | 'behind-clean' | 'catalog-differing' | 'behind-modified' | 'modified-current' | 'modified-ahead' | 'snapshot-less' | 'absorbed' | 'absorbed-behind' | 'storage-only' | 'storage-only-formerly' export interface AppStoreStatusInfo { status: AppStoreStatus installed: boolean inCatalog: boolean /** True when the installed definition differs from its snapshot. False for clean installs; meaningless for snapshot-less rows. */ modified: boolean installedVersion?: number catalogVersion?: number snapshotVersion?: number } /** * Derive one app's store status from installed fingerprint (I), snapshot * fingerprint (S), catalog fingerprint (C, canonicalized the same way), * installed catalogVersion (Iv), and catalog catalogVersion (Cv). * Content equality wins: I == C is up to date whatever the version * fields say. Edge case not named in the spec matrix: an app matching * its snapshot, ahead of the catalog (Iv > Cv), with a differing * catalog copy is classified modified-ahead for control purposes * (Restore, confirmed, never Update) with modified=false, since the * user changed nothing but the catalog copy is not the installed one. * When the snapshot carries `catalogFingerprint`, the absorbed cases * take precedence: I == S and the field equals C yields `absorbed`; * I == S and it differs yields `absorbed-behind`. */ export function get_app_status( id: string, store?: KeyStore, catalogBase?: string, ): Promise { return resolveStore(store).then(function (active: KeyStore) { return Promise.all([ readJson(active, defKey(id)), readInstallSnapshot(active, id), catalogBase !== undefined ? get_catalog_entry(id, catalogBase) : Promise.resolve(null), ]).then(function (parts) { var installed = parts[0] var snapshot = parts[1] var catalogEntry = parts[2] var catalogDef: { catalogVersion?: number } | null = catalogEntry if (!installed) { return { status: 'not-installed' as const, installed: false, inCatalog: catalogDef !== null, modified: false, catalogVersion: catalogDef !== null && catalogDef.catalogVersion !== undefined ? catalogDef.catalogVersion : undefined, } } if (catalogDef === null) { return { status: snapshot !== null ? ('storage-only-formerly' as const) : ('storage-only' as const), installed: true, inCatalog: false, modified: false, installedVersion: installed.catalogVersion, snapshotVersion: snapshot !== null ? snapshot.catalogVersion : undefined, } } if (snapshot === null) { return { status: 'snapshot-less' as const, installed: true, inCatalog: true, modified: false, installedVersion: installed.catalogVersion, catalogVersion: catalogDef.catalogVersion, } } var installedFingerprint = fingerprintDefinition(installed) var catalogFingerprint = catalogEntry !== null ? catalogEntry.fingerprint : '' var iv = typeof installed.catalogVersion === 'number' ? installed.catalogVersion : 0 var cv = catalogEntry !== null && typeof catalogEntry.catalogVersion === 'number' ? catalogEntry.catalogVersion : 0 var modified = installedFingerprint !== snapshot.fingerprint var status: AppStoreStatus if (!modified && snapshot.catalogFingerprint !== undefined) { status = snapshot.catalogFingerprint === catalogFingerprint ? 'absorbed' : 'absorbed-behind' } else if (installedFingerprint === catalogFingerprint) { status = 'up-to-date' } else if (!modified && iv < cv) { status = 'behind-clean' } else if (!modified && iv === cv) { status = 'catalog-differing' } else if (iv < cv) { status = 'behind-modified' } else if (iv === cv) { status = 'modified-current' } else { status = 'modified-ahead' } return { status: status, installed: true, inCatalog: true, modified: modified, installedVersion: installed.catalogVersion, catalogVersion: catalogDef.catalogVersion, snapshotVersion: snapshot.catalogVersion, } }) }) } export interface StoreRow { id: string label: string name: string icon?: string category?: string description?: string installMode: string /** Full URL of the app's catalog folder in GitHub tree form, set when the row came from a catalog entry. */ folderUrl?: string installed: boolean inCatalog: boolean status: AppStoreStatus modified: boolean pinned: boolean hidden: boolean homepage: boolean /** Declared capabilities of the catalog definition when present, * else of the installed definition, for Store disclosure. */ capabilities: CapabilitySummary /** Minimum shell version the catalog definition requires, when declared. */ minPackageVersion?: string /** Running shell version the incompatibility was computed against. */ shellVersion?: string /** True when the catalog definition's minimum is newer than the running shell: the Store shows the requirement instead of an install/update control. */ needsNewerShell?: boolean /** Definition schema the catalog definition carries, when known. */ schemaVersion?: number /** Shell's minimum supported schema version the floor check was computed against. */ schemaFloor?: number /** True when the catalog definition's schema is below the shell's floor: the Store shows the schema requirement instead of an install/update control. */ needsNewerSchema?: boolean } /** * Catalog-only list rows: one row per catalog id, in * alphabetical-by-id order, with each row's status and launcher flags. * Installed apps with no catalog entry do not appear here; they are * managed from Apps Edit and by agents, not from the Store. Hidden * apps are included (the list is unfiltered); Hide affects launcher * tiles only. */ export function get_store_rows(store?: KeyStore, catalogBase?: string): Promise { return resolveStore(store).then(function (active: KeyStore) { return Promise.all([ readPinned(active), readHidden(active), readHomepage(active), listInstalledIds(active), getRunningPackageVersion(), ]).then(function (parts) { var pinned = parts[0] var hidden = parts[1] var homepage = parts[2] var installedIds = parts[3] var running = parts[4] if (catalogBase === undefined) { return buildStoreRowsFromInstalled(active, pinned, hidden, homepage, installedIds, running) } return list_catalog(catalogBase).then(function (catalog) { return buildStoreRows(active, pinned, hidden, homepage, catalog, running, catalogBase) }, function () { return buildStoreRowsFromInstalled(active, pinned, hidden, homepage, installedIds, running) }) }) }) } function rowNeedsNewerShell(min: unknown, running: string): boolean { var parsedMin = parsePackageVersion(min) var parsedRun = parsePackageVersion(running) if (parsedMin === null || parsedRun === null) return false return comparePackageVersions(parsedRun, parsedMin) < 0 } function buildStoreRows( active: KeyStore, pinned: string[], hidden: string[], homepage: string[], catalog: { id: string; label: string; name: string; icon?: string; category?: string; description?: string; installMode?: string; recipePath?: string; minPackageVersion?: string; schemaVersion?: number; capabilities: CapabilitySummary }[], running: string, catalogBase: string, ): Promise { var idSet: Record = {} var ids: string[] = [] for (var ci = 0; ci < catalog.length; ci++) { if (!idSet[catalog[ci].id]) { idSet[catalog[ci].id] = true ids.push(catalog[ci].id) } } ids.sort() var rows: StoreRow[] = [] var chain = Promise.resolve() for (var ii = 0; ii < ids.length; ii++) { ;(function (want: string): void { chain = chain.then(function (): Promise { return Promise.all([ readJson(active, defKey(want)), get_app_status(want, active, catalogBase), ]).then(function (pair): void { var installedDef = pair[0] var info = pair[1] var catalogEntry: { id: string; label: string; name: string; icon?: string; category?: string; description?: string; installMode?: string; recipePath?: string; minPackageVersion?: string; schemaVersion?: number; capabilities: CapabilitySummary } | null = null for (var cj = 0; cj < catalog.length; cj++) { if (catalog[cj].id === want) catalogEntry = catalog[cj] } var label = installedDef ? (installedDef.label || installedDef.name) : (catalogEntry ? catalogEntry.label : want) var name = installedDef ? installedDef.name : (catalogEntry ? catalogEntry.name : want) var catalogMin = catalogEntry !== null && catalogEntry.minPackageVersion !== undefined ? catalogEntry.minPackageVersion : undefined var incompatible = catalogMin !== undefined ? rowNeedsNewerShell(catalogMin, running) : false var catalogSchema = catalogEntry !== null && catalogEntry.schemaVersion !== undefined ? catalogEntry.schemaVersion : undefined var belowFloor = catalogSchema !== undefined ? catalogSchema < MIN_SUPPORTED_SCHEMA_VERSION : false rows.push({ id: want, label: label, name: name, icon: installedDef ? installedDef.icon : (catalogEntry ? catalogEntry.icon : undefined), category: installedDef ? installedDef.category : (catalogEntry ? catalogEntry.category : undefined), description: catalogEntry && catalogEntry.description !== undefined ? catalogEntry.description : (installedDef ? installedDef.description : undefined), installMode: catalogEntry && catalogEntry.installMode !== undefined ? catalogEntry.installMode : 'json', folderUrl: catalogEntry ? folderUrlForBase(catalogBase, catalogEntry.id) : undefined, installed: info.installed, inCatalog: info.inCatalog, status: info.status, modified: info.modified, pinned: pinned.indexOf(want) !== -1, hidden: hidden.indexOf(want) !== -1, homepage: homepage.indexOf(want) !== -1, capabilities: catalogEntry !== null ? catalogEntry.capabilities : summarizeCapabilities(installedDef), minPackageVersion: catalogMin, shellVersion: running, needsNewerShell: incompatible, schemaVersion: catalogSchema, schemaFloor: MIN_SUPPORTED_SCHEMA_VERSION, needsNewerSchema: belowFloor, }) }) }) })(ids[ii]) } return chain.then(function (): StoreRow[] { return rows }) } function buildStoreRowsFromInstalled( active: KeyStore, pinned: string[], hidden: string[], homepage: string[], installedIds: string[], running: string, ): Promise { var ids = installedIds.slice().sort() var rows: StoreRow[] = [] var chain = Promise.resolve() for (var ii = 0; ii < ids.length; ii++) { ;(function (want: string): void { chain = chain.then(function (): Promise { return Promise.all([ readJson(active, defKey(want)), get_app_status(want, active), ]).then(function (pair): void { var installedDef = pair[0] var info = pair[1] if (!installedDef) return rows.push({ id: want, label: installedDef.label || installedDef.name, name: installedDef.name, icon: installedDef.icon, category: installedDef.category, description: installedDef.description, installMode: (installedDef as unknown as Record)['installMode'] === 'recipe-only' ? 'recipe-only' : 'json', installed: info.installed, inCatalog: info.inCatalog, status: info.status, modified: info.modified, pinned: pinned.indexOf(want) !== -1, hidden: hidden.indexOf(want) !== -1, homepage: homepage.indexOf(want) !== -1, capabilities: summarizeCapabilities(installedDef), minPackageVersion: (installedDef as unknown as Record)['minPackageVersion'] !== undefined ? String((installedDef as unknown as Record)['minPackageVersion']) : undefined, shellVersion: running, needsNewerShell: (installedDef as unknown as Record)['minPackageVersion'] !== undefined ? rowNeedsNewerShell((installedDef as unknown as Record)['minPackageVersion'], running) : false, schemaVersion: typeof installedDef.schemaVersion === 'number' ? installedDef.schemaVersion : undefined, schemaFloor: MIN_SUPPORTED_SCHEMA_VERSION, needsNewerSchema: typeof installedDef.schemaVersion === 'number' ? installedDef.schemaVersion < MIN_SUPPORTED_SCHEMA_VERSION : false, }) }) }) })(ids[ii]) } return chain.then(function (): StoreRow[] { return rows }) } /** * Export one app as complete JSON: full definition plus a state snapshot. * The result re-imports into a blank install with no code changes. */ export function export_app(id: string, store?: KeyStore): Promise { return resolveStore(store).then(function (active: KeyStore) { return loadEntry(active, id).then(function (entry) { if ('error' in entry) return { error: entry.error } return { format: EXPORT_FORMAT, exportedAt: new Date().toISOString(), definition: entry.definition, state: entry.state, } as AppExport }) }) } export interface InstallExport { format: 'kody-os-install/1' exportedAt: string apps: AppExport[] pinned: string[] hidden: string[] homepage?: string[] } /** Export the whole install: every app plus pinned/hidden prefs. Recency stays local. */ export function export_install(store?: KeyStore): Promise { return resolveStore(store).then(function (active: KeyStore) { return Promise.all([listInstalledIds(active), readPinned(active), readHidden(active), readHomepage(active)]).then(function (parts) { var ids = parts[0] var pinned = parts[1] var hidden = parts[2] var homepage = parts[3] var apps: AppExport[] = [] var chain = Promise.resolve() for (var id of ids) { ;(function (want: string): void { chain = chain.then(function (): Promise { return loadEntry(active, want).then(function (entry): void { if ('error' in entry) return apps.push({ format: EXPORT_FORMAT, exportedAt: new Date().toISOString(), definition: entry.definition, state: entry.state, } as AppExport) }) }) })(id) } return chain.then(function (): InstallExport { return { format: 'kody-os-install/1', exportedAt: new Date().toISOString(), apps: apps, pinned: pinned, hidden: hidden, homepage: homepage, } }) }) }) } /** Import an install payload into a blank store. Restores apps plus pinned/hidden; Recent starts empty. */ export function import_install( payload: unknown, store?: KeyStore, options?: { overwrite?: boolean }, ): Promise<{ ok: true; ids: string[] } | { ok: false; error: string }> { return resolveStore(store).then(function (active: KeyStore): Promise<{ ok: true; ids: string[] } | { ok: false; error: string }> { if (!isRecord(payload) || !Array.isArray((payload as Record)['apps'])) { return Promise.resolve({ ok: false as const, error: 'import payload needs an apps array' }) } var rec = payload as Record var list = rec['apps'] as unknown[] var ids: string[] = [] var chain: Promise<{ ok: true; id: string } | { ok: false; error: string } | null> = Promise.resolve(null) for (var item of list) { ;(function (one: unknown): void { var prev = chain chain = prev.then(function (blocked): Promise<{ ok: true; id: string } | { ok: false; error: string } | null> { if (blocked && 'ok' in blocked && blocked.ok === false) return Promise.resolve(blocked) return import_app(one, active, options).then(function (r) { if (!r.ok) return r ids.push(r.id) return null }) }) })(item) } return chain.then(function (failed): Promise<{ ok: true; ids: string[] } | { ok: false; error: string }> { if (failed && 'ok' in failed && failed.ok === false) return Promise.resolve(failed as { ok: false; error: string }) return listInstalledIds(active).then(function (installed: string[]) { var pinnedRaw = Array.isArray(rec['pinned']) ? (rec['pinned'] as unknown[]) : [] var hiddenRaw = Array.isArray(rec['hidden']) ? (rec['hidden'] as unknown[]) : [] var homepageRaw = Array.isArray(rec['homepage']) ? (rec['homepage'] as unknown[]) : [] var pinned: string[] = [] var hidden: string[] = [] var homepage: string[] = [] for (var pi = 0; pi < pinnedRaw.length; pi++) { if (typeof pinnedRaw[pi] === 'string' && installed.indexOf(pinnedRaw[pi] as string) !== -1 && pinned.indexOf(pinnedRaw[pi] as string) === -1) pinned.push(pinnedRaw[pi] as string) } for (var hi = 0; hi < hiddenRaw.length; hi++) { if (typeof hiddenRaw[hi] === 'string' && installed.indexOf(hiddenRaw[hi] as string) !== -1 && hidden.indexOf(hiddenRaw[hi] as string) === -1) hidden.push(hiddenRaw[hi] as string) } for (var gi = 0; gi < homepageRaw.length; gi++) { if (typeof homepageRaw[gi] === 'string' && installed.indexOf(homepageRaw[gi] as string) !== -1 && homepage.indexOf(homepageRaw[gi] as string) === -1) homepage.push(homepageRaw[gi] as string) } return Promise.all([writePinned(active, pinned), writeHidden(active, hidden), writeHomepage(active, homepage)]).then(function (): { ok: true; ids: string[] } { return { ok: true as const, ids: ids } }) }) }) }) } function migrateImportPayload(payload: unknown): { def?: AppDefinition; error?: string } { if (!isRecord(payload)) return { error: 'import payload must be an object' } var body: unknown = payload if (isRecord(payload['definition'])) { // Export envelope (v1 or v2). body = payload['definition'] } if (!isRecord(body)) return { error: 'import payload has no definition object' } var rec = body as Record var id = reqStr(rec, 'id') var name = reqStr(rec, 'name') var label = reqStr(rec, 'label') if (!id) { // v1 payloads keyed by name: derive the id. if (!name) return { error: 'import payload needs an id (or a v1 name to derive it)' } id = name } if (!name) name = label || id var migrated: Record = {} for (var k of Object.keys(rec)) migrated[k] = rec[k] migrated['id'] = id migrated['name'] = name if (migrated['label'] === undefined) migrated['label'] = name var problem = validateDefinition(migrated) if (problem) return { error: problem } return { def: migrated as unknown as AppDefinition } } /** * Import an export_app payload (v2, v1, or a bare definition) into this * install. Definition-and-state-write-only like add_app; no code changes, no republish. */ export function import_app( payload: unknown, store?: KeyStore, options?: { overwrite?: boolean }, ): Promise<{ ok: true; id: string } | { ok: false; error: string }> { return resolveStore(store).then(function (active: KeyStore) { var m = migrateImportPayload(payload) if (m.error || !m.def) return { ok: false as const, error: m.error || 'invalid payload' } var def = m.def var needCheck = !options || options.overwrite !== true var checkExisting: Promise<{ ok: true; id: string } | { ok: false; error: string } | null> = needCheck ? readJson(active, defKey(def.id)).then(function (existing) { if (existing) return { ok: false as const, error: 'app "' + def.id + '" already installed (pass overwrite:true to replace)' } return null }) : Promise.resolve(null) return checkExisting.then(function (blocked) { if (blocked) return blocked return add_app(def, active).then(function (added) { if (!added.ok) return added var rawState: unknown = isRecord(payload) && isRecord(payload['state']) ? payload['state'] : undefined if (rawState === undefined && isRecord(payload) && isRecord(payload['definition'])) { var env = payload as Record if (isRecord(env['state'])) rawState = env['state'] } if (!isRecord(rawState)) return { ok: true as const, id: def.id } var st = rawState as Record for (var field of Object.keys(def.stateSchema.fields)) { var ferr = checkFieldValue(field, def.stateSchema.fields[field], st[field]) if (ferr) return { ok: false as const, error: 'imported state invalid: ' + ferr } } return writeJson(active, stateKey(def.id), cloneState(st as AppState)).then(function () { return { ok: true as const, id: def.id } }) }) }) }) } /** * Install backups (replace-with-auto-snapshot). A backup is the * export_install envelope plus a backup tag, stored under * `kody-os.backups.`. Recency is not captured, exactly as * export_install excludes it; auth keys are never captured or touched. * * packageStorage() has no key listing, so backup names are also kept * in an index key, `kody-os.backups.index` (an array of names). The * index is maintained by backup/delete_backup only, is never wiped by * restore, and is never part of an export_install payload. */ export interface BackupEntry { format: 'kody-os-backup/1' name: string capturedAt: string install: InstallExport } export interface BackupSummary { name: string capturedAt: string appCount: number size: number } var BACKUP_PREFIX = 'kody-os.backups.' var BACKUP_INDEX_KEY = 'kody-os.backups.index' function backupKey(name: string): string { return BACKUP_PREFIX + name } function isBackupName(name: unknown): name is string { return typeof name === 'string' && NAME_RE.test(name) } function readBackupIndex(store: KeyStore): Promise { return readJson(store, BACKUP_INDEX_KEY).then(function (raw): string[] { if (!Array.isArray(raw)) return [] var out: string[] = [] for (var i = 0; i < raw.length; i++) { if (typeof raw[i] === 'string' && out.indexOf(raw[i]) === -1) out.push(raw[i]) } return out }) } function writeBackupIndex(store: KeyStore, names: string[]): Promise { return writeJson(store, BACKUP_INDEX_KEY, names) } function readBackupEntry(store: KeyStore, name: string): Promise { return readJson(store, backupKey(name)).then(function (raw): BackupEntry | null { if (!raw || raw.format !== 'kody-os-backup/1' || typeof raw.name !== 'string' || !isRecord(raw.install)) return null return raw }) } function writeBackupEntry(store: KeyStore, entry: BackupEntry): Promise { return readBackupIndex(store).then(function (names: string[]): Promise { if (names.indexOf(entry.name) === -1) names.push(entry.name) return writeJson(store, backupKey(entry.name), entry).then(function (): Promise { return writeBackupIndex(store, names) }) }) } export function backup( name: string, optsOrStore?: KeyStore | { overwrite?: boolean }, maybeStore?: KeyStore, ): Promise<{ ok: true; name: string; capturedAt: string; appCount: number; size: number } | { ok: false; error: string }> { var activeStore: KeyStore | undefined = undefined var overwrite = false if (optsOrStore && isKeyStore(optsOrStore)) { activeStore = optsOrStore } else if (optsOrStore && typeof optsOrStore === 'object') { overwrite = (optsOrStore as { overwrite?: boolean }).overwrite === true if (maybeStore) activeStore = maybeStore } if (!isBackupName(name)) return Promise.resolve({ ok: false as const, error: 'backup name must match ^[a-z0-9][a-z0-9-]{0,63}$' }) return resolveStore(activeStore).then(function (active: KeyStore) { return readBackupEntry(active, name).then(function (existing) { if (existing && !overwrite) return { ok: false as const, error: 'backup "' + name + '" already exists (pass overwrite:true to replace it)' } return export_install(active).then(function (install: InstallExport) { var entry: BackupEntry = { format: 'kody-os-backup/1', name: name, capturedAt: new Date().toISOString(), install: install, } return writeBackupEntry(active, entry).then(function (): { ok: true; name: string; capturedAt: string; appCount: number; size: number } { return { ok: true as const, name: name, capturedAt: entry.capturedAt, appCount: install.apps.length, size: JSON.stringify(entry).length } }) }) }) }) } export function list_backups(store?: KeyStore): Promise { return resolveStore(store).then(function (active: KeyStore) { return readBackupIndex(active).then(function (names: string[]) { var out: BackupSummary[] = [] var chain = Promise.resolve() for (var i = 0; i < names.length; i++) { ;(function (want: string): void { chain = chain.then(function (): Promise { return readBackupEntry(active, want).then(function (entry): void { if (!entry) return out.push({ name: entry.name, capturedAt: entry.capturedAt, appCount: Array.isArray(entry.install.apps) ? entry.install.apps.length : 0, size: JSON.stringify(entry).length, }) }) }) })(names[i]) } return chain.then(function (): BackupSummary[] { return out }) }) }) } export function delete_backup( name: string, store?: KeyStore, ): Promise<{ ok: true; name: string } | { ok: false; error: string }> { if (!isBackupName(name)) return Promise.resolve({ ok: false as const, error: 'unknown backup "' + String(name) + '"' }) return resolveStore(store).then(function (active: KeyStore) { return readBackupEntry(active, name).then(function (existing) { if (!existing) return { ok: false as const, error: 'unknown backup "' + name + '"' } return deleteKey(active, backupKey(name)).then(function () { return readBackupIndex(active).then(function (names: string[]) { var next = names.filter(function (one: string): boolean { return one !== name }) return writeBackupIndex(active, next).then(function (): { ok: true; name: string } { return { ok: true as const, name: name } }) }) }) }) }) } function validateBackupInstall(install: unknown): Promise<{ ok: true } | { ok: false; error: string }> { if (!isRecord(install) || !Array.isArray((install as Record)['apps'])) { return Promise.resolve({ ok: false as const, error: 'backup install payload needs an apps array' }) } var temp = createMemoryStore() return import_install(install, temp).then(function (result) { if (!result.ok) return { ok: false as const, error: result.error } return { ok: true as const } }) } /** * Restore a named backup: validate the snapshot fully (in a throwaway * memory store) before any delete, auto-snapshot the current install * first, wipe only install keys (registry, per-app def/state, pinned, * hidden, recent, homepage — never backups.* and never auth keys), * then write the snapshot contents. Unknown names, unknown format * tags, and corrupt entries return { ok:false } with the install * untouched. The result names the auto-snapshot so the caller can undo. */ export function restore( name: string, store?: KeyStore, ): Promise<{ ok: true; name: string; autoSnapshot: string; ids: string[] } | { ok: false; error: string }> { if (!isBackupName(name)) return Promise.resolve({ ok: false as const, error: 'unknown backup "' + String(name) + '"' }) return resolveStore(store).then(function (active: KeyStore) { return readBackupEntry(active, name).then(function (entry) { if (!entry) return { ok: false as const, error: 'unknown backup "' + name + '"' } return validateBackupInstall(entry.install).then(function (valid) { if (!valid.ok) return valid var autoBase = 'auto-' + String(Date.now()) return readBackupIndex(active).then(function (names: string[]) { var autoName = autoBase var counter = 1 while (names.indexOf(autoName) !== -1) { counter++ autoName = autoBase + '-' + String(counter) } return export_install(active).then(function (current: InstallExport) { var currentEntry: BackupEntry = { format: 'kody-os-backup/1', name: autoName, capturedAt: new Date().toISOString(), install: current, } return writeBackupEntry(active, currentEntry).then(function () { return listInstalledIds(active).then(function (ids: string[]) { var chain: Promise = Promise.resolve() for (var i = 0; i < ids.length; i++) { ;(function (want: string): void { chain = chain.then(function (): Promise { return deleteKey(active, defKey(want)).then(function (): Promise { return deleteKey(active, stateKey(want)).then(function (): Promise { return deleteInstallSnapshot(active, want) }) }) }) })(ids[i]) } return chain.then(function () { return Promise.all([ writePinned(active, []), writeHidden(active, []), writeRecent(active, []), writeHomepage(active, []), ]) }).then(function () { return import_install(entry.install, active).then(function (imported) { if (!imported.ok) return imported return { ok: true as const, name: name, autoSnapshot: autoName, ids: imported.ids } }) }) }) }) }) }) }) }) }) }