@scarn/sdk 0.0.0-stage → 0.8.0

package/dist/definitions/steps/env.d.ts

@@ -0,0 +1,136 @@
+import { type EnvVarApplies, type EnvVarsInput } from "../../env-vars";
+import { type PromptInputProxy } from "./prompt-template";
+/**
+ * True for names that look like they hold a credential. A static (input-free)
+ * literal on such a name is rejected at definition time unless the author opts
+ * in with `unsafeAllowStatic`.
+ */
+export declare function isSecretLookingEnvName(name: string): boolean;
+/**
+ * Which process a variable reaches. `agent` (the default) is the agent or code
+ * step process. `setup` is only the `devcontainer up` process, where
+ * `initializeCommand` runs; it overrides the worker's own variable of the same
+ * name and is not added to the container, so forward it with
+ * `${localEnv:NAME:default}` in `devcontainer.json` if the container needs it.
+ * `both` is both. `setup` and `both` are rejected on `Runtime.host()`, which
+ * has no container to set up.
+ */
+export type EnvAppliesOpt = {
+    readonly applies?: EnvVarApplies;
+};
+export type ValueOpts = EnvAppliesOpt & {
+    readonly value: string;
+    readonly secret?: boolean;
+    /**
+     * Allows a static (input-free) value on a secret-looking name such as
+     * `API_TOKEN`. Never serialized. A static value is still stored in
+     * plaintext, so only use this for values that are not actually secret.
+     */
+    readonly unsafeAllowStatic?: boolean;
+};
+/**
+ * `secret: true` and `default` are mutually exclusive: a default is stored in
+ * the definition in plaintext.
+ */
+export type InheritOpts = EnvAppliesOpt & ({
+    readonly from?: string;
+    readonly secret: true;
+    readonly optional?: boolean;
+    readonly default?: never;
+} | {
+    readonly from?: string;
+    readonly secret?: false;
+    readonly optional?: boolean;
+    readonly default?: string;
+});
+export type EnvValue<TSecret extends boolean = boolean> = {
+    readonly kind: "value";
+    readonly value: string;
+    readonly secret: TSecret;
+    readonly unsafeAllowStatic: boolean;
+    readonly applies: EnvVarApplies;
+};
+export type EnvInherit<TSecret extends boolean = boolean, TOptional extends boolean = boolean, TDefault extends string | undefined = string | undefined> = {
+    readonly kind: "inherit";
+    readonly from: string | undefined;
+    readonly secret: TSecret;
+    readonly optional: TOptional;
+    readonly default: TDefault;
+    readonly applies: EnvVarApplies;
+};
+export type EnvEntry = string | EnvValue | EnvInherit;
+export type EnvRecord = Record<string, EnvEntry>;
+/** Runs once at definition time, against the same input proxy `agentPrompt` uses. */
+export type EnvFn<TInput, TEnv extends EnvRecord = EnvRecord> = (context: {
+    input: PromptInputProxy<TInput>;
+}) => TEnv;
+type SecretOf<O> = O extends {
+    secret: infer S;
+} ? S extends false ? false : true : false;
+type OptionalOf<O> = O extends {
+    optional: infer P;
+} ? P extends false ? false : true : false;
+type DefaultOf<O> = O extends {
+    default: infer D extends string;
+} ? D : undefined;
+type PromptEntryValue<E> = E extends {
+    kind: "inherit";
+} ? E extends {
+    default: string;
+} ? string : E extends {
+    optional: false;
+} ? string : string | undefined : string;
+/**
+ * The `env` object an `agentPrompt` callback receives when the step declares
+ * `environment.vars`: only declared, non-secret keys. An entry whose secrecy is
+ * not provably `false` is dropped.
+ */
+export type PromptEnv<TEnv extends EnvRecord> = {
+    [K in keyof TEnv as TEnv[K] extends string ? K : TEnv[K] extends {
+        secret: false;
+    } ? K : never]: PromptEntryValue<TEnv[K]>;
+};
+/**
+ * The prompt `env` type for a step: strict (`PromptEnv`) once
+ * `environment.vars` is declared, today's loose record otherwise. Undeclared
+ * `vars` leaves `TEnv` at its `EnvRecord` default, whose index signature is the
+ * marker.
+ */
+export type PromptEnvContext<TEnv extends EnvRecord> = string extends keyof TEnv ? PromptInputProxy<Record<string, string | undefined>> : PromptEnv<TEnv>;
+export declare const Env: {
+    /**
+     * A literal or `{{input.…}}` template value. Same as writing a bare string,
+     * with an explicit `secret` flag.
+     *
+     * - Source: the step definition itself, rendered against the run's input.
+     * - Stored: yes, as the template, in plaintext. Visible in the API and UI.
+     * - Masked: in logs, when `secret` is true. A secret must contain an
+     *   `{{input.…}}` token, because a static secret would be stored in
+     *   plaintext.
+     */
+    readonly value: <const O extends ValueOpts>(opts: O) => EnvValue<SecretOf<O>>;
+    /**
+     * Reads the variable from the **worker** host (`.scarn/.env`, then
+     * `process.env`), not from the devcontainer's `containerEnv`. The name
+     * defaults to the key; `from` renames it.
+     *
+     * - Source: the worker environment at run time.
+     * - Stored: only the variable name (plus `default`, which is plaintext).
+     * - Masked: in logs, when `secret` is true. A secret cannot carry a
+     *   `default`.
+     *
+     * A required variable that is missing from the worker fails the step before
+     * it starts; `optional` omits it, and `default` fills it.
+     *
+     * `applies: "setup"` hands it to `devcontainer up` instead of the agent, for
+     * example to steer the repo's `initializeCommand`.
+     */
+    readonly inherit: <const O extends InheritOpts = Record<never, never>>(opts?: O) => EnvInherit<SecretOf<O>, OptionalOf<O>, DefaultOf<O>>;
+};
+/**
+ * Runs the authored `environment.vars` function once and returns the wire
+ * shape, or `null` when the step declares no `vars` (or an empty record).
+ * Throws on a static secret, or a static literal on a secret-looking name.
+ */
+export declare function normalizeEnv<TInput>(fn: EnvFn<TInput> | undefined): EnvVarsInput | null;
+export {};

package/dist/definitions/steps/index.d.ts

@@ -0,0 +1,14 @@
+export * as z from "../../z";
+export * from "../artifacts";
+export * from "./define-step";
+export * from "./define-code-step";
+export * from "./step-handle";
+export * from "./step-ref";
+export * from "./define-mcp";
+export { compileMcps, type CompiledMcps } from "./compile-mcps";
+export * from "./env";
+export * from "./prompt-template";
+export * from "./repo";
+export * from "./runtime";
+export * from "./step-definitions-client";
+export * from "./step-features";

package/dist/definitions/steps/index.js

@@ -0,0 +1,76 @@
+// @bun
+import {
+  ARTIFACT_BRAND,
+  Artifact,
+  ArtifactTypes,
+  Env,
+  Features,
+  Notify,
+  Repo,
+  Runtime,
+  artifact,
+  codeStep,
+  compileEnvironment,
+  compileMcps,
+  compileRepo,
+  compileStepErrors,
+  compileStepRetry,
+  createPromptInputProxy,
+  createPromptTemplateContext,
+  createStepDefinitionsClient,
+  defineMcp,
+  defineStep,
+  exports_z,
+  isMcpHandle,
+  isSecretLookingEnvName,
+  normalizeArtifactAccept,
+  normalizeEnv,
+  renderPromptTemplate,
+  resolveMcpChecks,
+  toStepHandle,
+  toStepSpec
+} from "../../chunk-3ctaaseb.js";
+import"../../chunk-mz53r914.js";
+import"../../chunk-5zsavw98.js";
+import"../../chunk-4ggr8af6.js";
+import"../../chunk-k4y5qt4y.js";
+import"../../chunk-cdanncng.js";
+import"../../chunk-e1h021kq.js";
+import"../../chunk-63f90zky.js";
+import"../../chunk-ngy1fdcx.js";
+import"../../chunk-y2pv8d6a.js";
+import"../../chunk-dp86pa6m.js";
+import"../../chunk-vfeytkqx.js";
+import"../../chunk-skzxcba3.js";
+import"../../chunk-y64skrwp.js";
+export {
+  ARTIFACT_BRAND,
+  Artifact,
+  ArtifactTypes,
+  Env,
+  Features,
+  Notify,
+  Repo,
+  Runtime,
+  artifact,
+  codeStep,
+  compileEnvironment,
+  compileMcps,
+  compileRepo,
+  compileStepErrors,
+  compileStepRetry,
+  createPromptInputProxy,
+  createPromptTemplateContext,
+  createStepDefinitionsClient,
+  defineMcp,
+  defineStep,
+  isMcpHandle,
+  isSecretLookingEnvName,
+  normalizeArtifactAccept,
+  normalizeEnv,
+  renderPromptTemplate,
+  resolveMcpChecks,
+  toStepHandle,
+  toStepSpec,
+  exports_z as z
+};

package/dist/definitions/steps/mcp-server-config.d.ts

@@ -0,0 +1,102 @@
+import type { z } from "zod";
+declare const refFieldsSchema: z.ZodObject<{
+    timeout: z.ZodOptional<z.ZodObject<{
+        startup: z.ZodOptional<z.ZodInt>;
+        catalog: z.ZodOptional<z.ZodInt>;
+        execution: z.ZodOptional<z.ZodInt>;
+    }, z.core.$strict>>;
+    protocol: z.ZodOptional<z.ZodEnum<{
+        auto: "auto";
+        legacy: "legacy";
+        "2026-07-28": "2026-07-28";
+    }>>;
+    codemode: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+declare const localFieldsSchema: z.ZodObject<{
+    timeout: z.ZodOptional<z.ZodObject<{
+        startup: z.ZodOptional<z.ZodInt>;
+        catalog: z.ZodOptional<z.ZodInt>;
+        execution: z.ZodOptional<z.ZodInt>;
+    }, z.core.$strict>>;
+    command: z.ZodArray<z.ZodString>;
+    protocol: z.ZodOptional<z.ZodEnum<{
+        auto: "auto";
+        legacy: "legacy";
+        "2026-07-28": "2026-07-28";
+    }>>;
+    cwd: z.ZodOptional<z.ZodString>;
+    environment: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    codemode: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+declare const remoteFieldsSchema: z.ZodObject<{
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    url: z.ZodString;
+    timeout: z.ZodOptional<z.ZodObject<{
+        startup: z.ZodOptional<z.ZodInt>;
+        catalog: z.ZodOptional<z.ZodInt>;
+        execution: z.ZodOptional<z.ZodInt>;
+    }, z.core.$strict>>;
+    protocol: z.ZodOptional<z.ZodEnum<{
+        auto: "auto";
+        legacy: "legacy";
+        "2026-07-28": "2026-07-28";
+    }>>;
+    oauth: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        client_id: z.ZodOptional<z.ZodString>;
+        client_secret: z.ZodOptional<z.ZodString>;
+        scope: z.ZodOptional<z.ZodString>;
+        callback_port: z.ZodOptional<z.ZodInt>;
+        redirect_uri: z.ZodOptional<z.ZodString>;
+        auth_server_metadata_url: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodLiteral<false>]>>;
+    codemode: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+/** The shared OpenCode fields a `ref` applies on top of the repo's definition. */
+export type McpRefServerFields = z.output<typeof refFieldsSchema>;
+/** A `local` server: `command`, `cwd?`, `environment?` and the shared fields. */
+export type McpLocalServerFields = z.output<typeof localFieldsSchema>;
+/** A `remote` server: `url`, `headers?`, `oauth?` and the shared fields. */
+export type McpRemoteServerFields = z.output<typeof remoteFieldsSchema>;
+export type McpServerType = "ref" | "local" | "remote";
+/**
+ * A `defineMcp` server. For `ref`, `name` is the server's name in the repo's
+ * MCP config. For `local`/`remote`, `name` only labels the server in errors;
+ * the step's `mcps` key names it at runtime.
+ */
+export type McpServerDefinition = {
+    readonly type: "ref";
+    readonly name: string;
+    readonly server: Readonly<McpRefServerFields>;
+} | {
+    readonly type: "local";
+    readonly name: string;
+    readonly server: Readonly<McpLocalServerFields>;
+} | {
+    readonly type: "remote";
+    readonly name: string;
+    readonly server: Readonly<McpRemoteServerFields>;
+};
+export type McpServerConfig = ({
+    type: "ref";
+    name: string;
+} & z.input<typeof refFieldsSchema>) | ({
+    type: "local";
+    name: string;
+} & z.input<typeof localFieldsSchema>) | ({
+    type: "remote";
+    name: string;
+} & z.input<typeof remoteFieldsSchema>);
+/**
+ * The `{env:VAR}` names an inline server reads, which compile into required
+ * env entries tagged with the server's key. Empty for a `ref`: the worker
+ * infers those from the repo's definition.
+ */
+export declare function inferredMcpEnv(definition: McpServerDefinition): string[];
+/**
+ * Validates a `defineMcp` config's server half and returns it with its
+ * OpenCode fields parsed. Throws on an unknown `type`, an invalid field, a
+ * literal (non-`{env:VAR}`) `environment` or `headers` value, or a
+ * placeholder naming an invalid or reserved variable.
+ */
+export declare function parseMcpServer(config: McpServerConfig): McpServerDefinition;
+export {};

package/dist/definitions/steps/prompt-template.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Type that maps T to a string-embeddable proxy shape.
+ * `-?` strips optionality so `input.user?.email` and `input.user.email` both work —
+ * the proxy is never nullish, so optional chaining is a no-op at definition time.
+ * `& string` lets each node embed in template literals (`${input.title}`).
+ */
+export type PromptInputProxy<T> = {
+    [K in keyof T]-?: PromptInputProxy<NonNullable<T[K]>>;
+} & string;
+export type PromptTemplateContext<TInput, TPromptEnv = PromptInputProxy<Record<string, string | undefined>>> = {
+    input: PromptInputProxy<TInput>;
+    env: TPromptEnv;
+    scarn: {
+        artifactsDir: string;
+    };
+};
+export declare function createPromptInputProxy<T>(path?: string[]): PromptInputProxy<T>;
+export declare function createPromptTemplateContext<TInput, TPromptEnv = PromptInputProxy<Record<string, string | undefined>>>(): PromptTemplateContext<TInput, TPromptEnv>;
+/**
+ * Renders a prompt template string by replacing `{{dot.path}}` tokens with
+ * values resolved from the provided context object. Missing or null values
+ * are replaced with an empty string.
+ */
+export declare function renderPromptTemplate(template: string, contextJson: unknown): string;

package/dist/definitions/steps/repo.d.ts

@@ -0,0 +1,67 @@
+import { type RepoConfigInput } from "../../repo-config";
+import { type PromptInputProxy } from "./prompt-template";
+import type { RuntimeSpec } from "./runtime";
+/**
+ * Authoring helpers for a step's `environment.repo` option, and the
+ * definition-time compilation that turns it into the `repo` wire field
+ * (`../../repo-config.ts`).
+ */
+/** The step gets no repository: no clone, branch, commit or push. */
+export type NoneRepoSpec = {
+    readonly mode: "none";
+};
+/** Clones and checks out the base branch; creates no branch, commits and pushes nothing. */
+export type ReadOnlyRepoSpec = {
+    readonly mode: "readOnly";
+};
+export type ReadWriteRepoSpec = {
+    readonly mode: "readWrite";
+    /**
+     * Commit message template; `{{input.…}}` and `{{result.…}}` tokens only, one
+     * line, at most 500 characters. Defaults to `scarn: task <taskId>`.
+     */
+    readonly message?: string;
+    /** Defaults to `"fail"`: a failed push fails the step. */
+    readonly onPushFailure?: "fail" | "warn";
+};
+export type RepoSpec = NoneRepoSpec | ReadOnlyRepoSpec | ReadWriteRepoSpec;
+/** What `Runtime.devcontainer()` accepts. */
+export type DevcontainerRepoSpec = ReadOnlyRepoSpec | ReadWriteRepoSpec;
+/** What `Runtime.host()` accepts. */
+export type HostRepoSpec = NoneRepoSpec;
+/** Runs once at definition time, against the same proxies `agentPrompt` and `vars` use. */
+export type RepoFn<TInput, TResult, TSpec extends RepoSpec> = (context: {
+    input: PromptInputProxy<TInput>;
+    result: PromptInputProxy<TResult>;
+}) => TSpec;
+export type RepoField<TInput, TResult, TSpec extends RepoSpec> = TSpec | RepoFn<TInput, TResult, TSpec>;
+export type ReadWriteRepoOpts = Omit<ReadWriteRepoSpec, "mode">;
+export declare const Repo: {
+    /**
+     * The step gets no repository. What `Runtime.host()` already implies, stated
+     * as a value. Only valid with `Runtime.host()`.
+     */
+    readonly none: () => NoneRepoSpec;
+    /**
+     * Clones and checks out the base branch, but creates no work branch, commits
+     * nothing, pushes nothing and reports no `workBranch`. A policy, not a
+     * sandbox: edits the agent makes stay in the workspace and are discarded.
+     */
+    readonly readOnly: () => ReadOnlyRepoSpec;
+    /**
+     * Creates a work branch, then commits and pushes it when the step succeeds.
+     * This is the default for a devcontainer step.
+     */
+    readonly readWrite: (opts?: ReadWriteRepoOpts) => ReadWriteRepoSpec;
+};
+export type CompileRepoContext = {
+    /** Named in error messages. */
+    readonly stepKey?: string;
+};
+/**
+ * Runs the authored `environment.repo` once (the function form against `input`
+ * and `result` proxies) and returns the wire shape, or `undefined` when the step
+ * declares no `repo`. Throws when the mode does not fit the runtime or breaks
+ * the `repoConfigInputSchema` rules.
+ */
+export declare function compileRepo<TInput, TResult>(repo: RepoField<TInput, TResult, RepoSpec> | undefined, runtime: RuntimeSpec | undefined, ctx?: CompileRepoContext): RepoConfigInput | undefined;

package/dist/definitions/steps/runtime.d.ts

@@ -0,0 +1,115 @@
+import type { EnvVarsInput } from "../../env-vars";
+import { type ManagedRuntimeId } from "../../managed-runtimes";
+import type { RepoConfigInput } from "../../repo-config";
+import { type EnvFn, type EnvRecord } from "./env";
+import { type CompileRepoContext, type DevcontainerRepoSpec, type HostRepoSpec, type RepoField } from "./repo";
+/**
+ * Authoring helpers for a step's `environment` option, and the definition-time
+ * compilation that turns it into the wire fields `executionMode`,
+ * `managedRuntime`, `devcontainerConfigPath`, `envJson` and `repo`.
+ */
+/** Where a step runs. Build one with `Runtime.devcontainer()`, `Runtime.host()` or `Runtime.managed.<id>()`. */
+export type DevcontainerRuntimeSpec = {
+    readonly kind: "devcontainer";
+    readonly config?: string;
+};
+export type HostRuntimeSpec = {
+    readonly kind: "host";
+};
+/**
+ * A worker-supplied container (image, config and dependency install owned by
+ * the worker). Build one with `Runtime.managed.<id>()`. `codeStep` only.
+ */
+export type ManagedRuntimeSpec<TId extends ManagedRuntimeId = ManagedRuntimeId> = {
+    readonly kind: "managed";
+    readonly id: TId;
+};
+export type RuntimeSpec = DevcontainerRuntimeSpec | HostRuntimeSpec | ManagedRuntimeSpec;
+/**
+ * How a step runs: its `runtime`, its environment `vars` and its `repo` access.
+ * A union on the runtime kind, so a `repo` the runtime cannot honor is a type
+ * error: a host step takes only `Repo.none()`, a devcontainer step takes
+ * `Repo.readOnly()` or `Repo.readWrite()`.
+ *
+ * Declare `vars` before `agentPrompt` so `TEnv` is inferred into the prompt's
+ * `env`, which is then strict: only declared, non-secret keys.
+ */
+export type StepEnvironment<TInput, TEnv extends EnvRecord = EnvRecord, TResult = unknown> = {
+    /** Defaults to `Runtime.devcontainer()`. */
+    runtime?: DevcontainerRuntimeSpec;
+    vars?: EnvFn<TInput, TEnv>;
+    /** Defaults to `Repo.readWrite()`. */
+    repo?: RepoField<TInput, TResult, DevcontainerRepoSpec>;
+} | {
+    runtime: HostRuntimeSpec;
+    vars?: EnvFn<TInput, TEnv>;
+    /** Defaults to `Repo.none()`. */
+    repo?: RepoField<TInput, TResult, HostRepoSpec>;
+};
+/**
+ * `codeStep`'s environment: `StepEnvironment`'s devcontainer variant plus
+ * managed runtimes. A code step runs repo code, which needs a clone, and the
+ * host runtime has none.
+ */
+export type CodeStepEnvironment<TInput, TResult = unknown> = {
+    /**
+     * Defaults to `Runtime.managed.bun1()`. `Runtime.devcontainer()` opts into the
+     * project's own container. `Runtime.host()` is not supported.
+     */
+    runtime?: DevcontainerRuntimeSpec | ManagedRuntimeSpec;
+    vars?: EnvFn<TInput>;
+    /** Defaults to `Repo.readWrite()`. */
+    repo?: RepoField<TInput, TResult, DevcontainerRepoSpec>;
+};
+export type DevcontainerRuntimeOpts = {
+    /**
+     * Full repo-relative path to the devcontainer config, e.g.
+     * `.devcontainer/frontend/devcontainer.json`. The basename must be
+     * `devcontainer.json` or `.devcontainer.json`. There is no fallback: if the
+     * file is missing on the step's base branch, the step fails.
+     */
+    readonly config?: string;
+};
+export type ManagedRuntimeFactories = {
+    readonly [K in ManagedRuntimeId]: () => ManagedRuntimeSpec<K>;
+};
+export declare const Runtime: {
+    /**
+     * Worker-supplied containers for `codeStep`, one factory per identifier, for
+     * example `Runtime.managed.bun1()`. The worker owns the image and installs the
+     * pipeline-builder dependencies; the repo holds nothing. An unknown identifier
+     * is a type error. Not supported for `defineStep`.
+     */
+    readonly managed: ManagedRuntimeFactories;
+    /**
+     * Runs the step in the repository's devcontainer. Without `config` the worker
+     * searches for `.devcontainer/devcontainer.json`, then `devcontainer.json`.
+     * Throws when `config` breaks the path rules.
+     */
+    readonly devcontainer: (opts?: DevcontainerRuntimeOpts) => DevcontainerRuntimeSpec;
+    /**
+     * Runs the step on the worker host, with no clone and no container. Takes no
+     * options, so a config path cannot be combined with it. Not supported for
+     * `codeStep`, which needs a workspace.
+     */
+    readonly host: () => HostRuntimeSpec;
+};
+export type CompiledEnvironment = {
+    executionMode: "workspace" | "no_workspace";
+    devcontainerConfigPath: string | null;
+    managedRuntime: ManagedRuntimeId | null;
+    envJson: EnvVarsInput | null;
+    /** `undefined` when the author wrote no `repo`; the server resolves the default. */
+    repo: RepoConfigInput | undefined;
+};
+export type CompileEnvironmentContext = CompileRepoContext & {
+    /** Used when the environment declares no `runtime`. `codeStep` passes the default managed runtime. */
+    readonly defaultRuntime?: ManagedRuntimeSpec;
+};
+/**
+ * Turns the authored `environment` into its wire fields. Runs `vars` and `repo`
+ * once. Throws on a static secret, or a static literal on a secret-looking name,
+ * on a setup variable on the host runtime, and on a `repo` the runtime cannot
+ * honor or that breaks the commit message rules.
+ */
+export declare function compileEnvironment<TInput, TEnv extends EnvRecord, TResult>(environment: StepEnvironment<TInput, TEnv, TResult> | CodeStepEnvironment<TInput, TResult> | undefined, ctx?: CompileEnvironmentContext): CompiledEnvironment;