@north-light/api 0.3.589 → 0.3.590

package/dist/core/scoped-state/person-store.d.ts

@@ -10,12 +10,33 @@ export interface PersonSnapshot {
     defaults: Record<string, string>;
     settings: Record<string, Record<string, unknown>>;
     state: Record<string, ScopeState>;
+    /** App installs (`app:<id>` → plugins, marketplaces) with a revision covering only that app's block. Cloud roles write plugins here, never to `settings`. */
+    apps: Record<string, AppInstallBlock>;
+}
+export interface AppInstallBlock {
+    plugins: Record<string, {
+        enabled?: boolean;
+        source_marketplace?: string;
+        version?: string;
+    }>;
+    marketplaces: Record<string, {
+        url?: string;
+        ref?: string;
+        installed_at?: string;
+    }>;
+    revision: string;
 }
 export type SettingsOp = {
     op: 'settings.replace';
     owner: string;
     raw: Record<string, unknown>;
     ifRevision: string;
+} | {
+    op: 'app-plugins.replace';
+    app: string;
+    plugins: AppInstallBlock['plugins'];
+    marketplaces: AppInstallBlock['marketplaces'];
+    ifRevision: string;
 } | {
     op: 'state.write';
     owner: string;
@@ -40,6 +61,8 @@ export declare class PersonSettingsNotLoadedError extends Error {
     constructor(person: string);
 }
 declare const BLOCKS: readonly ["plugins", "marketplaces"];
+/** The revision of an app's install block; `absent` for an app with no rows. */
+export declare function appRevisionOf(block: Pick<AppInstallBlock, 'plugins' | 'marketplaces'> | undefined): string;
 export declare function revisionOf(raw: Record<string, unknown> | undefined): string;
 export declare function installPersonSnapshot(person: string, snapshot: PersonSnapshot): void;
 export declare function heldPersons(): string[];

package/dist/core/scoped-state/person-store.js

@@ -13,6 +13,10 @@ export class PersonSettingsNotLoadedError extends Error {
 }
 const BLOCKS = ['plugins', 'marketplaces'];
 const caches = new Map();
+/** The revision of an app's install block; `absent` for an app with no rows. */
+export function appRevisionOf(block) {
+    return block === undefined ? 'absent' : revisionOf({ plugins: block.plugins, marketplaces: block.marketplaces });
+}
 export function revisionOf(raw) {
     return raw === undefined ? 'absent' : createHash('sha256').update(JSON.stringify(raw)).digest('hex');
 }
@@ -20,7 +24,7 @@ export function revisionOf(raw) {
 export function installPersonSnapshot(person, snapshot) { caches.set(person, snapshot); }
 export function heldPersons() { return [...caches.keys()]; }
 export function dropPersonSnapshots() { caches.clear(); }
-const emptySnapshot = () => ({ profiles: [], defaults: {}, settings: {}, state: {} });
+const emptySnapshot = () => ({ profiles: [], defaults: {}, settings: {}, state: {}, apps: {} });
 let prelude;
 /** Before the install's person is resolved (a Mac's first boot reads its config to resolve it), reads answer from this snapshot of
  *  the old local store; `loadPersonSettings` replaces it once the person is known. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/api",
-  "version": "0.3.589",
+  "version": "0.3.590",
   "description": "Typed crtrd /v1 API contract — DTOs, route builders, the error contract, the CrtrClient, and the command-plugin manifest format. Zero runtime dependencies.",
   "type": "module",
   "main": "./dist/api/index.js",

package/dist/core/graph/package-kinds.d.ts

@@ -1,22 +0,0 @@
-import type { CanvasDb } from '../canvas/db.js';
-export interface KindsReport {
-    /** every kind a valid plugin declares that now has its row, and what upserting it did */
-    applied: Array<{
-        plugin: string;
-        kind: string;
-        outcome: 'inserted' | 'updated' | 'unchanged';
-    }>;
-    /** kinds another owner holds; the plugin's other kinds still applied */
-    refused: Array<{
-        plugin: string;
-        kind: string;
-        code: 'kind_owned';
-        message: string;
-    }>;
-    /** enabled plugins whose manifest or commands are invalid (no kind update, no token); a provider bundle's kinds reconcile without a token, and plugins whose app handle another owner holds */
-    invalid: Array<{
-        plugin: string;
-        error: string;
-    }>;
-}
-export declare function reconcilePackageKinds(db: CanvasDb): Promise<KindsReport>;

package/dist/core/graph/package-kinds.js

@@ -1,49 +0,0 @@
-/** Installed plugins' `object_kinds` blocks → `object_kinds` rows. Runs in the caller's write transaction.
- *  A kind is never deleted and its catalog is never altered when undeclared: only `declared` flips, so the
- *  instances of a dropped kind go inert instead of vanishing. */
-import { CrtrError } from '../errors.js';
-import { invalidAppPlugins, kindPlugins } from '../plugin-app.js';
-import { upsertKind } from './custom.js';
-import { ensureOwner } from './objects.js';
-export async function reconcilePackageKinds(db) {
-    const report = { applied: [], refused: [], invalid: invalidAppPlugins().map((i) => ({ plugin: i.plugin.name, error: i.error })) };
-    const declared = new Set();
-    for (const plugin of kindPlugins()) {
-        const kinds = Object.entries(plugin.manifest.object_kinds ?? {});
-        if (kinds.length === 0)
-            continue;
-        let owner;
-        try {
-            owner = await ensureOwner(db, 'app', 'app', `app:${plugin.name}`, plugin.name);
-        }
-        catch (error) {
-            if (!(error instanceof CrtrError) || error.code !== 'conflict')
-                throw error;
-            report.invalid.push({ plugin: plugin.name, error: error.message });
-            continue;
-        }
-        for (const [kind, decl] of kinds) {
-            try {
-                const result = await upsertKind(db, {
-                    name: kind, owner, description: decl.description, events: decl.events,
-                    read: decl.read === undefined ? null : { command: decl.read.command }, source: 'manifest',
-                });
-                if (result.outcome === 'skipped')
-                    continue;
-                declared.add(kind);
-                report.applied.push({ plugin: plugin.name, kind, outcome: result.outcome });
-            }
-            catch (error) {
-                if (!(error instanceof CrtrError) || error.code !== 'kind_owned')
-                    throw error;
-                report.refused.push({ plugin: plugin.name, kind, code: 'kind_owned', message: error.message });
-            }
-        }
-    }
-    const rows = await db.prepare("SELECT name FROM object_kinds WHERE source = 'manifest' AND declared = 1").all();
-    for (const { name } of rows) {
-        if (!declared.has(name))
-            await db.prepare('UPDATE object_kinds SET declared = 0 WHERE name = ?').run(name);
-    }
-    return report;
-}

package/dist/core/scoped-state/materialized-plugins.d.ts

@@ -1,20 +0,0 @@
-/** One enabled plugin row of the person's user scope, with its marketplace's url and ref. */
-export interface PluginInstall {
-    name: string;
-    version: string | null;
-    sourcePath: string | null;
-    marketplace: {
-        name: string;
-        url: string | null;
-        ref: string | null;
-    } | null;
-    /** A directory provider bundle (`isProviderBundleRow`): a provider call installs it into this process's own plugin directory, so there is nothing to fetch. */
-    providerBundle: boolean;
-}
-/** The directory holding this person's materialized plugins as `<dir>/<plugin name>`; undefined when none were materialized. */
-export declare function materializedPluginsDir(person: string): string | undefined;
-/** Install `installs` for `person` at `revision` into this process's plugin cache, once per (person, revision). When a plugin cannot
- *  be installed — a source on another machine, a marketplace that does not list it, a failed clone — the failure is held for that person
- *  and thrown by the next read of their plugins (`materializedPluginsDir`), so a request that never reads plugins, such as the one that
- *  fixes the settings, still works; the next load retries. */
-export declare function materializePlugins(person: string, revision: number, installs: readonly PluginInstall[]): Promise<void>;

package/dist/core/scoped-state/materialized-plugins.js

@@ -1,105 +0,0 @@
-// materialized-plugins.ts — the plugin bytes a cloud-role process holds for the people it serves (D84). A person's enabled plugins are
-// rows (`scope_plugins`, `scope_marketplaces`); a fresh API process has no plugin directories, so before it reads plugin manifests it
-// installs each enabled plugin from its marketplace into a process-local directory keyed by (person, plugins_revision). Leaf-safe:
-// the installed-plugin reader imports this, so it imports no database. `loadPersonSettings` (person-rows.ts) fills it.
-import { cpSync, existsSync, mkdirSync, renameSync, rmSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { isAbsolute, join, relative, resolve } from 'node:path';
-import { CrtrError } from '../errors.js';
-import { gitAsync } from '../git.js';
-import { readMarketplaceManifest } from '../manifest.js';
-const materialized = new Map();
-const inFlight = new Map();
-/** The directory holding this person's materialized plugins as `<dir>/<plugin name>`; undefined when none were materialized. */
-export function materializedPluginsDir(person) {
-    const held = materialized.get(person);
-    if (held !== undefined && 'failure' in held)
-        throw held.failure;
-    return held?.dir;
-}
-function cacheRoot(person) { return join(tmpdir(), 'crtr-plugin-cache', person.replace(/[^A-Za-z0-9._-]/g, '_')); }
-async function cloneInto(url, ref, dest, what) {
-    const res = await gitAsync(['clone', '--depth', '1', ...(ref ? ['--branch', ref] : []), url, dest]);
-    if (res.status !== 0)
-        throw new CrtrError('plugin_install_failed', `${what}: git clone ${url} failed: ${res.stderr.trim()}`);
-}
-async function installAll(staging, installs) {
-    const marketRoots = new Map();
-    mkdirSync(join(staging, 'plugins'), { recursive: true });
-    for (const plugin of installs) {
-        if (plugin.sourcePath !== null)
-            throw new CrtrError('plugin_source_unreachable', `${plugin.name}: its source is ${plugin.sourcePath} on the machine that registered it, which the control plane cannot read`);
-        const market = plugin.marketplace;
-        if (plugin.providerBundle)
-            continue;
-        if (market === null)
-            throw new CrtrError('plugin_source_unreachable', `${plugin.name}: it names neither a marketplace nor a path`);
-        if (market.url === null || market.url === '')
-            throw new CrtrError('plugin_source_unreachable', `${plugin.name}: its marketplace ${market.name} has no url`);
-        const key = `${market.url}\0${market.ref ?? ''}`;
-        let root = marketRoots.get(key);
-        if (root === undefined) {
-            root = join(staging, 'marketplaces', String(marketRoots.size));
-            await cloneInto(market.url, market.ref, root, `${plugin.name}: marketplace ${market.name}`);
-            marketRoots.set(key, root);
-        }
-        const entry = readMarketplaceManifest(root)?.plugins.find((p) => p.name === plugin.name);
-        if (entry === undefined)
-            throw new CrtrError('plugin_install_failed', `${plugin.name}: marketplace ${market.name} (${market.url}) does not list it`);
-        const dest = join(staging, 'plugins', plugin.name);
-        if (isAbsolute(entry.source) || /^[a-z][a-z0-9+.-]*:|^git@/i.test(entry.source) || entry.source.endsWith('.git')) {
-            await cloneInto(entry.source, null, dest, plugin.name);
-            continue;
-        }
-        const from = resolve(root, entry.source);
-        const inside = relative(root, from);
-        if (inside.startsWith('..') || isAbsolute(inside))
-            throw new CrtrError('plugin_install_failed', `${plugin.name}: its source ${entry.source} leaves the marketplace`);
-        if (!existsSync(from))
-            throw new CrtrError('plugin_install_failed', `${plugin.name}: its source ${entry.source} is not in marketplace ${market.name}`);
-        cpSync(from, dest, { recursive: true });
-    }
-    rmSync(join(staging, 'marketplaces'), { recursive: true, force: true });
-}
-/** Install `installs` for `person` at `revision` into this process's plugin cache, once per (person, revision). When a plugin cannot
- *  be installed — a source on another machine, a marketplace that does not list it, a failed clone — the failure is held for that person
- *  and thrown by the next read of their plugins (`materializedPluginsDir`), so a request that never reads plugins, such as the one that
- *  fixes the settings, still works; the next load retries. */
-export async function materializePlugins(person, revision, installs) {
-    const held = materialized.get(person);
-    if (held?.revision === revision && !('failure' in held))
-        return;
-    const final = join(cacheRoot(person), String(revision));
-    const key = `${person}\0${revision}`;
-    let pending = inFlight.get(key);
-    if (pending === undefined) {
-        pending = (async () => {
-            if (!existsSync(join(final, 'plugins'))) {
-                const staging = join(cacheRoot(person), `${revision}.${process.pid}.${Date.now()}`);
-                try {
-                    await installAll(staging, installs);
-                    try {
-                        renameSync(staging, final);
-                    }
-                    catch (error) {
-                        if (!existsSync(join(final, 'plugins')))
-                            throw error;
-                    }
-                }
-                finally {
-                    rmSync(staging, { recursive: true, force: true });
-                }
-            }
-            return join(final, 'plugins');
-        })().finally(() => inFlight.delete(key));
-        inFlight.set(key, pending);
-    }
-    try {
-        materialized.set(person, { revision, dir: await pending });
-    }
-    catch (error) {
-        if (!(error instanceof CrtrError))
-            throw error;
-        materialized.set(person, { revision, failure: error });
-    }
-}