@orchestraworks/cli 0.5.5 → 0.5.8

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.
@@ -56,9 +56,9 @@ export interface FirstRunGateDeps extends InterviewDeps {
 }
 /**
  * The pre-command gate: the interview runs on a machine where a person is present and nothing is
- * configured. A credential supplied by the environment — an exported token, or the marker the platform sets
- * on a machine where the egress stamps the authorization — skips the interview and nothing else, so a
- * command's own rules are untouched either way.
+ * configured. A credential supplied by the environment — an exported token, the token file the worker
+ * names, written yet or not, or the marker the platform sets on a machine where the egress stamps the
+ * authorization — skips the interview and nothing else, so a command's own rules are untouched either way.
  *
  * The terminal is checked first, so a run with no person to ask touches neither the disk nor the network.
  */

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) {
@@ -169,9 +168,9 @@ async function resolveHarnesses(flags, context) {
 }
 /**
  * The pre-command gate: the interview runs on a machine where a person is present and nothing is
- * configured. A credential supplied by the environment — an exported token, or the marker the platform sets
- * on a machine where the egress stamps the authorization — skips the interview and nothing else, so a
- * command's own rules are untouched either way.
+ * configured. A credential supplied by the environment — an exported token, the token file the worker
+ * names, written yet or not, or the marker the platform sets on a machine where the egress stamps the
+ * authorization — skips the interview and nothing else, so a command's own rules are untouched either way.
  *
  * The terminal is checked first, so a run with no person to ask touches neither the disk nor the network.
  */
@@ -180,7 +179,9 @@ export async function runFirstRunIfNeeded(flags, deps = {}) {
     if ((deps.isTTY ?? process.stdin.isTTY === true) !== true) {
         return;
     }
-    if (firstPresent(env[AUTH_ENV.token]) !== undefined || firstPresent(env[AUTH_ENV.edgeInjected]) !== undefined) {
+    if (firstPresent(env[AUTH_ENV.token]) !== undefined ||
+        firstPresent(env[AUTH_ENV.tokenFile]) !== undefined ||
+        firstPresent(env[AUTH_ENV.edgeInjected]) !== undefined) {
         return;
     }
     const loadProfile = deps.loadProfile ?? loadProfileFromDisk;