@fungi.computer/oyster 0.0.1 → 0.2.0

package/dist/build/candidate-builder.d.ts

@@ -0,0 +1,68 @@
+import * as Schema from "effect/Schema";
+export declare class TeamCandidateBuildError extends Error {
+    readonly code: "invalid_recipe" | "output_limit" | "report_failed";
+    constructor(code: "invalid_recipe" | "output_limit" | "report_failed");
+}
+export declare const teamCandidateConfigurationSchema: Schema.Struct<{
+    /** The build policy the host expects; a builder that predates it refuses
+     * the request, and this one refuses any other. */
+    readonly buildPolicy: Schema.Literal<"package-json-fungi-build-v2">;
+    readonly appId: Schema.refine<import("@fungi.computer/puffball").AppId, Schema.String>;
+    readonly sourceRevision: Schema.refine<import("@fungi.computer/puffball").SourceRevision, Schema.String>;
+    readonly recipe: Schema.Struct<{
+        readonly kind: Schema.optional<Schema.Literals<readonly ["bundled-html", "source-html"]>>;
+        readonly bundle: Schema.Literal<true>;
+        readonly entry: Schema.String;
+        readonly format: Schema.Literals<readonly ["html", "esm", "assets"]>;
+        readonly assets: Schema.optional<Schema.Struct<{
+            readonly maxManifestBytes: Schema.Number;
+            readonly maxObjects: Schema.Number;
+            readonly maxObjectBytes: Schema.Number;
+            readonly maxTotalBytes: Schema.Number;
+        }>>;
+        readonly assetBase: Schema.optionalKey<Schema.String>;
+        readonly toolchain: Schema.$Record<Schema.String, Schema.String>;
+        readonly maxOutputBytes: Schema.Number;
+        readonly platform: Schema.Literals<readonly ["browser", "neutral"]>;
+        readonly backend: Schema.Union<readonly [Schema.Null, Schema.Struct<{
+            readonly entry: Schema.optional<Schema.String>;
+            readonly runtime: Schema.Struct<{
+                readonly kind: Schema.Literal<"durable-facet">;
+                readonly stateSchema: Schema.Number;
+            }>;
+            readonly compatibilityDate: Schema.String;
+            readonly exportName: Schema.String;
+        }>]>;
+        readonly target: Schema.Tuple<readonly [Schema.Literal<"es2022">]>;
+    }>;
+    readonly buildRecipeDigest: Schema.refine<import("@fungi.computer/puffball").Sha256Digest, Schema.String>;
+}>;
+/** Where a built candidate's manifest and its objects are written. */
+export declare function teamCandidateLayout(outputPath: string): {
+    manifest: string;
+    object: (digest: string) => string;
+};
+/**
+ * Runs inside the admitted Computer, using Oyster's captured builder.
+ * This is the one composition that runs a dependency's declared package
+ * build script; its executor refuses a recipe pinned under another policy.
+ * It writes a new directory: each built object under its digest, and the
+ * small manifest that names them, ready to upload one at a time.
+ */
+export declare function buildTeamCandidate(input: {
+    configuration: unknown;
+    repositoryPath: string;
+    /** A directory this build creates; it must not exist yet. */
+    outputPath: string;
+    /** Trusted Computer-local cache; never part of customer configuration. */
+    packageStoreDirectory?: string;
+}): Promise<Readonly<{
+    digest: string;
+    bytes: number;
+    /** Milliseconds: capturing the cloned source, installing, compiling. */
+    phases: Readonly<{
+        capture: number;
+        install: number;
+        build: number;
+    }>;
+}>>;

package/dist/build/candidate-builder.js

@@ -0,0 +1,91 @@
+import { createHash } from "node:crypto";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { appIdSchema, sourceRevisionSchema, sha256DigestSchema, } from "@fungi.computer/puffball/effect";
+import { parseReleaseId } from "@fungi.computer/puffball";
+import { capturedPinnedRecipeSchema, createCapturedCandidatePreparer, digestPinnedRecipe, encodeTeamAppCandidateManifest, TEAM_APP_CANDIDATE_MANIFEST_MAX_BYTES, workspaceBuildPolicy, } from "../build-contract.js";
+import { createLocalCommitSourceCapture, createLocalBuildExecutor, stageBuildOutput, } from "../build.js";
+export class TeamCandidateBuildError extends Error {
+    code;
+    constructor(code) {
+        super(`Team candidate ${code}`);
+        this.code = code;
+        this.name = "TeamCandidateBuildError";
+    }
+}
+export const teamCandidateConfigurationSchema = Schema.Struct({
+    /** The build policy the host expects; a builder that predates it refuses
+     * the request, and this one refuses any other. */
+    buildPolicy: Schema.Literal(workspaceBuildPolicy),
+    appId: appIdSchema,
+    sourceRevision: sourceRevisionSchema,
+    recipe: capturedPinnedRecipeSchema,
+    buildRecipeDigest: sha256DigestSchema,
+});
+/** Where a built candidate's manifest and its objects are written. */
+export function teamCandidateLayout(outputPath) {
+    return {
+        manifest: join(outputPath, "manifest.json"),
+        object: (digest) => join(outputPath, "objects", digest.replace(":", "-")),
+    };
+}
+/**
+ * Runs inside the admitted Computer, using Oyster's captured builder.
+ * This is the one composition that runs a dependency's declared package
+ * build script; its executor refuses a recipe pinned under another policy.
+ * It writes a new directory: each built object under its digest, and the
+ * small manifest that names them, ready to upload one at a time.
+ */
+export async function buildTeamCandidate(input) {
+    const config = Schema.decodeUnknownSync(teamCandidateConfigurationSchema, {
+        onExcessProperty: "error",
+    })(input.configuration);
+    if (digestPinnedRecipe(config.recipe) !== config.buildRecipeDigest)
+        throw new TeamCandidateBuildError("invalid_recipe");
+    const phases = { install: 0, build: 0 };
+    const onPhase = (phase, milliseconds) => {
+        phases[phase] += milliseconds;
+    };
+    const prepareStarted = performance.now();
+    const candidate = await Effect.runPromise(createCapturedCandidatePreparer(config, {
+        sourceCapture: createLocalCommitSourceCapture(input.repositoryPath, config.sourceRevision),
+        buildExecutor: createLocalBuildExecutor(input.packageStoreDirectory === undefined
+            ? { packageScripts: "run", onPhase }
+            : {
+                packageScripts: "run",
+                packageStoreDirectory: input.packageStoreDirectory,
+                onPhase,
+            }),
+    }).prepareCandidate(parseReleaseId("rel_build")));
+    const prepared = performance.now() - prepareStarted;
+    const staged = stageBuildOutput(candidate.output);
+    const bytes = Buffer.from(encodeTeamAppCandidateManifest({
+        appId: candidate.appId,
+        output: staged.manifest,
+        provenance: candidate.provenance,
+    }));
+    if (bytes.byteLength > TEAM_APP_CANDIDATE_MANIFEST_MAX_BYTES)
+        throw new TeamCandidateBuildError("output_limit");
+    const layout = teamCandidateLayout(input.outputPath);
+    // A new directory: an earlier build's output is never mixed in.
+    await mkdir(input.outputPath, { mode: 0o700 });
+    await mkdir(join(input.outputPath, "objects"), { mode: 0o700 });
+    for (const object of staged.objects)
+        await writeFile(layout.object(object.digest), object.bytes, {
+            flag: "wx",
+            mode: 0o600,
+        });
+    await writeFile(layout.manifest, bytes, { flag: "wx", mode: 0o600 });
+    return {
+        digest: `sha256:${createHash("sha256").update(bytes).digest("hex")}`,
+        bytes: bytes.byteLength,
+        phases: {
+            // Snapshot capture and staging: everything but the install and compile.
+            capture: Math.max(0, prepared - phases.install - phases.build),
+            install: phases.install,
+            build: phases.build,
+        },
+    };
+}

package/dist/build/candidate-cli.d.ts

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

package/dist/build/candidate-cli.js

@@ -0,0 +1,119 @@
+import * as Schema from "effect/Schema";
+import { releaseSchema } from "@fungi.computer/puffball/effect";
+import { readFile } from "node:fs/promises";
+import { candidateManifestObjects, teamAppCandidateManifestSchema, } from "../build-contract.js";
+import { buildTeamCandidate, teamCandidateConfigurationSchema, teamCandidateLayout, TeamCandidateBuildError, } from "./candidate-builder.js";
+/** Objects in flight at once; each is read from disk only while it uploads. */
+const uploadConcurrency = 4;
+/** Attempts per object when its connection drops before a response. */
+const uploadAttempts = 3;
+/** Report a failed build to the host's build output: its kind, never its text. */
+function reportFailure(cause) {
+    process.stderr.write(`${JSON.stringify({
+        source: "oyster-candidate-builder",
+        failureKind: cause instanceof Error ? "Error" : "NonErrorThrown",
+    })}\n`);
+}
+const [configuration, repositoryPath, outputPath] = process.argv.slice(2);
+if (!configuration || !repositoryPath || !outputPath)
+    throw new Error("Usage: team-candidate-builder CONFIG_BASE64 REPOSITORY OUTPUT_DIRECTORY");
+try {
+    const { uploadGrant, ...config } = Schema.decodeUnknownSync(Schema.Struct({
+        ...teamCandidateConfigurationSchema.fields,
+        uploadGrant: Schema.String,
+    }), { onExcessProperty: "error" })(JSON.parse(Buffer.from(configuration, "base64url").toString("utf8")));
+    const { phases, ...artifact } = await buildTeamCandidate({
+        configuration: config,
+        repositoryPath,
+        outputPath,
+        // Computer scratch survives captured snapshot cleanup, without a global or durable Workspace store.
+        packageStoreDirectory: "/var/tmp/fungi-app-package-store",
+    });
+    const reportUrl = process.env.TEAM_BUILD_REPORT;
+    if (!reportUrl)
+        throw new TeamCandidateBuildError("report_failed");
+    const layout = teamCandidateLayout(outputPath);
+    const manifestBytes = await readFile(layout.manifest);
+    const manifest = Schema.decodeUnknownSync(Schema.fromJsonString(teamAppCandidateManifestSchema))(new TextDecoder().decode(manifestBytes));
+    // Every object first, each streamed alone; the manifest only names them.
+    const uploadStarted = performance.now();
+    const pending = [...candidateManifestObjects(manifest.output)];
+    // A write-once PUT is safe to repeat, so a dropped connection is retried.
+    const put = async (object) => {
+        for (let attempt = 1;; attempt += 1) {
+            const stored = await fetch(`${reportUrl}/objects/${object.digest.replace(":", "-")}`, {
+                method: "PUT",
+                headers: {
+                    "Content-Type": object.mediaType,
+                    "X-Team-App-Build": uploadGrant,
+                },
+                body: await readFile(layout.object(object.digest)),
+            }).catch((cause) => {
+                if (attempt >= uploadAttempts)
+                    throw cause;
+                return null;
+            });
+            await stored?.body?.cancel();
+            if (stored?.ok)
+                return;
+            if (stored !== null || attempt >= uploadAttempts)
+                throw new TeamCandidateBuildError("report_failed");
+        }
+    };
+    const upload = async () => {
+        for (let object = pending.shift(); object; object = pending.shift())
+            await put(object);
+    };
+    await Promise.all(Array.from({ length: uploadConcurrency }, upload));
+    const candidate = await fetch(`${reportUrl}/candidate`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "X-Team-App-Build": uploadGrant,
+        },
+        body: manifestBytes,
+    });
+    if (!candidate.ok)
+        throw new TeamCandidateBuildError("report_failed");
+    const receipt = Schema.decodeUnknownSync(Schema.Struct({
+        kind: Schema.Literal("submitted"),
+        release: releaseSchema,
+    }))(await candidate.json());
+    const recorded = await fetch(`${reportUrl}/artifact`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(artifact),
+    });
+    if (!recorded.ok)
+        throw new TeamCandidateBuildError("report_failed");
+    await recorded.body?.cancel();
+    const uploaded = performance.now() - uploadStarted;
+    // The success detail reports where the build's time went; the owner reads
+    // it with the build. The clone ran before this program (TEAM_BUILD_CLONE_MS).
+    const cloned = Number(process.env.TEAM_BUILD_CLONE_MS ?? "0");
+    const status = await fetch(`${reportUrl}/status`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            status: "succeeded",
+            detail: JSON.stringify({
+                phasesMs: {
+                    clone: Math.round((Number.isFinite(cloned) ? cloned : 0) + phases.capture),
+                    install: Math.round(phases.install),
+                    build: Math.round(phases.build),
+                    upload: Math.round(uploaded),
+                },
+            }),
+        }),
+    });
+    if (!status.ok)
+        throw new TeamCandidateBuildError("report_failed");
+    await status.body?.cancel();
+    process.stdout.write(JSON.stringify({ ...artifact, release: receipt.release }));
+}
+catch (cause) {
+    reportFailure(cause);
+    // Customer source and provider messages can contain secrets; only expose the stage.
+    process.stderr.write("Team App source/build failed\n");
+    process.exitCode = 1;
+}