@altf4llc/vorpal-sdk 0.1.0-alpha.0

package/dist/artifact.d.ts

@@ -0,0 +1,392 @@
+import type { ArtifactSource as ArtifactSourceMsg, ArtifactStep as ArtifactStepMsg, ArtifactStepSecret } from "./api/artifact/artifact.js";
+import { ArtifactSystem } from "./api/artifact/artifact.js";
+import type { ConfigContext } from "./context.js";
+/**
+ * Returns the environment variable key for an artifact digest.
+ * Matches Rust get_env_key() and Go GetEnvKey().
+ */
+export declare function getEnvKey(digest: string): string;
+/**
+ * Converts a Map of secrets to a sorted array of proto objects.
+ * Matches Go SDK's SecretsToProto function.
+ */
+export declare function secretsToProto(secrets: Map<string, string>): ArtifactStepSecret[];
+/**
+ * Builder for ArtifactSource messages.
+ * Matches Rust sdk/rust/src/artifact.rs ArtifactSource impl.
+ */
+export declare class ArtifactSource {
+    private _digest;
+    private _excludes;
+    private _includes;
+    private _name;
+    private _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: string, path: string);
+    /**
+     * Sets a pre-computed digest for this source.
+     * When set, the agent skips re-hashing the source contents.
+     */
+    withDigest(digest: string): 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: string[]): 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: string[]): this;
+    /** Builds the {@link ArtifactSource} message. */
+    build(): ArtifactSourceMsg;
+}
+/**
+ * Builder for ArtifactStep messages.
+ * Matches Rust sdk/rust/src/artifact.rs ArtifactStep impl.
+ */
+export declare class ArtifactStep {
+    private _arguments;
+    private _artifacts;
+    private _entrypoint;
+    private _environments;
+    private _secrets;
+    private _script;
+    /**
+     * @param entrypoint - The executable entrypoint (e.g., `"bash"`, `"bwrap"`, `"docker"`)
+     */
+    constructor(entrypoint: string);
+    /**
+     * Sets command-line arguments passed to the entrypoint.
+     *
+     * @param args - Array of argument strings
+     */
+    withArguments(args: string[]): 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: string[]): this;
+    /**
+     * Sets environment variables for the step execution.
+     * Format: `"KEY=VALUE"`.
+     *
+     * @param environments - Array of environment variable strings
+     */
+    withEnvironments(environments: string[]): this;
+    /**
+     * Adds secrets available during the step. Secrets are deduplicated by name.
+     *
+     * @param secrets - Array of {@link ArtifactStepSecret} objects
+     */
+    withSecrets(secrets: ArtifactStepSecret[]): 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: string): this;
+    /** Builds the {@link ArtifactStep} message. */
+    build(): ArtifactStepMsg;
+}
+/**
+ * Builder for Artifact messages.
+ * Matches Rust sdk/rust/src/artifact.rs Artifact impl (lines 211-256).
+ */
+export declare class Artifact {
+    private _aliases;
+    private _name;
+    private _sources;
+    private _steps;
+    private _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: string, steps: ArtifactStepMsg[], systems: ArtifactSystem[]);
+    /**
+     * 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: string[]): this;
+    /**
+     * Adds source definitions for this artifact. Sources are deduplicated by name.
+     *
+     * @param sources - Array of {@link ArtifactSource} messages
+     */
+    withSources(sources: ArtifactSourceMsg[]): 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
+     */
+    build(context: ConfigContext): Promise<string>;
+}
+/**
+ * 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 declare class Job {
+    private _artifacts;
+    private _name;
+    private _secrets;
+    private _script;
+    private _systems;
+    /**
+     * @param name - Job artifact name
+     * @param script - Shell script to execute
+     * @param systems - Target systems this job supports
+     */
+    constructor(name: string, script: string, systems: ArtifactSystem[]);
+    /**
+     * Sets artifact digests whose outputs are available during the job's build step.
+     *
+     * @param artifacts - Array of artifact digest strings
+     */
+    withArtifacts(artifacts: string[]): this;
+    /**
+     * Adds secrets available during the job's build step.
+     *
+     * @param secrets - Map of secret name to value
+     */
+    withSecrets(secrets: Map<string, string>): this;
+    /**
+     * Builds the job artifact and registers it with the agent service.
+     *
+     * @returns The hex-encoded SHA-256 digest of the artifact
+     */
+    build(context: ConfigContext): Promise<string>;
+}
+/**
+ * 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 declare class Process {
+    private _arguments;
+    private _artifacts;
+    private _entrypoint;
+    private _name;
+    private _secrets;
+    private _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: string, entrypoint: string, systems: ArtifactSystem[]);
+    /**
+     * Sets command-line arguments passed to the process entrypoint.
+     *
+     * @param args - Array of argument strings
+     */
+    withArguments(args: string[]): this;
+    /**
+     * Adds artifact dependencies whose bin directories are added to PATH.
+     * Duplicates are ignored.
+     *
+     * @param artifacts - Array of artifact digest strings
+     */
+    withArtifacts(artifacts: string[]): this;
+    /**
+     * Adds secrets available during the process build step.
+     *
+     * @param secrets - Map of secret name to value
+     */
+    withSecrets(secrets: Map<string, string>): this;
+    /**
+     * Builds the process artifact, which includes start/stop/logs helper scripts.
+     *
+     * @returns The hex-encoded SHA-256 digest of the artifact
+     */
+    build(context: ConfigContext): Promise<string>;
+}
+/**
+ * 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 declare class DevelopmentEnvironment {
+    private _artifacts;
+    private _environments;
+    private _name;
+    private _secrets;
+    private _systems;
+    /**
+     * @param name - Environment name (shown in shell prompt as `(name)`)
+     * @param systems - Target systems this environment supports
+     */
+    constructor(name: string, systems: ArtifactSystem[]);
+    /**
+     * Sets artifact dependencies whose bin directories are added to PATH.
+     *
+     * @param artifacts - Array of artifact digest strings
+     */
+    withArtifacts(artifacts: string[]): 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: string[]): this;
+    /**
+     * Adds secrets available during the environment build step.
+     *
+     * @param secrets - Map of secret name to value
+     */
+    withSecrets(secrets: Map<string, string>): this;
+    /**
+     * Builds the development environment artifact, which includes activate/deactivate
+     * scripts for shell integration.
+     *
+     * @returns The hex-encoded SHA-256 digest of the artifact
+     */
+    build(context: ConfigContext): Promise<string>;
+}
+/**
+ * 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 declare class UserEnvironment {
+    private _artifacts;
+    private _environments;
+    private _name;
+    private _symlinks;
+    private _systems;
+    /**
+     * @param name - User environment name
+     * @param systems - Target systems this environment supports
+     */
+    constructor(name: string, systems: ArtifactSystem[]);
+    /**
+     * Sets artifact dependencies whose bin directories are added to PATH.
+     *
+     * @param artifacts - Array of artifact digest strings
+     */
+    withArtifacts(artifacts: string[]): 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: string[]): 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: Array<[string, string]>): this;
+    /**
+     * Builds the user environment artifact, which includes activate/deactivate
+     * scripts and symlink management.
+     *
+     * @returns The hex-encoded SHA-256 digest of the artifact
+     */
+    build(context: ConfigContext): Promise<string>;
+}
+/**
+ * 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 declare class OciImage {
+    private _aliases;
+    private _artifacts;
+    private _crane;
+    private _name;
+    private _rootfs;
+    private _rsync;
+    /**
+     * @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: string, rootfs: string);
+    /**
+     * Adds human-readable aliases for this image artifact.
+     *
+     * @param aliases - Array of alias strings
+     */
+    withAliases(aliases: string[]): 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: string[]): 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: string): 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: string): 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
+     */
+    build(context: ConfigContext): Promise<string>;
+}
+/**
+ * Argument builder for artifact variables.
+ * Matches Rust sdk/rust/src/artifact.rs Argument impl.
+ */
+export declare class Argument {
+    private _name;
+    private _require;
+    /**
+     * @param name - The variable name to look up in the context
+     */
+    constructor(name: string);
+    /**
+     * 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;
+    /**
+     * 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: ConfigContext): string | undefined;
+}
+//# sourceMappingURL=artifact.d.ts.map

package/dist/artifact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact.d.ts","sourceRoot":"","sources":["../src/artifact.ts"],"names":[],"mappings":"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"}