@fungi.computer/oyster 0.0.0-stage → 0.1.0

package/dist/tenancy/registry.js

@@ -0,0 +1,138 @@
+import { checkedOrigin, immutable, createMemberId, membershipVersionSchema, } from "./registry-record.js";
+import * as Schema from "effect/Schema";
+import { tenantIdSchema } from "../tenant.js";
+/** In-memory tenant and member owner; create updates both atomically. */
+export function memoryRegistry(options = {}) {
+    const tenants = new Map();
+    const handles = new Map();
+    const domains = new Map();
+    const identities = new Map();
+    const memberships = new Map();
+    let revision = 0;
+    const nextRevision = () => {
+        revision = Schema.decodeUnknownSync(membershipVersionSchema)(revision + 1);
+        return revision;
+    };
+    const canonicalMember = (identity) => identities.get(identity.provider)?.get(identity.subject);
+    const retainMember = (identity, memberId) => {
+        let subjects = identities.get(identity.provider);
+        if (subjects === undefined) {
+            subjects = new Map();
+            identities.set(identity.provider, subjects);
+        }
+        const previous = subjects.get(identity.subject);
+        if (previous !== undefined && previous !== memberId)
+            throw new Error("Identity already has a canonical member mapping");
+        subjects.set(identity.subject, memberId);
+    };
+    const insert = (tenant) => {
+        if (tenants.has(tenant.id) ||
+            handles.has(tenant.handle) ||
+            tenant.domains.some((domain) => domains.has(domain)))
+            throw new Error("Tenant identity, handle or domain already exists");
+        const stored = immutable(tenant);
+        tenants.set(tenant.id, stored);
+        handles.set(tenant.handle, tenant.id);
+        for (const domain of tenant.domains)
+            domains.set(domain, tenant.id);
+        return stored;
+    };
+    for (const tenant of options.tenants ?? []) {
+        Schema.decodeUnknownSync(tenantIdSchema)(tenant.id);
+        Schema.decodeUnknownSync(tenantIdSchema)(tenant.handle);
+        insert({ ...tenant, origin: checkedOrigin(tenant.origin, tenant.domains) });
+    }
+    for (const membership of options.memberships ?? []) {
+        if (!tenants.has(membership.tenantId))
+            throw new Error("Membership tenant does not exist");
+        retainMember(membership.identity, membership.memberId);
+        let entries = memberships.get(membership.tenantId);
+        if (entries === undefined) {
+            entries = new Map();
+            memberships.set(membership.tenantId, entries);
+        }
+        entries.set(membership.memberId, {
+            memberId: membership.memberId,
+            role: membership.role,
+            membershipVersion: nextRevision(),
+        });
+    }
+    const get = (id) => tenants.get(id) ?? null;
+    return {
+        get: (id) => Promise.resolve(get(id)),
+        byHandle(handle) {
+            const id = handles.get(handle);
+            return Promise.resolve(id === undefined ? null : get(id));
+        },
+        byDomain(host) {
+            const id = domains.get(host);
+            return Promise.resolve(id === undefined ? null : get(id));
+        },
+        status: (id) => Promise.resolve(get(id)?.status ?? null),
+        memberById(id, memberId) {
+            const member = memberships.get(id)?.get(memberId);
+            return Promise.resolve(member === undefined ? null : { ...member });
+        },
+        membershipOf(id, identity) {
+            const memberId = canonicalMember(identity);
+            return Promise.resolve(memberId === undefined
+                ? null
+                : (memberships.get(id)?.get(memberId) ?? null));
+        },
+        create(input) {
+            return Promise.resolve().then(() => {
+                const handle = Schema.decodeUnknownSync(tenantIdSchema)(input.handle);
+                const origin = checkedOrigin(input.origin, input.domains);
+                const id = handle;
+                const memberId = canonicalMember(input.owner) ?? createMemberId();
+                const tenant = {
+                    id,
+                    handle,
+                    origin,
+                    domains: [...input.domains],
+                    owners: [memberId],
+                    status: "active",
+                };
+                const stored = insert(tenant);
+                retainMember(input.owner, memberId);
+                memberships.set(id, new Map([
+                    [
+                        memberId,
+                        {
+                            memberId,
+                            role: "owner",
+                            membershipVersion: nextRevision(),
+                        },
+                    ],
+                ]));
+                return stored;
+            });
+        },
+        setStatus(id, status) {
+            const tenant = get(id);
+            if (tenant === null)
+                return Promise.reject(new Error("Tenant does not exist"));
+            if (tenant.status !== status) {
+                const membershipVersion = nextRevision();
+                for (const [memberId, membership] of memberships.get(id) ?? [])
+                    memberships
+                        .get(id)
+                        ?.set(memberId, { ...membership, membershipVersion });
+            }
+            tenants.set(id, immutable({ ...tenant, status }));
+            return Promise.resolve();
+        },
+        delete(id) {
+            const tenant = get(id);
+            if (tenant === null)
+                return Promise.resolve();
+            nextRevision();
+            tenants.delete(id);
+            handles.delete(tenant.handle);
+            memberships.delete(id);
+            for (const domain of tenant.domains)
+                domains.delete(domain);
+            return Promise.resolve();
+        },
+    };
+}

package/dist/tenancy/resolve.d.ts

@@ -0,0 +1,7 @@
+import type { ReadonlyTenantRegistry, TenantResolverAdapter } from "./contracts.js";
+/** Resolve a provisioned label immediately below a configured base hostname. */
+export declare function subdomain(baseDomain: string): TenantResolverAdapter<"origin">;
+/** Resolve a provisioned custom domain through the registry's domain index. */
+export declare function hosts(registry: ReadonlyTenantRegistry): TenantResolverAdapter<"origin">;
+/** Resolve provisioned path tenants for APIs; this resolver cannot host Oyster. */
+export declare function path(pattern: string): TenantResolverAdapter<"path">;

package/dist/tenancy/resolve.js

@@ -0,0 +1,64 @@
+import { match, parse } from "path-to-regexp";
+import * as Schema from "effect/Schema";
+import { tenantIdSchema } from "../tenant.js";
+/** Resolve a provisioned label immediately below a configured base hostname. */
+export function subdomain(baseDomain) {
+    const base = new URL(`https://${baseDomain}`);
+    if (base.host !== baseDomain.toLowerCase() ||
+        base.port !== "" ||
+        base.pathname !== "/" ||
+        base.search ||
+        base.hash ||
+        base.username ||
+        base.password ||
+        base.hostname.endsWith("."))
+        throw new TypeError("Configure a base hostname without credentials, path, port or trailing dot");
+    const suffix = `.${base.hostname}`;
+    return {
+        kind: "origin",
+        async resolve(url, registry) {
+            if (!url.hostname.endsWith(suffix))
+                return null;
+            const handle = url.hostname.slice(0, -suffix.length);
+            const parsed = Schema.decodeUnknownOption(tenantIdSchema)(handle);
+            if (parsed._tag === "None")
+                return null;
+            return (await registry.byHandle(handle))?.id ?? null;
+        },
+    };
+}
+/** Resolve a provisioned custom domain through the registry's domain index. */
+export function hosts(registry) {
+    return {
+        kind: "origin",
+        resolve: async (url) => (await registry.byDomain?.(url.host))?.id ?? null,
+    };
+}
+/** Resolve provisioned path tenants for APIs; this resolver cannot host Oyster. */
+export function path(pattern) {
+    const tokens = parse(pattern).tokens;
+    if (!tokens.some((token) => token.type === "param" && token.name === "tenant"))
+        throw new TypeError("A tenant path must contain the :tenant parameter");
+    const route = match(pattern, { end: false });
+    return {
+        kind: "path",
+        async resolve(url, registry) {
+            let result;
+            try {
+                result = route(url.pathname);
+            }
+            catch (cause) {
+                if (cause instanceof URIError)
+                    return null;
+                throw cause;
+            }
+            if (result === false)
+                return null;
+            const handle = result.params.tenant;
+            const parsed = Schema.decodeUnknownOption(tenantIdSchema)(handle);
+            if (parsed._tag === "None")
+                return null;
+            return (await registry.byHandle(parsed.value))?.id ?? null;
+        },
+    };
+}

package/dist/tenant.d.ts

@@ -0,0 +1,81 @@
+import type { HostActor } from "@fungi.computer/puffball/app-method-runtime";
+import * as Schema from "effect/Schema";
+import type { OysterAuth } from "./host.js";
+/**
+ * A host-minted tenant slug: 2–40 lowercase ASCII letters or digits, with
+ * single interior hyphens. The repository separator `--` is forbidden.
+ * Hosts resolve it before authentication; App-controlled inputs never select it.
+ */
+export declare const tenantIdSchema: Schema.brand<Schema.String, "OysterTenantId">;
+/** A validated host-selected tenant identity. */
+export type TenantId = typeof tenantIdSchema.Type;
+/** A canonical host actor with a tenant role only when the actor is a member. */
+export type TenantPrincipal = Readonly<{
+    /** Stored member identity resolved by the tenant registry. */
+    actor: Extract<HostActor, {
+        kind: "member";
+    }>;
+    /** The member's admitted role; membership does not imply ownership. */
+    role: "owner" | "member";
+    /** The host attests this member is the tenant's only member. */
+    soleMember?: true;
+}> | Readonly<{
+    /** An Agent or Team key retains its canonical actor identity. */
+    actor: Exclude<HostActor, {
+        kind: "member";
+    }>;
+}>;
+/** The single-tenant Oyster identity whose durable names remain unchanged. */
+export declare const defaultTenant: TenantId;
+/** Resolves a request before authentication; null means refuse, never fallback. */
+export type TenantResolver = Readonly<{
+    /** Return the host-selected tenant and canonical origin, or refuse this URL. */
+    resolve(request: Request): Promise<Readonly<{
+        tenantId: TenantId;
+        origin: string;
+    }> | null>;
+}>;
+/** The only source of durable names for a standalone Oyster tenant. */
+export type TenantScope = Readonly<{
+    /** Host-selected tenant identity; never taken from App input. */
+    tenantId: TenantId;
+    /** Canonical HTTP(S) origin for this tenant's public routes. */
+    origin: string;
+    /** Name of a tenant-owned Durable Object within its binding namespace. */
+    durableName(kind: "registry" | "keys" | "webhooks" | "git-push" | "agents" | "mcp"): string;
+    /** Name within the Computer binding; nondefault Computers await host support. */
+    computerName(computerId: string): string;
+    /** R2 prefix for mutable workspace files; immutable release bytes may be shared. */
+    workspacePrefix: string;
+    /**
+     * Provider prefix for an installation slug without `--`.
+     * The Git adapter must validate the final prefix + repo against the provider's
+     * 128-character limit; a prefix alone cannot establish that a repo name fits.
+     */
+    repositoryPrefix(installationId: string): string;
+}>;
+/**
+ * Name tenant-owned stores without changing any default-tenant name. The `t.`
+ * repository namespace cannot be a default installation slug, which forbids dots.
+ * Hub supplies its own Team-scoped ports and does not use this naming contract.
+ */
+export declare function tenantScope(tenantId: TenantId, origin: string): TenantScope;
+/**
+ * Admit defaultTenant only at the configured origin. Scheme, host and port must
+ * match after URL canonicalization; unknown origins never fall back to default.
+ */
+export declare function singleTenant(origin: string): TenantResolver;
+/** A host-selected scope paired with its existing authentication port. */
+export type ResolvedTenant = Readonly<{
+    /** Canonical origin and durable names selected before authentication. */
+    scope: TenantScope;
+    /** Authentication bound to this tenant; resolution does not invoke it. */
+    auth: OysterAuth;
+}>;
+/** Resolve an origin-scoped host; null refuses the request without a fallback. */
+export type OysterTenancy = Readonly<{
+    /** Select one tenant before authentication; unknown origins return null. */
+    resolve(request: Request): Promise<ResolvedTenant | null>;
+}>;
+/** Preserve the default tenant's names and auth only at the configured origin. */
+export declare function implicitTenancy(origin: string, auth: OysterAuth): OysterTenancy;

package/dist/tenant.js

@@ -0,0 +1,71 @@
+import * as Schema from "effect/Schema";
+/**
+ * A host-minted tenant slug: 2–40 lowercase ASCII letters or digits, with
+ * single interior hyphens. The repository separator `--` is forbidden.
+ * Hosts resolve it before authentication; App-controlled inputs never select it.
+ */
+export const tenantIdSchema = Schema.String.check(Schema.isPattern(/^[a-z0-9](?:[a-z0-9]|-(?!-)){0,38}[a-z0-9]$/u)).pipe(Schema.brand("OysterTenantId"));
+/** The single-tenant Oyster identity whose durable names remain unchanged. */
+export const defaultTenant = Schema.decodeUnknownSync(tenantIdSchema)("default");
+function configuredOrigin(origin) {
+    const url = new URL(origin);
+    if (!["https:", "http:"].includes(url.protocol) ||
+        url.username !== "" ||
+        url.password !== "" ||
+        url.pathname !== "/" ||
+        url.search !== "" ||
+        url.hash !== "") {
+        throw new TypeError("Configure an HTTP(S) origin without credentials or a path");
+    }
+    return url;
+}
+const installationIdSchema = Schema.String.check(Schema.isPattern(/^[a-z][a-z0-9-]{0,62}$/u), Schema.isPattern(/^(?!.*--)/u));
+/**
+ * Name tenant-owned stores without changing any default-tenant name. The `t.`
+ * repository namespace cannot be a default installation slug, which forbids dots.
+ * Hub supplies its own Team-scoped ports and does not use this naming contract.
+ */
+export function tenantScope(tenantId, origin) {
+    const canonicalOrigin = configuredOrigin(origin).origin;
+    const isDefault = tenantId === defaultTenant;
+    const durablePrefix = isDefault ? "" : `t.${tenantId}.`;
+    return {
+        tenantId,
+        origin: canonicalOrigin,
+        durableName: (kind) => `${durablePrefix}${kind}`,
+        computerName: (computerId) => `${durablePrefix}${computerId}`,
+        workspacePrefix: isDefault
+            ? "workspace/"
+            : `tenants/${tenantId}/workspace/`,
+        repositoryPrefix(installationId) {
+            const installation = Schema.decodeUnknownSync(installationIdSchema)(installationId);
+            return isDefault
+                ? `${installation}--`
+                : `t.${tenantId}--${installation}--`;
+        },
+    };
+}
+/**
+ * Admit defaultTenant only at the configured origin. Scheme, host and port must
+ * match after URL canonicalization; unknown origins never fall back to default.
+ */
+export function singleTenant(origin) {
+    const canonicalOrigin = configuredOrigin(origin).origin;
+    return {
+        resolve: (request) => Promise.resolve(new URL(request.url).origin === canonicalOrigin
+            ? { tenantId: defaultTenant, origin: canonicalOrigin }
+            : null),
+    };
+}
+/** Preserve the default tenant's names and auth only at the configured origin. */
+export function implicitTenancy(origin, auth) {
+    const resolver = singleTenant(origin);
+    const scope = tenantScope(defaultTenant, origin);
+    return {
+        async resolve(request) {
+            return (await resolver.resolve(request)) === null
+                ? null
+                : { scope, auth };
+        },
+    };
+}

package/dist/testing/capabilities.d.ts

@@ -0,0 +1,29 @@
+import { Hono } from "hono";
+import { type AppCapabilityId } from "@fungi.computer/puffball/app";
+import { type OysterAgents } from "../agents.js";
+import { type FileSource } from "../files.js";
+import { type OysterAuthResult, type OysterCapability } from "../host.js";
+/** How one capability fixture host admits its single installation. */
+export type CapabilityFixtureOptions = Readonly<{
+    /** `false` publishes a Release that declares no capability. */
+    declared?: boolean;
+    /** Capabilities the Release declares; defaults to `computer.list`. */
+    capabilities?: readonly AppCapabilityId[];
+    /** Adapters the host grants; defaults to a `computer.list` probe. */
+    adapters?: readonly OysterCapability[];
+    /** Grant the file adapters over this source instead of the probe. */
+    fileSource?: FileSource;
+    /** `false` clears the owner's approval after install. */
+    admitted?: boolean;
+    /** Serve a public installation to an anonymous visitor. */
+    visitor?: boolean;
+    authenticate?: (request: Request) => Promise<OysterAuthResult>;
+    agents?: OysterAgents;
+}>;
+/** One Oyster host with a single installation whose capability grants the options shape. */
+export declare function capabilityFixture(options?: CapabilityFixtureOptions): Promise<{
+    app: Hono<import("../host.js").OysterEnv, import("hono/types").BlankSchema, "/">;
+    page: () => Response | Promise<Response>;
+    request: () => Response | Promise<Response>;
+    removeDeclaration(): Promise<void>;
+}>;

package/dist/testing/capabilities.js

@@ -0,0 +1,130 @@
+import { Hono } from "hono";
+import * as Schema from "effect/Schema";
+import { releaseSchema } from "@fungi.computer/puffball/effect";
+import { parseArtifactRef, parseSha256Digest } from "@fungi.computer/puffball";
+import { createAppBuild, emptyAppDeclaration, } from "@fungi.computer/puffball/app";
+import { computerList } from "@fungi.computer/agar/computer";
+import { agentApprovalRoutes } from "../agents.js";
+import { fileCapabilities } from "../files.js";
+import { createOyster, } from "../host.js";
+import { instanceIds } from "../index.js";
+import { sha256, verifyRelease } from "../release.js";
+import { approvedInstallation } from "./installation.js";
+/** One Oyster host with a single installation whose capability grants the options shape. */
+export async function capabilityFixture(options = {}) {
+    const artifacts = new Map();
+    async function put(bytes) {
+        const digest = parseSha256Digest(await sha256(bytes));
+        const artifactRef = parseArtifactRef(`artifact:sha256-${digest.slice(7)}`);
+        artifacts.set(artifactRef, bytes);
+        return { artifactRef, digest };
+    }
+    const encode = (text) => new TextEncoder().encode(text);
+    const uiBytes = encode("<!doctype html><title>Capability fixture</title>");
+    const ui = {
+        ...(await put(uiBytes)),
+        version: "fixture",
+        byteLength: uiBytes.length,
+        mediaType: "text/html; charset=utf-8",
+    };
+    async function release(releaseId, capabilities) {
+        const root = await put(encode(JSON.stringify(createAppBuild(ui, null, { capabilities, handlers: [], roles: [] }))));
+        return Schema.decodeUnknownSync(releaseSchema)({
+            releaseId,
+            appId: "app_capability",
+            artifact: {
+                artifactRef: root.artifactRef,
+                artifactDigest: root.digest,
+                provenance: {
+                    sourceRevision: `git:${"a".repeat(40)}`,
+                    sourceTreeDigest: root.digest,
+                    buildRecipeDigest: root.digest,
+                },
+            },
+        });
+    }
+    const routes = new Hono().post("/list", (context) => context.json({ entries: [] }));
+    const capabilities = options.adapters ??
+        (options.fileSource
+            ? fileCapabilities(options.fileSource)
+            : [
+                {
+                    id: computerList.id,
+                    permission: "computer.list",
+                    version: computerList.version,
+                    base: "/probe/",
+                    routes,
+                    methods: { list: { kind: "json", method: "POST", path: "list" } },
+                },
+            ]);
+    const declaredRelease = await release("rel_declared", options.declared === false
+        ? []
+        : (options.capabilities ?? ["computer.list"]));
+    const declaration = (await verifyRelease({
+        get: (ref) => Promise.resolve(artifacts.get(ref) ?? null),
+        put: () => Promise.reject(new Error("Fixture artifacts are read-only")),
+    }, declaredRelease)).declaration;
+    let installation = await approvedInstallation({
+        installationId: "capability-fixture",
+        instanceId: instanceIds.instance.generate(),
+        release: declaredRelease,
+        declaration: declaration ?? emptyAppDeclaration,
+        descriptors: capabilities,
+    });
+    if (options.admitted === false)
+        installation = { ...installation, approvedGrants: [], approval: null };
+    // An anonymous reader reaches only a public App, as the host's visitor.
+    if (options.visitor)
+        installation = { ...installation, visibility: "public" };
+    const readOnly = () => Promise.reject(new Error("Fixture installations are read-only"));
+    const base = {
+        auth: {
+            resolve: () => Promise.reject(new Error("Capability fixture resolves no actor")),
+            authenticate: options.authenticate ??
+                ((request) => Promise.resolve(options.visitor || request.headers.get("x-who") === "visitor"
+                    ? { kind: "refused", status: 401 }
+                    : {
+                        kind: "admitted",
+                        principal: {
+                            actor: { kind: "member", memberId: "owner" },
+                            role: "owner",
+                        },
+                    })),
+        },
+        artifacts: {
+            get: (ref) => Promise.resolve(artifacts.get(ref) ?? null),
+            put: () => Promise.reject(new Error("Fixture artifacts are read-only")),
+        },
+        installations: {
+            list: () => Promise.resolve([installation]),
+            get: (id) => Promise.resolve(id === installation.installationId ? installation : null),
+            put: readOnly,
+            compareAndPut: readOnly,
+        },
+        instances: {
+            get: () => {
+                throw new Error("Capability routes must not execute an App backend");
+            },
+        },
+        capabilities,
+    };
+    const host = options.agents === undefined
+        ? base
+        : { ...base, ownerRoutes: agentApprovalRoutes(options.agents) };
+    const app = createOyster(host);
+    return {
+        app,
+        page: () => app.request("https://oyster.test/apps/capability-fixture/"),
+        request: () => app.request("https://oyster.test/probe/list", {
+            method: "POST",
+            headers: { "X-Oyster-Installation": installation.installationId },
+        }),
+        async removeDeclaration() {
+            installation = {
+                ...installation,
+                release: await release("rel_undeclared", []),
+                authorityVersion: installation.authorityVersion + 1,
+            };
+        },
+    };
+}

package/dist/testing/catalog.d.ts

@@ -0,0 +1,3 @@
+/** Digest-verifying local catalog shared by native App host proofs. */
+export declare function createFixtureCatalog(encoded: string): import("@fungi.computer/puffball/effect").AppReleaseCore;
+export declare function seedFixtureCatalog(encoded: string, catalog: ReturnType<typeof createFixtureCatalog>): Promise<void>;

package/dist/testing/catalog.js

@@ -0,0 +1,53 @@
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { createAppReleaseCore, createDeterministicMemoryAppReleaseStore, adaptPromiseAppReleaseStore, releaseSchema, adaptPromiseArtifactReader, } from "@fungi.computer/puffball/effect";
+import { parseSha256Digest } from "@fungi.computer/puffball";
+import { appMediaType } from "@fungi.computer/puffball/app";
+import { backendMediaType } from "@fungi.computer/puffball/backend";
+// The Publisher's artifact store: every Release root and child object by ref.
+const fixtureSchema = Schema.Struct({
+    releases: Schema.Array(releaseSchema),
+    objects: Schema.Record(Schema.String, Schema.Struct({
+        mediaType: Schema.Literals([
+            appMediaType,
+            backendMediaType,
+            "text/html; charset=utf-8",
+        ]),
+        body: Schema.String,
+    })),
+});
+const hex = (bytes) => Array.from(new Uint8Array(bytes), (b) => b.toString(16).padStart(2, "0")).join("");
+/** Digest-verifying local catalog shared by native App host proofs. */
+export function createFixtureCatalog(encoded) {
+    const fixture = Schema.decodeUnknownSync(Schema.fromJsonString(fixtureSchema))(encoded);
+    return createAppReleaseCore({
+        store: adaptPromiseAppReleaseStore(createDeterministicMemoryAppReleaseStore()),
+        artifactReader: adaptPromiseArtifactReader({
+            read: async ({ artifactRef, expectedDigest }) => {
+                const object = fixture.objects[artifactRef];
+                if (!object)
+                    return { kind: "missing" };
+                const bytes = new TextEncoder().encode(object.body);
+                const digest = parseSha256Digest(`sha256:${hex(await crypto.subtle.digest("SHA-256", bytes))}`);
+                if (digest !== expectedDigest)
+                    return { kind: "digest-mismatch", actualDigest: digest };
+                return {
+                    kind: "verified",
+                    digest,
+                    mediaType: object.mediaType,
+                    bytes: { byteLength: bytes.length, copy: () => bytes.slice() },
+                    byteLength: bytes.length,
+                };
+            },
+        }),
+        artifactPolicy: { maxBytes: 1024 * 1024 },
+    });
+}
+export async function seedFixtureCatalog(encoded, catalog) {
+    const fixture = Schema.decodeUnknownSync(Schema.fromJsonString(fixtureSchema))(encoded);
+    for (const release of fixture.releases) {
+        await Effect.runPromise(catalog.createApp({ appId: release.appId }));
+        await Effect.runPromise(catalog.createRelease(release));
+        await Effect.runPromise(catalog.verifyReleaseArtifact(release.releaseId));
+    }
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Test kit for Oyster hosts and Apps: fixture installations, a capability
+ * host, a digest-verifying release catalog and the frame binding wire.
+ * The `cloudflare:workers` stand-in lives at `./testing/workers-runtime`.
+ */
+export { approvedInstallation } from "./installation.js";
+export { capabilityFixture, type CapabilityFixtureOptions, } from "./capabilities.js";
+export { createFixtureCatalog, seedFixtureCatalog } from "./catalog.js";
+export { createFrameBindingWire, type FrameBindingReply, type FrameBindingWire, } from "../frame-binding-wire.js";
+export { startNativeWorker, type NativeWorker, type NativeWorkerOptions, } from "./native-worker.js";

package/dist/testing/index.js

@@ -0,0 +1,10 @@
+/**
+ * Test kit for Oyster hosts and Apps: fixture installations, a capability
+ * host, a digest-verifying release catalog and the frame binding wire.
+ * The `cloudflare:workers` stand-in lives at `./testing/workers-runtime`.
+ */
+export { approvedInstallation } from "./installation.js";
+export { capabilityFixture, } from "./capabilities.js";
+export { createFixtureCatalog, seedFixtureCatalog } from "./catalog.js";
+export { createFrameBindingWire, } from "../frame-binding-wire.js";
+export { startNativeWorker, } from "./native-worker.js";

package/dist/testing/installation.d.ts

@@ -0,0 +1,11 @@
+import type { AppDeclaration } from "@fungi.computer/puffball/app";
+import { type CapabilityOperationDescriptor, type Installation } from "../apps/index.js";
+/** Build fixture state through the same approval owner used by installation routes. */
+export declare function approvedInstallation(input: Readonly<{
+    release: Installation["release"];
+    declaration: AppDeclaration;
+    installationId: string;
+    instanceId: Installation["instanceId"];
+    descriptors?: readonly CapabilityOperationDescriptor[];
+    visibility?: Installation["visibility"];
+}>): Promise<Installation>;

package/dist/testing/installation.js

@@ -0,0 +1,25 @@
+import * as Result from "effect/Result";
+import { applyInstallationCommand, deriveDeclaredOperations, } from "../apps/index.js";
+/** Build fixture state through the same approval owner used by installation routes. */
+export async function approvedInstallation(input) {
+    const result = applyInstallationCommand(null, {
+        kind: "install",
+        release: input.release,
+        releasePin: "pinned",
+        grants: "declared",
+    }, {
+        by: { kind: "member", memberId: "fixture-owner" },
+        role: "owner",
+        expectedVersion: null,
+        declaration: input.declaration,
+        declaredOperations: await deriveDeclaredOperations(input.release, input.declaration, input.descriptors ?? []),
+        now: 1000,
+        identity: {
+            installationId: input.installationId,
+            instanceId: input.instanceId,
+        },
+    });
+    if (Result.isFailure(result))
+        throw new Error(result.failure.code);
+    return { ...result.success.next, visibility: input.visibility ?? "private" };
+}

package/dist/testing/native-worker.d.ts

@@ -0,0 +1,21 @@
+/** One `wrangler dev --local` launch: its config, vars and optional fixed port. */
+export type NativeWorkerOptions = Readonly<{
+    /** The Worker's wrangler config. */
+    configPath: string;
+    /** Plain-text vars passed with `--var`. */
+    vars: Readonly<Record<string, string>>;
+    /** A fixed port; 0 (the default) reserves a free one. */
+    port?: number;
+    /** Append the Worker's output to this file, which must have mode 0600. */
+    logFile?: string;
+}>;
+/** A ready local Worker; `stop` ends it and removes its persisted state. */
+export type NativeWorker = Readonly<{
+    port: number;
+    stop: () => Promise<void>;
+}>;
+/**
+ * Start `wrangler dev --local` on 127.0.0.1 with fresh persisted state and
+ * resolve once its root answers, or reject after 60 seconds.
+ */
+export declare function startNativeWorker({ configPath, vars, port: requestedPort, logFile, }: NativeWorkerOptions): Promise<NativeWorker>;