@fungi.computer/agar 0.0.0-stage → 0.0.1

package/dist/game-servers.js

@@ -0,0 +1,244 @@
+import { defineCapability } from "./capabilities.js";
+import { rpcDataSchema, rpcHandleSchema, rpcMethod, rpcVoid, } from "./internal/rpc-contract.js";
+import * as z from "zod";
+const identity = z.string().min(1).max(256);
+const count = z.number().int().nonnegative();
+const dollars = z.number().nonnegative();
+/** The games supported by the on-box controller's current catalog. */
+export const gameIdSchema = z.enum([
+    "minecraft",
+    "terraria",
+    "factorio",
+    "valheim",
+    "project-zomboid",
+]);
+export const gameServerSizeTierSchema = z.enum(["squad", "raid"]);
+export const gameServerSizes = {
+    minecraft: {
+        squad: { memoryMiB: 2048, vcpuCount: 1 },
+        raid: { memoryMiB: 4096, vcpuCount: 2 },
+    },
+    terraria: {
+        squad: { memoryMiB: 2048, vcpuCount: 1 },
+        raid: { memoryMiB: 4096, vcpuCount: 2 },
+    },
+    factorio: {
+        squad: { memoryMiB: 3072, vcpuCount: 1 },
+        raid: { memoryMiB: 6144, vcpuCount: 2 },
+    },
+    valheim: {
+        squad: { memoryMiB: 4096, vcpuCount: 2 },
+        raid: { memoryMiB: 6144, vcpuCount: 3 },
+    },
+    "project-zomboid": {
+        squad: { memoryMiB: 8192, vcpuCount: 2 },
+        raid: { memoryMiB: 12288, vcpuCount: 3 },
+    },
+};
+export const gameServerBillingModeSchema = z.enum(["insert-coin", "hardcore"]);
+export const gameServerPassIdSchema = z.enum(["booster-pack", "battle-pass"]);
+export const gameServerSizeSchema = z.strictObject({
+    tier: gameServerSizeTierSchema,
+    memoryMiB: z.number().int().positive(),
+    vcpuCount: z.number().int().positive(),
+});
+export const gameServerBackupSchema = z.strictObject({
+    backupId: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/),
+    createdAt: count,
+    sizeBytes: count,
+});
+export const gameServerCatalogSchema = z.strictObject({
+    games: z
+        .array(z.strictObject({
+        game: gameIdSchema,
+        variants: z.array(identity),
+        sizes: z.strictObject({
+            squad: z.strictObject({
+                size: gameServerSizeSchema,
+                hourlyPriceUsd: dollars.positive().nullable(),
+                monthlyCapUsd: dollars.positive().nullable(),
+                hardcoreMonthlyPriceUsd: dollars.positive().nullable(),
+            }),
+            raid: z.strictObject({
+                size: gameServerSizeSchema,
+                hourlyPriceUsd: dollars.positive().nullable(),
+                monthlyCapUsd: dollars.positive().nullable(),
+                hardcoreMonthlyPriceUsd: dollars.positive().nullable(),
+            }),
+        }),
+    }))
+        .length(5),
+    pricing: z
+        .strictObject({
+        labels: z.strictObject({
+            modes: z.strictObject({ insertCoin: identity, hardcore: identity }),
+            sizes: z.strictObject({ squad: identity, raid: identity }),
+            passes: z.strictObject({
+                "booster-pack": identity,
+                "battle-pass": identity,
+            }),
+        }),
+        passes: z
+            .array(z.strictObject({
+            id: gameServerPassIdSchema,
+            displayName: identity,
+            monthlyPriceUsd: dollars,
+            playerHours: count,
+            serverLimit: count,
+            eligibleGames: z.array(gameIdSchema),
+            includesRaid: z.boolean(),
+            includedWithPro: z.boolean(),
+        }))
+            .length(2),
+        alwaysOnMemoryCapMiB: count,
+    })
+        .nullable(),
+    creditRemainingUsd: dollars,
+});
+export const gameServerStateSchema = z.strictObject({
+    serverId: identity,
+    teamId: identity,
+    name: identity,
+    game: gameIdSchema,
+    variant: identity,
+    size: gameServerSizeSchema,
+    billingMode: gameServerBillingModeSchema,
+    passId: gameServerPassIdSchema.nullable(),
+    tunnelStatus: z.enum(["configured", "not_configured"]),
+    desiredState: z.enum(["running", "stopped"]),
+    phase: z.enum(["stopped", "starting", "awake", "sleeping", "failed"]),
+    players: count,
+    maxPlayers: count.nullable(),
+    connections: z
+        .array(z.strictObject({
+        purpose: identity,
+        protocol: z.enum(["tcp", "udp"]),
+        host: identity,
+        port: z.number().int().min(1).max(65_535),
+    }))
+        .max(16),
+    version: z.number().int().positive(),
+    createdAt: count,
+    updatedAt: count,
+});
+export const gameServerSchema = gameServerStateSchema.extend({
+    monthToDateCostUsd: dollars,
+    teamMonthToDateCostUsd: dollars,
+});
+export const gameServerPageSchema = z.strictObject({
+    servers: z.array(gameServerSchema).max(100),
+    nextOffset: count.nullable(),
+    teamMonthToDateCostUsd: dollars,
+});
+export const gameServerErrorCodeSchema = z.enum([
+    "denied",
+    "not_found",
+    "conflict",
+    "credit_exhausted",
+    "pricing_not_configured",
+    "pass_not_included",
+    "pass_not_active",
+    "pass_game_not_eligible",
+    "pass_size_not_eligible",
+    "pass_server_limit",
+    "pass_mode_incompatible",
+    "always_on_capacity",
+    "capacity",
+    "tunnel_unavailable",
+    "unsupported_variant",
+    "unavailable",
+]);
+/** Versioned command delivered from the Team projection outbox to the box. */
+export const gameServerHostCommandSchema = z.discriminatedUnion("kind", [
+    z.strictObject({
+        kind: z.literal("create"),
+        schemaVersion: z.literal(1),
+        teamId: identity,
+        serverId: identity,
+        version: z.number().int().positive(),
+        game: gameIdSchema,
+        variant: identity,
+        sizeTier: gameServerSizeTierSchema,
+        billingMode: gameServerBillingModeSchema,
+        passId: gameServerPassIdSchema.nullable(),
+        settings: z.union([
+            z.strictObject({
+                eulaAcceptedByOperator: z.literal(true),
+                onlineMode: z.boolean().optional(),
+            }),
+            z.strictObject({ password: z.string().min(5).max(128) }),
+            z.strictObject({ adminPassword: z.string().min(8).max(128) }),
+            z.strictObject({}),
+        ]),
+    }),
+    ...["start", "stop", "delete", "backup-now"].map((kind) => z.strictObject({
+        kind: z.literal(kind),
+        schemaVersion: z.literal(1),
+        teamId: identity,
+        serverId: identity,
+        version: z.number().int().positive(),
+    })),
+    z.strictObject({
+        kind: z.literal("restore"),
+        schemaVersion: z.literal(1),
+        teamId: identity,
+        serverId: identity,
+        version: z.number().int().positive(),
+        backupId: gameServerBackupSchema.shape.backupId,
+    }),
+]);
+/** Signed host observation; sequence and version reject stale or replayed reports. */
+export const gameServerHostReportSchema = z.strictObject({
+    schemaVersion: z.literal(1),
+    hostId: identity,
+    teamId: identity,
+    serverId: identity,
+    version: z.number().int().positive(),
+    sequence: count,
+    observedAt: count,
+    phase: gameServerStateSchema.shape.phase,
+    players: count,
+    maxPlayers: count.nullable(),
+    connections: gameServerStateSchema.shape.connections,
+    tunnelStatus: gameServerStateSchema.shape.tunnelStatus,
+    backups: z.array(gameServerBackupSchema).max(100),
+    runtime: z
+        .strictObject({
+        runtimeId: z.string().min(1).max(128),
+        startedAt: count,
+        ended: z.boolean(),
+    })
+        .nullable(),
+});
+/** A public or App game-server request refused by the Team decision. */
+export class GameServerRequestError extends Error {
+    code;
+    status;
+    constructor(code, status) {
+        super(`Game-server request refused: ${code}`);
+        this.code = code;
+        this.status = status;
+        this.name = "GameServerRequestError";
+    }
+}
+export const gamesServers = defineCapability("games:servers", 1, rpcHandleSchema({
+    list: rpcMethod(rpcDataSchema(z.unknown().transform((value) => gameServerPageSchema.parse(value)))),
+    catalog: rpcMethod(rpcDataSchema(z
+        .unknown()
+        .transform((value) => gameServerCatalogSchema.parse(value)))),
+    create: rpcMethod(rpcDataSchema(z.unknown().transform((value) => gameServerSchema.parse(value)))),
+    status: rpcMethod(rpcDataSchema(z.unknown().transform((value) => gameServerSchema.parse(value)))),
+    start: rpcMethod(rpcDataSchema(z.unknown().transform((value) => gameServerSchema.parse(value)))),
+    stop: rpcMethod(rpcDataSchema(z.unknown().transform((value) => gameServerSchema.parse(value)))),
+    restore: rpcMethod(rpcDataSchema(z.unknown().transform((value) => gameServerSchema.parse(value)))),
+    backups: rpcMethod(rpcDataSchema(z
+        .unknown()
+        .transform((value) => z.array(gameServerBackupSchema).parse(value)))),
+    delete: rpcVoid,
+    backupNow: rpcVoid,
+}));
+/** Decode the host's listing at the App boundary. */
+export async function listGameServers(capabilities, input) {
+    const page = await capabilities.require(gamesServers).list(input);
+    return gameServerPageSchema.parse(page);
+}

package/dist/gills.d.ts

@@ -0,0 +1,43 @@
+import { type AppDeclaredGill, type AppGillDesktopSize, type AppGillParam, type AppGillWatch, type GillCall, type GillReply } from "@fungi.computer/gills";
+import type { WhistleJsonValue } from "@fungi.computer/whistle";
+import { type GillResponse } from "@fungi.computer/gills";
+/** Decode the App host's strict isolation refusal into its permanent Gill state. */
+export declare function decodeGillRefusal(raw: unknown, declaration: Readonly<{
+    id: string;
+    title: string;
+}>): GillResponse | undefined;
+/** App-owned projection; methods keep their ordinary domain-shaped output. */
+export type AppBackendGill = Readonly<{
+    declaration: AppDeclaredGill;
+    /** Page size passed to the source; projection never discards rows. */
+    limit: number;
+    /** Map placement and continuation to the source method, forwarding its limit. */
+    input: (selection: Readonly<{
+        params: Readonly<Partial<Record<string, string>>>;
+        limit: number;
+        after?: string | undefined;
+    }>) => Readonly<{
+        limit: number;
+        [key: string]: WhistleJsonValue;
+    }>;
+    /** Decode the maintained call wire only for a backend declaring Gills. */
+    parseCall: (raw: GillCall) => GillCall;
+    /** Project through the backend's admitted read method callback. */
+    call: (selection: GillCall, read: (name: string, input: WhistleJsonValue, kind: "rows" | "options") => Promise<WhistleJsonValue>) => Promise<GillReply>;
+    /** Project parsed source output into text rows without dropping records. */
+    rows: (output: WhistleJsonValue, context: Readonly<{
+        params: Readonly<Record<string, string>>;
+    }>) => GillResponse;
+}>;
+/** Define a compact view of one of this App's declared read methods. */
+export declare function defineAppGill(options: Readonly<{
+    id: string;
+    title: string;
+    source: string;
+    limit: number;
+    sizes?: readonly AppGillDesktopSize[];
+    params?: readonly AppGillParam[];
+    watch?: AppGillWatch;
+    input: AppBackendGill["input"];
+    rows: AppBackendGill["rows"];
+}>): AppBackendGill;

package/dist/gills.js

@@ -0,0 +1,174 @@
+import * as z from "zod";
+import * as Schema from "effect/Schema";
+import { appDeclaredGillSchema, decodeDeclaredGillResponse, decodeGillOptionsResponse, gillCallSchema, } from "@fungi.computer/gills";
+import { appBackendRefusalSchema } from "./backend-refusal.js";
+import { decodeGillResponse } from "@fungi.computer/gills";
+/** Decode the App host's strict isolation refusal into its permanent Gill state. */
+export function decodeGillRefusal(raw, declaration) {
+    const refusal = appBackendRefusalSchema.safeParse(raw);
+    if (!refusal.success || refusal.data.reason !== "exec_isolation_required")
+        return undefined;
+    return decodeGillResponse({
+        viewId: declaration.id,
+        title: declaration.title,
+        state: "error",
+        rows: [],
+        reason: refusal.data.reason,
+        error: `${declaration.title} isn't available on this preview.`,
+    });
+}
+/** Define a compact view of one of this App's declared read methods. */
+export function defineAppGill(options) {
+    let declaration = {
+        id: options.id,
+        title: options.title,
+        source: options.source,
+    };
+    if (options.sizes !== undefined)
+        declaration = { ...declaration, desktop: { sizes: options.sizes } };
+    if (options.params !== undefined)
+        declaration = { ...declaration, params: options.params };
+    if (options.watch !== undefined)
+        declaration = { ...declaration, watch: options.watch };
+    declaration = Schema.decodeUnknownSync(appDeclaredGillSchema, {
+        onExcessProperty: "error",
+    })(declaration);
+    return Object.freeze({
+        declaration,
+        limit: z.number().int().min(1).max(200).parse(options.limit),
+        input: options.input,
+        rows: options.rows,
+        parseCall: Schema.decodeUnknownSync(gillCallSchema, {
+            onExcessProperty: "error",
+        }),
+        call: async (selection, read) => {
+            const params = selection.params ?? {};
+            const declared = declaration.params ?? [];
+            if (Object.keys(params).some((key) => !declared.some((param) => param.key === key)))
+                throw new Error("Undeclared Gill parameter");
+            if (selection.options !== undefined) {
+                const param = declared.find((candidate) => candidate.key === selection.options);
+                const source = param?.options;
+                if (source === undefined)
+                    throw new Error("Gill options source must be a declared read method");
+                let input = { limit: options.limit, params };
+                if (selection.after !== undefined)
+                    input = { ...input, after: selection.after };
+                return fitGillOptionsText(await read(source, input, "options"), options.limit);
+            }
+            const missing = declared.find((param) => param.required &&
+                (!Object.hasOwn(params, param.key) || !params[param.key]));
+            if (missing)
+                return {
+                    viewId: selection.id,
+                    title: declaration.title,
+                    state: "error",
+                    rows: [],
+                    reason: "params_required",
+                    error: `Choose ${missing.label.toLowerCase()}`,
+                    recovery: { kind: "configure", param: missing.key },
+                };
+            const input = options.input({
+                params,
+                after: selection.after,
+                limit: options.limit,
+            });
+            if (input.limit !== options.limit)
+                throw new Error("Gill input must preserve its page size");
+            const result = await read(declaration.source, input, "rows");
+            return decodeDeclaredGillResponse(fitGillText(options.rows(result, { params }), options.limit), declaration);
+        },
+    });
+}
+// The App-shard reply bound is 240 KiB. Navigation and cursors are never shortened.
+const gillReplyByteLimit = 240 * 1024;
+const utf8 = new TextEncoder();
+function shortenText(text, limit) {
+    if (text.length <= limit)
+        return text;
+    if (limit === 0)
+        return "";
+    let prefix = text.slice(0, limit - 1);
+    // Keep a surrogate pair intact when shortening Unicode display text.
+    if (/[\uD800-\uDBFF]$/.test(prefix))
+        prefix = prefix.slice(0, -1);
+    return `${prefix}…`;
+}
+function fitGillText(raw, pageSize) {
+    if (raw.rows.length > pageSize)
+        throw new Error("Gill source exceeded its page size");
+    let titleLimit = 4096;
+    let detailLimit = 1024;
+    for (;;) {
+        let page;
+        if (raw.state === "full")
+            page = {
+                ...raw,
+                title: shortenText(raw.title, titleLimit),
+                rows: raw.rows.map((row) => {
+                    let text = { ...row, title: shortenText(row.title, titleLimit) };
+                    if (row.detail !== undefined)
+                        text = { ...text, detail: shortenText(row.detail, detailLimit) };
+                    if (row.status !== undefined)
+                        text = {
+                            ...text,
+                            status: {
+                                ...row.status,
+                                label: shortenText(row.status.label, titleLimit),
+                            },
+                        };
+                    return text;
+                }),
+            };
+        else if (raw.state === "error")
+            page = {
+                ...raw,
+                title: shortenText(raw.title, titleLimit),
+                error: shortenText(raw.error, 512),
+            };
+        else
+            page = { ...raw, title: shortenText(raw.title, titleLimit) };
+        const decoded = decodeGillResponse(page);
+        if (utf8.encode(JSON.stringify(decoded)).byteLength <= gillReplyByteLimit)
+            return decoded;
+        if (titleLimit === 1 && detailLimit === 0)
+            throw new Error("Gill navigation exceeds the reply byte budget");
+        titleLimit = Math.max(1, Math.floor(titleLimit / 2));
+        detailLimit = Math.floor(detailLimit / 2);
+    }
+}
+function fitGillOptionsText(raw, pageSize) {
+    // The method's own output parse has already run. Bound display text before
+    // decoding the shared choice wire; values and continuation are preserved.
+    const projected = z
+        .strictObject({
+        options: z
+            .array(z.strictObject({
+            value: z.string().max(256),
+            label: z.string().min(1),
+            detail: z.string().optional(),
+        }))
+            .max(pageSize),
+        next: z.string().max(1024).optional(),
+    })
+        .parse(raw);
+    let labelLimit = 4096;
+    let detailLimit = 1024;
+    for (;;) {
+        const choices = decodeGillOptionsResponse({
+            ...projected,
+            options: projected.options.map((option) => {
+                let text = { ...option, label: shortenText(option.label, labelLimit) };
+                if (option.detail !== undefined)
+                    text = { ...text, detail: shortenText(option.detail, detailLimit) };
+                return text;
+            }),
+        });
+        if (utf8.encode(JSON.stringify(choices)).byteLength <= gillReplyByteLimit)
+            return choices;
+        if (labelLimit === 1 && detailLimit === 0)
+            throw new Error("Gill option values exceed the reply byte budget");
+        labelLimit = Math.max(1, Math.floor(labelLimit / 2));
+        detailLimit = Math.floor(detailLimit / 2);
+    }
+}

package/dist/git-commit.d.ts

@@ -0,0 +1,143 @@
+import type { GitBinding } from "./git.js";
+/** The binding operations these writes use. */
+export type GitCommitStore = Pick<GitBinding, "exchange">;
+/** One file to write (`content`) or delete (`content: null`), repository-relative. */
+export type GitFileChange = Readonly<{
+    /** Slash-separated path inside the repository, without `.` or `..` parts. */
+    path: string;
+    /** New file bytes, or null to delete the file. */
+    content: Uint8Array | null;
+    /**
+     * File mode for a written file. Defaults to the existing entry's mode, or
+     * `100644` for a new file.
+     */
+    mode?: "100644" | "100755";
+}>;
+/** Name and email recorded as a commit's author and committer. */
+export type GitIdentity = Readonly<{
+    name: string;
+    email: string;
+}>;
+/** A commit of file changes to one branch. */
+export type CommitFilesRequest = Readonly<{
+    /** Installation-local repository name. */
+    repository: string;
+    /** Branch to commit to, without `refs/heads/`. */
+    branch: string;
+    /** The branch head the changes were made against, or null to create the branch. */
+    expectedHead: string | null;
+    /** When creating the branch, start from this branch's head instead of an empty tree. */
+    startFrom?: string;
+    /** Files to write or delete. */
+    changes: readonly GitFileChange[];
+    /** Commit message. */
+    message: string;
+    /** Author and committer. */
+    author: GitIdentity;
+}>;
+/** What a compare-and-swap write did. */
+export type GitWriteOutcome = Readonly<{
+    kind: "committed";
+    commit: string;
+}> | Readonly<{
+    kind: "unchanged";
+    commit: string;
+}> | Readonly<{
+    kind: "updated";
+}>
+/** The ref was not at the expected head; nothing was written. */
+ | Readonly<{
+    kind: "stale";
+    head: string | null;
+}>;
+/** Merge a branch of `source` (such as a fork) into a branch of `target`. */
+export type MergeBranchRequest = Readonly<{
+    /** Repository receiving the merge. */
+    target: string;
+    /** Repository the work comes from; may equal `target`. */
+    source: string;
+    /** Branch in `target` to merge into, without `refs/heads/`. */
+    branch: string;
+    /** Branch in `source` to merge, without `refs/heads/`. */
+    sourceBranch: string;
+    /** Reviewed source commit; must match the fetched source branch head. */
+    expectedSource: string;
+    /** Copied target head; used only when full source history proves it is an ancestor. */
+    expectedTarget?: string;
+    /** Copied distance behind the target. Zero permits an ancestry-checked source-only fetch. */
+    behind?: number;
+    /** Merge commit message. */
+    message: string;
+    /** Author and committer of the merge commit. */
+    author: GitIdentity;
+}>;
+/** What a merge did. Merges always write a merge commit when there is new work. */
+export type GitMergeOutcome = Readonly<{
+    kind: "merged";
+    before: string;
+    after: string;
+}>
+/** The target already contains the source's work. */
+ | Readonly<{
+    kind: "up-to-date";
+    head: string;
+}>
+/** Both sides changed the same lines; nothing was written. */
+ | Readonly<{
+    kind: "conflict";
+    head: string;
+    paths: readonly string[];
+}>
+/** The target moved while merging; nothing was written. */
+ | Readonly<{
+    kind: "stale";
+    head: string | null;
+}>
+/** The fetched source differs from the reviewed commit; nothing was written. */
+ | Readonly<{
+    kind: "source-moved";
+    head: string;
+}>;
+/** Point a ref at a commit that is the head of `source`. */
+export type MoveRefRequest = Readonly<{
+    /** Installation-local repository name. */
+    repository: string;
+    /** Full ref name, such as `refs/heads/main` or `refs/tags/v1`. */
+    ref: string;
+    /** The ref's current commit, or null to create it. */
+    expected: string | null;
+    /** Commit to point the ref at. */
+    commit: string;
+    /** Branch (without `refs/heads/`) whose head is `commit`. */
+    source: string;
+}>;
+/** Ordered ref moves to one fetched source commit; each move has its own CAS guard. */
+export type MoveRefsRequest = Readonly<{
+    /** Installation-local repository name. */
+    repository: string;
+    /** Branch whose fetched head must be the selected commit. */
+    source: string;
+    /** Commit shared by all ref moves. */
+    commit: string;
+    /** Ordered compare-and-swap moves; an accepted prefix is never rolled back. */
+    updates: readonly Readonly<{
+        ref: string;
+        expected: string | null;
+    }>[];
+}>;
+/** Earlier moves remain accepted if a later ref is stale; this is not an atomic push. */
+export type GitRefMovesOutcome = Readonly<{
+    kind: "updated";
+}> | Readonly<{
+    kind: "stale";
+    ref: string;
+    head: string | null;
+}>;
+/** Commit files using independently resumable, CAS-guarded Git steps. */
+export declare function commitFiles(store: GitCommitStore, request: CommitFilesRequest, beforeWrite?: () => Promise<void>): Promise<GitWriteOutcome>;
+/** Point a ref at the head commit of `source`, compare-and-swap on the ref. */
+export declare function moveRef(store: GitCommitStore, request: MoveRefRequest): Promise<GitWriteOutcome>;
+/** Fetch a source once, then move refs in order with separate guarded pushes. */
+export declare function moveRefs(store: GitCommitStore, request: MoveRefsRequest): Promise<GitRefMovesOutcome>;
+/** Merge branches through the same one-exchange step engine as background owners. */
+export declare function mergeBranch(store: GitCommitStore, request: MergeBranchRequest): Promise<GitMergeOutcome>;