@altf4llc/vorpal-sdk 0.1.0-alpha.0

package/dist/artifact.js

@@ -0,0 +1,938 @@
+import { ArtifactSystem } from "./api/artifact/artifact.js";
+import { shell } from "./artifact/step.js";
+/**
+ * Returns the environment variable key for an artifact digest.
+ * Matches Rust get_env_key() and Go GetEnvKey().
+ */
+export function getEnvKey(digest) {
+    return `$VORPAL_ARTIFACT_${digest}`;
+}
+/**
+ * Converts a Map of secrets to a sorted array of proto objects.
+ * Matches Go SDK's SecretsToProto function.
+ */
+export function secretsToProto(secrets) {
+    const keys = Array.from(secrets.keys()).sort();
+    return keys.map((name) => ({ name, value: secrets.get(name) }));
+}
+// ---------------------------------------------------------------------------
+// ArtifactSource
+// ---------------------------------------------------------------------------
+/**
+ * Builder for ArtifactSource messages.
+ * Matches Rust sdk/rust/src/artifact.rs ArtifactSource impl.
+ */
+export class ArtifactSource {
+    _digest = undefined;
+    _excludes = [];
+    _includes = [];
+    _name;
+    _path;
+    /**
+     * @param name - Source name (used as a key in the artifact's source map)
+     * @param path - Filesystem path to the source directory or file
+     */
+    constructor(name, path) {
+        this._name = name;
+        this._path = path;
+    }
+    /**
+     * Sets a pre-computed digest for this source.
+     * When set, the agent skips re-hashing the source contents.
+     */
+    withDigest(digest) {
+        this._digest = digest;
+        return this;
+    }
+    /**
+     * Sets glob patterns to exclude from the source.
+     * Patterns are matched relative to the source path.
+     *
+     * @param excludes - Array of glob patterns (e.g., `["node_modules", "*.log"]`)
+     */
+    withExcludes(excludes) {
+        this._excludes = excludes;
+        return this;
+    }
+    /**
+     * Sets glob patterns to include in the source.
+     * Only matching files will be included. Patterns are matched relative to the source path.
+     *
+     * @param includes - Array of glob patterns (e.g., `["src/**", "package.json"]`)
+     */
+    withIncludes(includes) {
+        this._includes = includes;
+        return this;
+    }
+    /** Builds the {@link ArtifactSource} message. */
+    build() {
+        return {
+            digest: this._digest,
+            excludes: this._excludes,
+            includes: this._includes,
+            name: this._name,
+            path: this._path,
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// ArtifactStep
+// ---------------------------------------------------------------------------
+/**
+ * Builder for ArtifactStep messages.
+ * Matches Rust sdk/rust/src/artifact.rs ArtifactStep impl.
+ */
+export class ArtifactStep {
+    _arguments = [];
+    _artifacts = [];
+    _entrypoint;
+    _environments = [];
+    _secrets = [];
+    _script = undefined;
+    /**
+     * @param entrypoint - The executable entrypoint (e.g., `"bash"`, `"bwrap"`, `"docker"`)
+     */
+    constructor(entrypoint) {
+        this._entrypoint = entrypoint;
+    }
+    /**
+     * Sets command-line arguments passed to the entrypoint.
+     *
+     * @param args - Array of argument strings
+     */
+    withArguments(args) {
+        this._arguments = args;
+        return this;
+    }
+    /**
+     * Sets artifact digests whose outputs are available during this step.
+     * Each artifact's `$VORPAL_ARTIFACT_{digest}` directory will be mounted.
+     *
+     * @param artifacts - Array of artifact digest strings
+     */
+    withArtifacts(artifacts) {
+        this._artifacts = artifacts;
+        return this;
+    }
+    /**
+     * Sets environment variables for the step execution.
+     * Format: `"KEY=VALUE"`.
+     *
+     * @param environments - Array of environment variable strings
+     */
+    withEnvironments(environments) {
+        this._environments = environments;
+        return this;
+    }
+    /**
+     * Adds secrets available during the step. Secrets are deduplicated by name.
+     *
+     * @param secrets - Array of {@link ArtifactStepSecret} objects
+     */
+    withSecrets(secrets) {
+        for (const secret of secrets) {
+            if (!this._secrets.some((s) => s.name === secret.name)) {
+                this._secrets.push(secret);
+            }
+        }
+        return this;
+    }
+    /**
+     * Sets the shell script to execute in this step.
+     * A bash shebang and `set -euo pipefail` are **not** prepended automatically;
+     * use the {@link bash} or {@link shell} helpers for that behavior.
+     */
+    withScript(script) {
+        this._script = script;
+        return this;
+    }
+    /** Builds the {@link ArtifactStep} message. */
+    build() {
+        return {
+            entrypoint: this._entrypoint,
+            script: this._script,
+            secrets: this._secrets,
+            arguments: this._arguments,
+            artifacts: this._artifacts,
+            environments: this._environments,
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// Artifact
+// ---------------------------------------------------------------------------
+/**
+ * Builder for Artifact messages.
+ * Matches Rust sdk/rust/src/artifact.rs Artifact impl (lines 211-256).
+ */
+export class Artifact {
+    _aliases = [];
+    _name;
+    _sources = [];
+    _steps;
+    _systems;
+    /**
+     * @param name - Artifact name (must be unique within a namespace)
+     * @param steps - Build steps that produce the artifact output
+     * @param systems - Target systems this artifact supports (e.g., `[ArtifactSystem.AARCH64_DARWIN]`)
+     */
+    constructor(name, steps, systems) {
+        this._name = name;
+        this._steps = steps;
+        this._systems = systems;
+    }
+    /**
+     * Adds human-readable aliases for this artifact (e.g., `"my-tool:latest"`).
+     * Duplicates are ignored.
+     *
+     * @param aliases - Array of alias strings in `[namespace/]name[:tag]` format
+     */
+    withAliases(aliases) {
+        for (const alias of aliases) {
+            if (!this._aliases.includes(alias)) {
+                this._aliases.push(alias);
+            }
+        }
+        return this;
+    }
+    /**
+     * Adds source definitions for this artifact. Sources are deduplicated by name.
+     *
+     * @param sources - Array of {@link ArtifactSource} messages
+     */
+    withSources(sources) {
+        for (const source of sources) {
+            if (!this._sources.some((s) => s.name === source.name)) {
+                this._sources.push(source);
+            }
+        }
+        return this;
+    }
+    /**
+     * Builds the artifact, computes its SHA-256 digest, and registers it
+     * with the agent service via the provided {@link ConfigContext}.
+     *
+     * @returns The hex-encoded SHA-256 digest of the artifact
+     */
+    async build(context) {
+        const artifact = {
+            target: context.getSystem(),
+            sources: this._sources,
+            steps: this._steps,
+            systems: this._systems,
+            aliases: this._aliases,
+            name: this._name,
+        };
+        return context.addArtifact(artifact);
+    }
+}
+// ---------------------------------------------------------------------------
+// Job
+// ---------------------------------------------------------------------------
+/**
+ * Builder for Job artifacts (simple script execution).
+ * Matches Rust sdk/rust/src/artifact.rs Job impl (lines 259-297).
+ *
+ * CRITICAL: Secrets are sorted by name before building (Rust line 290).
+ */
+export class Job {
+    _artifacts = [];
+    _name;
+    _secrets = new Map();
+    _script;
+    _systems;
+    /**
+     * @param name - Job artifact name
+     * @param script - Shell script to execute
+     * @param systems - Target systems this job supports
+     */
+    constructor(name, script, systems) {
+        this._name = name;
+        this._script = script;
+        this._systems = systems;
+    }
+    /**
+     * Sets artifact digests whose outputs are available during the job's build step.
+     *
+     * @param artifacts - Array of artifact digest strings
+     */
+    withArtifacts(artifacts) {
+        this._artifacts = artifacts;
+        return this;
+    }
+    /**
+     * Adds secrets available during the job's build step.
+     *
+     * @param secrets - Map of secret name to value
+     */
+    withSecrets(secrets) {
+        for (const [k, v] of secrets) {
+            if (!this._secrets.has(k)) {
+                this._secrets.set(k, v);
+            }
+        }
+        return this;
+    }
+    /**
+     * Builds the job artifact and registers it with the agent service.
+     *
+     * @returns The hex-encoded SHA-256 digest of the artifact
+     */
+    async build(context) {
+        const step = await shell(context, this._artifacts, [], this._script, secretsToProto(this._secrets));
+        return new Artifact(this._name, [step], this._systems).build(context);
+    }
+}
+// ---------------------------------------------------------------------------
+// Process
+// ---------------------------------------------------------------------------
+/**
+ * Builder for Process artifacts.
+ * Matches Rust sdk/rust/src/artifact.rs Process impl (lines 432-553).
+ *
+ * CRITICAL: Shell script template must be character-for-character identical.
+ * Secrets sorted by name (Rust line 477).
+ */
+export class Process {
+    _arguments = [];
+    _artifacts = [];
+    _entrypoint;
+    _name;
+    _secrets = new Map();
+    _systems;
+    /**
+     * @param name - Process artifact name (used for start/stop/logs scripts)
+     * @param entrypoint - Path to the executable to run as a background process
+     * @param systems - Target systems this process supports
+     */
+    constructor(name, entrypoint, systems) {
+        this._name = name;
+        this._entrypoint = entrypoint;
+        this._systems = systems;
+    }
+    /**
+     * Sets command-line arguments passed to the process entrypoint.
+     *
+     * @param args - Array of argument strings
+     */
+    withArguments(args) {
+        this._arguments = args;
+        return this;
+    }
+    /**
+     * Adds artifact dependencies whose bin directories are added to PATH.
+     * Duplicates are ignored.
+     *
+     * @param artifacts - Array of artifact digest strings
+     */
+    withArtifacts(artifacts) {
+        for (const artifact of artifacts) {
+            if (!this._artifacts.includes(artifact)) {
+                this._artifacts.push(artifact);
+            }
+        }
+        return this;
+    }
+    /**
+     * Adds secrets available during the process build step.
+     *
+     * @param secrets - Map of secret name to value
+     */
+    withSecrets(secrets) {
+        for (const [k, v] of secrets) {
+            if (!this._secrets.has(k)) {
+                this._secrets.set(k, v);
+            }
+        }
+        return this;
+    }
+    /**
+     * Builds the process artifact, which includes start/stop/logs helper scripts.
+     *
+     * @returns The hex-encoded SHA-256 digest of the artifact
+     */
+    async build(context) {
+        const argumentsStr = this._arguments.join(" ");
+        const artifactsStr = this._artifacts
+            .map((v) => `$VORPAL_ARTIFACT_${v}/bin`)
+            .join(":");
+        // Script template matches Rust formatdoc! in Process::build()
+        const script = `mkdir -p $VORPAL_OUTPUT/bin
+
+cat > $VORPAL_OUTPUT/bin/${this._name}-logs << "EOF"
+#!/bin/bash
+set -euo pipefail
+
+if [ -f $VORPAL_OUTPUT/logs.txt ]; then
+    tail -f $VORPAL_OUTPUT/logs.txt
+else
+    echo "No logs found"
+fi
+EOF
+
+chmod +x $VORPAL_OUTPUT/bin/${this._name}-logs
+
+cat > $VORPAL_OUTPUT/bin/${this._name}-stop << "EOF"
+#!/bin/bash
+set -euo pipefail
+
+if [ -f $VORPAL_OUTPUT/pid ]; then
+    kill $(cat $VORPAL_OUTPUT/pid)
+    rm -rf $VORPAL_OUTPUT/pid
+fi
+EOF
+
+chmod +x $VORPAL_OUTPUT/bin/${this._name}-stop
+
+cat > $VORPAL_OUTPUT/bin/${this._name}-start << "EOF"
+#!/bin/bash
+set -euo pipefail
+
+export PATH=${artifactsStr}:$PATH
+
+$VORPAL_OUTPUT/bin/${this._name}-stop
+
+echo "Process: ${this._entrypoint} ${argumentsStr}"
+
+nohup ${this._entrypoint} ${argumentsStr} > $VORPAL_OUTPUT/logs.txt 2>&1 &
+
+PROCESS_PID=$!
+
+echo "Process ID: $PROCESS_PID"
+
+echo $PROCESS_PID > $VORPAL_OUTPUT/pid
+
+echo "Process commands:"
+echo "- ${this._name}-logs (tail logs)"
+echo "- ${this._name}-stop (stop process)"
+echo "- ${this._name}-start (start process)"
+EOF
+
+chmod +x $VORPAL_OUTPUT/bin/${this._name}-start`;
+        const step = await shell(context, this._artifacts, [], script, secretsToProto(this._secrets));
+        return new Artifact(this._name, [step], this._systems).build(context);
+    }
+}
+// ---------------------------------------------------------------------------
+// DevelopmentEnvironment
+// ---------------------------------------------------------------------------
+/**
+ * Builder for DevelopmentEnvironment artifacts.
+ * Matches Rust sdk/rust/src/artifact.rs DevelopmentEnvironment impl (lines 300-429).
+ *
+ * CRITICAL: Shell script template must match exactly. Secrets sorted by name.
+ */
+export class DevelopmentEnvironment {
+    _artifacts = [];
+    _environments = [];
+    _name;
+    _secrets = new Map();
+    _systems;
+    /**
+     * @param name - Environment name (shown in shell prompt as `(name)`)
+     * @param systems - Target systems this environment supports
+     */
+    constructor(name, systems) {
+        this._name = name;
+        this._systems = systems;
+    }
+    /**
+     * Sets artifact dependencies whose bin directories are added to PATH.
+     *
+     * @param artifacts - Array of artifact digest strings
+     */
+    withArtifacts(artifacts) {
+        this._artifacts = artifacts;
+        return this;
+    }
+    /**
+     * Sets environment variables exported when the environment is activated.
+     * Format: `"KEY=VALUE"`. PATH entries are handled specially and merged
+     * with artifact bin paths.
+     *
+     * @param environments - Array of environment variable strings
+     */
+    withEnvironments(environments) {
+        this._environments = environments;
+        return this;
+    }
+    /**
+     * Adds secrets available during the environment build step.
+     *
+     * @param secrets - Map of secret name to value
+     */
+    withSecrets(secrets) {
+        for (const [k, v] of secrets) {
+            if (!this._secrets.has(k)) {
+                this._secrets.set(k, v);
+            }
+        }
+        return this;
+    }
+    /**
+     * Builds the development environment artifact, which includes activate/deactivate
+     * scripts for shell integration.
+     *
+     * @returns The hex-encoded SHA-256 digest of the artifact
+     */
+    async build(context) {
+        const envsBackup = [
+            'export VORPAL_SHELL_BACKUP_PATH="$PATH"',
+            'export VORPAL_SHELL_BACKUP_PS1="$PS1"',
+            'export VORPAL_SHELL_BACKUP_VORPAL_SHELL="$VORPAL_SHELL"',
+        ];
+        const envsExport = [
+            `export PS1="(${this._name}) $PS1"`,
+            'export VORPAL_SHELL="1"',
+        ];
+        const envsRestore = [
+            'export PATH="$VORPAL_SHELL_BACKUP_PATH"',
+            'export PS1="$VORPAL_SHELL_BACKUP_PS1"',
+            'export VORPAL_SHELL="$VORPAL_SHELL_BACKUP_VORPAL_SHELL"',
+        ];
+        const envsUnset = [
+            "unset VORPAL_SHELL_BACKUP_PATH",
+            "unset VORPAL_SHELL_BACKUP_PS1",
+            "unset VORPAL_SHELL_BACKUP_VORPAL_SHELL",
+        ];
+        for (const env of this._environments) {
+            const key = env.split("=")[0];
+            if (key === "PATH") {
+                continue;
+            }
+            envsBackup.push(`export VORPAL_SHELL_BACKUP_${key}="\$${key}"`);
+            envsExport.push(`export ${env}`);
+            envsRestore.push(`export ${key}="\$VORPAL_SHELL_BACKUP_${key}"`);
+            envsUnset.push(`unset VORPAL_SHELL_BACKUP_${key}`);
+        }
+        // Setup path
+        const stepPathArtifacts = this._artifacts
+            .map((artifact) => `${getEnvKey(artifact)}/bin`)
+            .join(":");
+        let stepPath = stepPathArtifacts;
+        const pathEnv = this._environments.find((x) => x.startsWith("PATH="));
+        if (pathEnv) {
+            const pathValue = pathEnv.split("=").slice(1).join("=");
+            if (pathValue) {
+                stepPath = `${pathValue}:${stepPath}`;
+            }
+        }
+        envsExport.push(`export PATH=${stepPath}:$PATH`);
+        // Setup script - matches Rust formatdoc!
+        const stepScript = `mkdir -p $VORPAL_WORKSPACE/bin
+
+cat > bin/activate << "EOF"
+#!/bin/bash
+
+${envsBackup.join("\n")}
+${envsExport.join("\n")}
+
+deactivate(){
+${envsRestore.join("\n")}
+${envsUnset.join("\n")}
+}
+
+exec "$@"
+EOF
+
+chmod +x $VORPAL_WORKSPACE/bin/activate
+
+mkdir -p $VORPAL_OUTPUT/bin
+
+cp -pr bin "$VORPAL_OUTPUT"`;
+        const steps = [
+            await shell(context, this._artifacts, [], stepScript, secretsToProto(this._secrets)),
+        ];
+        return new Artifact(this._name, steps, this._systems).build(context);
+    }
+}
+// ---------------------------------------------------------------------------
+// UserEnvironment
+// ---------------------------------------------------------------------------
+/**
+ * Builder for UserEnvironment artifacts.
+ * Matches Rust sdk/rust/src/artifact.rs UserEnvironment impl (lines 556-682).
+ *
+ * CRITICAL: Symlinks MUST be sorted by source path (Rust line 586).
+ */
+export class UserEnvironment {
+    _artifacts = [];
+    _environments = [];
+    _name;
+    _symlinks = [];
+    _systems;
+    /**
+     * @param name - User environment name
+     * @param systems - Target systems this environment supports
+     */
+    constructor(name, systems) {
+        this._name = name;
+        this._systems = systems;
+    }
+    /**
+     * Sets artifact dependencies whose bin directories are added to PATH.
+     *
+     * @param artifacts - Array of artifact digest strings
+     */
+    withArtifacts(artifacts) {
+        this._artifacts = artifacts;
+        return this;
+    }
+    /**
+     * Sets environment variables exported when the user environment is activated.
+     * Format: `"KEY=VALUE"`. PATH entries are handled specially and merged
+     * with artifact bin paths.
+     *
+     * @param environments - Array of environment variable strings
+     */
+    withEnvironments(environments) {
+        this._environments = environments;
+        return this;
+    }
+    /**
+     * Adds symlinks created when the user environment is activated.
+     * Symlinks are sorted by source path before building for deterministic output.
+     *
+     * @param symlinks - Array of `[source, target]` path tuples
+     */
+    withSymlinks(symlinks) {
+        for (const [source, target] of symlinks) {
+            this._symlinks.push([source, target]);
+        }
+        return this;
+    }
+    /**
+     * Builds the user environment artifact, which includes activate/deactivate
+     * scripts and symlink management.
+     *
+     * @returns The hex-encoded SHA-256 digest of the artifact
+     */
+    async build(context) {
+        // Sort for deterministic output -- sorted by source path (index 0)
+        this._symlinks.sort((a, b) => a[0].localeCompare(b[0]));
+        // Setup path
+        const stepPathArtifacts = this._artifacts
+            .map((artifact) => `${getEnvKey(artifact)}/bin`)
+            .join(":");
+        let stepPath = stepPathArtifacts;
+        const pathEnv = this._environments.find((x) => x.startsWith("PATH="));
+        if (pathEnv) {
+            const pathValue = pathEnv.split("=").slice(1).join("=");
+            if (pathValue) {
+                stepPath = `${pathValue}:${stepPath}`;
+            }
+        }
+        // Setup environments for script (filter PATH)
+        const stepEnvironments = this._environments
+            .filter((e) => !e.startsWith("PATH="))
+            .map((e) => `export ${e}`)
+            .join("\n");
+        const symlinksDeactivate = this._symlinks
+            .map(([_, target]) => `rm -f ${target}`)
+            .join("\n");
+        const symlinksCheck = this._symlinks
+            .map(([_, target]) => `if [ -f ${target} ]; then echo "ERROR: Symlink target exists -> ${target}" && exit 1; fi`)
+            .join("\n");
+        const symlinksActivate = this._symlinks
+            .map(([source, target]) => `ln -s ${source} ${target}`)
+            .join("\n");
+        // Script template matches Rust formatdoc! in UserEnvironment::build()
+        const stepScript = `mkdir -p $VORPAL_OUTPUT/bin
+
+cat > $VORPAL_OUTPUT/bin/vorpal-activate-shell << "EOF"
+${stepEnvironments}
+export PATH="$VORPAL_OUTPUT/bin:${stepPath}:$PATH"
+EOF
+
+cat > $VORPAL_OUTPUT/bin/vorpal-deactivate-symlinks << "EOF"
+#!/bin/bash
+set -euo pipefail
+${symlinksDeactivate}
+EOF
+
+cat > $VORPAL_OUTPUT/bin/vorpal-activate-symlinks << "EOF"
+#!/bin/bash
+set -euo pipefail
+${symlinksCheck}
+${symlinksActivate}
+EOF
+
+cat > $VORPAL_OUTPUT/bin/vorpal-activate << "EOF"
+#!/bin/bash
+set -euo pipefail
+
+echo "Deactivating previous symlinks..."
+
+if [ -f $HOME/.vorpal/bin/vorpal-deactivate-symlinks ]; then
+    $HOME/.vorpal/bin/vorpal-deactivate-symlinks
+fi
+
+echo "Activating symlinks..."
+
+$VORPAL_OUTPUT/bin/vorpal-activate-symlinks
+
+echo "Vorpal userenv installed. Run 'source vorpal-activate-shell' to activate."
+
+ln -sf $VORPAL_OUTPUT/bin/vorpal-activate-shell $HOME/.vorpal/bin/vorpal-activate-shell
+ln -sf $VORPAL_OUTPUT/bin/vorpal-activate-symlinks $HOME/.vorpal/bin/vorpal-activate-symlinks
+ln -sf $VORPAL_OUTPUT/bin/vorpal-deactivate-symlinks $HOME/.vorpal/bin/vorpal-deactivate-symlinks
+EOF
+
+
+chmod +x $VORPAL_OUTPUT/bin/vorpal-activate-shell
+chmod +x $VORPAL_OUTPUT/bin/vorpal-deactivate-symlinks
+chmod +x $VORPAL_OUTPUT/bin/vorpal-activate-symlinks
+chmod +x $VORPAL_OUTPUT/bin/vorpal-activate`;
+        const steps = [
+            await shell(context, this._artifacts, [], stepScript, []),
+        ];
+        return new Artifact(this._name, steps, this._systems).build(context);
+    }
+}
+// ---------------------------------------------------------------------------
+// OciImage
+// ---------------------------------------------------------------------------
+/**
+ * Builder for OCI container image artifacts.
+ * Matches Rust sdk/rust/src/artifact/oci_image.rs OciImage impl.
+ *
+ * Produces a container image tarball using crane, rsync, and a rootfs artifact.
+ * Only supports Linux systems (AARCH64_LINUX, X8664_LINUX).
+ */
+export class OciImage {
+    _aliases = [];
+    _artifacts = [];
+    _crane = undefined;
+    _name;
+    _rootfs;
+    _rsync = undefined;
+    /**
+     * @param name - OCI image name (must be lowercase, valid chars: a-z, 0-9, / : - . _)
+     * @param rootfs - Artifact digest for the rootfs base layer
+     */
+    constructor(name, rootfs) {
+        this._name = name;
+        this._rootfs = rootfs;
+    }
+    /**
+     * Adds human-readable aliases for this image artifact.
+     *
+     * @param aliases - Array of alias strings
+     */
+    withAliases(aliases) {
+        this._aliases = aliases;
+        return this;
+    }
+    /**
+     * Sets artifact digests to include as layers in the container image.
+     * Each artifact's bin directory is symlinked into /usr/local/bin.
+     *
+     * @param artifacts - Array of artifact digest strings
+     */
+    withArtifacts(artifacts) {
+        this._artifacts = artifacts;
+        return this;
+    }
+    /**
+     * Overrides the default crane artifact used for building the OCI image.
+     * When not set, crane is fetched from the registry alias "crane:0.21.1".
+     *
+     * @param crane - Artifact digest for crane
+     */
+    withCrane(crane) {
+        this._crane = crane;
+        return this;
+    }
+    /**
+     * Overrides the default rsync artifact used for building the OCI image.
+     * When not set, rsync is fetched from the registry alias "rsync:3.4.1".
+     *
+     * @param rsync - Artifact digest for rsync
+     */
+    withRsync(rsync) {
+        this._rsync = rsync;
+        return this;
+    }
+    /**
+     * Builds the OCI image artifact and registers it with the agent service.
+     *
+     * Fetches crane and rsync as pre-built aliases from the registry,
+     * generates the build script, and creates the artifact.
+     *
+     * @returns The hex-encoded SHA-256 digest of the artifact
+     */
+    async build(context) {
+        // Validate image name (matches Rust validation)
+        if (this._name !== this._name.toLowerCase()) {
+            throw new Error(`container image name must be lowercase: '${this._name}'`);
+        }
+        for (const c of this._name) {
+            if (!((c >= "a" && c <= "z") ||
+                (c >= "0" && c <= "9") ||
+                c === "/" ||
+                c === ":" ||
+                c === "-" ||
+                c === "." ||
+                c === "_")) {
+                throw new Error(`container image name invalid character '${c}': '${this._name}'. ` +
+                    `Allowed: lowercase letters, digits, and / : - . _`);
+            }
+        }
+        const crane = this._crane ?? await context.fetchArtifactAlias("crane:0.21.1");
+        const rsync = this._rsync ?? await context.fetchArtifactAlias("rsync:3.4.1");
+        const artifactsList = this._artifacts.join(" ");
+        const namespace = context.getArtifactNamespace();
+        const stepScript = `OCI_IMAGE_ARTIFACTS="${artifactsList}"
+OCI_IMAGE_CRANE="${getEnvKey(crane)}"
+OCI_IMAGE_NAME="${this._name}"
+OCI_IMAGE_ROOTFS="${getEnvKey(this._rootfs)}"
+OCI_IMAGE_RSYNC="${getEnvKey(rsync)}"
+OUTPUT_TAR=\${PWD}/rootfs.tar
+ROOTFS_DIR=\${PWD}/rootfs
+STORE_PREFIX=var/lib/vorpal/store/artifact/output/${namespace}
+
+# Detect platform based on build architecture
+case "$(uname -m)" in
+    x86_64)  OCI_PLATFORM="linux/amd64" ;;
+    aarch64) OCI_PLATFORM="linux/arm64" ;;
+    *)       OCI_PLATFORM="linux/$(uname -m)" ;;
+esac
+
+mkdir -p \${ROOTFS_DIR}
+
+for artifact in \${OCI_IMAGE_ARTIFACTS}; do
+    SOURCE_DIR=/\${STORE_PREFIX}/\${artifact}
+    TARGET_PATH=\${STORE_PREFIX}/\${artifact}
+
+    mkdir -p \${ROOTFS_DIR}/\${TARGET_PATH}
+
+    echo "Copying artifact layer \${artifact}..."
+
+    \${OCI_IMAGE_RSYNC}/bin/rsync -aW \${SOURCE_DIR}/ \${ROOTFS_DIR}/\${TARGET_PATH}
+
+    echo "Copied artifact layer \${artifact}"
+
+    # Symlink bin files to /usr/local/bin
+    if [ -d "\${SOURCE_DIR}/bin" ]; then
+        mkdir -p \${ROOTFS_DIR}/usr/local/bin
+        for bin_file in \${SOURCE_DIR}/bin/*; do
+            if [ -f "\${bin_file}" ]; then
+                bin_name=$(basename "\${bin_file}")
+                ln -sf /\${TARGET_PATH}/bin/\${bin_name} \${ROOTFS_DIR}/usr/local/bin/\${bin_name}
+                echo "Symlinked \${bin_name} to /usr/local/bin"
+            fi
+        done
+    fi
+done
+
+echo "Copying Vorpal operating system files..."
+
+\${OCI_IMAGE_RSYNC}/bin/rsync -aW \${OCI_IMAGE_ROOTFS}/ \${ROOTFS_DIR}
+
+echo "Copied Vorpal operating system files"
+
+echo "Creating output tarball..."
+
+tar -cf \${OUTPUT_TAR} -C \${ROOTFS_DIR} .
+
+echo "Created output tarball"
+
+mkdir -p \${VORPAL_OUTPUT}
+
+echo "Creating OCI image \${OCI_IMAGE_NAME}:latest"
+
+\${OCI_IMAGE_CRANE}/bin/crane append \\
+    --new_layer \${OUTPUT_TAR} \\
+    --new_tag \${OCI_IMAGE_NAME}:latest \\
+    --oci-empty-base \\
+    --output \${VORPAL_OUTPUT}/image.tar \\
+    --platform \${OCI_PLATFORM}
+
+echo "Setting platform metadata in image config..."
+
+# Extract tarball to modify config (crane mutate cannot work with local files)
+WORK_DIR=\${PWD}/image-work
+mkdir -p \${WORK_DIR}
+tar -xf \${VORPAL_OUTPUT}/image.tar -C \${WORK_DIR}
+
+# Get config filename from manifest
+CONFIG_FILE=$(sed -n 's/.*"Config":"\\([^"]*\\)".*/\\1/p' \${WORK_DIR}/manifest.json)
+
+# Detect architecture for config metadata
+case "$(uname -m)" in
+    x86_64)  CONFIG_ARCH="amd64" ;;
+    aarch64) CONFIG_ARCH="arm64" ;;
+    *)       CONFIG_ARCH="$(uname -m)" ;;
+esac
+
+# Modify config to set platform (crane append leaves these empty)
+sed -i "s/\\"architecture\\":\\"\\"/\\"architecture\\":\\"\${CONFIG_ARCH}\\"/" \${WORK_DIR}/\${CONFIG_FILE}
+sed -i "s/\\"os\\":\\"\\"/\\"os\\":\\"linux\\"/" \${WORK_DIR}/\${CONFIG_FILE}
+
+# Compute new hash and rename config file
+NEW_HASH=$(sha256sum \${WORK_DIR}/\${CONFIG_FILE} | awk '{print $1}')
+NEW_CONFIG="sha256:\${NEW_HASH}"
+mv \${WORK_DIR}/\${CONFIG_FILE} \${WORK_DIR}/\${NEW_CONFIG}
+
+# Update manifest with new config reference
+sed -i "s|\${CONFIG_FILE}|\${NEW_CONFIG}|" \${WORK_DIR}/manifest.json
+
+# Repackage tarball
+pushd \${WORK_DIR}
+tar -cf \${VORPAL_OUTPUT}/image.tar manifest.json \${NEW_CONFIG} *.tar.gz
+popd
+
+# Cleanup
+rm -rf \${WORK_DIR}
+
+echo "Created OCI image \${OCI_IMAGE_NAME}:latest"`;
+        const stepArtifacts = [crane, rsync, this._rootfs, ...this._artifacts];
+        const step = await shell(context, stepArtifacts, [], stepScript, []);
+        const systems = [
+            ArtifactSystem.AARCH64_LINUX,
+            ArtifactSystem.X8664_LINUX,
+        ];
+        return new Artifact(this._name, [step], systems)
+            .withAliases(this._aliases)
+            .build(context);
+    }
+}
+// ---------------------------------------------------------------------------
+// Argument
+// ---------------------------------------------------------------------------
+/**
+ * Argument builder for artifact variables.
+ * Matches Rust sdk/rust/src/artifact.rs Argument impl.
+ */
+export class Argument {
+    _name;
+    _require = false;
+    /**
+     * @param name - The variable name to look up in the context
+     */
+    constructor(name) {
+        this._name = name;
+    }
+    /**
+     * Marks this argument as required. If the variable is not set in the
+     * context when {@link Argument.build} is called, an error is thrown.
+     */
+    withRequire() {
+        this._require = true;
+        return this;
+    }
+    /**
+     * Resolves the argument value from the {@link ConfigContext}.
+     *
+     * @returns The variable value, or `undefined` if not set and not required
+     * @throws If the variable is required but not set
+     */
+    build(context) {
+        const variable = context.getVariable(this._name);
+        if (this._require && variable === undefined) {
+            throw new Error(`variable '${this._name}' is required`);
+        }
+        return variable;
+    }
+}
+//# sourceMappingURL=artifact.js.map