@mentra/engine 0.1.0-dev.0

package/build/services/AppRegistry.d.ts

@@ -0,0 +1,303 @@
+/**
+ * AppRegistry — on-disk install/uninstall registry for local miniapps.
+ *
+ * Owns the `Documents/lmas/<packageName>/<version>/` filesystem layout, the
+ * download/unzip pipeline, and the active-version pointer in MMKV. It does
+ * NOT touch the apps store directly — instead it notifies subscribers when
+ * the install set changes, so the host (mobile manager, OEM app) can refresh
+ * its own state.
+ *
+ * Public surface:
+ *   - installFromUrl(url, opts?)            install/replace a miniapp from a URL
+ *   - installFromLocalZip(path, opts?)      install/replace from a local zip
+ *   - uninstall(packageName, version?)      remove one or all versions
+ *   - getInstalledMiniapps()                ClientApp[] derived from disk
+ *   - getActiveVersion(packageName)         active version string for a package
+ *   - getBundleDir / getMiniappManifest     filesystem helpers used by hosts
+ *   - subscribe(fn)                         register a refresh listener
+ */
+import { AsyncResult, Result } from "typesafe-ts";
+import type { AppletPermission, AppletType, ClientApp, DeclaredAction } from "../types/applet";
+import { HardwareRequirement } from "../types";
+/**
+ * Normalize the `permissions` field from a miniapp.json manifest.
+ *
+ * New miniapps ship `[{type, required?, description?}]` objects. A few older
+ * installed bundles may have `["MICROPHONE", ...]` plain strings. Accept both.
+ */
+export declare function normalizeManifestPermissions(raw: Array<string | {
+    type: string;
+    required?: boolean;
+    description?: string;
+}> | undefined): AppletPermission[];
+/**
+ * Normalize a manifest's `actions` into DeclaredAction[]. Defensive — keeps only
+ * well-formed `{id, description}` entries (installed/dev bundles may be
+ * malformed). Shared by installed (disk) and dev-sideload projection so both
+ * surface declared actions to session.miniapps.list + the invoke gate.
+ */
+export declare function normalizeManifestActions(raw: unknown): DeclaredAction[];
+/**
+ * Convert declared hardwareRequirements from a miniapp.json manifest into
+ * runtime `HardwareRequirement[]`, always appending `{EXIST, REQUIRED}` so
+ * launchers show "Glasses Required" when no glasses are connected.
+ *
+ * Malformed entries are dropped with a single warning per package so the
+ * rest of the manifest still works.
+ */
+export declare function buildHardwareRequirements(raw: Array<{
+    type: string;
+    level: string;
+    description?: string;
+}> | undefined, packageName: string): HardwareRequirement[];
+interface InstalledInfo {
+    name: string;
+    logoUrl: string;
+}
+interface InstalledLma {
+    packageName: string;
+    versions: Record<string, InstalledInfo>;
+}
+type Listener = () => void;
+declare class AppRegistry {
+    private cachedApps;
+    private offlineApps;
+    /** Package names whose start() requires the on-device STT model (host-declared). */
+    private sttModelRequired;
+    private refreshNeeded;
+    private listeners;
+    private static instance;
+    private constructor();
+    static getInstance(): AppRegistry;
+    /** Subscribe to install/uninstall events. Listener fires after refreshNeeded flips. */
+    subscribe(fn: Listener): () => void;
+    private notify;
+    /**
+     * On-disk path for a given miniapp bundle version.
+     */
+    getBundleDir(packageName: string, version: string): string;
+    /**
+     * Resolve the two-layer entry paths for an installed miniapp version.
+     * Returns absolute file:// URIs for `background` and (when present) `ui`.
+     *
+     * Legacy single-layer bundles (no `entry` object in manifest) fall back
+     * to `index.html` discovery so the WebView host keeps working unchanged.
+     * Two-layer bundles ship `entry.background` and optional `entry.ui`
+     * paths relative to the bundle root.
+     *
+     * Returns null if neither shape resolves to existing files on disk.
+     */
+    getMiniappEntryPaths(packageName: string, version: string): {
+        background: string | null;
+        ui: string | null;
+    } | null;
+    /**
+     * Verify a manifest declares an SDK / host version range compatible
+     * with the current host. Delegates to the pure
+     * {@link checkManifestVersions} helper — same shape, no React Native
+     * imports, unit-testable. Manifests missing either field pass
+     * through unchanged (legacy single-layer path).
+     */
+    checkManifestVersions(manifest: {
+        sdkVersion?: string;
+        minHostVersion?: string;
+    } | null, options: {
+        hostVersion: string;
+        supportedSdkRange: string;
+    }): {
+        ok: true;
+    } | {
+        ok: false;
+        reason: string;
+    };
+    /**
+     * Read and parse the miniapp manifest (miniapp.json with app.json fallback)
+     * from a given bundle directory.
+     */
+    getMiniappManifest(packageName: string, version: string): any;
+    /**
+     * Download and install a miniapp bundle from a URL. The URL must serve a
+     * zip whose root contains `miniapp.json` plus the bundle entry files.
+     *
+     * @param opts.versionOverride  if set, install under this version instead
+     *   of `manifest.version`. The dev caching path uses `dev-<ms>` so multiple
+     *   snapshots can coexist alongside semver-installed versions.
+     */
+    installFromUrl(url: string, opts?: {
+        versionOverride?: string;
+    }): AsyncResult<void, Error>;
+    /**
+     * Install a miniapp from a zip already on local disk (e.g. a bundled asset
+     * copied into cache). Skips the HTTP download path that `installFromUrl`
+     * uses — `File.downloadFileAsync` is HTTP(S)-only and rejects file:// URIs.
+     *
+     * @param zipPath  file:// URI of the local zip.
+     */
+    installFromLocalZip(zipPath: string, opts?: {
+        versionOverride?: string;
+    }): AsyncResult<{
+        packageName: string;
+        version: string;
+    }, Error>;
+    /**
+     * Post-install bookkeeping shared by every install path: clear stale dev
+     * artifacts on release installs, point the active-version at the just-
+     * installed bundle, and notify subscribers to refresh.
+     */
+    private finalizeInstall;
+    installFromJsonUrl(baseUrl: string): AsyncResult<{
+        packageName: string;
+        version: string;
+        name: string;
+    }, Error>;
+    /**
+     * Drop every dev-* version directory for a package plus ALL dev MMKV keys
+     * (URL/port/reachability + the home-tile metadata record). Called on a
+     * release install (dev → released transition) and on uninstall, so a dev
+     * package leaves nothing behind that `projectDevApps` could re-surface.
+     */
+    private clearDevArtifacts;
+    /**
+     * Garbage-collect older `dev-*` version directories for this package,
+     * keeping the latest `keep` (by lexicographic sort, which matches
+     * timestamp ordering since dev-<ms> is zero-padded).
+     *
+     * Only touches `dev-*` versions; semver-installed versions are left alone.
+     */
+    gcDevVersions(packageName: string, keep: number): void;
+    uninstall(packageName: string, version?: string): AsyncResult<void, Error>;
+    getPackageNames(): string[];
+    getInstalledVersions(packageName: string): string[];
+    getActiveVersion(packageName: string): Promise<string>;
+    setActiveVersion(packageName: string, version: string): Result<void, Error>;
+    getMetadata(packageName: string, version: string): InstalledInfo;
+    getInstalledInfo(): InstalledLma[];
+    /**
+     * Read the lmas/ tree and return one ClientApp per installed package,
+     * picking each package's active version. The store/host overlays runtime
+     * state (loading, hidden, compatibility) on top of these.
+     *
+     * `running` reflects MiniappHost mount state via miniappRunningRegistry.
+     */
+    /**
+     * Merge disk-derived apps with the projected dev + offline layers,
+     * de-duping by packageName. A real on-disk install (or offline app) wins
+     * over a dev tile of the same package — a dev record is just a launcher
+     * stub that an actual install supersedes.
+     */
+    private mergeProjectedApps;
+    getInstalledMiniapps(): Promise<ClientApp[]>;
+    /** Force the next getInstalledMiniapps() to re-derive from disk + records. */
+    markRefreshNeeded(): void;
+    /**
+     * Project persisted dev-app metadata records into ClientApp tiles. Dev
+     * miniapps aren't installed to disk (they load over HTTP), so they don't
+     * appear in the `lmas/` scan — this surfaces them on the home screen so
+     * they're re-launchable without re-scanning the QR.
+     */
+    private projectDevApps;
+    private projectOfflineApps;
+    installOfflineApp(app: ClientApp, opts?: {
+        requiresLocalSttModel?: boolean;
+    }): void;
+    /**
+     * Registered as needing the on-device STT model before it can start (the
+     * host declares this per offline app; the apps store gates start() on it).
+     */
+    requiresLocalSttModel(packageName: string): boolean;
+    getMiniappHtml(packageName: string, version: string): Result<string, Error>;
+}
+/**
+ * Persist the running flag for a local miniapp (read on next cold boot so
+ * autostart picks the right set of apps). Exported for hosts that want to
+ * track running state independently.
+ */
+export declare function saveLocalAppRunningState(packageName: string, status: boolean): void;
+export declare function getLocalAppRunningState(packageName: string): boolean;
+export declare function getLocalAppScreenshot(packageName: string): string | undefined;
+/**
+ * Persisted metadata for a dev miniapp's home tile.
+ *
+ * Dev miniapps load directly off the dev server over HTTP and are NOT
+ * installed into `lmas/`, so the disk scan in `getInstalledMiniapps` can't
+ * see them. We persist a tiny record at scan / dev-URL-entry time so the
+ * tile survives across app launches and is re-launchable without re-scanning.
+ * `permissions` / `hardwareRequirements` are snapshotted from the manifest so
+ * the home-screen permission gate has data without a disk bundle.
+ */
+export interface DevAppRecord {
+    packageName: string;
+    name: string;
+    iconUrl: string;
+    devUrl: string;
+    devPort?: number;
+    type?: AppletType;
+    permissions?: Array<string | {
+        type: string;
+        required?: boolean;
+        description?: string;
+    }>;
+    hardwareRequirements?: Array<{
+        type: string;
+        level: string;
+        description?: string;
+    }>;
+    /** Manifest-declared actions — so dev-sideloaded miniapps can be invoked too. */
+    actions?: Array<{
+        id?: unknown;
+        description?: unknown;
+        parameters?: unknown;
+    }>;
+    /**
+     * The dev miniapp's real manifest package name. `packageName` is overwritten to
+     * {@link DEV_APP_PACKAGE_NAME} so the launch chain routes consistently, so this field
+     * preserves the original so install/uninstall of OTHER packages don't wipe the dev slot.
+     */
+    sourcePackageName?: string;
+    /**
+     * Short-lived Core-verifiable proof emitted by `mentra dev`. This lets the
+     * single `com.dev` slot request auto-auth for the real package without
+     * letting arbitrary dev URLs claim any package name.
+     */
+    devAttestation?: string;
+}
+/**
+ * The one and only package name a dev miniapp is registered under.
+ *
+ * There is a SINGLE dev slot: scanning a new QR (or entering a new dev URL)
+ * replaces the previous dev app rather than adding a second tile. Because the
+ * whole launch chain — JSContext registration, UI-router binding,
+ * setForeground, dev_url/dev_port storage keys, respawn-bg lookup — keys on
+ * this package name, every consumer MUST use `DEV_APP_PACKAGE_NAME` (not the
+ * manifest's real packageName) so messages route consistently. Mixing the two
+ * was the cause of the "CONNECT_ACK timeout" — the tile said `com.dev` while
+ * the dev URL/port and foreground target used the manifest name.
+ */
+export declare const DEV_APP_PACKAGE_NAME = "com.dev";
+export declare const DEV_APP_NAME = "Dev";
+/**
+ * Register (or replace) THE dev miniapp. Persists the home-tile metadata AND
+ * the dev_url/dev_port keyed on {@link DEV_APP_PACKAGE_NAME}, so this function
+ * is the single source of truth for the dev slot — callers must not write the
+ * `*_dev_url` / `*_dev_port` keys under the manifest's real package name.
+ *
+ * Callers pass the manifest's REAL packageName/name. Only the packageName is
+ * forced to {@link DEV_APP_PACKAGE_NAME} so the home tile and launch chain key
+ * on the single dev slot (the real package survives in `sourcePackageName` for
+ * clearDevArtifacts). The name + icon are kept as-is so the home tile reflects
+ * the actual dev miniapp — marked as dev by the {@link DevMiniappBadge} dot
+ * rather than renamed to a generic "Dev" tile.
+ */
+export declare function registerDevApp(record: DevAppRecord): void;
+/** Drop the dev miniapp's home-tile metadata + dev URL/port keys. */
+export declare function unregisterDevApp(): void;
+/**
+ * The real manifest package name currently occupying the dev slot, or null if no dev app is
+ * registered. Used to decide whether clearing a package's artifacts should also drop the dev slot.
+ */
+export declare function getDevAppSourcePackage(): string | null;
+export declare function getDevAppAttestation(): string | null;
+export declare function getDevAppRecords(): DevAppRecord[];
+declare const appRegistry: AppRegistry;
+export default appRegistry;
+//# sourceMappingURL=AppRegistry.d.ts.map

package/build/services/AppRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AppRegistry.d.ts","sourceRoot":"","sources":["../../src/services/AppRegistry.ts"],"names":[],"mappings":"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"}