@orchestraworks/cli 0.5.5 → 0.5.7

package/dist/cli/factory/image-upload.js

@@ -0,0 +1,489 @@
+// Apply's hosted-image phase: a declared image whose tag has no registry path is built into an OCI layout,
+// its manifest is offered to `POST /images`, the blobs the platform does not hold go up through the File
+// API, and apply waits until the platform has copied the image before an environment may name it.
+//
+// Two rules here are not style. The build runs on the `orchestra-oci` builder, created when absent and never made
+// the default, because the default `docker` driver cannot export an OCI layout. And each image reaches
+// `READY` before the next one builds, so a failure names one image and leaves the later ones untouched.
+import { createHash } from "node:crypto";
+import { existsSync, mkdtempSync, readFileSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { hostedImageName, isHostedImageTag } from "../../constructs/references.js";
+import { httpStatusOf } from "../../engine/client.js";
+import { readApiError } from "../core/errors.js";
+import { objectStoreFetch } from "../core/platform-client.js";
+import { uploadFile } from "../upload.js";
+import { imageBuildSpecs } from "./docker.js";
+export const OCI_BUILDER = "orchestra-oci";
+export const HOSTED_PLATFORM = "linux/amd64";
+export const POLL_INTERVAL_MS = 5_000;
+export const POLL_TIMEOUT_MS = 30 * 60_000;
+const BLOBS_MISSING = "IMAGE_BLOBS_MISSING";
+const QUOTA_EXCEEDED = "QUOTA_EXCEEDED";
+const IMAGE_COUNT_DIMENSION = "IMAGES";
+const LIST_PAGE_SIZE = 100;
+/** Carries the images already `READY`, so the abort message says what landed. */
+export class ImageUploadError extends Error {
+    ready;
+    constructor(message, ready = []) {
+        super(ready.length > 0 ? `${message} Already READY: [${ready.join(", ")}].` : message);
+        this.ready = ready;
+        this.name = "ImageUploadError";
+    }
+}
+export function hostedSpecs(specs) {
+    return specs.filter((spec) => isHostedImageTag(spec.ref));
+}
+export async function readHostedImages(images, names) {
+    const wanted = new Set(names);
+    const newestReady = new Map();
+    try {
+        for (let page = 0;; page += 1) {
+            const listed = await images.listImages({
+                name: [...wanted],
+                status: ["READY"],
+                page,
+                limit: LIST_PAGE_SIZE,
+            });
+            // The platform lists newest first, so the first unmarked row of a name is its newest. A marked image is
+            // being deleted, and an environment naming it would fail at reconcile.
+            for (const image of listed.data) {
+                if (image.deleteRequestedAt === undefined && !newestReady.has(image.name))
+                    newestReady.set(image.name, image);
+            }
+            const done = [...wanted].every((name) => newestReady.has(name));
+            if (done || listed.data.length === 0 || (page + 1) * listed.limit >= listed.total)
+                break;
+        }
+    }
+    catch (error) {
+        const status = httpStatusOf(error);
+        const api = await readApiError(error);
+        if (status === 501) {
+            return { available: false, message: api?.message ?? "this platform keeps no images" };
+        }
+        throw new ImageUploadError(`cannot read the platform's images: ${describeFailure(status, api, error)}`);
+    }
+    return { available: true, newestReady };
+}
+/** The reference of the newest `READY` image for each hosted tag that has one, keyed by tag. */
+function readyReferences(specs, hosted) {
+    const pins = new Map();
+    if (!hosted.available)
+        return pins;
+    for (const spec of hostedSpecs(specs)) {
+        const ready = hosted.newestReady.get(hostedImageName(spec.ref));
+        if (ready !== undefined)
+            pins.set(spec.ref, ready.reference);
+    }
+    return pins;
+}
+/** A copy of the plan whose environments name the image reference in place of each pinned tag. */
+export function pinHostedReferences(plan, pins) {
+    if (pins.size === 0)
+        return plan;
+    const pinned = structuredClone(plan);
+    for (const resource of pinned.resources) {
+        if (resource.kind !== "environment")
+            continue;
+        const spec = resource.payload.provisionSpec;
+        if (spec === undefined || typeof spec.image !== "string")
+            continue;
+        const reference = pins.get(spec.image);
+        if (reference !== undefined)
+            spec.image = reference;
+    }
+    return pinned;
+}
+/** Reads `/images` once when the plan declares a hosted image, and pins each tag to its newest READY image. */
+export async function pinNewestReadyImages(plan, images) {
+    const declared = hostedSpecs(imageBuildSpecs(plan));
+    if (declared.length === 0)
+        return { declared, pins: new Map(), plan };
+    const hosted = await readHostedImages(images, declared.map((spec) => hostedImageName(spec.ref)));
+    const pins = readyReferences(declared, hosted);
+    return { declared, hosted, pins, plan: pinHostedReferences(plan, pins) };
+}
+/** Every refusal that needs no write: the declared platform, buildx, and a builder that starts. */
+export async function prepareOciBuilder(specs, runner) {
+    for (const spec of specs) {
+        if (spec.platform !== undefined && spec.platform !== HOSTED_PLATFORM) {
+            throw new ImageUploadError(`image '${spec.ref}' declares the platform '${spec.platform}', and the platform keeps only ` +
+                `${HOSTED_PLATFORM} images. Remove the platform, or set it to ${HOSTED_PLATFORM}.`);
+        }
+    }
+    const buildx = await runner.run(["buildx", "version"]);
+    if (buildx.code !== 0) {
+        throw new ImageUploadError(`docker buildx is not available (${lastLine(buildx.output)}). Install the Docker buildx plugin, or pass ` +
+            `--no-docker-build to name the newest READY image of each declared image.`);
+    }
+    const existing = await runner.run(["buildx", "inspect", OCI_BUILDER]);
+    if (existing.code !== 0) {
+        const created = await runner.run(["buildx", "create", "--name", OCI_BUILDER, "--driver", "docker-container"]);
+        if (created.code !== 0) {
+            throw new ImageUploadError(`cannot create the '${OCI_BUILDER}' buildx builder: ${lastLine(created.output)}`);
+        }
+    }
+    const started = await runner.run(["buildx", "inspect", "--bootstrap", OCI_BUILDER]);
+    if (started.code !== 0) {
+        throw new ImageUploadError(`the '${OCI_BUILDER}' buildx builder cannot start: ${lastLine(started.output)}. Start Docker, or pass ` +
+            `--no-docker-build to name the newest READY image of each declared image.`);
+    }
+}
+/** Paths resolve against the factory directory; values are data, never shell. */
+export function ociBuildArgv(spec, appDir, layoutDir) {
+    const argv = [
+        "buildx",
+        "build",
+        "--builder",
+        OCI_BUILDER,
+        "--platform",
+        HOSTED_PLATFORM,
+        "--provenance=false",
+        "--sbom=false",
+        "--output",
+        `type=oci,dest=${layoutDir},tar=false`,
+        "-f",
+        resolve(appDir, spec.dockerfile),
+    ];
+    for (const [key, value] of Object.entries(spec.buildArgs)) {
+        argv.push("--build-arg", `${key}=${value}`);
+    }
+    argv.push(resolve(appDir, spec.context));
+    return argv;
+}
+/**
+ * Builds, uploads and waits for each image in order; answers each tag's image reference. The Files uploaded
+ * for the `READY` images are deleted once, after the last image, so a later image may still use an earlier
+ * one's File as a held blob; they are deleted when a later image stops the run too.
+ */
+export async function uploadHostedImages(specs, appDir, deps) {
+    const references = new Map();
+    const uploaded = [];
+    try {
+        for (const spec of specs) {
+            const landed = await uploadOne(spec, appDir, deps);
+            references.set(spec.ref, landed.reference);
+            uploaded.push(landed.uploaded);
+        }
+    }
+    catch (error) {
+        await deleteUploadedFiles(uploaded, deps);
+        throw new ImageUploadError(error instanceof Error ? error.message : String(error), [...references.keys()]);
+    }
+    await deleteUploadedFiles(uploaded, deps);
+    return references;
+}
+async function uploadOne(spec, appDir, deps) {
+    const { runner, io } = deps;
+    const name = hostedImageName(spec.ref);
+    const work = mkdtempSync(join(deps.tempDir ?? tmpdir(), "orchestra-image-"));
+    try {
+        const layoutDir = join(work, "layout");
+        io.out(`Building ${spec.ref} for ${HOSTED_PLATFORM} with the '${OCI_BUILDER}' builder...`);
+        const build = await runner.run(ociBuildArgv(spec, appDir, layoutDir), { stream: true });
+        if (build.code !== 0)
+            throw await buildFailure(spec, build, runner);
+        const layout = readOciLayout(layoutDir);
+        const { image: created, uploaded } = await createImage(name, layout, deps);
+        const ready = await waitUntilReady(created, uploaded, deps);
+        io.out(`Image '${name}' is READY: ${ready.reference}`);
+        return { reference: ready.reference, uploaded: { name, fileIds: uploaded } };
+    }
+    finally {
+        rmSync(work, { recursive: true, force: true });
+    }
+}
+async function deleteUploadedFiles(uploaded, deps) {
+    for (const { name, fileIds } of uploaded) {
+        for (const id of fileIds) {
+            try {
+                await deps.files.deleteFile({ id });
+            }
+            catch (error) {
+                deps.io.err(`warning: image '${name}' is READY, but the File ${id} uploaded for it was not deleted: ` +
+                    `${describeFailure(httpStatusOf(error), await readApiError(error), error)}. ` +
+                    `Run 'orchestra files delete ${id}' to delete it.`);
+            }
+        }
+    }
+}
+/** The images a hosted build names: each build argument's value, and each `FROM` that is not an earlier stage. */
+export function imagesNamedBy(spec, appDir) {
+    const named = Object.entries(spec.buildArgs).map(([key, value]) => ({
+        ref: value,
+        how: `takes the build argument ${key} naming`,
+    }));
+    let text;
+    try {
+        text = readFileSync(resolve(appDir, spec.dockerfile), "utf8");
+    }
+    catch {
+        return named;
+    }
+    const argDefaults = new Map();
+    const stages = new Set();
+    for (const line of dockerfileInstructions(text)) {
+        const arg = /^ARG\s+([A-Za-z_][A-Za-z0-9_]*)=(\S+)/i.exec(line);
+        if (arg !== null) {
+            if (!argDefaults.has(arg[1]))
+                argDefaults.set(arg[1], unquote(arg[2]));
+            continue;
+        }
+        const from = /^FROM\s+(.*)$/i.exec(line);
+        if (from === null)
+            continue;
+        const words = from[1].split(/\s+/).filter((word) => word !== "" && !word.startsWith("--"));
+        if (words.length === 0)
+            continue;
+        const image = words[0].replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g, (_match, braced, bare) => {
+            const key = braced ?? bare ?? "";
+            return spec.buildArgs[key] ?? argDefaults.get(key) ?? "";
+        });
+        if (!stages.has(image))
+            named.push({ ref: image, how: "is built FROM" });
+        if (words.length >= 3 && words[1].toLowerCase() === "as")
+            stages.add(words[2]);
+    }
+    return named;
+}
+/** Joins `\` continuations and drops comment lines, so each entry is one instruction. */
+function dockerfileInstructions(text) {
+    const instructions = [];
+    let pending = "";
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (line.startsWith("#"))
+            continue;
+        if (line.endsWith("\\")) {
+            pending += `${line.slice(0, -1)} `;
+            continue;
+        }
+        instructions.push(`${pending}${line}`.trim());
+        pending = "";
+    }
+    if (pending !== "")
+        instructions.push(pending.trim());
+    return instructions;
+}
+function unquote(value) {
+    return value.replace(/^(["'])(.*)\1$/, "$2");
+}
+const UNRESOLVED_BASE = /failed to resolve source metadata for (\S+): /;
+/** A base the registry does not have but the local store does is the one failure the author can act on by name. */
+async function buildFailure(spec, build, runner) {
+    const base = UNRESOLVED_BASE.exec(build.output)?.[1];
+    if (base !== undefined) {
+        const short = base.replace(/^docker\.io\/library\//, "");
+        for (const candidate of new Set([base, short])) {
+            const local = await runner.run(["image", "inspect", candidate]);
+            if (local.code === 0) {
+                return new ImageUploadError(`image '${spec.ref}' is built FROM '${short}', which is only in this machine's Docker image store. The ` +
+                    `'${OCI_BUILDER}' builder pulls every base from a registry: push '${short}' to a registry and name it ` +
+                    `there in FROM.`);
+            }
+        }
+    }
+    return new ImageUploadError(`docker buildx build failed for declared image '${spec.ref}' (exit ${build.code}).`);
+}
+const IMAGE_MANIFEST_TYPES = new Set([
+    "application/vnd.oci.image.manifest.v1+json",
+    "application/vnd.docker.distribution.manifest.v2+json",
+]);
+const IMAGE_INDEX_TYPES = new Set([
+    "application/vnd.oci.image.index.v1+json",
+    "application/vnd.docker.distribution.manifest.list.v2+json",
+]);
+/** Bounds a JSON document read whole from the layout; the platform takes a manifest of at most 256 KiB. */
+const MAX_JSON_BYTES = 4 * 1024 * 1024;
+export function readOciLayout(dir) {
+    const index = readJson(dir, "index.json");
+    const chosen = chooseManifest(dir, index.manifests ?? [], 0);
+    if (chosen === undefined) {
+        throw new ImageUploadError(`the build wrote no ${HOSTED_PLATFORM} image manifest to its OCI layout.`);
+    }
+    const bytes = readSmall(dir, blobPath(chosen.digest));
+    if (`sha256:${createHash("sha256").update(bytes).digest("hex")}` !== chosen.digest) {
+        throw new ImageUploadError(`the OCI layout's manifest does not hash to ${chosen.digest}.`);
+    }
+    const manifest = bytes.toString("utf8");
+    const parsed = JSON.parse(manifest);
+    const blobs = new Map();
+    for (const blob of [...(parsed.config !== undefined ? [parsed.config] : []), ...(parsed.layers ?? [])]) {
+        blobs.set(blob.digest, blob);
+    }
+    return { dir, manifest, digest: chosen.digest, blobs };
+}
+function chooseManifest(dir, descriptors, depth) {
+    const images = descriptors.filter((d) => (d.mediaType === undefined || IMAGE_MANIFEST_TYPES.has(d.mediaType)) &&
+        d.annotations?.["vnd.docker.reference.type"] !== "attestation-manifest");
+    const matches = (d) => d.platform?.os === "linux" && d.platform?.architecture === "amd64";
+    const explicit = images.find(matches);
+    if (explicit !== undefined)
+        return explicit;
+    const unlabelled = images.filter((d) => d.platform === undefined);
+    if (unlabelled.length === 1 && images.length === 1)
+        return unlabelled[0];
+    if (depth >= 2)
+        return undefined;
+    for (const nested of descriptors.filter((d) => d.mediaType !== undefined && IMAGE_INDEX_TYPES.has(d.mediaType))) {
+        const inner = readJson(dir, blobPath(nested.digest));
+        const found = chooseManifest(dir, inner.manifests ?? [], depth + 1);
+        if (found !== undefined)
+            return found;
+    }
+    return undefined;
+}
+function blobPath(digest) {
+    const [algorithm, hex] = digest.split(":");
+    return `blobs/${algorithm}/${hex}`;
+}
+function readSmall(dir, name) {
+    const path = join(dir, name);
+    if (!existsSync(path)) {
+        throw new ImageUploadError(`the build's OCI layout holds no ${name}.`);
+    }
+    const size = statSync(path).size;
+    if (size > MAX_JSON_BYTES) {
+        throw new ImageUploadError(`the build's OCI layout holds a ${size}-byte ${name}, too large to read.`);
+    }
+    return readFileSync(path);
+}
+function readJson(dir, name) {
+    const bytes = readSmall(dir, name);
+    try {
+        return JSON.parse(bytes.toString("utf8"));
+    }
+    catch {
+        throw new ImageUploadError(`the build's OCI layout holds a ${name} that is not JSON.`);
+    }
+}
+async function createImage(name, layout, deps) {
+    const uploaded = [];
+    for (let attempt = 1;; attempt += 1) {
+        let missing;
+        try {
+            const image = await deps.images.createImage({ createImageRequest: { name, manifest: layout.manifest } });
+            return { image, uploaded };
+        }
+        catch (error) {
+            const api = await readApiError(error);
+            if (api?.code !== BLOBS_MISSING || attempt !== 1) {
+                throw keepingFiles(createFailure(name, layout, httpStatusOf(error), api, error), name, uploaded);
+            }
+            missing = missingDigestsOf(api);
+        }
+        try {
+            await uploadBlobs(name, missing, layout, deps, uploaded);
+        }
+        catch (error) {
+            throw keepingFiles(error, name, uploaded);
+        }
+    }
+}
+/** A failure after the first upload names the Files this run stored, which nothing else deletes. */
+function keepingFiles(error, name, uploaded) {
+    const message = error instanceof Error ? error.message : String(error);
+    return new ImageUploadError(`${message}${keptFilesNote(name, uploaded)}`);
+}
+function missingDigestsOf(api) {
+    const listed = api.details?.missingDigests;
+    return Array.isArray(listed) ? listed.filter((digest) => typeof digest === "string") : [];
+}
+/**
+ * Adds to `created` the id of each File this call stores as it stores it, so a failure partway still knows
+ * them; a File that already held the bytes is left out.
+ */
+async function uploadBlobs(name, digests, layout, deps, created) {
+    deps.io.out(`Uploading ${digests.length} blob(s) of image '${name}' that the platform does not hold...`);
+    for (const digest of digests) {
+        const descriptor = layout.blobs.get(digest);
+        const path = join(layout.dir, blobPath(digest));
+        if (descriptor === undefined || !existsSync(path)) {
+            throw new ImageUploadError(`the platform asked for blob ${digest} of image '${name}', which its OCI layout does not hold.`);
+        }
+        try {
+            const stored = await uploadFile(path, {
+                apis: { files: deps.files },
+                fetchApi: objectStoreFetch(deps.fetchApi),
+                io: deps.io,
+                filename: digest.replace(":", "-"),
+                ...(descriptor.mediaType !== undefined ? { contentType: descriptor.mediaType } : {}),
+            });
+            if (!stored.alreadyStored)
+                created.push(stored.fileId);
+        }
+        catch (error) {
+            const api = await readApiError(error);
+            throw new ImageUploadError(`blob ${digest} of image '${name}' (${descriptor.size} bytes) was not uploaded: ` +
+                `${api?.message ?? error.message}`);
+        }
+    }
+}
+function createFailure(name, layout, status, api, error) {
+    if (api?.code === BLOBS_MISSING) {
+        return new ImageUploadError(`the platform still holds no copy of blob(s) ${missingDigestsOf(api).join(", ")} of image '${name}' ` +
+            `after the upload.`);
+    }
+    if (api?.code === QUOTA_EXCEEDED && api.details?.dimension === IMAGE_COUNT_DIMENSION) {
+        return new ImageUploadError(`image '${name}' does not fit the organization's image count: it holds ${String(api.details?.current)} ` +
+            `of the ${String(api.details?.limit)} images its images.maxCount limit allows. Delete an image, or ask ` +
+            `for a higher limit.`);
+    }
+    if (api?.code === QUOTA_EXCEEDED) {
+        const layerBytes = [...layout.blobs.values()].reduce((sum, blob) => sum + blob.size, 0);
+        return new ImageUploadError(`image '${name}' does not fit the organization's image storage: the plan allows ` +
+            `${String(api.details?.limit)} bytes, ${String(api.details?.current)} bytes are in use, and this image ` +
+            `holds ${layerBytes} bytes, of which the runtime's own layers do not count.`);
+    }
+    return new ImageUploadError(`the platform refused image '${name}': ${describeFailure(status, api, error)}`);
+}
+/**
+ * A stopped image keeps the Files this run uploaded for it: the platform deletes no File, and a later run that
+ * finds the image already copying uploads nothing, so it has no File of its own to delete. The message names them.
+ */
+async function waitUntilReady(image, uploaded, deps) {
+    const sleep = deps.sleep ?? ((ms) => new Promise((done) => setTimeout(done, ms)));
+    const now = deps.now ?? Date.now;
+    const deadline = now() + POLL_TIMEOUT_MS;
+    const kept = keptFilesNote(image.name, uploaded);
+    let current = image;
+    for (;;) {
+        if (current.status === "READY")
+            return current;
+        if (current.status === "FAILED") {
+            throw new ImageUploadError(`the platform could not copy image '${current.name}' (${current.digest}): ` +
+                `${current.failureReason ?? "no reason given"}` +
+                `${current.failureMessage !== undefined ? `: ${current.failureMessage}` : ""}.${kept}`);
+        }
+        if (now() >= deadline) {
+            throw new ImageUploadError(`image '${current.name}' (${current.digest}) is still ${current.status} after ` +
+                `${POLL_TIMEOUT_MS / 60_000} minutes. Run apply again to wait for it.${kept}`);
+        }
+        await sleep(POLL_INTERVAL_MS);
+        try {
+            current = await deps.images.getImage({ id: current.id });
+        }
+        catch (error) {
+            throw new ImageUploadError(`cannot read image '${current.name}': ` +
+                `${describeFailure(httpStatusOf(error), await readApiError(error), error)}.${kept}`);
+        }
+    }
+}
+function keptFilesNote(name, fileIds) {
+    if (fileIds.length === 0)
+        return "";
+    return (` The Files this apply uploaded for image '${name}' stay until you delete them: ${fileIds.join(", ")}. ` +
+        `Run 'orchestra files delete <id>' for each one.`);
+}
+function describeFailure(status, api, error) {
+    if (api !== undefined) {
+        return `${api.status ?? status ?? "no status"}${api.code !== undefined ? ` ${api.code}` : ""}: ${api.message}`;
+    }
+    return status !== undefined ? `HTTP ${status}` : error.message;
+}
+function lastLine(output) {
+    const lines = output.trim().split(/\r?\n/);
+    return lines[lines.length - 1] || "no output";
+}

package/dist/cli/factory/synth.d.ts

@@ -1,3 +1,4 @@
+import type { PlanDocument } from "../../core/plan.js";
 import { type CliIo } from "../core/output.js";
 /** `dir` is a test seam — commander never supplies it; it defaults to `process.cwd()`. */
 export interface SynthCommandOptions {
@@ -11,3 +12,9 @@ export interface SynthCommandOptions {
 export declare function synthCommand(options?: SynthCommandOptions, io?: CliIo): Promise<void>;
 /** A missing or invalid file reads as zero triggers, so a summary line never fails the command. */
 export declare function describeTriggers(outDir: string): string;
+/**
+ * A hosted image is built by the `orchestra-oci` builder, which pulls every base from a registry and never reads
+ * the local Docker image store, so a hosted image built on another hosted image of the same factory cannot
+ * build. An unreadable Dockerfile is left to the build to report.
+ */
+export declare function hostedImageRefusals(plan: PlanDocument, appDir: string): string[];

package/dist/cli/factory/synth.js

@@ -1,7 +1,10 @@
 // Synth is local-only and touches no platform state, so the shared auth flags are accepted but unused.
 import { existsSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { hostedImageName, isHostedImageTag } from "../../constructs/references.js";
 import { loadConfig, runFactoryForPlan } from "./config.js";
+import { imageBuildSpecs } from "./docker.js";
+import { imagesNamedBy } from "./image-upload.js";
 import { defaultIo, printWarnings } from "../core/output.js";
 /** The artifacts are written by the factory program's own beforeExit auto-synth, not by this handler. */
 export async function synthCommand(options = {}, io = defaultIo) {
@@ -9,6 +12,10 @@ export async function synthCommand(options = {}, io = defaultIo) {
     const effective = options.out !== undefined ? { ...config, outDir: options.out } : config;
     const result = await runFactoryForPlan(effective);
     printWarnings(result.warnings, io);
+    const refusals = hostedImageRefusals(result.plan, effective.cwd);
+    if (refusals.length > 0) {
+        throw new Error(refusals.join("\n"));
+    }
     const outDir = resolve(effective.cwd, effective.outDir);
     const triggerSuffix = describeTriggers(outDir);
     io.out(`Synthesized ${result.plan.resources.length} resource(s) and ${result.plan.imports.length} import(s)` +
@@ -27,3 +34,31 @@ export function describeTriggers(outDir) {
         return "";
     }
 }
+/**
+ * A hosted image is built by the `orchestra-oci` builder, which pulls every base from a registry and never reads
+ * the local Docker image store, so a hosted image built on another hosted image of the same factory cannot
+ * build. An unreadable Dockerfile is left to the build to report.
+ */
+export function hostedImageRefusals(plan, appDir) {
+    const hosted = imageBuildSpecs(plan).filter((spec) => isHostedImageTag(spec.ref));
+    const hostedByRef = new Map(hosted.map((spec) => [normalizedImageRef(spec.ref), spec.ref]));
+    const refusals = [];
+    for (const spec of hosted) {
+        for (const named of imagesNamedBy(spec, appDir)) {
+            const other = hostedByRef.get(normalizedImageRef(named.ref));
+            if (other === undefined || other === spec.ref)
+                continue;
+            refusals.push(`image '${spec.ref}' ${named.how} '${other}', another image this factory uploads as ` +
+                `'${hostedImageName(other)}'. The builder that uploads images cannot read an image that exists only ` +
+                `on this machine: build both in one Dockerfile, or give '${other}' a registry path.`);
+        }
+    }
+    return refusals;
+}
+/** Docker Hub's implicit `library/` path and `latest` tag, written out so two spellings of one image compare equal. */
+function normalizedImageRef(ref) {
+    const bare = ref.replace(/^(?:docker\.io\/)?library\//, "").replace(/^docker\.io\//, "");
+    const lastSlash = bare.lastIndexOf("/");
+    const tagged = bare.includes("@") || bare.indexOf(":", lastSlash + 1) !== -1;
+    return tagged ? bare : `${bare}:latest`;
+}

package/dist/cli/firstRun.d.ts

@@ -17,7 +17,7 @@ export type MachineRole = (typeof MACHINE_ROLES)[number];
 export declare const HARNESS_FAMILIES: readonly string[];
 /** The flags that answer the questions, alongside the sign-in's own. */
 export interface InterviewFlags extends AuthFlags {
-    project?: string;
+    team?: string;
     role?: string;
     harness?: string;
     /** commander's `--no-browser` negation, passed through to the sign-in. */
@@ -45,7 +45,7 @@ export declare class InterviewInputError extends Error {
     constructor(message: string);
 }
 /**
- * Runs the questions in the accepted order — sign in, organization and project, role, harness families —
+ * Runs the questions in the accepted order — sign in, organization and team, role, harness families —
  * and records every answer in the profile. A question whose flag is set is not asked; a question that
  * cannot be asked because there is no terminal (or because `--yes` says the flags are the whole answer) is
  * an error naming its flag, unless not naming it has a defined meaning of its own.

package/dist/cli/firstRun.js

@@ -55,7 +55,7 @@ function parseHarnesses(declared) {
         .filter((name) => name !== "");
 }
 /**
- * Runs the questions in the accepted order — sign in, organization and project, role, harness families —
+ * Runs the questions in the accepted order — sign in, organization and team, role, harness families —
  * and records every answer in the profile. A question whose flag is set is not asked; a question that
  * cannot be asked because there is no terminal (or because `--yes` says the flags are the whole answer) is
  * an error naming its flag, unless not naming it has a defined meaning of its own.
@@ -73,7 +73,7 @@ export async function runFirstRunInterview(flags, deps = {}) {
     const declaredRole = parseRole(flags.role);
     if (declaredRole !== "image") {
         await signIn(flags, { env, io, askable, loadProfile, login: deps.login ?? loginCommand }, profileName);
-        await recordProject(flags, { io, askable, ask, loadProfile, saveProfile }, profileName);
+        await recordTeam(flags, { io, askable, ask, loadProfile, saveProfile }, profileName);
     }
     const role = declaredRole ?? (await askRole({ io, askable, ask }));
     const harnesses = role === "laptop" ? [] : await resolveHarnesses(flags, { io, askable, ask });
@@ -113,22 +113,21 @@ async function signIn(flags, context, profileName) {
     }
 }
 /**
- * A project is a grouping inside the organization and not naming one is itself an answer — the
- * organization's shared commons — so an absent `--project` with no terminal is never an error.
+ * A team is a grouping inside the organization and not naming one is itself an answer, Shared, so an
+ * absent `--team` with no terminal is never an error.
  */
-async function recordProject(flags, context, profileName) {
-    let projectId = firstPresent(flags.project);
-    if (projectId === undefined && context.askable) {
-        const answer = await context.ask("Which project should this machine's work belong to? Give an id or slug, or press Enter for the " +
-            "organization's shared commons: ");
-        projectId = answer === "" ? undefined : answer;
-    }
-    if (projectId === undefined) {
+async function recordTeam(flags, context, profileName) {
+    let teamId = firstPresent(flags.team);
+    if (teamId === undefined && context.askable) {
+        const answer = await context.ask("Which team should this machine's work belong to? Give an id or slug, or press Enter for Shared: ");
+        teamId = answer === "" ? undefined : answer;
+    }
+    if (teamId === undefined) {
         return;
     }
     const stored = context.loadProfile(profileName);
     if (stored !== undefined) {
-        context.saveProfile(profileName, { ...stored, projectId });
+        context.saveProfile(profileName, { ...stored, teamId });
     }
 }
 async function askRole(context) {

package/dist/cli/main.d.ts

@@ -34,7 +34,7 @@ import { type SynthCommandOptions } from "./factory/synth.js";
  *
  * {@link topLevelHelpText} is what `orchestra --help` actually prints — this body plus a runtime epilogue.
  */
-export declare const TOP_LEVEL_HELP = "orchestra \u2014 the Orchestra command line.\n\norchestra fdk is the software factory as code. A software factory \u2014\nagents, environments, workflows, and the credentials that power them \u2014 is\ndefined in code: versioned, reviewed, type-checked. fdk apply reconciles\nthe platform to it, like cdk or terraform.\n\nUSAGE\n  orchestra <command> [flags]\n\nThe orchestra CLI does two jobs:\n\n  1  Factory as code \u2014 where change happens.\n     Declare the factory in code; fdk synth renders the plan, fdk diff\n     previews it, fdk apply makes the platform match. Code is the source of\n     truth, so every change is version-controlled, reviewed, and type-guarded.\n\n  2  Platform commands \u2014 probe the live factory.\n     Read state, reason about what exists, trial an idea before codifying\n     it, or fall back for a one-off: orchestra <noun> <verb>.\n\n  Rule of thumb: observe with commands. Change in code.\n\nSIGN IN\n  auth login   Authenticate and save a profile (both jobs use it)\n\nFACTORY AS CODE\n  fdk init     Write a starter factory into this folder\n  fdk synth    Render the factory to a plan\n  fdk diff     Preview what apply would change\n  fdk apply    Make the platform match the code\n\nPLATFORM COMMANDS   orchestra <noun> <verb> \u2014 nouns match API paths exactly\n  Build & run      agents  environments  sessions  machines  compute-enrollments\n                   pipelines  work-items  workflows  decisions  skills\n                   files  artifacts  volumes  projects  room-tokens\n                   compute-providers\n  Events & wiring  triggers  events  deliveries  connections\n                   connection-intents  install-links  connectors  providers\n  Models           models  model-aliases  model-configs  model-providers\n                   model-provider-keys  gateway-keys\n  Credentials      secrets  api-keys\n  Organization     organizations  organization-memberships  organization-invitations\n                   users  groups  user-grants  service-accounts  roles  policies  me\n  Observability    metrics  dashboards  health\n\n  Standard verbs: list \u00B7 get \u00B7 create \u00B7 update \u00B7 delete.\n  Command endpoints keep their own verb: sessions interrupt, work-items move,\n  workflows revert.\n  Typed flows: user-grants grant (mint a user-grant and walk its consent flow) \u00B7\n               sessions wait (poll a session until it settles) \u00B7\n               sessions tail (print a session's items as they are saved) \u00B7\n               compute-providers check (show why a Launcher fails) \u00B7\n               artifacts preview (serve an HTML page locally).\n  Write verbs exist for trial and fallback; durable change belongs in code.\n  Writing to a factory-managed resource warns: the next apply reverts it.\n  orchestra <noun> --help lists a noun's verbs and flags.\n\nBACKUP\n  api <METHOD> </path>   Raw authenticated call (like gh api). For when a typed\n                         command is missing or wrong \u2014 needing it is a bug; file it.\n\nYOUR CODING AGENT\n  skills install         Link the two bundled skills, orchestra and orchestra-fdk,\n                         into Claude Code or Codex. Both flags are required:\n                         --harness claude|codex|both|other --scope user|project.\n\nTHIS MACHINE\n  install                Install the CLI globally, ask what this machine is, then\n                         install the worker and the harness families you choose.\n  worker run             Serve this machine: claim its identity, then register.\n  worker install         Install the worker here, taking every answer from flags.\n  worker enroll          Redeem an enrollment token, then serve this machine.\n\nRUN YOUR AGENT HERE    The local environment on this machine, and the machines it runs.\n  local up               Start it, and print the two lines a shell needs to reach it.\n  local status           Read its four checks: boot, content, turns, environment.\n  local down             Stop it, and the machines it launched.\n  outpost token          Mint an offer for a machine you already own.\n  outpost up             Enrol this machine, or this container, and hold its worker.\n  outpost down           Stop that worker and revoke its enrollment.\n  Every other command reaches it the ordinary way, by base URL.\n\nCONVENTIONS\n  --output json          On every platform command; the default is a human table.\n  --body @file.json      Full request body where flags are too coarse.\n  --file <path>          On files create and artifacts create / create-version:\n                         store the bytes at <path> and let the create name them.\n  Credential values in responses print masked; --reveal or --output-file is the\n  deliberate path.\n  fdk apply defaults to any-change: it confirms the whole pre-flight preview\n  before any write, and stays silent when nothing changes. A single platform\n  command defaults to sensitive-only \u2014 it asks for credential values and IAM only.\n  Override with --require-approval never | sensitive-only | any-change or with\n  ORCHESTRA_REQUIRE_APPROVAL; the legacy --approve-secrets is exactly never.\n  Prompts and bindings are written as prompt`\u2026` / binding`\u2026` tagged templates\n  over the typed context handle \u2014 never hand-spelled {{\u2026}} strings.\n\nEXAMPLES\n  orchestra fdk apply                                    # reconcile the factory in ./\n  orchestra secrets create --name deepseek --value-from-command-line\n  orchestra sessions list --status RUNNING --output json\n  orchestra work-items move bug-12 --stage review\n  orchestra gateway-keys create --slug ci-smoke --output-file key.json\n\nLEARN MORE\n  orchestra <command> --help \u00B7 orchestra skills install --harness <name>\n  --scope user (links the reference and setup skills into your coding agent \u2014\n  the same documents AI agents use)\n";
+export declare const TOP_LEVEL_HELP = "orchestra \u2014 the Orchestra command line.\n\norchestra fdk is the software factory as code. A software factory \u2014\nagents, environments, workflows, and the credentials that power them \u2014 is\ndefined in code: versioned, reviewed, type-checked. fdk apply reconciles\nthe platform to it, like cdk or terraform.\n\nUSAGE\n  orchestra <command> [flags]\n\nThe orchestra CLI does two jobs:\n\n  1  Factory as code \u2014 where change happens.\n     Declare the factory in code; fdk synth renders the plan, fdk diff\n     previews it, fdk apply makes the platform match. Code is the source of\n     truth, so every change is version-controlled, reviewed, and type-guarded.\n\n  2  Platform commands \u2014 probe the live factory.\n     Read state, reason about what exists, trial an idea before codifying\n     it, or fall back for a one-off: orchestra <noun> <verb>.\n\n  Rule of thumb: observe with commands. Change in code.\n\nSIGN IN\n  auth login   Authenticate and save a profile (both jobs use it)\n\nFACTORY AS CODE\n  fdk init     Write a starter factory into this folder\n  fdk synth    Render the factory to a plan\n  fdk diff     Preview what apply would change\n  fdk apply    Make the platform match the code\n\nPLATFORM COMMANDS   orchestra <noun> <verb> \u2014 nouns match API paths exactly\n  Build & run      agents  environments  sessions  machines  compute-enrollments\n                   pipelines  work-items  workflows  decisions  skills\n                   files  images  artifacts  volumes  room-tokens\n                   compute-providers\n  Events & wiring  triggers  events  deliveries  connections\n                   connection-intents  install-links  connectors  providers\n  Models           models  model-aliases  model-configs  model-providers\n                   model-provider-keys  gateway-keys\n  Credentials      secrets  api-keys\n  Organization     organizations  organization-memberships  organization-invitations\n                   users  teams  team-memberships  user-grants  service-accounts\n                   roles  policies  me\n  Observability    metrics  dashboards  health\n\n  Standard verbs: list \u00B7 get \u00B7 create \u00B7 update \u00B7 delete.\n  Command endpoints keep their own verb: sessions interrupt, work-items move,\n  workflows revert.\n  Typed flows: user-grants grant (mint a user-grant and walk its consent flow) \u00B7\n               sessions wait (poll a session until it settles) \u00B7\n               sessions tail (print a session's items as they are saved) \u00B7\n               compute-providers check (show why a Launcher fails) \u00B7\n               artifacts preview (serve an HTML page locally).\n  Write verbs exist for trial and fallback; durable change belongs in code.\n  Writing to a factory-managed resource warns: the next apply reverts it.\n  orchestra <noun> --help lists a noun's verbs and flags.\n\nBACKUP\n  api <METHOD> </path>   Raw authenticated call (like gh api). For when a typed\n                         command is missing or wrong \u2014 needing it is a bug; file it.\n\nYOUR CODING AGENT\n  skills install         Link the two bundled skills, orchestra and orchestra-fdk,\n                         into Claude Code or Codex. Both flags are required:\n                         --harness claude|codex|both|other --scope user|project.\n\nTHIS MACHINE\n  install                Install the CLI globally, ask what this machine is, then\n                         install the worker and the harness families you choose.\n  worker run             Serve this machine: claim its identity, then register.\n  worker install         Install the worker here, taking every answer from flags.\n  worker enroll          Redeem an enrollment token, then serve this machine.\n\nRUN YOUR AGENT HERE    The local environment on this machine, and the machines it runs.\n  local up               Start it, and print the two lines a shell needs to reach it.\n  local status           Read its four checks: boot, content, turns, environment.\n  local down             Stop it, and the machines it launched.\n  outpost token          Mint an offer for a machine you already own.\n  outpost up             Enrol this machine, or this container, and hold its worker.\n  outpost down           Stop that worker and revoke its enrollment.\n  Every other command reaches it the ordinary way, by base URL.\n\nCONVENTIONS\n  --output json          On every platform command; the default is a human table.\n  --body @file.json      Full request body where flags are too coarse.\n  --file <path>          On files create and artifacts create / create-version:\n                         store the bytes at <path> and let the create name them.\n  Credential values in responses print masked; --reveal or --output-file is the\n  deliberate path.\n  fdk apply defaults to any-change: it confirms the whole pre-flight preview\n  before any write, and stays silent when nothing changes. A single platform\n  command defaults to sensitive-only \u2014 it asks for credential values and IAM only.\n  Override with --require-approval never | sensitive-only | any-change or with\n  ORCHESTRA_REQUIRE_APPROVAL; the legacy --approve-secrets is exactly never.\n  Prompts and bindings are written as prompt`\u2026` / binding`\u2026` tagged templates\n  over the typed context handle \u2014 never hand-spelled {{\u2026}} strings.\n\nEXAMPLES\n  orchestra fdk apply                                    # reconcile the factory in ./\n  orchestra secrets create --name deepseek --value-from-command-line\n  orchestra sessions list --status RUNNING --output json\n  orchestra work-items move bug-12 --stage review\n  orchestra gateway-keys create --slug ci-smoke --output-file key.json\n\nLEARN MORE\n  orchestra <command> --help \u00B7 orchestra skills install --harness <name>\n  --scope user (links the reference and setup skills into your coding agent \u2014\n  the same documents AI agents use)\n";
 /**
  * A function rather than a constant because the epilogue names an ABSOLUTE PATH that differs per install and
  * can only be resolved by the running process. `buildProgram` calls it once and pins the result, so the text