@fungi.computer/agar 0.0.0-stage → 0.0.1

package/dist/roles/files.d.ts

@@ -0,0 +1,295 @@
+/**
+ * The `files` App role contract. An App that fills the Team's files role
+ * receives a {@link FilesLocation} through an `apps.open` navigate intent, and
+ * file browsing, edit and snapshot payloads travel in these shapes. Role names
+ * belong to Puffball's App vocabulary; this module owns the files role's wire.
+ */
+import * as z from "zod";
+import type { AppNavigateIntent } from "../apps.js";
+/** The App role this contract serves. */
+export declare const filesRole = "files";
+export declare const commit: z.ZodObject<{
+    hash: z.ZodString;
+    treeHash: z.ZodString;
+    message: z.ZodString;
+    author: z.ZodObject<{
+        name: z.ZodString;
+        email: z.ZodString;
+    }, z.core.$strict>;
+    committer: z.ZodObject<{
+        name: z.ZodString;
+        email: z.ZodString;
+    }, z.core.$strict>;
+    parents: z.ZodArray<z.ZodString>;
+    authoredAt: z.ZodNumber;
+    committedAt: z.ZodNumber;
+}, z.core.$strict>;
+export type Commit = z.infer<typeof commit>;
+export declare const treeEntry: z.ZodObject<{
+    name: z.ZodString;
+    mode: z.ZodString;
+    hash: z.ZodString;
+    type: z.ZodEnum<{
+        blob: "blob";
+        tree: "tree";
+        commit: "commit";
+    }>;
+}, z.core.$strict>;
+export type TreeEntry = z.infer<typeof treeEntry>;
+export declare const treeListing: z.ZodObject<{
+    ref: z.ZodString;
+    commit: z.ZodObject<{
+        hash: z.ZodString;
+        treeHash: z.ZodString;
+        message: z.ZodString;
+        author: z.ZodObject<{
+            name: z.ZodString;
+            email: z.ZodString;
+        }, z.core.$strict>;
+        committer: z.ZodObject<{
+            name: z.ZodString;
+            email: z.ZodString;
+        }, z.core.$strict>;
+        parents: z.ZodArray<z.ZodString>;
+        authoredAt: z.ZodNumber;
+        committedAt: z.ZodNumber;
+    }, z.core.$strict>;
+    path: z.ZodString;
+    entries: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        mode: z.ZodString;
+        hash: z.ZodString;
+        type: z.ZodEnum<{
+            blob: "blob";
+            tree: "tree";
+            commit: "commit";
+        }>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type TreeListing = z.infer<typeof treeListing>;
+/** Saved text stays bounded by the admitted file-edit request. */
+export declare const repositoryFileByteLimit: number;
+export declare const repositoryFilePath: z.ZodString;
+/** A repository branch name as the files role carries it. */
+export declare const repositoryBranch: z.ZodString;
+export declare const fileEditState: z.ZodEnum<{
+    failed: "failed";
+    pending: "pending";
+    conflict: "conflict";
+    synced: "synced";
+}>;
+export declare const pendingFileEdit: z.ZodObject<{
+    text: z.ZodString;
+    revision: z.ZodNumber;
+    state: z.ZodEnum<{
+        failed: "failed";
+        pending: "pending";
+        conflict: "conflict";
+        synced: "synced";
+    }>;
+    theirs: z.ZodOptional<z.ZodObject<{
+        blob: z.ZodNullable<z.ZodString>;
+        commit: z.ZodString;
+    }, z.core.$strict>>;
+    failure: z.ZodOptional<z.ZodEnum<{
+        branch_missing: "branch_missing";
+        access_changed: "access_changed";
+        sync_failed: "sync_failed";
+        permanent_material: "permanent_material";
+    }>>;
+}, z.core.$strict>;
+export declare const fileSaveInput: z.ZodObject<{
+    baseBlob: z.ZodNullable<z.ZodString>;
+    baseCommit: z.ZodString;
+    text: z.ZodString;
+    revision: z.ZodNullable<z.ZodNumber>;
+    repo: z.ZodString;
+    branch: z.ZodString;
+    path: z.ZodString;
+}, z.core.$strict>;
+export declare const fileSaveResult: z.ZodUnion<readonly [z.ZodObject<{
+    kind: z.ZodLiteral<"saved">;
+    revision: z.ZodNumber;
+    state: z.ZodLiteral<"pending">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"synced">;
+    revision: z.ZodNumber;
+    commit: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"conflict">;
+    revision: z.ZodNumber;
+    theirs: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+        blob: z.ZodNullable<z.ZodString>;
+        commit: z.ZodString;
+    }, z.core.$strict>>>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"failed">;
+    revision: z.ZodNumber;
+    reason: z.ZodEnum<{
+        branch_missing: "branch_missing";
+        access_changed: "access_changed";
+        sync_failed: "sync_failed";
+        permanent_material: "permanent_material";
+    }>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"refused">;
+    reason: z.ZodEnum<{
+        "not-source-writer": "not-source-writer";
+        "background-unavailable": "background-unavailable";
+    }>;
+}, z.core.$strict>]>;
+export declare const fileDiscardInput: z.ZodObject<{
+    revision: z.ZodNumber;
+    repo: z.ZodString;
+    branch: z.ZodString;
+    path: z.ZodString;
+}, z.core.$strict>;
+export declare const fileDiscardResult: z.ZodUnion<readonly [z.ZodObject<{
+    kind: z.ZodEnum<{
+        not_found: "not_found";
+        discarded: "discarded";
+    }>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"conflict">;
+    revision: z.ZodNumber;
+}, z.core.$strict>]>;
+export declare const fileSyncResult: z.ZodObject<{
+    settled: z.ZodArray<z.ZodObject<{
+        result: z.ZodUnion<readonly [z.ZodObject<{
+            kind: z.ZodLiteral<"saved">;
+            revision: z.ZodNumber;
+            state: z.ZodLiteral<"pending">;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"synced">;
+            revision: z.ZodNumber;
+            commit: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"conflict">;
+            revision: z.ZodNumber;
+            theirs: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+                blob: z.ZodNullable<z.ZodString>;
+                commit: z.ZodString;
+            }, z.core.$strict>>>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"failed">;
+            revision: z.ZodNumber;
+            reason: z.ZodEnum<{
+                branch_missing: "branch_missing";
+                access_changed: "access_changed";
+                sync_failed: "sync_failed";
+                permanent_material: "permanent_material";
+            }>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"refused">;
+            reason: z.ZodEnum<{
+                "not-source-writer": "not-source-writer";
+                "background-unavailable": "background-unavailable";
+            }>;
+        }, z.core.$strict>]>;
+        repo: z.ZodString;
+        branch: z.ZodString;
+        path: z.ZodString;
+    }, z.core.$strict>>;
+    more: z.ZodBoolean;
+}, z.core.$strict>;
+export type FileSaveInput = z.output<typeof fileSaveInput>;
+export type FileSaveResult = z.output<typeof fileSaveResult>;
+export declare const fileContent: z.ZodObject<{
+    version: z.ZodNullable<z.ZodNumber>;
+    commit: z.ZodString;
+    blob: z.ZodNullable<z.ZodString>;
+    pending: z.ZodOptional<z.ZodObject<{
+        text: z.ZodString;
+        revision: z.ZodNumber;
+        state: z.ZodEnum<{
+            failed: "failed";
+            pending: "pending";
+            conflict: "conflict";
+            synced: "synced";
+        }>;
+        theirs: z.ZodOptional<z.ZodObject<{
+            blob: z.ZodNullable<z.ZodString>;
+            commit: z.ZodString;
+        }, z.core.$strict>>;
+        failure: z.ZodOptional<z.ZodEnum<{
+            branch_missing: "branch_missing";
+            access_changed: "access_changed";
+            sync_failed: "sync_failed";
+            permanent_material: "permanent_material";
+        }>>;
+    }, z.core.$strict>>;
+    ref: z.ZodString;
+    path: z.ZodString;
+    size: z.ZodNumber;
+    binary: z.ZodBoolean;
+    text: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type FileContent = z.infer<typeof fileContent>;
+export declare const commitPage: z.ZodObject<{
+    ref: z.ZodString;
+    commits: z.ZodArray<z.ZodObject<{
+        commit: z.ZodObject<{
+            hash: z.ZodString;
+            treeHash: z.ZodString;
+            message: z.ZodString;
+            author: z.ZodObject<{
+                name: z.ZodString;
+                email: z.ZodString;
+            }, z.core.$strict>;
+            committer: z.ZodObject<{
+                name: z.ZodString;
+                email: z.ZodString;
+            }, z.core.$strict>;
+            parents: z.ZodArray<z.ZodString>;
+            authoredAt: z.ZodNumber;
+            committedAt: z.ZodNumber;
+        }, z.core.$strict>;
+        agent: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+    next: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type CommitPage = z.infer<typeof commitPage>;
+/** Every path at a commit: files, and directories with a trailing slash. */
+export declare const fileList: z.ZodObject<{
+    ref: z.ZodString;
+    commit: z.ZodObject<{
+        hash: z.ZodString;
+        treeHash: z.ZodString;
+        message: z.ZodString;
+        author: z.ZodObject<{
+            name: z.ZodString;
+            email: z.ZodString;
+        }, z.core.$strict>;
+        committer: z.ZodObject<{
+            name: z.ZodString;
+            email: z.ZodString;
+        }, z.core.$strict>;
+        parents: z.ZodArray<z.ZodString>;
+        authoredAt: z.ZodNumber;
+        committedAt: z.ZodNumber;
+    }, z.core.$strict>;
+    paths: z.ZodArray<z.ZodString>;
+    truncated: z.ZodBoolean;
+}, z.core.$strict>;
+export type FileList = z.infer<typeof fileList>;
+/** A foreground copy rebuild needs another admitted method frame. */
+export declare const readCopyRebuilding: z.ZodObject<{
+    kind: z.ZodLiteral<"rebuilding">;
+}, z.core.$strict>;
+export declare const copyRebuildPage: z.ZodObject<{
+    done: z.ZodBoolean;
+    cursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+/** Where the files role opens: a repository file at a branch, or a Computer file. */
+export declare const filesLocation: z.ZodUnion<readonly [z.ZodObject<{
+    repository: z.ZodString;
+    branch: z.ZodString;
+    path: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    path: z.ZodString;
+}, z.core.$strict>]>;
+export type FilesLocation = z.output<typeof filesLocation>;
+/** The `apps.open` navigate intent that opens a location in the files role App. */
+export declare function filesNavigateIntent(location: FilesLocation): AppNavigateIntent;
+/** Decode a received navigate intent's params; null when they name no files location. */
+export declare function readFilesLocation(params: AppNavigateIntent["params"]): FilesLocation | null;

package/dist/roles/files.js

@@ -0,0 +1,184 @@
+/**
+ * The `files` App role contract. An App that fills the Team's files role
+ * receives a {@link FilesLocation} through an `apps.open` navigate intent, and
+ * file browsing, edit and snapshot payloads travel in these shapes. Role names
+ * belong to Puffball's App vocabulary; this module owns the files role's wire.
+ */
+import * as z from "zod";
+import { gitRepositoryNameSchema as repoName, gitSha1Schema as hash, } from "@fungi.computer/puffball/git-representation";
+/** The App role this contract serves. */
+export const filesRole = "files";
+const person = z.strictObject({
+    name: z.string(),
+    email: z.string(),
+});
+export const commit = z.strictObject({
+    hash,
+    treeHash: hash,
+    message: z.string(),
+    author: person,
+    committer: person,
+    parents: z.array(hash),
+    authoredAt: z.number(),
+    committedAt: z.number(),
+});
+export const treeEntry = z.strictObject({
+    name: z.string(),
+    mode: z.string(),
+    hash,
+    /** Git object kind; executable and symlink permissions live in mode. */
+    type: z.enum(["blob", "tree", "commit"]),
+});
+export const treeListing = z.strictObject({
+    ref: z.string(),
+    commit: commit,
+    path: z.string(),
+    entries: z.array(treeEntry),
+});
+/** Saved text stays bounded by the admitted file-edit request. */
+export const repositoryFileByteLimit = 64 * 1024;
+export const repositoryFilePath = z
+    .string()
+    .min(1)
+    .max(1024)
+    .refine((path) => !path.startsWith("/") &&
+    !path.includes("\\") &&
+    !path.includes("\0") &&
+    path
+        .split("/")
+        .every((part) => part !== "" && part !== "." && part !== ".." && part !== ".git"), "Choose a relative repository file path.");
+/** A repository branch name as the files role carries it. */
+export const repositoryBranch = z.string().min(1).max(256);
+const editKey = {
+    repo: repoName,
+    branch: repositoryBranch,
+    path: repositoryFilePath,
+};
+export const fileEditState = z.enum([
+    "pending",
+    "synced",
+    "conflict",
+    "failed",
+]);
+export const pendingFileEdit = z.strictObject({
+    text: z.string(),
+    revision: z.number().int().positive(),
+    state: fileEditState,
+    theirs: z.strictObject({ blob: hash.nullable(), commit: hash }).optional(),
+    failure: z
+        .enum([
+        "branch_missing",
+        "access_changed",
+        "sync_failed",
+        "permanent_material",
+    ])
+        .optional(),
+});
+export const fileSaveInput = z.strictObject({
+    ...editKey,
+    baseBlob: hash.nullable(),
+    baseCommit: hash,
+    text: z.string().max(repositoryFileByteLimit),
+    revision: z.number().int().positive().nullable(),
+});
+export const fileSaveResult = z.union([
+    z.strictObject({
+        kind: z.literal("saved"),
+        revision: z.number().int().positive(),
+        state: z.literal("pending"),
+    }),
+    z.strictObject({
+        kind: z.literal("synced"),
+        revision: z.number().int().positive(),
+        commit: hash,
+    }),
+    z.strictObject({
+        kind: z.literal("conflict"),
+        revision: z.number().int().nonnegative(),
+        theirs: pendingFileEdit.shape.theirs.optional(),
+    }),
+    z.strictObject({
+        kind: z.literal("failed"),
+        revision: z.number().int().positive(),
+        reason: z.enum([
+            "branch_missing",
+            "access_changed",
+            "sync_failed",
+            "permanent_material",
+        ]),
+    }),
+    z.strictObject({
+        kind: z.literal("refused"),
+        reason: z.enum(["not-source-writer", "background-unavailable"]),
+    }),
+]);
+export const fileDiscardInput = z.strictObject({
+    ...editKey,
+    revision: z.number().int().positive(),
+});
+export const fileDiscardResult = z.union([
+    z.strictObject({ kind: z.enum(["discarded", "not_found"]) }),
+    z.strictObject({
+        kind: z.literal("conflict"),
+        revision: z.number().int().positive(),
+    }),
+]);
+export const fileSyncResult = z.strictObject({
+    settled: z.array(z.strictObject({ ...editKey, result: fileSaveResult })),
+    more: z.boolean(),
+});
+export const fileContent = z.strictObject({
+    /** This member's saved row revision; null for committed-only readers or no row. */
+    version: z.number().int().positive().nullable(),
+    commit: hash,
+    /** Null only for a path proven absent at this committed branch head. */
+    blob: hash.nullable(),
+    pending: pendingFileEdit.optional(),
+    ref: z.string(),
+    path: z.string(),
+    size: z.number(),
+    binary: z.boolean(),
+    /** Absent when binary or larger than the viewer limit. */
+    text: z.string().nullable(),
+});
+export const commitPage = z.strictObject({
+    ref: z.string(),
+    commits: z.array(z.strictObject({ commit, agent: z.string().nullable() })),
+    next: z.string().optional(),
+});
+/** Every path at a commit: files, and directories with a trailing slash. */
+export const fileList = z.strictObject({
+    ref: z.string(),
+    commit,
+    paths: z.array(z.string()),
+    truncated: z.boolean(),
+});
+/** A foreground copy rebuild needs another admitted method frame. */
+export const readCopyRebuilding = z.strictObject({
+    kind: z.literal("rebuilding"),
+});
+export const copyRebuildPage = z.strictObject({
+    done: z.boolean(),
+    cursor: z.string().nullable(),
+});
+/** Where the files role opens: a repository file at a branch, or a Computer file. */
+export const filesLocation = z.union([
+    z.strictObject({
+        repository: repoName,
+        branch: repositoryBranch,
+        path: repositoryFilePath,
+    }),
+    z.strictObject({ path: z.string().min(1).max(1024) }),
+]);
+/** The `apps.open` navigate intent that opens a location in the files role App. */
+export function filesNavigateIntent(location) {
+    return {
+        kind: "navigate",
+        params: Object.entries(filesLocation.parse(location)).map(([key, value]) => ({ key, value })),
+    };
+}
+/** Decode a received navigate intent's params; null when they name no files location. */
+export function readFilesLocation(params) {
+    const parsed = filesLocation.safeParse(Object.fromEntries(params.map(({ key, value }) => [key, value])));
+    return parsed.success ? parsed.data : null;
+}

package/dist/root.d.ts

@@ -0,0 +1,21 @@
+import type { CapabilityDirectory } from "./capabilities.js";
+import type { AppCommands } from "./commands.js";
+import type { AppContext, AppIdentity, AppLifecycle } from "./lifecycle.js";
+import type { ReadonlyStore } from "./store.js";
+import type { HostUi } from "./ui.js";
+import type { AppWindow } from "./window.js";
+/** The App's live connection to its host: its admitted capabilities,
+ * commands, context, theme, UI door and window, all torn down together
+ * by `dispose`. Returned by `connectApp` and passed to `mountApp`. */
+export type AppRoot = {
+    readonly capabilities: CapabilityDirectory;
+    readonly commands: AppCommands;
+    readonly context: ReadonlyStore<AppContext>;
+    /** End this App's connection to its host and release everything it owns. */
+    dispose(): void;
+    readonly identity: Readonly<AppIdentity>;
+    readonly lifecycle: ReadonlyStore<AppLifecycle>;
+    readonly theme: ReadonlyStore<string>;
+    readonly ui: HostUi;
+    readonly window: AppWindow;
+};

package/dist/root.js

@@ -0,0 +1 @@
+export {};

package/dist/rpc.d.ts

@@ -0,0 +1 @@
+export { rpcDataSchema, rpcHandleSchema, rpcMethod, rpcVoid, } from "./internal/rpc-contract.js";

package/dist/rpc.js

@@ -0,0 +1 @@
+export { rpcDataSchema, rpcHandleSchema, rpcMethod, rpcVoid, } from "./internal/rpc-contract.js";

package/dist/status.d.ts

@@ -0,0 +1,17 @@
+import type { AppStatusAction, AppStatusItem } from "./ui.js";
+/**
+ * Control, separator, zero-width and bidi characters: anything that could
+ * break one line of host chrome or reorder what it says.
+ */
+export declare function isUnsafeStatusCodeUnit(code: number): boolean;
+/**
+ * Make person- or Computer-supplied text fit one status item: drop unsafe
+ * characters, collapse whitespace and shorten with an ellipsis.
+ */
+export declare function statusText(value: string, max?: number): string;
+/**
+ * Whether an action names something the App declares now: an enabled item,
+ * and for a menu exactly one enabled option. Every hop that delivers an
+ * action applies this rule against its own latest copy of the items.
+ */
+export declare function statusActionAllowed(items: readonly AppStatusItem[], action: AppStatusAction): boolean;

package/dist/status.js

@@ -0,0 +1,50 @@
+import { APP_STATUS_TEXT_MAX } from "./ui.js";
+/**
+ * Control, separator, zero-width and bidi characters: anything that could
+ * break one line of host chrome or reorder what it says.
+ */
+export function isUnsafeStatusCodeUnit(code) {
+    return (code < 0x20 ||
+        (code >= 0x7f && code <= 0x9f) ||
+        code === 0x061c ||
+        (code >= 0x200b && code <= 0x200f) ||
+        code === 0x2028 ||
+        code === 0x2029 ||
+        (code >= 0x202a && code <= 0x202e) ||
+        (code >= 0x2066 && code <= 0x2069) ||
+        code === 0xfeff);
+}
+/**
+ * Make person- or Computer-supplied text fit one status item: drop unsafe
+ * characters, collapse whitespace and shorten with an ellipsis.
+ */
+export function statusText(value, max = APP_STATUS_TEXT_MAX) {
+    let clean = "";
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        clean += isUnsafeStatusCodeUnit(code) ? " " : value.charAt(index);
+    }
+    clean = clean.replace(/\s+/gu, " ").trim();
+    if (clean.length <= max)
+        return clean;
+    return `${clean.slice(0, Math.max(0, max - 1)).trimEnd()}…`;
+}
+/**
+ * Whether an action names something the App declares now: an enabled item,
+ * and for a menu exactly one enabled option. Every hop that delivers an
+ * action applies this rule against its own latest copy of the items.
+ */
+export function statusActionAllowed(items, action) {
+    const item = items.find((candidate) => candidate.id === action.itemId);
+    if (item === undefined)
+        return false;
+    if (item.kind === "text")
+        return false;
+    if (item.kind === "menu") {
+        const option = item.options.find((candidate) => candidate.id === action.optionId);
+        return option !== undefined && option.disabled !== true;
+    }
+    if (action.optionId !== undefined)
+        return false;
+    return item.kind !== "button" || item.disabled !== true;
+}