spawnfile 0.1.12 → 0.1.14

package/dist/deployment/simfileFixtureBoundary.test-helper.js

@@ -0,0 +1,103 @@
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import * as ts from "typescript";
+const normalize = (value) => value.replace(/\\/g, "/");
+const fixturePath = (value) => {
+    const normalized = normalize(value);
+    const index = normalized.toLowerCase().indexOf("ecosystem/simfile/fixtures");
+    if (index < 0 || (index > 0 && !/[\\/]/u.test(normalized[index - 1])))
+        return null;
+    return normalized.slice(index);
+};
+const aliasesFor = (sourceFile) => {
+    const namespaceAliases = new Set();
+    const functionAliases = new Map();
+    for (const statement of sourceFile.statements) {
+        if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier)
+            || !["node:path", "path"].includes(statement.moduleSpecifier.text))
+            continue;
+        const clause = statement.importClause;
+        if (!clause)
+            continue;
+        if (clause.name)
+            namespaceAliases.add(clause.name.text);
+        if (!clause.namedBindings)
+            continue;
+        if (ts.isNamespaceImport(clause.namedBindings))
+            namespaceAliases.add(clause.namedBindings.name.text);
+        if (ts.isNamedImports(clause.namedBindings)) {
+            for (const element of clause.namedBindings.elements) {
+                const imported = element.propertyName?.text ?? element.name.text;
+                if (imported === "join" || imported === "resolve")
+                    functionAliases.set(element.name.text, imported);
+            }
+        }
+    }
+    return { namespaceAliases, functionAliases };
+};
+const pathCallViolations = (node, aliases, sourceFile) => {
+    const callee = node.expression;
+    let kind = null;
+    if (ts.isPropertyAccessExpression(callee) && ts.isIdentifier(callee.expression)
+        && aliases.namespaceAliases.has(callee.expression.text) && ["join", "resolve"].includes(callee.name.text)) {
+        kind = callee.name.text;
+    }
+    else if (ts.isIdentifier(callee)) {
+        kind = aliases.functionAliases.get(callee.text) ?? null;
+    }
+    if (!kind)
+        return [];
+    const segments = node.arguments.map((argument) => ts.isStringLiteral(argument) || ts.isNoSubstitutionTemplateLiteral(argument) ? normalize(argument.text) : null);
+    const start = segments.findIndex((segment, index) => index <= segments.length - 3 && segment === "ecosystem" && segments[index + 1] === "simfile" && segments[index + 2] === "fixtures");
+    if (start < 0)
+        return [];
+    const matchedSegments = [];
+    for (const segment of segments.slice(start)) {
+        if (segment === null)
+            break;
+        matchedSegments.push(segment);
+    }
+    return [{
+            file: path.relative(process.cwd(), sourceFile.fileName),
+            classification: kind === "join" ? "simfile-scenario-path-join" : "simfile-scenario-path-resolve",
+            matchedPath: matchedSegments.join("/")
+        }];
+};
+export const scanSimfileFixtureSource = (text, file = "synthetic.ts") => {
+    const sourceFile = ts.createSourceFile(file, text, ts.ScriptTarget.ES2022, true, ts.ScriptKind.TS);
+    const aliases = aliasesFor(sourceFile);
+    const violations = [];
+    const visit = (node) => {
+        if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
+            const matchedPath = fixturePath(node.text);
+            if (matchedPath)
+                violations.push({ file, classification: "simfile-scenario-direct-literal", matchedPath });
+        }
+        if (ts.isCallExpression(node))
+            violations.push(...pathCallViolations(node, aliases, sourceFile));
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    return violations;
+};
+export const scanSimfileFixtureFile = async (file) => scanSimfileFixtureSource(await readFile(file, "utf8"), file);
+const typescriptFiles = async (directory) => {
+    const entries = await readdir(directory, { withFileTypes: true });
+    const nested = await Promise.all(entries.map(async (entry) => {
+        const file = path.join(directory, entry.name);
+        if (entry.isDirectory())
+            return typescriptFiles(file);
+        return entry.isFile() && entry.name.endsWith(".ts") ? [file] : [];
+    }));
+    return nested.flat();
+};
+export const scanSimfileFixtureTree = async (repositoryRoot) => {
+    const excluded = new Set([
+        path.resolve(repositoryRoot, "src/deployment/providerRuntimeBoundary.test.ts"),
+        path.resolve(repositoryRoot, "src/deployment/simfileFixtureBoundary.test-helper.ts")
+    ]);
+    const files = (await typescriptFiles(path.join(repositoryRoot, "src")))
+        .map((file) => path.resolve(file))
+        .filter((file) => !excluded.has(file));
+    return (await Promise.all(files.map(scanSimfileFixtureFile))).flat();
+};

package/dist/deployment/target.d.ts

@@ -1,35 +1 @@
-export type DockerDeploymentTarget = {
-    endpoint_fingerprint: string;
-    kind: "context";
-    name: string;
-} | {
-    endpoint_fingerprint: string;
-    kind: "docker-context";
-    context: string;
-} | {
-    kind: "host";
-    value: string;
-};
-export type DockerTargetExecFile = (file: string, args: string[], options: {
-    timeout: number;
-}) => Promise<{
-    stderr: string;
-    stdout: string;
-}>;
-export interface ResolveDockerDeploymentTargetOptions {
-    context?: string | null;
-    dockerCommand?: string;
-    dockerHost?: string | null;
-    execFile?: DockerTargetExecFile;
-    timeoutMs?: number;
-}
-export declare const createEndpointFingerprint: (endpoint: string) => string;
-export declare const createDockerDeploymentTarget: (input: {
-    context?: string;
-    endpoint?: string;
-    host?: string;
-}) => DockerDeploymentTarget;
-export declare const dockerContextNameForTarget: (target: DockerDeploymentTarget) => string | null;
-export declare const dockerHostValueForTarget: (target: DockerDeploymentTarget) => string | null;
-export declare const resolveDockerDeploymentTarget: (input?: ResolveDockerDeploymentTargetOptions) => Promise<DockerDeploymentTarget>;
-export declare const verifyDockerDeploymentTarget: (target: DockerDeploymentTarget, options?: Omit<ResolveDockerDeploymentTargetOptions, "context" | "dockerHost">) => Promise<string | null>;
+export * from "../target/dockerTarget.js";

package/dist/deployment/target.js

@@ -1,96 +1 @@
-import { createHash } from "node:crypto";
-import { execFile as execFileCallback } from "node:child_process";
-import { promisify } from "node:util";
-import { SpawnfileError } from "../shared/index.js";
-const execFile = promisify(execFileCallback);
-export const createEndpointFingerprint = (endpoint) => {
-    const normalized = endpoint.trim();
-    if (normalized.length === 0) {
-        throw new SpawnfileError("validation_error", "Deployment target endpoint must not be empty");
-    }
-    return `sha256:${createHash("sha256").update(normalized).digest("hex").slice(0, 32)}`;
-};
-const parseDockerEndpoint = (stdout) => {
-    const trimmed = stdout.trim();
-    if (trimmed.length === 0) {
-        throw new SpawnfileError("runtime_error", "Docker context endpoint was empty");
-    }
-    try {
-        const parsed = JSON.parse(trimmed);
-        if (typeof parsed === "string" && parsed.trim().length > 0) {
-            return parsed.trim();
-        }
-    }
-    catch {
-        // Docker/podman variants may return a plain string instead of JSON.
-    }
-    return trimmed;
-};
-const resolveDockerContextEndpoint = async (context, options) => {
-    try {
-        const { stdout } = await options.execFile(options.dockerCommand, ["context", "inspect", context, "--format", "{{json .Endpoints.docker.Host}}"], { timeout: options.timeoutMs });
-        return parseDockerEndpoint(stdout);
-    }
-    catch (error) {
-        const reason = error instanceof Error ? error.message : String(error);
-        throw new SpawnfileError("runtime_error", `Unable to resolve Docker context "${context}": ${reason}`);
-    }
-};
-export const createDockerDeploymentTarget = (input) => {
-    const host = input.host?.trim();
-    if (host) {
-        return {
-            kind: "host",
-            value: host
-        };
-    }
-    const context = input.context?.trim();
-    const endpoint = input.endpoint?.trim();
-    if (!context || !endpoint) {
-        throw new SpawnfileError("validation_error", "Docker context deployment targets require both context and endpoint");
-    }
-    return {
-        name: context,
-        endpoint_fingerprint: createEndpointFingerprint(endpoint),
-        kind: "context"
-    };
-};
-export const dockerContextNameForTarget = (target) => target.kind === "context"
-    ? target.name
-    : target.kind === "docker-context"
-        ? target.context
-        : null;
-export const dockerHostValueForTarget = (target) => target.kind === "host" ? target.value : null;
-export const resolveDockerDeploymentTarget = async (input = {}) => {
-    const explicitContext = input.context?.trim();
-    const host = explicitContext ? undefined : input.dockerHost?.trim() ?? process.env.DOCKER_HOST?.trim();
-    if (host) {
-        return createDockerDeploymentTarget({ host });
-    }
-    const resolvedOptions = {
-        dockerCommand: input.dockerCommand ?? "docker",
-        execFile: input.execFile ?? execFile,
-        timeoutMs: input.timeoutMs ?? 10_000
-    };
-    const context = explicitContext || "default";
-    const endpoint = await resolveDockerContextEndpoint(context, resolvedOptions);
-    return createDockerDeploymentTarget({ context, endpoint });
-};
-export const verifyDockerDeploymentTarget = async (target, options = {}) => {
-    if (target.kind === "host") {
-        return null;
-    }
-    const context = dockerContextNameForTarget(target);
-    if (!context) {
-        return null;
-    }
-    const current = await resolveDockerDeploymentTarget({
-        ...options,
-        context
-    });
-    const currentFingerprint = current.kind === "host" ? null : current.endpoint_fingerprint;
-    if (currentFingerprint !== target.endpoint_fingerprint) {
-        throw new SpawnfileError("runtime_error", `Docker context "${context}" endpoint changed since deployment`);
-    }
-    return context;
-};
+export * from "../target/dockerTarget.js";

package/dist/deployment/upReceiptTypes.d.ts

@@ -0,0 +1,111 @@
+import { z } from "zod";
+import { type OrganizationReadiness } from "./organizationReady.js";
+import { type OrganizationHandoff } from "./organizationHandoffTypes.js";
+import { type OpaqueTargetHandle } from "../target/index.js";
+/**
+ * `spawnfile.up-receipt.v1` — the machine contract `spawnfile up --json` writes to stdout
+ * (contracts.md's Spawnfile up-receipt registry row; Decision 21's Piece 4). It is thin by
+ * design: enough for a non-Docker caller (simfile's sim harness, later its supervisor) to
+ * drive lifecycle without touching Docker directly, per `contracts.md`'s rule that
+ * "Simfile -> spawnfile only through documented CLI + versioned receipts".
+ *
+ * `compiled_schedule` is populated even though nothing consumes it yet — it freezes the
+ * shape simfile's wake-diff (the expected-wake denominator oracle, see contracts.md's
+ * `simfile.run-manifest.v1` field notes) will read from later, so the receipt shape does
+ * not need to change again when that consumer lands.
+ *
+ * No credentials/tokens ever belong on this contract (contracts.md: "No credentials in
+ * exchanged artifacts") — `moltnet_base_url` is a bare URL, never an auth header/token.
+ */
+export declare const UP_RECEIPT_VERSION: "spawnfile.up-receipt.v1";
+declare const readinessStateSchema: z.ZodUnion<readonly [z.ZodLiteral<"running">, z.ZodLiteral<"exited">, z.ZodLiteral<"unknown">]>;
+export type UpReceiptReadinessState = z.infer<typeof readinessStateSchema>;
+declare const compiledScheduleEntrySchema: z.ZodObject<{
+    agent: z.ZodString;
+    cron: z.ZodString;
+}, z.core.$strict>;
+export type CompiledScheduleEntry = z.infer<typeof compiledScheduleEntrySchema>;
+/**
+ * `{agent, engine}` disclosure entry (Piece 5, Slice B): ground truth for the
+ * run-manifest's `pinned-engine` field, so a `scripted` (or any non-default)
+ * pi engine is visibly disclosed rather than an invisible test-only branch.
+ * Derived in `buildUpReceipt` from the compiled report's
+ * `container.runtime_instances[].engine_by_node_id`. Optional on the schema
+ * so existing (pre-Piece-5) receipts without this field still validate.
+ */
+declare const compiledEngineEntrySchema: z.ZodObject<{
+    agent: z.ZodString;
+    engine: z.ZodString;
+}, z.core.$strict>;
+export type CompiledEngineEntry = z.infer<typeof compiledEngineEntrySchema>;
+declare const moltnetReleaseIdentitySchema: z.ZodObject<{
+    architecture: z.ZodUnion<readonly [z.ZodLiteral<"amd64">, z.ZodLiteral<"arm64">]>;
+    asset: z.ZodString;
+    asset_sha256: z.ZodString;
+    capabilities: z.ZodTuple<[z.ZodLiteral<"pi-bridge">], null>;
+    release_version: z.ZodString;
+    source_revision: z.ZodString;
+    version: z.ZodLiteral<"spawnfile.moltnet-release-identity.v1">;
+}, z.core.$strict>;
+export type MoltnetReleaseReceiptIdentity = z.infer<typeof moltnetReleaseIdentitySchema>;
+export declare const upReceiptSchema: z.ZodPreprocess<z.ZodObject<{
+    version: z.ZodLiteral<"spawnfile.up-receipt.v1">;
+    run_id: z.ZodNullable<z.ZodString>;
+    fingerprint: z.ZodString;
+    deployment: z.ZodObject<{
+        name: z.ZodNullable<z.ZodString>;
+        container_ids: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>;
+    readiness: z.ZodObject<{
+        state: z.ZodUnion<readonly [z.ZodLiteral<"running">, z.ZodLiteral<"exited">, z.ZodLiteral<"unknown">]>;
+        moltnet_base_url: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+    compiled_schedule: z.ZodArray<z.ZodObject<{
+        agent: z.ZodString;
+        cron: z.ZodString;
+    }, z.core.$strict>>;
+    engines: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        agent: z.ZodString;
+        engine: z.ZodString;
+    }, z.core.$strict>>>;
+    moltnet_release: z.ZodOptional<z.ZodObject<{
+        architecture: z.ZodUnion<readonly [z.ZodLiteral<"amd64">, z.ZodLiteral<"arm64">]>;
+        asset: z.ZodString;
+        asset_sha256: z.ZodString;
+        capabilities: z.ZodTuple<[z.ZodLiteral<"pi-bridge">], null>;
+        release_version: z.ZodString;
+        source_revision: z.ZodString;
+        version: z.ZodLiteral<"spawnfile.moltnet-release-identity.v1">;
+    }, z.core.$strict>>;
+    organization_handoff: z.ZodOptional<z.ZodObject<{
+        binding_digest: z.ZodString;
+        deployment_handle: z.ZodString;
+        lifecycle_receipts: z.ZodObject<{
+            down: z.ZodLiteral<"spawnfile.down-receipt.v1">;
+            export: z.ZodLiteral<"spawnfile.export-index.v1">;
+            up: z.ZodLiteral<"spawnfile.up-receipt.v1">;
+        }, z.core.$strict>;
+        network_attachment_handle: z.ZodString;
+        run_id: z.ZodString;
+        selected_target_receipt_digest: z.ZodString;
+        version: z.ZodLiteral<"spawnfile.organization-handoff.v1">;
+    }, z.core.$strict>>;
+    organization_handoff_handle: z.ZodOptional<z.ZodString>;
+    organization_ready: z.ZodOptional<z.ZodPreprocess<z.ZodObject<{
+        code: z.ZodUnion<readonly [z.ZodLiteral<"organization_ready">, z.ZodLiteral<"external_moltnet">, z.ZodLiteral<"compiled_evidence_missing">, z.ZodLiteral<"unit_unavailable">, z.ZodLiteral<"unit_restarted">, z.ZodLiteral<"probe_unavailable">, z.ZodLiteral<"identity_mismatch">, z.ZodLiteral<"topology_mismatch">, z.ZodLiteral<"probe_timeout">, z.ZodLiteral<"probe_cancelled">]>;
+        compile_fingerprint: z.ZodString;
+        run_id: z.ZodNullable<z.ZodString>;
+        state: z.ZodUnion<readonly [z.ZodLiteral<"ready">, z.ZodLiteral<"pending">, z.ZodLiteral<"failed">, z.ZodLiteral<"cancelled">]>;
+        unit_id: z.ZodString;
+        version: z.ZodLiteral<"spawnfile.organization-ready.v1">;
+        world_binding_digest: z.ZodNullable<z.ZodString>;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>>;
+export type UpReceipt = Omit<z.infer<typeof upReceiptSchema>, "organization_handoff" | "organization_handoff_handle" | "organization_ready"> & {
+    organization_handoff?: OrganizationHandoff;
+    organization_handoff_handle?: OpaqueTargetHandle;
+    organization_ready?: OrganizationReadiness;
+};
+export declare const parseUpReceipt: (raw: unknown) => UpReceipt;
+export {};

package/dist/deployment/upReceiptTypes.js

@@ -0,0 +1,164 @@
+import { z } from "zod";
+import { organizationReadinessSchema, parseOrganizationReadiness } from "./organizationReady.js";
+import { ORGANIZATION_HANDOFF_VERSION, parseOrganizationHandoff } from "./organizationHandoffTypes.js";
+import { assertOrdinaryJsonGraph, parseOpaqueTargetHandle } from "../target/index.js";
+/**
+ * `spawnfile.up-receipt.v1` — the machine contract `spawnfile up --json` writes to stdout
+ * (contracts.md's Spawnfile up-receipt registry row; Decision 21's Piece 4). It is thin by
+ * design: enough for a non-Docker caller (simfile's sim harness, later its supervisor) to
+ * drive lifecycle without touching Docker directly, per `contracts.md`'s rule that
+ * "Simfile -> spawnfile only through documented CLI + versioned receipts".
+ *
+ * `compiled_schedule` is populated even though nothing consumes it yet — it freezes the
+ * shape simfile's wake-diff (the expected-wake denominator oracle, see contracts.md's
+ * `simfile.run-manifest.v1` field notes) will read from later, so the receipt shape does
+ * not need to change again when that consumer lands.
+ *
+ * No credentials/tokens ever belong on this contract (contracts.md: "No credentials in
+ * exchanged artifacts") — `moltnet_base_url` is a bare URL, never an auth header/token.
+ */
+export const UP_RECEIPT_VERSION = "spawnfile.up-receipt.v1";
+const readinessStateSchema = z.union([
+    z.literal("running"),
+    z.literal("exited"),
+    z.literal("unknown")
+]);
+const compiledScheduleEntrySchema = z
+    .object({
+    agent: z.string().min(1),
+    cron: z.string().min(1)
+})
+    .strict();
+/**
+ * `{agent, engine}` disclosure entry (Piece 5, Slice B): ground truth for the
+ * run-manifest's `pinned-engine` field, so a `scripted` (or any non-default)
+ * pi engine is visibly disclosed rather than an invisible test-only branch.
+ * Derived in `buildUpReceipt` from the compiled report's
+ * `container.runtime_instances[].engine_by_node_id`. Optional on the schema
+ * so existing (pre-Piece-5) receipts without this field still validate.
+ */
+const compiledEngineEntrySchema = z
+    .object({
+    agent: z.string().min(1),
+    engine: z.string().min(1)
+})
+    .strict();
+const moltnetReleaseIdentitySchema = z.object({
+    architecture: z.union([z.literal("amd64"), z.literal("arm64")]),
+    asset: z.string().regex(/^moltnet_linux_(amd64|arm64)\.tar\.gz$/u),
+    asset_sha256: z.string().regex(/^sha256:[a-f0-9]{64}$/u),
+    capabilities: z.tuple([z.literal("pi-bridge")]),
+    release_version: z.string().regex(/^v?\d+\.\d+\.\d+(?:-\d+-g[a-f0-9]{7,40})?$/u),
+    source_revision: z.string().regex(/^[a-f0-9]{40}$/u),
+    version: z.literal("spawnfile.moltnet-release-identity.v1")
+}).strict().superRefine((value, context) => {
+    if (!value.asset.includes(`_${value.architecture}.`)) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["asset"],
+            message: "Moltnet asset architecture must match identity architecture"
+        });
+    }
+    const describedRevision = value.release_version.match(/-g([a-f0-9]{7,40})$/u)?.[1];
+    if (describedRevision && !value.source_revision.startsWith(describedRevision)) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["source_revision"],
+            message: "Moltnet release version must match source revision"
+        });
+    }
+});
+const organizationHandoffReceiptSchema = z.object({
+    binding_digest: z.string().regex(/^sha256:[a-f0-9]{64}$/u),
+    deployment_handle: z.string().regex(/^sf-oh1-[a-f0-9]{64}$/u),
+    lifecycle_receipts: z.object({
+        down: z.literal("spawnfile.down-receipt.v1"),
+        export: z.literal("spawnfile.export-index.v1"),
+        up: z.literal(UP_RECEIPT_VERSION)
+    }).strict(),
+    network_attachment_handle: z.string().regex(/^opaque_[a-z0-9]{16,64}$/u),
+    run_id: z.string().min(1),
+    selected_target_receipt_digest: z.string().regex(/^sha256:[a-f0-9]{64}$/u),
+    version: z.literal(ORGANIZATION_HANDOFF_VERSION)
+}).strict().superRefine((value, context) => {
+    try {
+        parseOrganizationHandoff(value);
+    }
+    catch {
+        context.addIssue({ code: z.ZodIssueCode.custom, message: "invalid organization handoff" });
+    }
+});
+const INVALID_JSON_GRAPH = Symbol("invalid-json-graph");
+const upReceiptObjectSchema = z
+    .object({
+    version: z.literal(UP_RECEIPT_VERSION),
+    run_id: z.string().min(1).nullable(),
+    fingerprint: z.string().min(1),
+    deployment: z
+        .object({
+        name: z.string().min(1).nullable(),
+        container_ids: z.array(z.string().min(1))
+    })
+        .strict(),
+    readiness: z
+        .object({
+        state: readinessStateSchema,
+        moltnet_base_url: z.string().min(1).nullable()
+    })
+        .strict(),
+    compiled_schedule: z.array(compiledScheduleEntrySchema),
+    engines: z.array(compiledEngineEntrySchema).optional(),
+    moltnet_release: moltnetReleaseIdentitySchema.optional(),
+    organization_handoff: organizationHandoffReceiptSchema.optional(),
+    organization_handoff_handle: z.string().optional(),
+    organization_ready: organizationReadinessSchema.optional()
+})
+    .strict()
+    .superRefine((value, context) => {
+    if (value.organization_handoff && (value.run_id === null || value.run_id !== value.organization_handoff.run_id)) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["organization_handoff", "run_id"],
+            message: "organization handoff run_id must match receipt run_id"
+        });
+    }
+    if (value.organization_handoff_handle !== undefined) {
+        if (!value.organization_handoff) {
+            context.addIssue({ code: z.ZodIssueCode.custom, path: ["organization_handoff_handle"], message: "organization handoff handle requires organization handoff" });
+        }
+        try {
+            parseOpaqueTargetHandle(value.organization_handoff_handle);
+        }
+        catch {
+            context.addIssue({ code: z.ZodIssueCode.custom, path: ["organization_handoff_handle"], message: "invalid organization handoff handle" });
+        }
+    }
+});
+export const upReceiptSchema = z
+    .preprocess((value) => {
+    try {
+        assertOrdinaryJsonGraph(value);
+        return value;
+    }
+    catch {
+        return INVALID_JSON_GRAPH;
+    }
+}, upReceiptObjectSchema);
+export const parseUpReceipt = (raw) => {
+    try {
+        assertOrdinaryJsonGraph(raw);
+        const result = upReceiptSchema.safeParse(raw);
+        if (!result.success)
+            throw new TypeError();
+        const { organization_handoff: handoff, organization_handoff_handle: handoffHandle, organization_ready: readiness, ...receipt } = result.data;
+        return {
+            ...receipt,
+            ...(handoff ? { organization_handoff: parseOrganizationHandoff(handoff) } : {}),
+            ...(handoffHandle ? { organization_handoff_handle: parseOpaqueTargetHandle(handoffHandle) } : {}),
+            ...(readiness ? { organization_ready: parseOrganizationReadiness(readiness) } : {})
+        };
+    }
+    catch {
+        throw new Error(`invalid ${UP_RECEIPT_VERSION}`);
+    }
+};

package/dist/dev/activity.d.ts

@@ -0,0 +1,14 @@
+import { type DevExecFile } from "./docker.js";
+import { type DevProjectOptions } from "./project.js";
+export interface DevActivityProjectOptions extends DevProjectOptions {
+    agent?: string;
+    execFile?: DevExecFile;
+    tail?: number;
+}
+export interface DevActivityProjectResult {
+    containerName: string;
+    deploymentName: string;
+    events: unknown[];
+    outputDirectory: string;
+}
+export declare const devActivityProject: (inputPath: string, options?: DevActivityProjectOptions) => Promise<DevActivityProjectResult>;

package/dist/dev/activity.js

@@ -0,0 +1,48 @@
+import { defaultExecFile, dockerArgsForRecord, firstContainerName, runDocker } from "./docker.js";
+import { PI_CONTROL_URL, resolveDevOutputDirectory, selectDeploymentRecord } from "./project.js";
+import { SpawnfileError } from "../shared/index.js";
+const activityPath = (options) => {
+    const params = new URLSearchParams();
+    if (options.agent) {
+        params.set("agent", options.agent);
+    }
+    if (typeof options.tail === "number" && Number.isInteger(options.tail) && options.tail > 0) {
+        params.set("tail", String(options.tail));
+    }
+    const query = params.toString();
+    return `${PI_CONTROL_URL}/spawnfile/activity${query ? `?${query}` : ""}`;
+};
+const parseActivityEvents = (stdout) => {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        throw new SpawnfileError("runtime_error", "Pi activity endpoint returned invalid JSON");
+    }
+    if (typeof parsed !== "object" ||
+        parsed === null ||
+        !Array.isArray(parsed.events)) {
+        throw new SpawnfileError("runtime_error", "Pi activity endpoint response did not include an events array");
+    }
+    return parsed.events;
+};
+export const devActivityProject = async (inputPath, options = {}) => {
+    const outputDirectory = await resolveDevOutputDirectory(inputPath, options.outputDirectory);
+    const record = await selectDeploymentRecord(outputDirectory, options.deploymentName);
+    const containerName = firstContainerName(record);
+    const stdout = await runDocker(options.dockerCommand ?? "docker", [
+        ...dockerArgsForRecord(record),
+        "exec",
+        containerName,
+        "curl",
+        "-fsS",
+        activityPath(options)
+    ], options.execFile ?? defaultExecFile);
+    return {
+        containerName,
+        deploymentName: record.name,
+        events: parseActivityEvents(stdout),
+        outputDirectory
+    };
+};

package/dist/dev/docker.d.ts

@@ -0,0 +1,16 @@
+import { type CompileProjectResult } from "../compiler/index.js";
+import { type DeploymentRecord } from "../deployment/index.js";
+export type DevExecFile = (file: string, args: string[], options: {
+    timeout: number;
+}) => Promise<{
+    stderr: string;
+    stdout: string;
+}>;
+export declare const defaultExecFile: DevExecFile;
+export declare const dockerArgsForRecord: (record: DeploymentRecord) => string[];
+export declare const firstContainerName: (record: DeploymentRecord) => string;
+export declare const compileForDevApply: (inputPath: string, outputDirectory: string, record: DeploymentRecord, dockerCommand: string, execFileImpl: DevExecFile) => Promise<CompileProjectResult>;
+export declare const runDocker: (command: string, args: string[], execFileImpl: DevExecFile, timeout?: number) => Promise<string>;
+export declare const copyIntoContainer: (dockerCommand: string, dockerPrefix: string[], source: string, destination: string, execFileImpl: DevExecFile) => Promise<void>;
+export declare const ensureContainerDirectories: (dockerCommand: string, dockerPrefix: string[], containerName: string, paths: string[], execFileImpl: DevExecFile) => Promise<void>;
+export declare const chownContainerPaths: (dockerCommand: string, dockerPrefix: string[], containerName: string, paths: string[], execFileImpl: DevExecFile) => Promise<void>;

package/dist/dev/docker.js

@@ -0,0 +1,71 @@
+import { execFile as execFileCallback } from "node:child_process";
+import { promisify } from "node:util";
+import { compileProject, normalizeDockerArchitecture } from "../compiler/index.js";
+import { dockerContextNameForTarget, dockerHostValueForTarget } from "../deployment/index.js";
+import { SpawnfileError } from "../shared/index.js";
+export const defaultExecFile = promisify(execFileCallback);
+export const dockerArgsForRecord = (record) => {
+    const context = dockerContextNameForTarget(record.target);
+    if (context) {
+        return ["--context", context];
+    }
+    const host = dockerHostValueForTarget(record.target);
+    return host ? ["--host", host] : [];
+};
+export const firstContainerName = (record) => {
+    const unit = record.units.find((candidate) => candidate.kind === "container") ?? record.units[0];
+    const name = unit?.container_name;
+    if (!name) {
+        throw new SpawnfileError("runtime_error", `Deployment "${record.name}" has no recorded container name`);
+    }
+    return name;
+};
+export const compileForDevApply = async (inputPath, outputDirectory, record, dockerCommand, execFileImpl) => {
+    const dockerContext = dockerContextNameForTarget(record.target) ?? undefined;
+    const architecture = dockerContext
+        ? normalizeDockerArchitecture((await execFileImpl(dockerCommand, ["--context", dockerContext, "info", "--format", "{{.Architecture}}"], { timeout: 10_000 })).stdout)
+        : undefined;
+    return compileProject(inputPath, {
+        clean: false,
+        containerArchitecture: architecture,
+        outputDirectory
+    });
+};
+export const runDocker = async (command, args, execFileImpl, timeout = 30_000) => {
+    const { stdout } = await execFileImpl(command, args, { timeout });
+    return stdout;
+};
+export const copyIntoContainer = async (dockerCommand, dockerPrefix, source, destination, execFileImpl) => {
+    await runDocker(dockerCommand, [...dockerPrefix, "cp", source, destination], execFileImpl, 60_000);
+};
+export const ensureContainerDirectories = async (dockerCommand, dockerPrefix, containerName, paths, execFileImpl) => {
+    if (paths.length === 0) {
+        return;
+    }
+    await runDocker(dockerCommand, [
+        ...dockerPrefix,
+        "exec",
+        "--user",
+        "root",
+        containerName,
+        "mkdir",
+        "-p",
+        ...paths
+    ], execFileImpl);
+};
+export const chownContainerPaths = async (dockerCommand, dockerPrefix, containerName, paths, execFileImpl) => {
+    if (paths.length === 0) {
+        return;
+    }
+    await runDocker(dockerCommand, [
+        ...dockerPrefix,
+        "exec",
+        "--user",
+        "root",
+        containerName,
+        "chown",
+        "-R",
+        "spawnfile:spawnfile",
+        ...paths
+    ], execFileImpl);
+};

package/dist/dev/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./activity.js";
+export * from "./project.js";