@fungi.computer/agar 0.0.0-stage → 0.0.1

package/dist/react.js

@@ -0,0 +1,111 @@
+import { useCallback, useEffect, useMemo, useRef, useSyncExternalStore, } from "react";
+import { createWhistle, } from "@fungi.computer/whistle";
+import { registerCatalog } from "./commands.js";
+import { AppError } from "./errors.js";
+export { mountApp } from "./react-mount.js";
+/** Read an SDK snapshot and release its subscription when the store changes. */
+export function useStore(store) {
+    const subscribe = useCallback((listener) => store?.subscribe(listener) ?? (() => undefined), [store]);
+    const snapshot = useCallback(() => store?.get(), [store]);
+    return useSyncExternalStore(subscribe, snapshot, snapshot);
+}
+/** Read the App's live context (focus, visibility, Computer selection, any
+ * pending open request), or null while there is no connected App. */
+export function useAppContext(app) {
+    return useStore(app?.context) ?? null;
+}
+/** Read the id of the Computer currently selected for this App, or null
+ * when no App is connected or no Computer is selected yet. */
+export function useComputerId(app) {
+    return useAppContext(app)?.computerId ?? null;
+}
+/**
+ * Keep this window's status bar items current in the host while mounted, and
+ * hear the person use them. Items compare by value; the bar clears on unmount.
+ */
+export function useWindowStatus(app, items, onAction, 
+/** Hear a report the host refused, so the App can say so. */
+onReportFailure) {
+    const latest = useRef(items);
+    latest.current = items;
+    const handler = useRef(onAction);
+    handler.current = onAction;
+    const failed = useRef(onReportFailure);
+    failed.current = onReportFailure;
+    const key = JSON.stringify(items);
+    const listening = onAction !== undefined;
+    useEffect(() => {
+        if (!app)
+            return;
+        void app.ui.reportStatus(latest.current).catch((cause) => {
+            if (failed.current)
+                failed.current(cause);
+            else
+                console.error("Window status report failed", cause);
+        });
+    }, [app, key]);
+    useEffect(() => {
+        if (!app || !listening)
+            return;
+        return app.ui.onStatusAction((action) => handler.current?.(action) ?? false);
+    }, [app, listening]);
+    useEffect(() => () => {
+        void app?.ui.reportStatus([]).catch((cause) => {
+            console.error("Window status report failed", cause);
+        });
+    }, [app]);
+}
+/**
+ * Own one catalog's local slash runtime and host registrations. Memoize `build`
+ * with useCallback; changing it replaces the catalog and its availability.
+ */
+export function useAppCommandCatalog(app, { sourceId, namespace }, build) {
+    const runtime = useMemo(() => createWhistle(), []);
+    const catalog = useMemo(build, [build]);
+    useEffect(() => {
+        const lease = runtime.contribute({
+            sourceId,
+            namespace,
+            commands: catalog,
+        });
+        return () => {
+            lease.dispose();
+        };
+    }, [runtime, sourceId, namespace, catalog]);
+    useEffect(() => (app ? registerCatalog(app.commands, catalog) : undefined), [app, catalog]);
+    return runtime;
+}
+/**
+ * Publish an App's navigation state to its host and own the host's Back
+ * requests while mounted. Pass `app?.window.navigation`; with no connected
+ * App it does nothing. Unmounting withdraws Back from the host chrome.
+ */
+export function useHostNavigation(navigation, { canGoBack, title, onBack }) {
+    const latestBack = useRef(onBack);
+    useEffect(() => {
+        latestBack.current = onBack;
+    }, [onBack]);
+    useEffect(() => {
+        if (!navigation)
+            return undefined;
+        const release = navigation.onBack(() => latestBack.current());
+        return () => {
+            release();
+            report(navigation, { canGoBack: false });
+        };
+    }, [navigation]);
+    // Each change replaces the last report; only unmount withdraws Back.
+    useEffect(() => {
+        if (!navigation)
+            return;
+        report(navigation, title === undefined ? { canGoBack } : { canGoBack, title });
+    }, [navigation, canGoBack, title]);
+}
+function report(navigation, state) {
+    navigation.publish(state).catch((cause) => {
+        // A closing App has no host left to tell; anything else is a real fault.
+        if (cause instanceof AppError && cause.code === "DISCONNECTED")
+            return;
+        console.warn("App navigation report failed", cause);
+    });
+}

package/dist/read-copy.d.ts

@@ -0,0 +1,103 @@
+import * as z from "zod";
+import { type GitBinding } from "./git.js";
+/** A facet's synchronous SQLite port, shared by Workers and local proofs. */
+export type ReadCopySql = {
+    /** Execute immediately, as ctx.storage.sql does. */
+    exec(query: string, ...bindings: (string | number | null | ArrayBuffer)[]): {
+        /** Decode the returned SQLite rows at the App boundary. */ toArray(): readonly unknown[];
+    };
+};
+/** App-selected shape and retention bounds; changing version discards old representations. */
+export type ReadCopyLimits = {
+    /** App copy-shape version, changed by a clean representation break. */
+    version: number;
+    /** Maximum retained document rows across this facet. */
+    maxRows: number;
+    /** Maximum UTF-8 JSON bytes per row. */
+    maxValueBytes: number;
+    /** Maximum bytes of one immutable blob. */
+    maxBlobBytes: number;
+    /** Maximum total retained blob bytes, oldest objects evicted first. */
+    maxBlobTotalBytes: number;
+};
+/** A screen reads this projection without asking Git whether it is current. */
+export type ReadCopyResult<T> = {
+    kind: "ready";
+    head: string | null;
+    value: T;
+} | {
+    kind: "missing";
+} | {
+    kind: "rebuilding";
+};
+/** A rebuild stops before dispatching the first call beyond its budget. */
+export declare class ReadCopyBudgetExceeded extends Error {
+    constructor();
+}
+/** Count binding operations, never authority or results. The signal is the caller's frame lifetime. */
+export declare function countingGit(binding: GitBinding, options: {
+    limit: number;
+    signal: AbortSignal;
+}): {
+    git: Readonly<{
+        create(name: string, options?: {
+            description?: string;
+            defaultBranch?: string;
+        }): Promise<import("./git.js").GitRepositoryInfo>;
+        fork(source: string, target: string, options?: {
+            description?: string;
+        }): Promise<import("./git.js").GitRepositoryInfo>;
+        cloneUrl(name: string): Promise<string>;
+        info(name: string): Promise<import("./git.js").GitRepositoryInfo | null>;
+        delete(name: string): Promise<boolean>;
+        log(name: string, options: {
+            ref: string;
+            limit?: number;
+            offset?: number;
+        }): Promise<import("./git.js").GitCommit[]>;
+        readCommit(name: string, hash: string): Promise<import("./git.js").GitCommit | null>;
+        readTree(name: string, hash: string): Promise<import("./git.js").GitTreeEntry[] | null>;
+        readBlob(name: string, hash: string): Promise<Uint8Array | null>;
+        refs(name: string): Promise<{
+            name: string;
+            hash: string;
+        }[]>;
+        exchange(name: string, request: import("./git.js").GitExchangeRequest): Promise<import("./git.js").GitExchangeResponse>;
+    }>;
+    /** Number of dispatched operations. */ total: () => number;
+    /** Dispatch counts by maintained Git operation. */ counts: () => {
+        [k: string]: number;
+    };
+};
+/** Own bounded rows and content-addressed bytes in the App facet, not a host/provider cache. */
+export declare function createReadCopies(sql: ReadCopySql, limits: ReadCopyLimits): {
+    /** Bind a namespace to its maintained App decoder. */
+    open: <T>(copy: string, schema: z.ZodType<T>) => {
+        /** Read the schema-decoded local projection. */
+        read: (key: string) => ReadCopyResult<T>;
+        /** Publish a successful Git write. */
+        write: (key: string, head: string | null, value: T) => void;
+        /** Refuse the row until rebuilt. */
+        stale: (key: string) => void;
+        /** An accepted push chains on before, ignores its own-write echo, and invalidates gaps/deletions. */
+        apply(key: string, update: {
+            before: string;
+            after: string;
+            value: T;
+            unexplained?: boolean;
+        }): "applied" | "echo" | "stale";
+        /** A missing key rebuilds only in this frame; budget exhaustion publishes no partial row. */
+        load(key: string, options: {
+            git: GitBinding;
+            signal: AbortSignal;
+            rebuild: (git: GitBinding) => Promise<{
+                head: string | null;
+                value: T;
+            }>;
+        }): Promise<ReadCopyResult<T>>;
+    };
+    /** Store immutable provider-identified bytes; enforce per-object and total retention bounds. */
+    putBlob(hash: string, bytes: Uint8Array): void;
+    /** A blob miss never performs I/O; the App decides which bounded rebuild owns it. */
+    readBlob(hash: string): Uint8Array | null;
+};

package/dist/read-copy.js

@@ -0,0 +1,195 @@
+import * as z from "zod";
+import {} from "./git.js";
+import { gitSha1Schema } from "@fungi.computer/puffball/git-representation";
+/** A rebuild stops before dispatching the first call beyond its budget. */
+export class ReadCopyBudgetExceeded extends Error {
+    constructor() {
+        super("Read-copy Git call budget exhausted");
+        this.name = "ReadCopyBudgetExceeded";
+    }
+}
+/** Count binding operations, never authority or results. The signal is the caller's frame lifetime. */
+export function countingGit(binding, options) {
+    z.number().int().positive().parse(options.limit);
+    const counts = new Map();
+    let total = 0;
+    function wrap(operation, call) {
+        return async (...args) => {
+            options.signal.throwIfAborted();
+            if (total >= options.limit)
+                throw new ReadCopyBudgetExceeded();
+            total++;
+            counts.set(operation, (counts.get(operation) ?? 0) + 1);
+            const result = await call(...args);
+            options.signal.throwIfAborted();
+            return result;
+        };
+    }
+    const git = {
+        create: wrap("create", (...args) => binding.create(...args)),
+        fork: wrap("fork", (...args) => binding.fork(...args)),
+        cloneUrl: wrap("cloneUrl", (...args) => binding.cloneUrl(...args)),
+        info: wrap("info", (...args) => binding.info(...args)),
+        delete: wrap("delete", (...args) => binding.delete(...args)),
+        log: wrap("log", (...args) => binding.log(...args)),
+        readCommit: wrap("readCommit", (...args) => binding.readCommit(...args)),
+        readTree: wrap("readTree", (...args) => binding.readTree(...args)),
+        readBlob: wrap("readBlob", (...args) => binding.readBlob(...args)),
+        refs: wrap("refs", (...args) => binding.refs(...args)),
+        exchange: wrap("exchange", (...args) => binding.exchange(...args)),
+    };
+    return {
+        git,
+        /** Number of dispatched operations. */ total: () => total,
+        /** Dispatch counts by maintained Git operation. */ counts: () => Object.fromEntries(counts),
+    };
+}
+const rowSchema = z.strictObject({
+    head: gitSha1Schema.nullable(),
+    version: z.number().int(),
+    revision: z.number().int(),
+    value: z.string().nullable(),
+});
+const name = z.string().min(1).max(1024);
+const zero = "0".repeat(40);
+const blobHash = z.union([
+    gitSha1Schema,
+    z.string().regex(/^sha256:[0-9a-f]{64}$/),
+]);
+/** Own bounded rows and content-addressed bytes in the App facet, not a host/provider cache. */
+export function createReadCopies(sql, limits) {
+    z.strictObject({
+        version: z.number().int().positive(),
+        maxRows: z.number().int().positive(),
+        maxValueBytes: z.number().int().positive(),
+        maxBlobBytes: z.number().int().positive(),
+        maxBlobTotalBytes: z.number().int().positive(),
+    }).parse(limits);
+    sql.exec("CREATE TABLE IF NOT EXISTS app_read_copy (copy TEXT NOT NULL, key TEXT NOT NULL, head TEXT, version INTEGER NOT NULL, revision INTEGER NOT NULL, value TEXT, PRIMARY KEY(copy,key))");
+    sql.exec("CREATE TABLE IF NOT EXISTS app_read_blob (hash TEXT PRIMARY KEY, bytes BLOB NOT NULL)");
+    function row(copy, key) {
+        const raw = sql
+            .exec("SELECT head,version,revision,value FROM app_read_copy WHERE copy=? AND key=?", copy, key)
+            .toArray()[0];
+        return raw === undefined ? null : rowSchema.parse(raw);
+    }
+    /** Bind an App-owned schema and copy namespace. */
+    function open(copy, schema) {
+        name.parse(copy);
+        /** Decode a local row; missing and stale never probe Git. */
+        function read(key) {
+            name.parse(key);
+            const saved = row(copy, key);
+            if (saved?.version !== limits.version || saved.value === null)
+                return { kind: "missing" };
+            return {
+                kind: "ready",
+                head: saved.head,
+                value: schema.parse(JSON.parse(saved.value)),
+            };
+        }
+        /** Store an accepted write after Git CAS succeeds. */
+        function write(key, head, value) {
+            name.parse(key);
+            gitSha1Schema.nullable().parse(head);
+            const encoded = JSON.stringify(z.json().parse(schema.parse(value)));
+            if (new TextEncoder().encode(encoded).byteLength > limits.maxValueBytes)
+                throw new RangeError("Read-copy row exceeds its byte bound");
+            sql.exec("INSERT INTO app_read_copy(copy,key,head,version,revision,value) VALUES(?,?,?,?,1,?) ON CONFLICT(copy,key) DO UPDATE SET head=excluded.head,version=excluded.version,revision=app_read_copy.revision+1,value=excluded.value", copy, key, head, limits.version, encoded);
+            sql.exec("DELETE FROM app_read_copy WHERE rowid IN (SELECT rowid FROM app_read_copy ORDER BY rowid DESC LIMIT -1 OFFSET ?)", limits.maxRows);
+        }
+        /** Invalidate one key and its in-flight rebuild. */
+        function stale(key) {
+            name.parse(key);
+            sql.exec("INSERT INTO app_read_copy(copy,key,head,version,revision,value) VALUES(?,?,NULL,?,1,NULL) ON CONFLICT(copy,key) DO UPDATE SET revision=app_read_copy.revision+1,value=NULL", copy, key, limits.version);
+            sql.exec("DELETE FROM app_read_copy WHERE rowid IN (SELECT rowid FROM app_read_copy ORDER BY rowid DESC LIMIT -1 OFFSET ?)", limits.maxRows);
+        }
+        return {
+            /** Read the schema-decoded local projection. */
+            read,
+            /** Publish a successful Git write. */
+            write,
+            /** Refuse the row until rebuilt. */
+            stale,
+            /** An accepted push chains on before, ignores its own-write echo, and invalidates gaps/deletions. */
+            apply(key, update) {
+                gitSha1Schema.parse(update.before);
+                gitSha1Schema.parse(update.after);
+                const current = read(key);
+                if (update.unexplained || update.after === zero) {
+                    stale(key);
+                    return "stale";
+                }
+                if (current.kind === "ready" && current.head === update.after)
+                    return "echo";
+                if (current.kind !== "ready" ||
+                    (current.head ?? zero) !== update.before) {
+                    stale(key);
+                    return "stale";
+                }
+                write(key, update.after, update.value);
+                return "applied";
+            },
+            /** A missing key rebuilds only in this frame; budget exhaustion publishes no partial row. */
+            async load(key, options) {
+                options.signal.throwIfAborted();
+                const ready = read(key);
+                if (ready.kind === "ready")
+                    return ready;
+                const before = JSON.stringify(row(copy, key));
+                const counted = countingGit(options.git, {
+                    limit: 40,
+                    signal: options.signal,
+                });
+                try {
+                    const rebuilt = await options.rebuild(counted.git);
+                    options.signal.throwIfAborted();
+                    if (JSON.stringify(row(copy, key)) !== before)
+                        return read(key);
+                    write(key, rebuilt.head, rebuilt.value);
+                    return read(key);
+                }
+                catch (error) {
+                    if (error instanceof ReadCopyBudgetExceeded)
+                        return { kind: "rebuilding" };
+                    throw error;
+                }
+            },
+        };
+    }
+    return {
+        /** Bind a namespace to its maintained App decoder. */
+        open,
+        /** Store immutable provider-identified bytes; enforce per-object and total retention bounds. */
+        putBlob(hash, bytes) {
+            blobHash.parse(hash);
+            if (bytes.byteLength >
+                Math.min(limits.maxBlobBytes, limits.maxBlobTotalBytes))
+                throw new RangeError("Read-copy blob exceeds its byte bound");
+            sql.exec("INSERT INTO app_read_blob(hash,bytes) VALUES(?,?) ON CONFLICT(hash) DO NOTHING", hash, new Uint8Array(bytes).buffer);
+            while (z
+                .strictObject({ size: z.number() })
+                .parse(sql
+                .exec("SELECT COALESCE(SUM(length(bytes)),0) AS size FROM app_read_blob")
+                .toArray()[0]).size > limits.maxBlobTotalBytes)
+                sql.exec("DELETE FROM app_read_blob WHERE rowid=(SELECT MIN(rowid) FROM app_read_blob)");
+        },
+        /** A blob miss never performs I/O; the App decides which bounded rebuild owns it. */
+        readBlob(hash) {
+            blobHash.parse(hash);
+            const result = sql
+                .exec("SELECT bytes FROM app_read_blob WHERE hash=?", hash)
+                .toArray()[0];
+            return result === undefined
+                ? null
+                : new Uint8Array(z
+                    .strictObject({
+                    bytes: z.union([
+                        z.instanceof(ArrayBuffer),
+                        z.instanceof(Uint8Array),
+                    ]),
+                })
+                    .parse(result).bytes);
+        },
+    };
+}