@fungi.computer/oyster 0.0.0-stage → 0.0.1

package/dist/pack.js

@@ -0,0 +1,134 @@
+import { mkdir, mkdtemp, readdir, readFile, rm, writeFile, } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, relative, resolve } from "node:path";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { releaseSchema } from "@fungi.computer/puffball/effect";
+import { parseArtifactRef, parseReleaseId, parseSha256Digest, parseSourceRevision, } from "@fungi.computer/puffball";
+import { commitPreparedCandidate, createAppCandidatePreparer, createArtifactsSourceCapture, createFirstPartyAppSourceDistribution, createLocalArtifactWriter, createLocalBuildExecutor, createLocalCommitSourceCapture, } from "./build.js";
+import { templateWriteInputSchema } from "./source/template-write.js";
+import { sha256 } from "./release.js";
+async function filesUnder(directory) {
+    const entries = await readdir(directory, {
+        recursive: true,
+        withFileTypes: true,
+    });
+    return entries
+        .filter((entry) => entry.isFile())
+        .map((entry) => join(entry.parentPath, entry.name))
+        .sort();
+}
+async function packCapturedSource(options, sourceCapture) {
+    const revision = parseSourceRevision(options.sourceRevision);
+    const out = resolve(options.outDirectory);
+    const artifactsDirectory = join(out, "artifacts");
+    const preparer = createAppCandidatePreparer({
+        config: { appId: options.appId, recipe: options.recipe },
+        sourceCapture,
+        buildExecutor: createLocalBuildExecutor({
+            packageStoreDirectory: options.packageStoreDirectory,
+        }),
+    });
+    const prepared = await Effect.runPromise(Effect.scoped(preparer.prepareCandidate(parseReleaseId(options.releaseId ??
+        `rel_${revision.slice("git:".length, "git:".length + 12)}`))));
+    const release = await Effect.runPromise(commitPreparedCandidate(prepared, {
+        artifactWriter: createLocalArtifactWriter(artifactsDirectory, options.recipe.assets),
+        releaseCatalog: { createRelease: (value) => Promise.resolve(value) },
+    }));
+    await mkdir(out, { recursive: true });
+    await writeFile(join(out, "release.json"), `${Schema.encodeUnknownSync(Schema.fromJsonString(releaseSchema))(release)}\n`);
+    const artifacts = (await filesUnder(artifactsDirectory)).map((path) => ({
+        artifactRef: parseArtifactRef(`artifact:${relative(artifactsDirectory, path)}`),
+        path,
+    }));
+    return { release, artifacts };
+}
+/** Build an exact local Git commit with the canonical compiler and artifact writer. */
+export async function packRelease(options) {
+    return packCapturedSource(options, createLocalCommitSourceCapture(resolve(options.sourceDirectory), parseSourceRevision(options.sourceRevision)));
+}
+/**
+ * Capture an Artifacts Git commit, build its Release, upload it to an Oyster,
+ * and install it, or switch an existing installation to it
+ * ({@link installRelease}).
+ */
+export async function installFromSource(input) {
+    const outDirectory = await mkdtemp(join(tmpdir(), "oyster-source-release-"));
+    try {
+        await packCapturedSource({
+            appId: input.appId,
+            releaseId: input.releaseId,
+            recipe: input.recipe,
+            sourceRevision: input.source.sourceRevision,
+            packageStoreDirectory: input.packageStoreDirectory,
+            outDirectory,
+        }, createArtifactsSourceCapture({
+            ...input.source,
+            sourceRevision: parseSourceRevision(input.source.sourceRevision),
+        }));
+        return await installRelease({
+            directory: outDirectory,
+            url: input.url,
+            key: input.key,
+            installationId: input.installationId,
+        });
+    }
+    finally {
+        await rm(outDirectory, { recursive: true, force: true });
+    }
+}
+/**
+ * Upload a packed Release to an Oyster and install it. The host installs a
+ * new installation (201) or switches an existing one to this Release (200),
+ * keeping its state; both go through its one install-or-select owner.
+ */
+export async function installRelease(input) {
+    const directory = resolve(input.directory);
+    const release = Schema.decodeUnknownSync(Schema.fromJsonString(releaseSchema))(await readFile(join(directory, "release.json"), "utf8"));
+    const authorization = { Authorization: `Bearer ${input.key}` };
+    for (const file of await filesUnder(join(directory, "artifacts"))) {
+        const bytes = new Uint8Array(await readFile(file));
+        const artifactRef = `artifact:${relative(join(directory, "artifacts"), file)}`;
+        const digest = parseSha256Digest(await sha256(bytes));
+        const response = await fetch(new URL(`/api/artifacts/${encodeURIComponent(artifactRef)}?digest=${digest}`, input.url), { method: "PUT", headers: authorization, body: bytes });
+        if (!response.ok)
+            throw new Error(`Artifact upload failed (${String(response.status)}): ${artifactRef}`);
+    }
+    return fetch(new URL("/api/installations", input.url), {
+        method: "POST",
+        headers: { ...authorization, "Content-Type": "application/json" },
+        body: JSON.stringify({
+            release: Schema.encodeUnknownSync(releaseSchema)(release),
+            installationId: input.installationId,
+        }),
+    });
+}
+/** Project one exact first-party commit's editable source and seed it into
+ * an Oyster's own template, so `APPS.fork` can later fork it. The operator
+ * owner key authenticates; no provider credential ever leaves this call. */
+export async function publishSource(input) {
+    const revision = parseSourceRevision(input.sourceRevision);
+    const distribution = await Effect.runPromise(Effect.scoped(Effect.gen(function* () {
+        const source = yield* createLocalCommitSourceCapture(resolve(input.repositoryPath), revision).capture();
+        return yield* createFirstPartyAppSourceDistribution({
+            appId: input.appId,
+            entry: input.entry,
+            source,
+        });
+    })));
+    const body = Schema.encodeUnknownSync(templateWriteInputSchema)({
+        appId: input.appId,
+        sourceRevision: revision,
+        sourceTreeDigest: distribution.sourceTreeDigest,
+        recipe: input.recipe,
+        files: distribution.files,
+    });
+    return fetch(new URL(`/api/apps/${encodeURIComponent(input.appId)}/source`, input.url), {
+        method: "PUT",
+        headers: {
+            Authorization: `Bearer ${input.key}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify(body),
+    });
+}

package/dist/page/capabilities.d.ts

@@ -0,0 +1,23 @@
+import * as Schema from "effect/Schema";
+import { type CapabilityContract } from "@fungi.computer/agar";
+import type { AppHostLaunch } from "@fungi.computer/agar/host";
+import type { CapabilityDescriptor } from "../capability-descriptor.js";
+/** Agar's opaque host handle, shared by the page's exported factory contracts. */
+export type HostCapabilityHandle = AppHostLaunch["capabilities"][number]["handle"];
+/** Bind a page-local JSON caller; cancellation never enters serialized input. */
+export declare function capabilityJsonCaller(descriptor: CapabilityDescriptor, installationId: string): (method: string, raw?: unknown, options?: {
+    readonly signal?: AbortSignal;
+}) => Promise<import("zod").JSONType | undefined>;
+/** Local JSON calls carry cancellation separately from their serialized input. */
+export type CapabilityJsonCaller = ReturnType<typeof capabilityJsonCaller>;
+/** Local factories may open only transports present in their descriptor. */
+export type CapabilityTransportOpener = (method: string, input?: Schema.Json) => WebSocket;
+/** Build the App's RPC handle from its admitted descriptor and installation. */
+export declare function capabilityHandle(descriptor: CapabilityDescriptor, installationId: string): HostCapabilityHandle;
+/** A supported contract may adapt local JSON calls into its App-facing handle. */
+export type CapabilityRegistration = Readonly<{
+    contract: CapabilityContract<unknown>;
+    createHandle?: (call: CapabilityJsonCaller, transport: CapabilityTransportOpener) => HostCapabilityHandle | Promise<HostCapabilityHandle>;
+}>;
+/** Create a registered handle, using the descriptor's ordinary RPC handle by default. */
+export declare function registeredCapabilityHandle(registration: CapabilityRegistration, descriptor: CapabilityDescriptor, installationId: string): Promise<HostCapabilityHandle>;

package/dist/page/capabilities.js

@@ -0,0 +1,256 @@
+import { RpcTarget } from "@fungi.computer/capnweb";
+import { compile, parse, pathToRegexp } from "path-to-regexp";
+import * as Schema from "effect/Schema";
+import { AppError } from "@fungi.computer/agar";
+import { parseJsonValue } from "@fungi.computer/whistle/wire";
+const queryInput = Schema.Record(Schema.String, Schema.Union([Schema.String, Schema.Number, Schema.Boolean]));
+const capabilityInputSchema = Schema.Union([Schema.Json, Schema.Undefined]);
+function resolveRoute(path, input) {
+    const template = parse(path);
+    const names = new Set(pathToRegexp(template).keys.map((key) => key.name));
+    if (names.size === 0)
+        return { path: compile(template)(), input };
+    const fields = Schema.decodeUnknownSync(Schema.Record(Schema.String, Schema.Json))(input);
+    const params = Object.fromEntries(Object.entries(fields)
+        .filter(([name]) => names.has(name))
+        .map(([name, value]) => [
+        name,
+        String(Schema.decodeUnknownSync(Schema.Union([Schema.String, Schema.Number, Schema.Boolean]))(value)),
+    ]));
+    return {
+        path: compile(template)(params),
+        input: Object.fromEntries(Object.entries(fields).filter(([name]) => !names.has(name))),
+    };
+}
+function query(input) {
+    if (input === undefined)
+        return "";
+    const entries = Object.entries(Schema.decodeUnknownSync(queryInput)(input));
+    const params = new URLSearchParams(entries.map(([name, value]) => [name, String(value)]));
+    return params.size === 0 ? "" : `?${params.toString()}`;
+}
+function check(response) {
+    if (response.ok)
+        return;
+    throw new AppError("Capability request failed", {
+        code: response.status === 401 || response.status === 403
+            ? "CAPABILITY_DENIED"
+            : response.status === 413
+                ? "FILE_TOO_LARGE"
+                : response.status === 404
+                    ? "INVALID_ARGUMENT"
+                    : "HOST_FAILURE",
+        retryable: response.status >= 500,
+    });
+}
+// Chromium can expose an empty stream for bodyless HTTP responses. Cap'n Web
+// reconstructs Responses in the App; their constructor rejects a stream for
+// 204/205/304, which would otherwise break the entire App RPC connection.
+async function fetchResponse(url, init) {
+    const response = await fetch(url, init);
+    if (init.method === "HEAD" ||
+        response.status === 204 ||
+        response.status === 205 ||
+        response.status === 304) {
+        await response.body?.cancel();
+        return new Response(null, response);
+    }
+    return response;
+}
+class ReadHandle extends RpcTarget {
+    #abort = new AbortController();
+    #url;
+    #init;
+    constructor(url, init) {
+        super();
+        this.#url = url;
+        this.#init = init;
+    }
+    async response() {
+        const response = await fetchResponse(this.#url, {
+            ...this.#init,
+            signal: this.#abort.signal,
+        });
+        check(response);
+        return response;
+    }
+    close() {
+        this.#abort.abort();
+        return Promise.resolve();
+    }
+}
+class WriteHandle extends RpcTarget {
+    #abort = new AbortController();
+    #url;
+    #init;
+    constructor(url, init) {
+        super();
+        this.#url = url;
+        this.#init = init;
+    }
+    async write(content) {
+        // R2 requires a known length, as on the existing file upload route.
+        const body = await new Response(content).arrayBuffer();
+        check(await fetch(this.#url, {
+            ...this.#init,
+            body,
+            signal: this.#abort.signal,
+        }));
+    }
+    close() {
+        this.#abort.abort();
+        return Promise.resolve();
+    }
+}
+class TransportHandle extends RpcTarget {
+    #abort = new AbortController();
+    #url;
+    #init;
+    constructor(url, init) {
+        super();
+        this.#url = url;
+        this.#init = init;
+    }
+    async fetch(raw) {
+        const request = Schema.decodeUnknownSync(Schema.instanceOf(Request))(raw);
+        if (this.#init.method !== "ANY" && request.method !== this.#init.method)
+            throw new AppError("This transport does not admit that HTTP method", {
+                code: "CAPABILITY_DENIED",
+                retryable: false,
+            });
+        const incoming = new URL(request.url);
+        const target = new URL(this.#url, "https://oyster.invalid");
+        target.pathname = `${target.pathname.replace(/\/$/u, "")}${incoming.pathname}`;
+        for (const [name, value] of incoming.searchParams) {
+            if (target.searchParams.has(name))
+                throw new AppError("A transport request cannot replace its handle arguments", {
+                    code: "INVALID_ARGUMENT",
+                    retryable: false,
+                });
+            target.searchParams.append(name, value);
+        }
+        const headers = new Headers(this.#init.headers);
+        for (const name of [
+            "accept",
+            "content-type",
+            "last-event-id",
+            "acp-connection-id",
+            "acp-session-id",
+        ]) {
+            const value = request.headers.get(name);
+            if (value !== null)
+                headers.set(name, value);
+        }
+        const init = {
+            ...this.#init,
+            method: request.method,
+            headers,
+            signal: AbortSignal.any([request.signal, this.#abort.signal]),
+        };
+        if (request.method !== "GET" && request.method !== "HEAD") {
+            const body = await request.arrayBuffer();
+            if (body.byteLength > 512 * 1024)
+                throw new AppError("Transport request is too large", {
+                    code: "INVALID_ARGUMENT",
+                    retryable: false,
+                });
+            init.body = body;
+        }
+        return fetchResponse(`${target.pathname}${target.search}`, init);
+    }
+    close() {
+        this.#abort.abort();
+        return Promise.resolve();
+    }
+}
+function capabilityRequest(descriptor, installationId, route, raw) {
+    const resolved = resolveRoute(route.path, raw);
+    const input = resolved.input;
+    const headers = new Headers({ "X-Oyster-Installation": installationId });
+    const url = `${descriptor.base}${resolved.path}`;
+    const target = new URL(url, "https://oyster.invalid");
+    if (target.origin !== "https://oyster.invalid" || target.pathname !== url)
+        throw new AppError("Capability arguments change the route", {
+            code: "INVALID_ARGUMENT",
+            retryable: false,
+        });
+    const init = {
+        method: route.method,
+        headers,
+        credentials: "same-origin",
+        cache: "no-store",
+        redirect: "error",
+    };
+    if (route.kind === "json" && route.method !== "GET") {
+        headers.set("Content-Type", "application/json");
+        init.body = JSON.stringify(input);
+        return { url, init };
+    }
+    return { url: `${url}${query(input)}`, init };
+}
+async function jsonReply(url, init) {
+    const response = await fetch(url, init);
+    check(response);
+    if (response.status === 204)
+        return undefined;
+    return parseJsonValue(await response.json());
+}
+/** Bind a page-local JSON caller; cancellation never enters serialized input. */
+export function capabilityJsonCaller(descriptor, installationId) {
+    return async (method, raw, options) => {
+        const input = Schema.decodeUnknownSync(capabilityInputSchema)(raw);
+        const route = descriptor.methods[method];
+        if (route?.kind !== "json")
+            throw new AppError("This method is not a JSON capability method", {
+                code: "INVALID_ARGUMENT",
+                retryable: false,
+            });
+        const { url, init } = capabilityRequest(descriptor, installationId, route, input);
+        return jsonReply(url, { ...init, signal: options?.signal });
+    };
+}
+/** Open a browser transport using the page's admitted installation. */
+function capabilityTransportOpener(descriptor, installationId) {
+    return (method, raw) => {
+        const route = descriptor.methods[method];
+        if (route?.kind !== "transport" ||
+            (route.method !== "GET" && route.method !== "ANY"))
+            throw new AppError("This method does not admit a WebSocket transport", {
+                code: "INVALID_ARGUMENT",
+                retryable: false,
+            });
+        const { url } = capabilityRequest(descriptor, installationId, route, Schema.decodeUnknownSync(capabilityInputSchema)(raw));
+        const target = new URL(url, "https://oyster.invalid");
+        // Browser WebSockets cannot send the installation header used by Fetch.
+        target.searchParams.set("oysterInstallation", installationId);
+        return new WebSocket(`${target.pathname}${target.search}`);
+    };
+}
+/** Build the App's RPC handle from its admitted descriptor and installation. */
+export function capabilityHandle(descriptor, installationId) {
+    // Cap'n Web exposes prototype methods, never an instance's own properties.
+    // Only input crosses RPC; AbortSignal options belong to the local caller.
+    class CapabilityHandle extends RpcTarget {
+    }
+    Object.assign(CapabilityHandle.prototype, Object.fromEntries(Object.entries(descriptor.methods).map(([name, route]) => [
+        name,
+        async (raw) => {
+            const input = Schema.decodeUnknownSync(capabilityInputSchema)(raw);
+            const { url, init } = capabilityRequest(descriptor, installationId, route, input);
+            if (route.kind === "read")
+                return new ReadHandle(url, init);
+            if (route.kind === "write")
+                return new WriteHandle(url, init);
+            if (route.kind === "transport")
+                return new TransportHandle(url, init);
+            return jsonReply(url, init);
+        },
+    ])));
+    return new CapabilityHandle();
+}
+/** Create a registered handle, using the descriptor's ordinary RPC handle by default. */
+export async function registeredCapabilityHandle(registration, descriptor, installationId) {
+    if (registration.createHandle === undefined)
+        return capabilityHandle(descriptor, installationId);
+    return await registration.createHandle(capabilityJsonCaller(descriptor, installationId), capabilityTransportOpener(descriptor, installationId));
+}

package/dist/page/computer-handles.d.ts

@@ -0,0 +1,79 @@
+import { RpcTarget } from "@fungi.computer/capnweb";
+import type { CapabilityContract } from "@fungi.computer/agar";
+import { type ComputerProcessStart, type computerPorts, type computerProcesses } from "@fungi.computer/agar/computer";
+import type { CapabilityJsonCaller } from "./capabilities.js";
+/** The App-facing handle a capability contract describes. */
+export type HandleOf<Contract> = Contract extends CapabilityContract<infer Handle> ? Handle : never;
+/**
+ * Agar's `computer.ports` handle over the host's wire. The App passes a bare
+ * port; Hub's routes and the Computer owner take `{ port }` as the body, so
+ * this handle is the one place that maps between the two.
+ */
+export declare class ComputerPortsHandle extends RpcTarget implements HandleOf<typeof computerPorts> {
+    #private;
+    constructor(call: CapabilityJsonCaller);
+    list(): Promise<{
+        readonly ports: readonly {
+            readonly port: number;
+            readonly previewUrl: string;
+            readonly openMode: "inline" | "external-only";
+            readonly expiresAt: number;
+        }[];
+    } | {
+        readonly error: "port_previews_not_configured";
+    }>;
+    expose(port: number): Promise<{
+        readonly port: number;
+        readonly exposed: boolean;
+    }>;
+    unexpose(port: number): Promise<{
+        readonly port: number;
+        readonly removed: boolean;
+    }>;
+}
+/**
+ * Agar's `computer.processes` handle over the host's wire. The App passes a
+ * bare process ID to `kill`; the host route takes `{ id }` as the body.
+ */
+export declare class ComputerProcessesHandle extends RpcTarget implements HandleOf<typeof computerProcesses> {
+    #private;
+    constructor(call: CapabilityJsonCaller);
+    start(input: ComputerProcessStart): Promise<{
+        readonly port: number | null;
+        readonly id: string;
+        readonly command: string;
+        readonly cwd: string | null;
+        readonly startedAt: number;
+        readonly state: "running" | "exited" | "uncertain";
+        readonly exitCode: number | null;
+        readonly sync: "synced" | "pending" | "unknown";
+        readonly endedAt: number | null;
+    }>;
+    list(): Promise<{
+        readonly processes: readonly {
+            readonly port: number | null;
+            readonly id: string;
+            readonly command: string;
+            readonly cwd: string | null;
+            readonly startedAt: number;
+            readonly state: "running" | "exited" | "uncertain";
+            readonly exitCode: number | null;
+            readonly sync: "synced" | "pending" | "unknown";
+            readonly endedAt: number | null;
+        }[];
+    }>;
+    kill(id: string): Promise<{
+        readonly process: {
+            readonly port: number | null;
+            readonly id: string;
+            readonly command: string;
+            readonly cwd: string | null;
+            readonly startedAt: number;
+            readonly state: "running" | "exited" | "uncertain";
+            readonly exitCode: number | null;
+            readonly sync: "synced" | "pending" | "unknown";
+            readonly endedAt: number | null;
+        };
+        readonly signalled: boolean;
+    }>;
+}

package/dist/page/computer-handles.js

@@ -0,0 +1,44 @@
+import { RpcTarget } from "@fungi.computer/capnweb";
+import * as Schema from "effect/Schema";
+import { computerPortExposureSchema, computerPortRemovalSchema, computerPortsResultSchema, computerProcessKillSchema, computerProcessSchema, computerProcessesSchema, } from "@fungi.computer/agar/computer";
+/**
+ * Agar's `computer.ports` handle over the host's wire. The App passes a bare
+ * port; Hub's routes and the Computer owner take `{ port }` as the body, so
+ * this handle is the one place that maps between the two.
+ */
+export class ComputerPortsHandle extends RpcTarget {
+    #call;
+    constructor(call) {
+        super();
+        this.#call = call;
+    }
+    async list() {
+        return Schema.decodeUnknownSync(computerPortsResultSchema)(await this.#call("list"));
+    }
+    async expose(port) {
+        return Schema.decodeUnknownSync(computerPortExposureSchema)(await this.#call("expose", { port }));
+    }
+    async unexpose(port) {
+        return Schema.decodeUnknownSync(computerPortRemovalSchema)(await this.#call("unexpose", { port }));
+    }
+}
+/**
+ * Agar's `computer.processes` handle over the host's wire. The App passes a
+ * bare process ID to `kill`; the host route takes `{ id }` as the body.
+ */
+export class ComputerProcessesHandle extends RpcTarget {
+    #call;
+    constructor(call) {
+        super();
+        this.#call = call;
+    }
+    async start(input) {
+        return Schema.decodeUnknownSync(computerProcessSchema)(await this.#call("start", input));
+    }
+    async list() {
+        return Schema.decodeUnknownSync(computerProcessesSchema)(await this.#call("list"));
+    }
+    async kill(id) {
+        return Schema.decodeUnknownSync(computerProcessKillSchema)(await this.#call("kill", { id }));
+    }
+}

package/dist/page/lifetime.d.ts

@@ -0,0 +1,6 @@
+/** Owns the page's App connections and services until disconnect or pagehide. */
+export declare function createPageLifetime(page: EventTarget): {
+    signal: AbortSignal;
+    own: (release: () => void) => void;
+    dispose: () => void;
+};

package/dist/page/lifetime.js

@@ -0,0 +1,19 @@
+/** Owns the page's App connections and services until disconnect or pagehide. */
+export function createPageLifetime(page) {
+    const controller = new AbortController();
+    const dispose = () => {
+        controller.abort();
+        page.removeEventListener("pagehide", dispose);
+    };
+    page.addEventListener("pagehide", dispose, { once: true });
+    return {
+        signal: controller.signal,
+        own: (release) => {
+            if (controller.signal.aborted)
+                release();
+            else
+                controller.signal.addEventListener("abort", release, { once: true });
+        },
+        dispose,
+    };
+}