@fungi.computer/oyster 0.0.1 → 0.2.0

package/dist/build/content-objects.d.ts

@@ -0,0 +1,37 @@
+/**
+ * A build's uploaded objects in an R2-shaped store: content addressed
+ * (`artifact:sha256-<hex>`), written once from a stream with the store
+ * itself verifying the digest, and described by `head()` without a read.
+ * The bytes never pass through an isolate's memory as a whole.
+ */
+import { type ArtifactRef, type Sha256Digest } from "@fungi.computer/puffball";
+import type { ArtifactHead } from "../release.js";
+import type { CandidateObject, CandidateObjectMediaType } from "./submission-contract.js";
+/** The parts of an R2 bucket a content-object store uses. */
+export type ContentObjectBucket = Readonly<{
+    /** Describe the object at `key` without its body, or `null` when absent. */
+    head(key: string): Promise<Readonly<{
+        size: number;
+        checksums: Readonly<{
+            sha256?: ArrayBuffer;
+        }>;
+    }> | null>;
+    /** Store `value` at `key`; the bucket refuses bytes whose SHA-256 differs. */
+    put(key: string, value: ReadableStream<Uint8Array> | Uint8Array, options: Readonly<{
+        sha256: string;
+        httpMetadata: Readonly<{
+            contentType: CandidateObjectMediaType;
+        }>;
+    }>): Promise<object | null>;
+}>;
+/** The store key of one content-addressed object. */
+export declare function contentObjectRef(digest: Sha256Digest): ArtifactRef;
+/** Describe a stored object by its size and the SHA-256 the store verified. */
+export declare function headContentObject(bucket: ContentObjectBucket, artifactRef: ArtifactRef): Promise<ArtifactHead | null>;
+/**
+ * Stream one object into the store under its digest. The store refuses a
+ * body whose SHA-256 differs; an object already stored with the same
+ * verified digest and size is kept (write-once: a stored version may be
+ * pinned by a Release) and the body is discarded, never stored.
+ */
+export declare function putContentObject(bucket: ContentObjectBucket, object: CandidateObject, body: ReadableStream<Uint8Array> | null, mediaType: CandidateObjectMediaType): Promise<"stored" | "refused">;

package/dist/build/content-objects.js

@@ -0,0 +1,53 @@
+/**
+ * A build's uploaded objects in an R2-shaped store: content addressed
+ * (`artifact:sha256-<hex>`), written once from a stream with the store
+ * itself verifying the digest, and described by `head()` without a read.
+ * The bytes never pass through an isolate's memory as a whole.
+ */
+import { parseArtifactRef, parseSha256Digest, } from "@fungi.computer/puffball";
+/** The store key of one content-addressed object. */
+export function contentObjectRef(digest) {
+    return parseArtifactRef(`artifact:sha256-${digest.slice("sha256:".length)}`);
+}
+function hex(bytes) {
+    return Array.from(new Uint8Array(bytes), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+/** Describe a stored object by its size and the SHA-256 the store verified. */
+export async function headContentObject(bucket, artifactRef) {
+    const object = await bucket.head(artifactRef);
+    if (object === null)
+        return null;
+    const sha256 = object.checksums.sha256;
+    return {
+        byteLength: object.size,
+        digest: sha256 === undefined ? null : parseSha256Digest(`sha256:${hex(sha256)}`),
+    };
+}
+/**
+ * Stream one object into the store under its digest. The store refuses a
+ * body whose SHA-256 differs; an object already stored with the same
+ * verified digest and size is kept (write-once: a stored version may be
+ * pinned by a Release) and the body is discarded, never stored.
+ */
+export async function putContentObject(bucket, object, body, mediaType) {
+    const artifactRef = contentObjectRef(object.digest);
+    const existing = await headContentObject(bucket, artifactRef);
+    if (existing !== null &&
+        existing.digest === object.digest &&
+        existing.byteLength === object.byteLength) {
+        // Read the body through (discarding it) rather than cancel it: a
+        // cancelled request body resets the uploader's connection mid-send.
+        await body?.pipeTo(new WritableStream());
+        return "stored";
+    }
+    try {
+        await bucket.put(artifactRef, body ?? new Uint8Array(0), {
+            sha256: object.digest.slice("sha256:".length),
+            httpMetadata: { contentType: mediaType },
+        });
+    }
+    catch {
+        return "refused";
+    }
+    return "stored";
+}

package/dist/build/effect.d.ts

@@ -3,6 +3,7 @@ import type { AppDeclaration } from "@fungi.computer/puffball";
 import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
 import type * as Scope from "effect/Scope";
+import type { CandidateOutputManifest } from "./submission-contract.js";
 /** Canonical recipe policy shared by core and the local adapter. */
 export declare const pinnedRecipeSchema: Schema.Struct<{
     readonly kind: Schema.optional<Schema.Literals<readonly ["bundled-html", "source-html"]>>;
@@ -211,6 +212,12 @@ export type CapturedConfig = Readonly<{
     readonly recipe: PinnedRecipe;
     readonly buildRecipeDigest: Sha256Digest;
 }>;
+/**
+ * Whether a pinned recipe pins this Publisher's current toolchain (its build
+ * policy included). An executor refuses any other: a recipe pinned under
+ * another policy describes a build this code does not perform.
+ */
+export declare function pinsCurrentToolchain(recipe: PinnedRecipe): boolean;
 /** Hash every captured build and output-policy input in the Publisher recipe. */
 export declare function digestPinnedRecipe(recipe: PinnedRecipe): Sha256Digest;
 /** Decode and normalize Publisher-owned recipe policy for durable seed proof. */
@@ -221,6 +228,17 @@ export declare function normalizeAppPublisherRecipe(input: {
     recipe: PinnedRecipe;
     buildRecipeDigest: Sha256Digest;
 }>;
+/**
+ * The largest single object a build under this recipe may upload: no larger
+ * than the largest output bound the recipe could assign it under.
+ */
+export declare function pinnedRecipeObjectBound(recipe: PinnedRecipe): number;
+/**
+ * Whether output built elsewhere (a Computer's candidate manifest) is one
+ * this recipe could assign: the same surfaces and `maxOutputBytes` bound the
+ * preparer applies here. Asset sizes stay the artifact writer's policy.
+ */
+export declare function fitsPinnedRecipe(output: CandidateOutputManifest, recipe: PinnedRecipe): boolean;
 /** Construct one private App Publisher with copied core configuration and roles. */
 export declare function createAppCandidatePreparer(options: Pick<AppPublisherOptions, "config" | "sourceCapture" | "buildExecutor">): AppCandidatePreparer;
 /** Prepare a candidate from a previously captured recipe. */

package/dist/build/effect.js

@@ -1,5 +1,6 @@
 import { assetBuildPolicySchema, assetBaseSchema, } from "@fungi.computer/puffball/assets";
 import { boundedBundlePolicy, bundledHtmlRecipe } from "./html-recipe.js";
+import { workspaceBuildPolicy } from "./build-policy.js";
 import * as crypto from "node:crypto";
 import { backendJsonSchema, durableBackendSchema, } from "@fungi.computer/puffball/backend";
 import { parseSha256Digest, } from "@fungi.computer/puffball";
@@ -63,7 +64,7 @@ const workspaceHtmlToolchain = Object.freeze({
     tailwindOxide: "4.2.1",
     tailwindResolver: "5.24.5",
     typography: "0.5.19",
-    buildPolicy: "package-json-fungi-build-v1",
+    buildPolicy: workspaceBuildPolicy,
     recipe: "captured-workspace-html-v1",
 });
 const workspaceHtmlBackendToolchain = Object.freeze({
@@ -104,6 +105,29 @@ export class AppPublisherError extends Error {
 function sha256Digest(value) {
     return parseSha256Digest(`sha256:${crypto.createHash("sha256").update(value, "utf8").digest("hex")}`);
 }
+/** The toolchain this Publisher pins for a recipe of this kind, entry and backend. */
+function currentToolchain(recipe) {
+    if (recipe.kind === "source-html")
+        return sourceHtmlToolchain;
+    if (recipe.kind === bundledHtmlRecipe.kind)
+        return recipe.backend === null
+            ? bundledHtmlRecipe.toolchain
+            : { ...bundledHtmlRecipe.toolchain, ...esmToolchain, pnpm: "11.24.0" };
+    if (recipe.entry.endsWith(".html"))
+        return recipe.backend === null
+            ? workspaceHtmlToolchain
+            : workspaceHtmlBackendToolchain;
+    return esmToolchain;
+}
+/**
+ * Whether a pinned recipe pins this Publisher's current toolchain (its build
+ * policy included). An executor refuses any other: a recipe pinned under
+ * another policy describes a build this code does not perform.
+ */
+export function pinsCurrentToolchain(recipe) {
+    const entries = (toolchain) => JSON.stringify(Object.entries(toolchain).sort(([a], [b]) => a.localeCompare(b)));
+    return entries(currentToolchain(recipe)) === entries(recipe.toolchain);
+}
 function captureConfig(input) {
     let decoded;
     try {
@@ -148,17 +172,7 @@ function captureConfig(input) {
             : workspaceHtml
                 ? "html"
                 : "esm",
-        toolchain: sourceHtml
-            ? sourceHtmlToolchain
-            : bundled
-                ? decoded.recipe.backend === null
-                    ? bundledHtmlRecipe.toolchain
-                    : { ...bundledHtmlRecipe.toolchain, ...esmToolchain, pnpm: "11.24.0" }
-                : workspaceHtml
-                    ? decoded.recipe.backend === null
-                        ? workspaceHtmlToolchain
-                        : workspaceHtmlBackendToolchain
-                    : esmToolchain,
+        toolchain: currentToolchain(decoded.recipe),
         maxOutputBytes: decoded.recipe.maxOutputBytes,
         platform: decoded.recipe.backend === null
             ? "browser"
@@ -303,6 +317,32 @@ function encodeBackendOutput(bytes, recipe) {
         code: new TextDecoder().decode(bytes),
     }).pipe(Effect.map((encoded) => new TextEncoder().encode(encoded)), Effect.filterOrFail((encoded) => encoded.byteLength <= recipe.maxOutputBytes, () => stageFailure("build")), Effect.mapError(() => stageFailure("build")));
 }
+/**
+ * The largest single object a build under this recipe may upload: no larger
+ * than the largest output bound the recipe could assign it under.
+ */
+export function pinnedRecipeObjectBound(recipe) {
+    return Math.max(recipe.maxOutputBytes, recipe.assets?.maxObjectBytes ?? 0);
+}
+/**
+ * Whether output built elsewhere (a Computer's candidate manifest) is one
+ * this recipe could assign: the same surfaces and `maxOutputBytes` bound the
+ * preparer applies here. Asset sizes stay the artifact writer's policy.
+ */
+export function fitsPinnedRecipe(output, recipe) {
+    const uiFits = (ui) => ui.content.kind === "html"
+        ? ui.content.byteLength <= recipe.maxOutputBytes
+        : recipe.assets !== undefined && ui.content.base === recipe.assetBase;
+    const backendFits = (backend) => recipe.backend !== null && backend.byteLength <= recipe.maxOutputBytes;
+    switch (output.kind) {
+        case "ui":
+            return recipe.backend === null && uiFits(output.ui);
+        case "backend":
+            return backendFits(output.backend);
+        case "app":
+            return uiFits(output.ui) && backendFits(output.backend);
+    }
+}
 function assignAppOutput(built, recipe) {
     switch (built.kind) {
         case "bytes":

package/dist/build/git-environment.d.ts

@@ -1,5 +1,8 @@
 /** Run a nested repository without inheriting the caller's Git checkout. */
 export declare function repositoryEnvironment(): NodeJS.ProcessEnv;
+/** Git environment carrying host-held request headers (credentials) only in
+ * Git's own config environment: never argv, a URL or a trace. */
+export declare function authenticatedGitEnvironment(headers: Readonly<Record<string, string>>): NodeJS.ProcessEnv;
 /** Git environment for one authenticated Artifacts fetch; caller validates token. */
 export declare function artifactsGitEnvironment(token: string): NodeJS.ProcessEnv;
 /** Credential-free private route used by the hosted Publisher Git client. */

package/dist/build/git-environment.js

@@ -2,8 +2,9 @@
 export function repositoryEnvironment() {
     return Object.fromEntries(Object.entries(process.env).filter(([name]) => !name.startsWith("GIT_")));
 }
-/** Git environment for one authenticated Artifacts fetch; caller validates token. */
-export function artifactsGitEnvironment(token) {
+/** Git environment carrying host-held request headers (credentials) only in
+ * Git's own config environment: never argv, a URL or a trace. */
+export function authenticatedGitEnvironment(headers) {
     const excludedEnvironmentNames = new Set([
         "GIT_CURL_VERBOSE",
         "CLOUDFLARE_API_TOKEN",
@@ -12,19 +13,30 @@ export function artifactsGitEnvironment(token) {
         "ARTIFACTS_TOKEN",
     ]);
     const environment = Object.fromEntries(Object.entries(repositoryEnvironment()).filter(([name]) => !name.startsWith("GIT_TRACE") && !excludedEnvironmentNames.has(name)));
+    for (const [name, value] of Object.entries(headers))
+        if (!/^[A-Za-z0-9-]+$/u.test(name) || /[\r\n\0]/u.test(value))
+            throw new Error("Git request header is invalid");
+    // An empty first value resets any inherited extra headers.
+    const config = [
+        ["http.extraHeader", ""],
+        ...Object.entries(headers).map(([name, value]) => ["http.extraHeader", `${name}: ${value}`]),
+        ["http.followRedirects", "false"],
+    ];
     return {
         ...environment,
-        GIT_CONFIG_KEY_0: "http.extraHeader",
-        GIT_CONFIG_VALUE_0: "",
-        GIT_CONFIG_KEY_1: "http.extraHeader",
-        GIT_CONFIG_VALUE_1: `Authorization: Bearer ${token}`,
-        GIT_CONFIG_KEY_2: "http.followRedirects",
-        GIT_CONFIG_VALUE_2: "false",
-        GIT_CONFIG_COUNT: "3",
+        ...Object.fromEntries(config.flatMap(([key, value], index) => [
+            [`GIT_CONFIG_KEY_${String(index)}`, key],
+            [`GIT_CONFIG_VALUE_${String(index)}`, value],
+        ])),
+        GIT_CONFIG_COUNT: String(config.length),
         GIT_TRACE: "0",
         GIT_TRACE_CURL: "0",
     };
 }
+/** Git environment for one authenticated Artifacts fetch; caller validates token. */
+export function artifactsGitEnvironment(token) {
+    return authenticatedGitEnvironment({ Authorization: `Bearer ${token}` });
+}
 /** Credential-free private route used by the hosted Publisher Git client. */
 export function hostedArtifactsGitRemote(endpoint, repository) {
     if (!/^[a-zA-Z0-9._-]{1,128}$/.test(repository))

package/dist/build/local-build.d.ts

@@ -40,12 +40,22 @@ export declare function createFirstPartyAppSourceDistribution(options: {
     readonly source: CapturedSource;
     readonly entry: string;
 }): Effect.Effect<FirstPartyAppSourceDistribution, unknown>;
+/** How one build executor is composed; never part of a recipe or request. */
+export type LocalBuildExecutorOptions = Readonly<{
+    packageStoreDirectory?: string;
+    /**
+     * `run` executes a dependency's declared `fungi.build.script`. Only the
+     * admitted Computer build sets it; every other composition refuses a source
+     * that declares one, before installing anything.
+     */
+    packageScripts?: "run";
+    /** Hears how long the dependency install and the compile each took. */
+    onPhase?: (phase: "install" | "build", milliseconds: number) => void;
+}>;
 /** Exact pinned esbuild options shared by local builds and artifact-budget proofs. */
 export declare function localSnapshotBuildOptions(source: CapturedSource, recipe: PinnedRecipe, emission: DefinitionEmission): esbuild.BuildOptions;
 /** Local proving adapter; it builds only the captured extracted snapshot. */
-export declare function createLocalBuildExecutor(options?: Readonly<{
-    packageStoreDirectory?: string;
-}>): BuildExecutor;
+export declare function createLocalBuildExecutor(options?: LocalBuildExecutorOptions): BuildExecutor;
 /** Local proving adapter; the configured root is private and write-once. */
 export declare function createLocalArtifactWriter(artifactRoot: string, assetPolicy?: AssetBuildPolicy): ArtifactWriter;
 /** Local Git, recipe and artifact directory configuration with a Release catalog. */