Skip to content
← Public packages

@hypercubed/kody-os

Minimal shared Human/Agent OS shell — ReKindle-style blank slate for browser-first use.

FollowFork

Files

registry.ts

2269 lines · 93.0 KB · TypeScript
/**
 * 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<string> | 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<string> {
	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<AppDefinition>(store, defKey(id)),
		readJson<AppState>(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<string[]> {
	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<string[]> {
	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<string[]> {
	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<string[]> {
	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<void> {
	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<string[]> {
	return resolveStore(store).then(function (active: KeyStore) {
		return readHomepage(active).then(function (ids: string[]): Promise<string[]> {
			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<string[]> {
	return resolveStore(store).then(function (active: KeyStore) {
		return readHomepage(active).then(function (ids: string[]): Promise<string[]> {
			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<void> {
	return resolveStore(store).then(function (active: KeyStore) {
		return writePinned(active, ids)
	})
}

/** Overwrite the hidden list. */
export function set_hidden(ids: string[], store?: KeyStore): Promise<void> {
	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<void> {
	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<string[]> {
	return resolveStore(store).then(function (active: KeyStore) {
		return readRecent(active).then(function (ids: string[]): Promise<string[]> {
			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<string[]> {
	return resolveStore(store).then(function (active: KeyStore) {
		return readPinned(active).then(function (ids: string[]): Promise<string[]> {
			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<string[]> {
	return resolveStore(store).then(function (active: KeyStore) {
		return readHidden(active).then(function (ids: string[]): Promise<string[]> {
			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<string[]> {
	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<string[]> {
		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<string[]> {
	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<unknown> = Promise.resolve()
	for (var r = 0; r < retired.length; r++) {
		;(function (id: string): void {
			chain = chain
				.then(function (): Promise<void> { return deleteKey(store, defKey(id)) })
				.then(function (): Promise<void> { return deleteKey(store, stateKey(id)) })
				.then(function (): Promise<void> { return deleteInstallSnapshot(store, id) })
		})(retired[r])
	}
	return chain.then(function (): Promise<string[]> {
		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<string[]> {
			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<AppSummary[]> {
	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<AppSummary[]> {
		var hiddenP: Promise<string[]> = options && options.includeHidden === false ? readHidden(active) : Promise.resolve([] as string[])
		return hiddenP.then(function (hidden: string[]): Promise<AppSummary[]> {
			return listInstalledIds(active).then(function (derived: string[]): Promise<AppSummary[]> {
				return pruneRetiredApps(derived, active).then(function (ids: string[]): Promise<AppSummary[]> {
					var out: AppSummary[] = []
					var chain = Promise.resolve()
					for (var id of ids) {
						;(function (want: string): void {
							chain = chain.then(function (): Promise<void> {
								if (hidden.indexOf(want) !== -1) return Promise.resolve()
								return readJson<AppDefinition>(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<AppState | { error: string }> {
	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<string, unknown>,
	store?: KeyStore,
): Promise<ActResult> {
	return resolveStore(store).then(function (active: KeyStore): Promise<ActResult> {
		return loadEntry(active, id).then(function (entry): Promise<ActResult> {
			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<string, ActionDef> | 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<string, number | string | boolean> = {}
			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<string, unknown>
			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<number | string | boolean>).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<string, unknown>)['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<ActResult> {
				return record_use(id, active).then(function (): ActResult {
					return { ok: true, state: next }
				})
			})
		})
	})
}

export interface AddAppOptions {
	resetState?: boolean
	migrate?: Record<string, string>
}

/**
 * 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<AppDefinition>(active, defKey(definition.id)),
			readJson<AppState>(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<string, StateFieldDef>
				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<string, unknown>
						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<AppDefinition>(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<string | null> {
	return readJson<unknown>(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<string | null> {
	return readJson<AppDefinition>(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<string | null> {
	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<string | null> {
	return readJson<AppDefinition>(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<string | null> {
	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<string | null> {
	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<string | null> {
	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.<id>.
 */
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<InstallSnapshot | null> {
	return readJson<InstallSnapshot>(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<void> {
	return writeJson(store, snapshotKey(id), snapshot)
}

export function deleteInstallSnapshot(store: KeyStore, id: string): Promise<void> {
	return deleteKey(store, snapshotKey(id))
}

function recordInstallSnapshot(store: KeyStore, id: string): Promise<{ ok: true } | { ok: false; error: string }> {
	return readJson<AppDefinition>(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<AppDefinition>(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<boolean> {
	return readJson<AppDefinition>(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<StoreSelfUpdate> {
	return Promise.all([
		readJson<AppDefinition>(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<ManageResult> {
	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<ManageResult> {
	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<ManageResult> {
	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<AppDefinition>(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<ManageResult> {
	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<ManageResult> {
	return manage_update_with_status(actingId, targetId, confirmed, store, 'update')
}

export function manage_restore(actingId: string, targetId: string, confirmed: boolean, store?: KeyStore): Promise<ManageResult> {
	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<AppStoreStatusInfo> {
	return resolveStore(store).then(function (active: KeyStore) {
		return Promise.all([
			readJson<AppDefinition>(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<StoreRow[]> {
	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<StoreRow[]> {
			var idSet: Record<string, boolean> = {}
			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<void> {
						return Promise.all([
							readJson<AppDefinition>(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<StoreRow[]> {
	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<void> {
				return Promise.all([
					readJson<AppDefinition>(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<string, unknown>)['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<string, unknown>)['minPackageVersion'] !== undefined ? String((installedDef as unknown as Record<string, unknown>)['minPackageVersion']) : undefined,
						shellVersion: running,
						needsNewerShell: (installedDef as unknown as Record<string, unknown>)['minPackageVersion'] !== undefined ? rowNeedsNewerShell((installedDef as unknown as Record<string, unknown>)['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<AppExport | { error: string }> {
	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<InstallExport> {
	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<void> {
						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<string, unknown>)['apps'])) {
			return Promise.resolve({ ok: false as const, error: 'import payload needs an apps array' })
		}
		var rec = payload as Record<string, unknown>
		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<string, unknown>
	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<string, unknown> = {}
	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<string, unknown>
					if (isRecord(env['state'])) rawState = env['state']
				}
				if (!isRecord(rawState)) return { ok: true as const, id: def.id }
				var st = rawState as Record<string, unknown>
				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.<name>`. 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<string[]> {
	return readJson<string[]>(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<void> {
	return writeJson(store, BACKUP_INDEX_KEY, names)
}

function readBackupEntry(store: KeyStore, name: string): Promise<BackupEntry | null> {
	return readJson<BackupEntry>(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<void> {
	return readBackupIndex(store).then(function (names: string[]): Promise<void> {
		if (names.indexOf(entry.name) === -1) names.push(entry.name)
		return writeJson(store, backupKey(entry.name), entry).then(function (): Promise<void> {
			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<BackupSummary[]> {
	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<void> {
						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<string, unknown>)['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<void> = Promise.resolve()
								for (var i = 0; i < ids.length; i++) {
									;(function (want: string): void {
										chain = chain.then(function (): Promise<void> {
											return deleteKey(active, defKey(want)).then(function (): Promise<void> {
												return deleteKey(active, stateKey(want)).then(function (): Promise<void> {
													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 }
									})
								})
							})
						})
					})
				})
			})
		})
	})
}