@fungi.computer/nacre 0.0.0-stage → 0.0.1

package/dist/app-directory.js

@@ -0,0 +1,323 @@
+import * as Schema from "effect/Schema";
+import { appDeclaredCommandSchema, appCallsSchema, } from "@fungi.computer/puffball/app";
+import { appDeclaredGillSchema, appGillParamsSchema, } from "@fungi.computer/gills";
+import * as z from "zod";
+/** An App address selects a host default or a specific installation. */
+export const appAddressSchema = z.lazy(() => z.union([
+    z.strictObject({
+        /** Marks an address that selects a host default App. */
+        kind: z.literal("default"),
+        /** The App whose host default is selected. */
+        appId: z.string().min(1),
+    }),
+    z.strictObject({
+        /** Marks an address that selects one installation. */
+        kind: z.literal("installation"),
+        /** The installation that is selected. */
+        installationId: z.string().min(1),
+    }),
+]));
+/** Host-reported progress of applying a revised App authority version. */
+export const appAuthorityEnforcementSchema = z.lazy(() => z.strictObject({
+    /** The host's id for the authority change being applied. */
+    requestId: z.string().min(1),
+    /** The App address whose authority changed. */
+    address: appAddressSchema,
+    /** The authority version being applied. */
+    authorityVersion: z.number().int().positive(),
+    /** How far the change has progressed. */
+    state: z.enum({
+        /** The change needs no delivery. */
+        unaffected: "unaffected",
+        /** Some deliveries are still unconfirmed. */
+        pending: "pending",
+        /** Every delivery was confirmed. */
+        applied: "applied",
+        /** Nothing is outstanding, but not every delivery was confirmed. */
+        expired: "expired",
+    }),
+    /** How many deliveries of the change are still unconfirmed. */
+    outstanding: z.number().int().nonnegative(),
+}));
+/** Stable identity of one App address across directory and settings views. */
+export const addressKey = (address) => address.kind === "default"
+    ? `default:${address.appId}`
+    : `installation:${address.installationId}`;
+/** Reusable App metadata supplied by an embedding host; it conveys no permissions. */
+export const appDirectoryEntrySchema = z.strictObject({
+    /** The address that selects this App. */
+    address: appAddressSchema,
+    /** The installation this row describes, or null when it describes none. */
+    installationId: z.string().min(1).nullable(),
+    /** The id of the App surface this row opens. */
+    surfaceId: z.string().min(1),
+    /** The App's id. */
+    appId: z.string().min(1),
+    /** The name shown for the App. */
+    displayName: z.string().trim().min(1).optional(),
+    /** The App's icon, or null when it has none. */
+    icon: z.string().min(1).nullable().optional(),
+    /** The Release the row runs, or null when none is recorded. */
+    releaseId: z.string().min(1).nullable(),
+    /** The version of the App's authority. */
+    authorityVersion: z.number().int().nonnegative(),
+    /**
+     * Progress of applying a revised authority version, or null when none is in
+     * progress.
+     */
+    enforcement: appAuthorityEnforcementSchema.nullable(),
+    /** The kinds of handler the App offers, such as file.open. */
+    handlers: z.array(z.literal("file.open")),
+    /** The roles the App can fill. */
+    roles: z.array(z.string().min(1)),
+    /** Capabilities the Release declares: the ceiling for host consent, never a grant. */
+    declaredCapabilities: z.array(z.string().min(1)),
+    /** The calls the App's Release declares. */
+    calls: z
+        .unknown()
+        .transform((value) => Schema.decodeUnknownSync(appCallsSchema)(value))
+        .optional(),
+    /** The commands the App's Release declares. */
+    commands: z
+        .array(z.unknown())
+        .transform((values) => values.map((value) => Schema.decodeUnknownSync(appDeclaredCommandSchema)(value))),
+    /** The Gills the App's Release declares. */
+    gills: z.array(z.unknown()).transform((values) => values.map((value) => Schema.decodeUnknownSync(appDeclaredGillSchema, {
+        onExcessProperty: "error",
+    })(value))),
+    /** Whether the App can be opened now. */
+    availability: z.enum({
+        /** The App can be opened. */
+        available: "available",
+        /** The App cannot be opened now. */
+        unavailable: "unavailable",
+    }),
+    /** The App's surface, or null when it has none. */
+    surface: z
+        .strictObject({
+        /** The route that identifies the surface across Releases. */
+        stableRoute: z.string().min(1),
+    })
+        .nullable(),
+    /** The path, starting with a slash, where the surface is served. */
+    surfacePath: z.string().startsWith("/"),
+});
+/** A host-resolved role selection; a surface address is not launch authority. */
+export const appRoleSelectionSchema = z.strictObject({
+    /** The surface selected for the role, or null when none is. */
+    surfaceId: z.string().min(1).nullable(),
+    /** Whether an App is selected for the role. */
+    chosen: z.boolean(),
+});
+const appComputerOperationSchema = z.enum({
+    /** List the Team's Computers. */
+    "computer.list": "computer.list",
+    /** Read a file on a Computer. */
+    "computer.readFile": "computer.readFile",
+    /** Write a file on a Computer. */
+    "computer.writeFile": "computer.writeFile",
+    /** Run a command on a Computer. */
+    "computer.execute": "computer.execute",
+});
+const selectedComputerPermissionSchema = z.lazy(() => z.strictObject({
+    /** Marks a permission limited to selected Computers. */
+    kind: z.literal("selected-computers"),
+    /** The selected Computers and what the App may do on each. */
+    computers: z.array(z.strictObject({
+        /** The Computer the operations apply to. */
+        computerId: z.string().min(1),
+        /** The operations the App may request on that Computer. */
+        operations: z.array(appComputerOperationSchema),
+    })),
+}));
+const allTeamComputersPermissionSchema = z.lazy(() => z.strictObject({
+    /** Marks a permission covering all of the Team's Computers. */
+    kind: z.literal("all-team-computers"),
+    /** The operations the App may request on any Team Computer. */
+    operations: z.array(appComputerOperationSchema),
+}));
+/** App Computer permissions limited to selected Computers or the Team's Computers. */
+export const appComputerPermissionSchema = z.discriminatedUnion("kind", [
+    selectedComputerPermissionSchema,
+    allTeamComputersPermissionSchema,
+]);
+const agentDirectoryOperationSchema = z.enum({
+    /** List the Team's agents. */
+    "agent.list": "agent.list",
+});
+const agentSessionOperationSchema = z.enum({
+    /** Read an agent's session. */
+    "agent.read": "agent.read",
+    /** Send a message in an agent's session. */
+    "agent.send": "agent.send",
+    /** Manage an agent's session. */
+    "agent.manage": "agent.manage",
+});
+/** Agent directory and session operations an App may request from its host. */
+export const appAgentPermissionSchema = z.discriminatedUnion("kind", [
+    z.strictObject({
+        /** Marks a permission covering all of the Team's agents. */
+        kind: z.literal("all-team-agents"),
+        /** What the App may do with the agent directory. */
+        directoryOperations: z.array(agentDirectoryOperationSchema),
+        /** What the App may do in any agent's session. */
+        sessionOperations: z.array(agentSessionOperationSchema),
+    }),
+    z.strictObject({
+        /** Marks a permission limited to selected agents. */
+        kind: z.literal("selected-agents"),
+        /** What the App may do with the agent directory. */
+        directoryOperations: z.array(agentDirectoryOperationSchema),
+        /** The selected agents and what the App may do in each one's session. */
+        agents: z.array(z.strictObject({
+            /** The agent the operations apply to. */
+            agentId: z.string().min(1).max(256),
+            /** What the App may do in that agent's session. */
+            sessionOperations: z.array(agentSessionOperationSchema),
+        })),
+    }),
+]);
+/** Whether an App may use language-model and media generation services. */
+export const appGenerationPermissionsSchema = z.strictObject({
+    /** Whether the App may use language-model generation. */
+    llm: z.boolean(),
+    /** Whether the App may use media generation. */
+    media: z.boolean(),
+});
+/** Whether an App may browse, buy, or install free marketplace entries. */
+export const appMarketplacePermissionsSchema = z.strictObject({
+    /** Whether the App may browse marketplace entries. */
+    browse: z.boolean(),
+    /** Whether the App may buy marketplace entries. */
+    purchase: z.boolean(),
+    /** Whether the App may install free marketplace entries. */
+    installFree: z.boolean(),
+});
+/**
+ * A host's Team App directory with its permission projection, parsed strictly
+ * by every consumer: an unknown field is a contract change both sides make.
+ */
+export const appDirectoryResponseSchema = z.lazy(() => z.strictObject({
+    /** Whether the person asking owns the Team. */
+    actorIsTeamOwner: z.boolean(),
+    /** Directory records the host rejected. Each carries identity only, never launch authority. */
+    needsUpdate: z
+        .array(z.strictObject({
+        /** The rejected record's installation, or null when it has none. */
+        installationId: z.string().min(1).nullable(),
+        /** The rejected record's App, or null when unknown. */
+        appId: z.string().min(1).nullable(),
+        /** The name shown for the rejected record. */
+        displayName: z.string().min(1),
+    }))
+        .optional(),
+    /** The Team's App rows with their permissions. */
+    apps: z.array(appDirectoryEntrySchema.extend({
+        /**
+         * The Release and surface route the Team has set for this App, or null when none.
+         */
+        override: z
+            .strictObject({
+            /** The App the override names. */
+            appId: z.string().min(1).optional(),
+            /** The Release the override pins. */
+            releaseId: z.string().min(1),
+            /**
+             * The surface route the override pins, or null when it pins none.
+             */
+            surfaceRoute: z.string().min(1).nullable(),
+        })
+            .nullable(),
+        /** The operation grants held for this App. */
+        grants: z.array(z.strictObject({
+            /** The operation that is granted. */
+            operation: z.string().min(1),
+            /** The resource the grant covers. */
+            resourceId: z.string().min(1),
+        })),
+        /**
+         * The App's Computer permission, or null or absent when it has none.
+         */
+        computerPermission: appComputerPermissionSchema.nullable().optional(),
+        /** The App's generation permissions. */
+        generationPermissions: appGenerationPermissionsSchema,
+        /** The App's marketplace permissions. */
+        marketplacePermissions: appMarketplacePermissionsSchema,
+        /** The App's Agent permission. */
+        agentPermission: appAgentPermissionSchema,
+    })),
+    /** The Team's effective App per role, owned and resolved by the host. */
+    roles: z.record(z.string().min(1), appRoleSelectionSchema),
+}));
+/** Desktop metadata is a method result, distinct from the full Release Gill declaration. */
+const catalogGillParamsSchema = z.lazy(() => z
+    .array(z.strictObject({
+    /** The parameter's key. */
+    key: z.string().max(64),
+    /** The label shown for the parameter. */
+    label: z.string().max(256),
+    /** What the parameter picks: a Computer, a repository or a branch. */
+    kind: z.enum(["computer", "repository", "branch"]),
+    /** Whether the Gill cannot be placed without it. */
+    required: z.boolean(),
+    /** Extra options for the parameter. */
+    options: z.string().max(256).optional(),
+}))
+    .max(4)
+    // The wire shape is representable; Gill owns its domain refinements.
+    .refine(Schema.is(appGillParamsSchema), "Invalid Gill placement parameters"));
+const catalogGillSchema = z.strictObject({
+    /** The Gill's id. */
+    id: z.string().trim().min(1).max(256),
+    /** The name shown for the Gill. */
+    title: z.string().trim().min(1).max(256),
+    /** Placement parameters the Gill asks for. */
+    params: catalogGillParamsSchema.optional(),
+    /** How the Gill may appear on the dashboard. */
+    desktop: z
+        .strictObject({
+        /** Layout sizes the Gill supports. */
+        sizes: z
+            .array(z.enum({
+            /** Small: one dashboard cell. */
+            S: "S",
+            /** Medium: two cells wide, one tall. */
+            M: "M",
+            /** Large: two cells wide, two tall. */
+            L: "L",
+        }))
+            .min(1)
+            .max(3)
+            .refine((sizes) => new Set(sizes).size === sizes.length, "Repeated Gill size"),
+    })
+        .optional(),
+});
+/** Read-only catalog metadata for one App, without host-specific role policy. */
+export const appCatalogEntrySchema = appDirectoryEntrySchema
+    .pick({
+    surfaceId: true,
+    appId: true,
+    displayName: true,
+})
+    .extend({
+    /** The Gills the App declares for the desktop. */
+    gills: z.array(catalogGillSchema).max(16),
+});
+/** Read-only desktop metadata; identities are surface addresses, never launch authority. */
+export const appCatalogResponseSchema = z.lazy(() => z.strictObject({
+    /** The Apps in the catalog. */
+    apps: z.array(appCatalogEntrySchema).max(50),
+    /** The role selections the catalog reports. */
+    roles: z.strictObject({
+        /** The selection for the inbox role, when there is one. */
+        inbox: appRoleSelectionSchema.optional(),
+    }),
+}));
+/** Complete APPS.catalog reply, including broker admission failures. */
+export const appCatalogBrokerResultSchema = z.lazy(() => z.union([
+    appCatalogResponseSchema,
+    z.strictObject({
+        /** Why the broker refused the catalog request. */
+        error: z.string(),
+    }),
+]));

package/dist/browser-actions.d.ts

@@ -0,0 +1,7 @@
+import type { AppBrowserAction, AppBrowserActionOutcome } from "@fungi.computer/agar";
+/** Browser effects stay in the trusted host, bound to one mounted App frame. */
+export declare function createBrowserActionHandler(options: {
+    frame: HTMLIFrameElement;
+    hostWindow: Window;
+    signal: AbortSignal;
+}): (request: AppBrowserAction) => Promise<AppBrowserActionOutcome>;

package/dist/browser-actions.js

@@ -0,0 +1,56 @@
+import { APP_BROWSER_SAVE_MAX_BYTES, APP_BROWSER_COPY_MAX_BYTES, } from "@fungi.computer/agar";
+/** Browser effects stay in the trusted host, bound to one mounted App frame. */
+export function createBrowserActionHandler(options) {
+    let pending = false;
+    return async (request) => {
+        const { frame, hostWindow, signal } = options;
+        if (signal.aborted || !frame.isConnected)
+            return { kind: "refused", reason: "unavailable" };
+        if (!hostWindow.navigator.userActivation.isActive ||
+            hostWindow.document.activeElement !== frame)
+            return { kind: "refused", reason: "no-user-gesture" };
+        if (request.kind === "saveFile"
+            ? request.bytes.byteLength > APP_BROWSER_SAVE_MAX_BYTES
+            : new TextEncoder().encode(request.text).byteLength >
+                APP_BROWSER_COPY_MAX_BYTES)
+            return { kind: "refused", reason: "too-large" };
+        if (pending)
+            return { kind: "refused", reason: "busy" };
+        pending = true;
+        try {
+            if (request.kind === "copyText") {
+                await hostWindow.navigator.clipboard.writeText(request.text);
+                return { kind: "copied" };
+            }
+            const blob = new Blob([new Uint8Array(request.bytes)], {
+                type: request.mime,
+            });
+            const url = URL.createObjectURL(blob);
+            try {
+                const link = hostWindow.document.createElement("a");
+                link.href = url;
+                link.download = request.name;
+                link.click();
+            }
+            finally {
+                // Keep the bytes alive until the browser handles the navigation task.
+                hostWindow.setTimeout(() => {
+                    URL.revokeObjectURL(url);
+                }, 0);
+            }
+            // The browser accepted a download; this does not attest a disk write.
+            return { kind: "saved" };
+        }
+        catch (cause) {
+            return {
+                kind: "refused",
+                reason: cause instanceof DOMException && cause.name === "NotAllowedError"
+                    ? "denied"
+                    : "unavailable",
+            };
+        }
+        finally {
+            pending = false;
+        }
+    };
+}

package/dist/command-host.d.ts

@@ -0,0 +1,140 @@
+/** An optional field a declaration may carry as explicitly undefined. */
+export type AppCommandOptional<T> = T | undefined;
+/**
+ * The digest-covered command rows a mounted App's Release declares, as the
+ * host receives them. Oyster compares and projects them; the Release
+ * declaration grammar stays with its owner, which hands rows of this shape.
+ */
+export type AppCommandDeclaration = Readonly<{
+    /** The command's id inside the App's Release declaration. */
+    id: string;
+    /** The name people see for the command. */
+    title: string;
+    /** The group the command is listed under. */
+    category: string;
+    /** What the command does, in a sentence. */
+    description?: AppCommandOptional<string>;
+    /** Where the command is offered, with a sort position for each place. */
+    projections?: AppCommandOptional<Readonly<{
+        /** Key bindings that run the command. */
+        bindings?: AppCommandOptional<Readonly<{
+            /** Sort position among the binding rows. */
+            order?: AppCommandOptional<number>;
+            /**
+             * The binding strings, such as alt+left or a sequence after the
+             * leader key.
+             */
+            values: readonly string[];
+        }>>;
+        /** The command as offered to an agent. */
+        agent?: AppCommandOptional<Readonly<{
+            /** Sort position among the agent rows. */
+            order?: AppCommandOptional<number>;
+            /** The key binding an agent uses to run the command. */
+            keybind?: AppCommandOptional<string>;
+        }>>;
+        /** The command as listed in help. */
+        help?: AppCommandOptional<Readonly<{
+            /** Sort position among the help rows. */
+            order?: AppCommandOptional<number>;
+        }>>;
+        /** The command as listed in a menu. */
+        menu?: AppCommandOptional<Readonly<{
+            /** Sort position among the menu rows. */
+            order?: AppCommandOptional<number>;
+        }>>;
+        /** The command as listed in the command palette. */
+        palette?: AppCommandOptional<Readonly<{
+            /** Sort position among the palette rows. */
+            order?: AppCommandOptional<number>;
+        }>>;
+        /** The command as a slash command. */
+        slash?: AppCommandOptional<Readonly<{
+            /** Sort position among the slash rows. */
+            order?: AppCommandOptional<number>;
+            /** Other slash names that run the command. */
+            aliases: readonly string[];
+        }>>;
+    }>>;
+}>;
+import type { AppHostHandlers, AppHostReservedChord } from "@fungi.computer/agar/host";
+import { type WhistleExecutionInput, type WhistleExecutionOutcome, type WhistleContributionLease, type WhistleCommand, type WhistleMenuProjection, type WhistleRuntime, type WhistleSnapshot } from "@fungi.computer/whistle";
+/** Select the shell command-palette chord for a Mac or non-Mac keyboard. */
+export declare function commandPaletteReservedChordForPlatform(mac: boolean): AppHostReservedChord;
+/** Select the shell command-palette chord from the embedding browser user agent. */
+export declare function commandPaletteReservedChordForUserAgent(userAgent: string): AppHostReservedChord;
+/** Whistle source of Release-advertised rows for Apps not yet mounted. */
+export declare const appDirectorySourceId = "app-directory";
+/** The command side of one mounted App's host handlers. */
+export type AppSurfaceCommandMount = Readonly<{
+    /** Borrow this mount's live Agent projection and gated execution, not the shell graph. */
+    readonly agentCommands: Pick<WhistleRuntime, "snapshot" | "execute">;
+    /** The narrow handler shape consumed by Agar's App host connection. */
+    readonly handlers: Pick<AppHostHandlers, "registerCommands" | "invokeReservedChord">;
+    /** Release this App's contribution and its mount identity. */
+    readonly dispose: () => void;
+}>;
+/** Commands owned by one pane, projected to globals plus its focus scope. */
+export type PaneCommands = Readonly<{
+    /** Qualify a locally contributed id in this pane's own namespace. */
+    commandId: (id: string) => string;
+    /** Contribute or replace commands owned by this pane through the returned lease. */
+    contribute: (commands: readonly WhistleCommand<never>[]) => WhistleContributionLease;
+    /** Run a command by id. */
+    execute: WhistleRuntime["execute"];
+    /** Read the commands and bindings currently available. */
+    snapshot: WhistleRuntime["snapshot"];
+    /** Be told when the available commands change. */
+    subscribe: WhistleRuntime["subscribe"];
+    /** Registered locally; only the focused pane presents human executions. */
+    present: WhistleRuntime["present"];
+}>;
+/** Closing a pane withdraws all its leases, presenters and subscriptions. */
+export type PaneCommandMount = PaneCommands & Readonly<{
+    /** Withdraw this pane's contributions, presenters and subscriptions. */
+    dispose: () => void;
+}>;
+/** The shell-owned Whistle graph and its focused menu projection. */
+export type AppSurfaceCommandHost = Readonly<{
+    /** Create the command scope for one locally rendered pane. */
+    readonly mountPane: (paneId: string) => PaneCommandMount;
+    /** Create one command admission scope for a mounted App. */
+    readonly mount: (mountId: string, declarations: readonly AppCommandDeclaration[]) => AppSurfaceCommandMount;
+    /** Select the App or pane whose commands are the active human-facing ones. */
+    readonly focus: (mountId: string | null) => void;
+    /** Register the shell's own global commands in the shared Whistle graph. */
+    readonly registerShellCommands: (commands: readonly WhistleCommand<never>[]) => () => void;
+    /** Publish verified Release command rows before their App is mounted. */
+    readonly registerDirectoryCommands: (commands: readonly Readonly<{
+        surfaceId: string;
+        appTitle: string;
+        command: AppCommandDeclaration;
+    }>[], run: (surfaceId: string, commandId: string) => Promise<void>) => () => void;
+    /** Read the menu rows belonging to the focused App. */
+    readonly menu: () => readonly WhistleMenuProjection[];
+    /**
+     * The human-facing commands for the current focus: shell rows plus the
+     * focused mount's rows, with its aliases and keys shadowing the shell's.
+     */
+    readonly active: () => WhistleSnapshot;
+    /** Execute an active row, an agent row, or an exact programmatic action. */
+    readonly execute: (commandId: string, input: WhistleExecutionInput) => Promise<WhistleExecutionOutcome>;
+    /** Read the complete renderer-neutral graph for host consumers. */
+    readonly snapshot: () => WhistleSnapshot;
+    /** Observe graph changes, including contribution replacement and disposal. */
+    readonly subscribe: (listener: () => void) => () => void;
+    /** Dispose all App contributions and close the shell runtime. */
+    readonly dispose: () => void;
+}>;
+/**
+ * Own one shell's Whistle runtime for mounted Apps and local panes. The
+ * embedding host supplies verified Release declarations and decides which
+ * App or pane has focus.
+ *
+ * Agar invokes `registerCommands` once for the aggregate command set of a
+ * mount. The adapter keeps that aggregate as one Whistle generation, so an
+ * Agar update replaces the generation atomically and disposal releases only
+ * that App. Command handlers remain the App's callback; the shell only adds
+ * the Whistle identity and routes focused menu execution to it.
+ */
+export declare function createAppSurfaceCommandHost(whistle?: WhistleRuntime): AppSurfaceCommandHost;