@fungi.computer/agar 0.0.0-stage → 0.0.1

package/dist/git.js

@@ -0,0 +1,98 @@
+import { gitRepositoryNameSchema, gitSha1Schema, gitRefUpdateSchema, gitPushEventIdSchema, } from "@fungi.computer/puffball/git-representation";
+import * as z from "zod";
+import { appMethodCallerSchema, hostActorSchema, workflowAttestationSchema, } from "@fungi.computer/puffball/app-method-runtime";
+/** Requested installation-scoped Git authority; a declaration is never a grant. */
+export const gitRepositoryCapability = "git.repository";
+/**
+ * Host-selected repository namespace. Team identity comes from the host;
+ * decoding this reference never grants access to either namespace.
+ */
+export const repositoryRefSchema = z.discriminatedUnion("kind", [
+    z.strictObject({
+        kind: z.literal("installation"),
+        installationId: z.string().min(1).max(256),
+        repository: gitRepositoryNameSchema,
+    }),
+    z.strictObject({
+        kind: z.literal("team-source"),
+        repository: gitRepositoryNameSchema,
+    }),
+]);
+/** Stable namespace identity, serialized through the canonical repository decoder. */
+export function repositoryRefKey(repository) {
+    return JSON.stringify(repositoryRefSchema.parse(repository));
+}
+/** Compare repository namespace and coordinates independently of allocation or property order. */
+export function repositoryRefsEqual(left, right) {
+    return repositoryRefKey(left) === repositoryRefKey(right);
+}
+const hostActor = z.discriminatedUnion("kind", [
+    z.strictObject(hostActorSchema.def.options[0].shape),
+    z.strictObject(hostActorSchema.def.options[1].shape),
+    z.strictObject(hostActorSchema.def.options[2].shape),
+]);
+/** Canonical Git writer decoder; identity is attested by a host, never by an App. */
+export const gitWriterSchema = z.discriminatedUnion("kind", [
+    z.strictObject({
+        kind: z.literal("actor"),
+        actor: hostActor,
+        role: appMethodCallerSchema.shape.role,
+        workflow: z
+            .strictObject({
+            ...workflowAttestationSchema.shape,
+            armedBy: hostActor,
+            branches: z
+                .array(z.string().startsWith("refs/heads/").max(1024))
+                .min(1)
+                .max(256),
+        })
+            .optional(),
+    }),
+    z.strictObject({
+        kind: z.literal("installation"),
+        installationId: z.string().min(1).max(256),
+        onBehalfOf: hostActor.nullable(),
+    }),
+]);
+/** The App's question covers the whole push, under host-held attribution. */
+export const gitPushQuestionSchema = z.strictObject({
+    repository: gitRepositoryNameSchema,
+    writer: gitWriterSchema.options[0],
+    updates: z.array(gitRefUpdateSchema).min(1).max(256),
+});
+/** A whole push verdict; refusal messages are shown by ordinary Git clients. */
+export const gitPushVerdictSchema = z.discriminatedUnion("allowed", [
+    z.strictObject({ allowed: z.literal(true) }),
+    z.strictObject({
+        allowed: z.literal(false),
+        refused: z
+            .array(z.strictObject({
+            ref: z.string().startsWith("refs/").max(1024),
+            message: z.string().max(200),
+        }))
+            .min(1)
+            .max(256),
+    }),
+]);
+/** One accepted push, with host attribution and no remote or credential. */
+export const appGitPushFactSchema = z.strictObject({
+    repository: gitRepositoryNameSchema,
+    writer: gitWriterSchema,
+    updates: z.array(gitRefUpdateSchema).min(1).max(256),
+    unexplained: z
+        .array(z.strictObject({
+        ref: z.string().startsWith("refs/").max(1024),
+        journaled: gitSha1Schema.nullable(),
+    }))
+        .max(256)
+        .optional(),
+    // Host event IDs may include a Computer ID as well as its local event ID.
+    eventId: gitPushEventIdSchema,
+});
+/** Parse a host-admitted fact and invoke its lifecycle handler, preserving rejection. */
+export async function dispatchAppGitPush(lifecycle, raw) {
+    const fact = appGitPushFactSchema.parse(raw);
+    if (lifecycle.onGitPush === undefined)
+        throw new Error("App Git push handler unavailable");
+    await lifecycle.onGitPush(fact);
+}

package/dist/host.d.ts

@@ -0,0 +1,97 @@
+import type { AppCommand } from "./commands.js";
+import type { WhistleExecutionOrigin, WhistleJsonValue } from "@fungi.computer/whistle";
+import type { AppContext, AppIdentity, FocusState } from "./lifecycle.js";
+import type { AppNavigationState } from "./window.js";
+import type { AppBrowserAction, AppBrowserActionOutcome, AgentSessionSelection, AppPermissionOutcome, AppPermissionRequest, AppStatusAction, AppStatusItem, FileNavigationInput, ToastInput } from "./ui.js";
+import { AppError } from "./errors.js";
+import { type AppConnectMessage } from "./internal/protocol.js";
+export type AppHost = {
+    disconnect(error?: AppError): Promise<void>;
+    dispose(): void;
+    requestClose(): Promise<boolean>;
+    /** Ask the App to go back one step in its own history; `true` when it did. */
+    requestBack(): Promise<boolean>;
+    /** Deliver the person's use of a status item; `true` when the App acted. */
+    activateStatus(action: AppStatusAction): Promise<boolean>;
+    updateContext(fact: AppHostFact<AppContext>): Promise<void>;
+    reconfigure(value: AppHostReconfiguration): Promise<void>;
+    updateLifecycle(fact: AppHostFact<"connected" | "suspended">): Promise<void>;
+    updateReservedChords(fact: AppHostFact<readonly AppHostReservedChord[]>): Promise<void>;
+    updateTheme(fact: AppHostFact<string>): Promise<void>;
+};
+export type AppHostReconfiguration = {
+    readonly capabilities: AppHostLaunch["capabilities"];
+    readonly context: AppHostFact<AppContext>;
+};
+export type AppHostFact<T> = {
+    readonly value: T;
+    readonly version: number;
+};
+export type AppHostHandlers = {
+    /** Open the embedding host's picker, without accepting an App-selected Computer. */
+    readonly requestComputerChoice?: () => Promise<void>;
+    readonly requestBrowserAction?: (input: AppBrowserAction) => Promise<AppBrowserActionOutcome>;
+    readonly invokeReservedChord: (input: {
+        readonly id: string;
+        readonly repeat: boolean;
+    }) => Promise<void>;
+    readonly onDisconnect: () => Promise<void>;
+    readonly openNavigation: (input: FileNavigationInput) => Promise<void>;
+    readonly openTeamBilling?: () => Promise<void>;
+    readonly openDesktopSettings?: () => Promise<void>;
+    readonly requestAppPermissions?: (input: AppPermissionRequest) => Promise<AppPermissionOutcome>;
+    readonly registerCommands: (input: {
+        readonly commands: readonly AppCommand[];
+        readonly invoke: (commandId: string, input: {
+            readonly arguments?: WhistleJsonValue;
+            readonly origin: WhistleExecutionOrigin;
+            readonly signal?: AbortSignal;
+        }) => Promise<WhistleJsonValue | undefined>;
+    }) => Promise<AppCommandContribution>;
+    readonly reportFocus: (input: FocusState) => Promise<void>;
+    /** The App's latest navigation state; hosts without window chrome omit it. */
+    readonly reportNavigation?: (input: AppNavigationState) => Promise<void>;
+    /** The App's latest status readouts; hosts without a status bar omit it. */
+    readonly reportStatus?: (items: readonly AppStatusItem[]) => Promise<void>;
+    readonly reportAgentSessionSelection: (input: AgentSessionSelection | null) => Promise<void>;
+    readonly showToast: (input: ToastInput) => Promise<void>;
+};
+/** One host-owned Whistle contribution for all commands in an App mount. */
+export type AppCommandContribution = {
+    readonly update: (commands: readonly AppCommand[]) => void;
+    readonly dispose: () => void;
+};
+export type AppHostLaunch = {
+    readonly capabilities: readonly {
+        /** A live Cap'n Web handle; it remains opaque to the adapter. */
+        readonly handle: object;
+        readonly id: string;
+        readonly version: number;
+    }[];
+    readonly context: AppHostFact<AppContext>;
+    readonly identity: AppIdentity;
+    readonly lifecycle: AppHostFact<"connected" | "suspended">;
+    readonly reservedChords: AppHostFact<readonly AppHostReservedChord[]>;
+    readonly theme: AppHostFact<string>;
+};
+export type AppHostReservedChord = {
+    readonly altKey: boolean;
+    readonly ctrlKey: boolean;
+    readonly id: string;
+    readonly key: string;
+    readonly metaKey: boolean;
+    readonly shiftKey: boolean;
+};
+export type ConnectAppHostOptions = {
+    readonly appWindow: {
+        postMessage(message: AppConnectMessage, targetOrigin: string, transfer: Transferable[]): void;
+    };
+    /** Serialized document origin; "null" requires a host-owned opaque sandbox. */
+    readonly expectedAppOrigin: string;
+    readonly handlers: AppHostHandlers;
+    readonly hostWindow: Pick<Window, "addEventListener" | "removeEventListener">;
+    readonly launch: AppHostLaunch;
+    readonly signal?: AbortSignal;
+};
+/** The host-only adapter owns iframe authentication and the hidden Cap'n Web epoch. */
+export declare function connectAppHost(options: ConnectAppHostOptions): Promise<AppHost>;