@scarn/sdk 0.0.0-stage → 0.8.0

package/dist/definitions/steps/step-definitions-client.d.ts

@@ -0,0 +1,400 @@
+import { StepDefinitions } from "../../generated/sdk.gen";
+import type { PostApiStepDefinitionsData, PutApiStepDefinitionsData } from "../../generated/types.gen";
+import type { StepDefinitionSpec } from "./define-step";
+type RequestOptions = {
+    headers?: Record<string, unknown> | undefined;
+};
+export type CreateStepDefinitionInput = PostApiStepDefinitionsData["body"];
+export type UpsertStepDefinitionInput = PutApiStepDefinitionsData["body"];
+export declare function createStepDefinitionsClient(baseUrl: string): ReturnType<typeof buildStepDefinitionsClient>;
+declare const buildStepDefinitionsClient: (stepDefinitions: StepDefinitions) => {
+    listByProjectId: (projectId: string, options?: RequestOptions) => Promise<{
+        id: string;
+        projectId: string;
+        key: string;
+        name: string;
+        description: string | unknown;
+        prompt: string | unknown;
+        version: number;
+        kind: "built_in" | "user_defined" | "code";
+        entrypointJson: {
+            sourceFile: string;
+        } | unknown;
+        executionMode: "workspace" | "no_workspace";
+        inputSchemaJson: {
+            [key: string]: unknown;
+        };
+        resultSchemaJson: {
+            [key: string]: unknown;
+        } | unknown;
+        errors: Array<string>;
+        retry: Array<{
+            on: Array<string>;
+            maxAttempts: number;
+        }>;
+        opencodeMcpJson: {
+            [key: string]: {
+                type: string;
+                command: Array<string>;
+                cwd?: string;
+                environment?: {
+                    [key: string]: string;
+                };
+                disabled?: boolean;
+                codemode?: boolean;
+                timeout?: {
+                    startup?: number;
+                    catalog?: number;
+                    execution?: number;
+                };
+                protocol?: "legacy" | "auto" | "2026-07-28";
+            } | {
+                type: string;
+                url: string;
+                headers?: {
+                    [key: string]: string;
+                };
+                oauth?: {
+                    client_id?: string;
+                    client_secret?: string;
+                    scope?: string;
+                    callback_port?: number;
+                    redirect_uri?: string;
+                    auth_server_metadata_url?: string;
+                } | boolean;
+                disabled?: boolean;
+                codemode?: boolean;
+                timeout?: {
+                    startup?: number;
+                    catalog?: number;
+                    execution?: number;
+                };
+                protocol?: "legacy" | "auto" | "2026-07-28";
+            } | {
+                type: string;
+                name?: string;
+                disabled?: boolean;
+                codemode?: boolean;
+                timeout?: {
+                    startup?: number;
+                    catalog?: number;
+                    execution?: number;
+                };
+                protocol?: "legacy" | "auto" | "2026-07-28";
+            };
+        } | unknown;
+        healthChecksJson: Array<{
+            name?: string;
+            severity: "required" | "warn";
+            timeoutSeconds: number;
+            serialGroup?: string;
+            kind: string;
+            tool: string;
+            mcp?: string;
+            args?: {
+                [key: string]: unknown;
+            };
+        } | {
+            name?: string;
+            severity: "required" | "warn";
+            timeoutSeconds: number;
+            serialGroup?: string;
+            kind: string;
+            command: Array<string>;
+            expectExitCode: number;
+        }> | unknown;
+        envJson: Array<{
+            name: string;
+            source: string;
+            value: string;
+            secret: boolean;
+            applies: "agent" | "setup" | "both";
+        } | {
+            name: string;
+            source: string;
+            from: string;
+            secret: boolean;
+            optional: boolean;
+            default?: string;
+            mcp?: string;
+            applies: "agent" | "setup" | "both";
+        }> | unknown;
+        devcontainerConfigPath: string | unknown;
+        managedRuntime: "bun1" | "node24" | unknown;
+        repo: {
+            mode: string;
+        } | {
+            mode: string;
+        } | {
+            mode: string;
+            message: string | unknown;
+            onPushFailure: "fail" | "warn";
+        };
+        status: "draft" | "active" | "archived";
+        createdAt: string;
+        updatedAt: string;
+    }[]>;
+    create: (body: CreateStepDefinitionInput, options?: RequestOptions) => Promise<{
+        id: string;
+        projectId: string;
+        key: string;
+        name: string;
+        description: string | unknown;
+        prompt: string | unknown;
+        version: number;
+        kind: "built_in" | "user_defined" | "code";
+        entrypointJson: {
+            sourceFile: string;
+        } | unknown;
+        executionMode: "workspace" | "no_workspace";
+        inputSchemaJson: {
+            [key: string]: unknown;
+        };
+        resultSchemaJson: {
+            [key: string]: unknown;
+        } | unknown;
+        errors: Array<string>;
+        retry: Array<{
+            on: Array<string>;
+            maxAttempts: number;
+        }>;
+        opencodeMcpJson: {
+            [key: string]: {
+                type: string;
+                command: Array<string>;
+                cwd?: string;
+                environment?: {
+                    [key: string]: string;
+                };
+                disabled?: boolean;
+                codemode?: boolean;
+                timeout?: {
+                    startup?: number;
+                    catalog?: number;
+                    execution?: number;
+                };
+                protocol?: "legacy" | "auto" | "2026-07-28";
+            } | {
+                type: string;
+                url: string;
+                headers?: {
+                    [key: string]: string;
+                };
+                oauth?: {
+                    client_id?: string;
+                    client_secret?: string;
+                    scope?: string;
+                    callback_port?: number;
+                    redirect_uri?: string;
+                    auth_server_metadata_url?: string;
+                } | boolean;
+                disabled?: boolean;
+                codemode?: boolean;
+                timeout?: {
+                    startup?: number;
+                    catalog?: number;
+                    execution?: number;
+                };
+                protocol?: "legacy" | "auto" | "2026-07-28";
+            } | {
+                type: string;
+                name?: string;
+                disabled?: boolean;
+                codemode?: boolean;
+                timeout?: {
+                    startup?: number;
+                    catalog?: number;
+                    execution?: number;
+                };
+                protocol?: "legacy" | "auto" | "2026-07-28";
+            };
+        } | unknown;
+        healthChecksJson: Array<{
+            name?: string;
+            severity: "required" | "warn";
+            timeoutSeconds: number;
+            serialGroup?: string;
+            kind: string;
+            tool: string;
+            mcp?: string;
+            args?: {
+                [key: string]: unknown;
+            };
+        } | {
+            name?: string;
+            severity: "required" | "warn";
+            timeoutSeconds: number;
+            serialGroup?: string;
+            kind: string;
+            command: Array<string>;
+            expectExitCode: number;
+        }> | unknown;
+        envJson: Array<{
+            name: string;
+            source: string;
+            value: string;
+            secret: boolean;
+            applies: "agent" | "setup" | "both";
+        } | {
+            name: string;
+            source: string;
+            from: string;
+            secret: boolean;
+            optional: boolean;
+            default?: string;
+            mcp?: string;
+            applies: "agent" | "setup" | "both";
+        }> | unknown;
+        devcontainerConfigPath: string | unknown;
+        managedRuntime: "bun1" | "node24" | unknown;
+        repo: {
+            mode: string;
+        } | {
+            mode: string;
+        } | {
+            mode: string;
+            message: string | unknown;
+            onPushFailure: "fail" | "warn";
+        };
+        status: "draft" | "active" | "archived";
+        createdAt: string;
+        updatedAt: string;
+    }>;
+    /**
+     * Upserts a step definition keyed by (projectId, key, version). Accepts a
+     * step handle from `defineStep()`/`codeStep()` or a plain spec directly —
+     * no separate fetch-existing/branch-on-id step needed.
+     *
+     * The request body is built field by field so the spec's transient
+     * `entrypoint.fn` (a live, unserializable function reference — present
+     * only if a caller bypasses `collect-definitions.ts`'s own strip step)
+     * is never included.
+     */
+    upsertFromSpec: (projectId: string, step: StepDefinitionSpec, options?: RequestOptions) => Promise<{
+        id: string;
+        projectId: string;
+        key: string;
+        name: string;
+        description: string | unknown;
+        prompt: string | unknown;
+        version: number;
+        kind: "built_in" | "user_defined" | "code";
+        entrypointJson: {
+            sourceFile: string;
+        } | unknown;
+        executionMode: "workspace" | "no_workspace";
+        inputSchemaJson: {
+            [key: string]: unknown;
+        };
+        resultSchemaJson: {
+            [key: string]: unknown;
+        } | unknown;
+        errors: Array<string>;
+        retry: Array<{
+            on: Array<string>;
+            maxAttempts: number;
+        }>;
+        opencodeMcpJson: {
+            [key: string]: {
+                type: string;
+                command: Array<string>;
+                cwd?: string;
+                environment?: {
+                    [key: string]: string;
+                };
+                disabled?: boolean;
+                codemode?: boolean;
+                timeout?: {
+                    startup?: number;
+                    catalog?: number;
+                    execution?: number;
+                };
+                protocol?: "legacy" | "auto" | "2026-07-28";
+            } | {
+                type: string;
+                url: string;
+                headers?: {
+                    [key: string]: string;
+                };
+                oauth?: {
+                    client_id?: string;
+                    client_secret?: string;
+                    scope?: string;
+                    callback_port?: number;
+                    redirect_uri?: string;
+                    auth_server_metadata_url?: string;
+                } | boolean;
+                disabled?: boolean;
+                codemode?: boolean;
+                timeout?: {
+                    startup?: number;
+                    catalog?: number;
+                    execution?: number;
+                };
+                protocol?: "legacy" | "auto" | "2026-07-28";
+            } | {
+                type: string;
+                name?: string;
+                disabled?: boolean;
+                codemode?: boolean;
+                timeout?: {
+                    startup?: number;
+                    catalog?: number;
+                    execution?: number;
+                };
+                protocol?: "legacy" | "auto" | "2026-07-28";
+            };
+        } | unknown;
+        healthChecksJson: Array<{
+            name?: string;
+            severity: "required" | "warn";
+            timeoutSeconds: number;
+            serialGroup?: string;
+            kind: string;
+            tool: string;
+            mcp?: string;
+            args?: {
+                [key: string]: unknown;
+            };
+        } | {
+            name?: string;
+            severity: "required" | "warn";
+            timeoutSeconds: number;
+            serialGroup?: string;
+            kind: string;
+            command: Array<string>;
+            expectExitCode: number;
+        }> | unknown;
+        envJson: Array<{
+            name: string;
+            source: string;
+            value: string;
+            secret: boolean;
+            applies: "agent" | "setup" | "both";
+        } | {
+            name: string;
+            source: string;
+            from: string;
+            secret: boolean;
+            optional: boolean;
+            default?: string;
+            mcp?: string;
+            applies: "agent" | "setup" | "both";
+        }> | unknown;
+        devcontainerConfigPath: string | unknown;
+        managedRuntime: "bun1" | "node24" | unknown;
+        repo: {
+            mode: string;
+        } | {
+            mode: string;
+        } | {
+            mode: string;
+            message: string | unknown;
+            onPushFailure: "fail" | "warn";
+        };
+        status: "draft" | "active" | "archived";
+        createdAt: string;
+        updatedAt: string;
+    }>;
+};
+export {};

package/dist/definitions/steps/step-features.d.ts

@@ -0,0 +1,109 @@
+import { z } from "zod";
+import type { ZodObject, ZodRawShape } from "zod";
+export type StepFeature<TResultExtension extends Record<string, unknown> = Record<string, unknown>> = {
+    readonly _resultExtension: ZodObject<ZodRawShape>;
+    readonly _promptAddition: string;
+    readonly __resultExtension?: TResultExtension;
+};
+export type AnyStepFeature = StepFeature;
+type UnionToIntersection<U> = (U extends unknown ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
+export type FeatureResultExtensions<TFeatures extends readonly AnyStepFeature[]> = [TFeatures[number]] extends [never] ? Record<never, never> : UnionToIntersection<TFeatures[number] extends StepFeature<infer R> ? R : never>;
+declare const notificationKindSchema: z.ZodEnum<{
+    feedback_request: "feedback_request";
+    status_update: "status_update";
+    blocked: "blocked";
+    result_ready: "result_ready";
+    warning: "warning";
+}>;
+export type NotificationKind = z.infer<typeof notificationKindSchema>;
+declare const notificationPrioritySchema: z.ZodEnum<{
+    high: "high";
+    low: "low";
+    normal: "normal";
+    urgent: "urgent";
+}>;
+export type NotificationPriority = z.infer<typeof notificationPrioritySchema>;
+declare const notificationChannelSchema: z.ZodEnum<{
+    in_app: "in_app";
+    work_item_platform_comment: "work_item_platform_comment";
+    email: "email";
+    slack: "slack";
+}>;
+export type NotificationChannel = z.infer<typeof notificationChannelSchema>;
+export type FeedbackRequestUrgency = "blocking" | "clarification" | "assumption" | "informational";
+declare const NOTIFICATION_RESULT_KEY: "$scarn_notifications_v1";
+declare const notificationItemSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        feedback_request: "feedback_request";
+        status_update: "status_update";
+        blocked: "blocked";
+        result_ready: "result_ready";
+        warning: "warning";
+    }>;
+    title: z.ZodOptional<z.ZodString>;
+    body: z.ZodString;
+    priority: z.ZodEnum<{
+        high: "high";
+        low: "low";
+        normal: "normal";
+        urgent: "urgent";
+    }>;
+    suggestedChannels: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        in_app: "in_app";
+        work_item_platform_comment: "work_item_platform_comment";
+        email: "email";
+        slack: "slack";
+    }>>>;
+    payload: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+/** A single notification. Inferred from `notificationItemSchema` — the
+ * schema is the source of truth; this type can never drift from what's
+ * actually validated and pushed as JSON Schema. */
+export type NotificationItem = z.infer<typeof notificationItemSchema>;
+/**
+ * The shape `Notify.*` returns: a step result fragment carrying one or more
+ * notifications. Spread it into a larger result object, or return it
+ * directly if the notification *is* the step's whole result — either way it
+ * slots into the same `$scarn_notifications_v1` field `Features.notifications()`
+ * adds to the step's result.
+ */
+export type NotificationResultFragment = {
+    readonly [NOTIFICATION_RESULT_KEY]: NotificationItem[];
+};
+type NotificationsFeature = StepFeature<{
+    [NOTIFICATION_RESULT_KEY]?: NotificationItem[];
+}>;
+export type FeedbackRequestItem = {
+    question: string;
+    category: string;
+    urgency: FeedbackRequestUrgency;
+};
+export declare const Features: {
+    readonly notifications: () => NotificationsFeature;
+    /**
+     * A real specialization of `notifications()`, not an alias: narrows every
+     * emitted item to `kind: "feedback_request"` and swaps in a
+     * feedback-request-specific prompt section. Writes the same
+     * `$scarn_notifications_v1` result field.
+     */
+    readonly feedbackRequests: () => NotificationsFeature;
+};
+export declare const Notify: {
+    /** The one generic constructor. Field names match `NotificationItem`
+     * exactly, so a new optional field never forces a call-site rewrite. */
+    readonly create: (item: NotificationItem) => NotificationResultFragment;
+    /** Build a notification for the in-app inbox — the one channel the
+     * platform always delivers, so it's the safest default when the caller
+     * doesn't need a specific channel. */
+    readonly inApp: (title: string, body: string, priority: NotificationPriority, options?: {
+        kind?: NotificationKind;
+        payload?: Record<string, unknown>;
+    }) => NotificationResultFragment;
+    /** Build a `kind: "feedback_request"` notification — the value-builder
+     * counterpart to `Features.feedbackRequests()`. */
+    readonly feedbackRequest: (question: string, category: string, urgency: FeedbackRequestUrgency) => NotificationResultFragment;
+    /** Combine several notification result fragments (e.g. more than one
+     * `Notify.*` call) into a single result value. */
+    readonly merge: (...fragments: NotificationResultFragment[]) => NotificationResultFragment;
+};
+export {};

package/dist/definitions/steps/step-handle.d.ts

@@ -0,0 +1,25 @@
+import type { PipelineStep } from "../../pipelines/types";
+import type { StepDefinitionSpec, StepRetryEntry } from "./define-step";
+export type StepHandle<TInput = unknown, TResult = unknown, TErrors extends string = string> = PipelineStep<TInput, TResult, TErrors> & Omit<StepDefinitionSpec, "errors">;
+/**
+ * Checks a step's declared error names: non-empty and unique, the same rules
+ * the server applies on upsert.
+ */
+export declare function compileStepErrors(stepKey: string, errors: readonly string[] | undefined): string[];
+/**
+ * Checks a step's `retry` policy the way the server does on upsert: each
+ * entry names at least one built-in or declared error, and `maxAttempts`
+ * is a positive integer.
+ */
+export declare function compileStepRetry(stepKey: string, retry: readonly StepRetryEntry[] | undefined, errors: readonly string[]): StepRetryEntry[];
+/**
+ * Wraps a compiled spec in a callable handle. `name` is set with
+ * `Object.defineProperty` because a function's own `name` is read-only. The
+ * pipeline chain methods are non-enumerable, so they aren't spec fields.
+ */
+export declare function toStepHandle(spec: StepDefinitionSpec): StepHandle;
+/**
+ * The plain, serializable spec behind a step handle: its own enumerable
+ * fields, in a new object. Accepts a plain spec too, and copies it.
+ */
+export declare function toStepSpec(step: StepDefinitionSpec): StepDefinitionSpec;

package/dist/definitions/steps/step-ref.d.ts

@@ -0,0 +1,19 @@
+import type { JsonSchema } from "../../contracts/pipeline-document";
+/**
+ * What a pipeline needs to know about a step: its key, its input and result
+ * schemas, the error names it declares, and its input and result types.
+ *
+ * Every `defineStep` / `codeStep` handle satisfies this structurally. It is the
+ * only step type the pipeline authoring SDK depends on, so the rest of a
+ * step's definition (prompt, runtime, MCPs, ...) can change without touching
+ * pipelines. `__input` and `__result` are phantom fields: they exist only in
+ * the type, never at runtime.
+ */
+export type StepRef<TInput, TResult, TErrors extends string = string> = {
+    key: string;
+    inputSchemaJson: JsonSchema | null;
+    resultSchemaJson: JsonSchema | null;
+    errors: readonly TErrors[];
+    readonly __input: TInput;
+    readonly __result: TResult;
+};

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

@@ -0,0 +1,2 @@
+export * from "./validate-definition-specs";
+export * from "./validation-issue";

package/dist/definitions/validation/index.js

@@ -0,0 +1,19 @@
+// @bun
+import {
+  assertValidDefinitionSpecs,
+  listPaths,
+  validateDefinitionSpecs
+} from "../../chunk-gds7w7zh.js";
+import"../../chunk-5zsavw98.js";
+import"../../chunk-4ggr8af6.js";
+import"../../chunk-k4y5qt4y.js";
+import"../../chunk-cdanncng.js";
+import"../../chunk-ngy1fdcx.js";
+import"../../chunk-y2pv8d6a.js";
+import"../../chunk-skzxcba3.js";
+import"../../chunk-y64skrwp.js";
+export {
+  assertValidDefinitionSpecs,
+  listPaths,
+  validateDefinitionSpecs
+};

package/dist/definitions/validation/validate-artifact-markers.d.ts

@@ -0,0 +1,3 @@
+import type { StepDefinitionSpec } from "../steps/define-step";
+import { type DefinitionValidationIssue } from "./validation-issue";
+export declare function checkArtifactMarkers(steps: readonly StepDefinitionSpec[], stepsByKey: Map<string, readonly StepDefinitionSpec[]>): DefinitionValidationIssue[];

package/dist/definitions/validation/validate-artifacts.d.ts

@@ -0,0 +1,7 @@
+import type { StepDefinitionSpec } from "../steps/define-step";
+import type { DefinitionValidationIssue } from "./validation-issue";
+/**
+ * Check: artifact fields (`x-scarn-artifact`) never sit inside an array.
+ * v1 has no way to say which array item a submitted file belongs to.
+ */
+export declare function checkArtifactFields(steps: readonly StepDefinitionSpec[]): DefinitionValidationIssue[];

package/dist/definitions/validation/validate-definition-specs.d.ts

@@ -0,0 +1,16 @@
+import type { StepDefinitionSpec } from "../steps/define-step";
+import { type DefinitionValidationIssue } from "./validation-issue";
+/**
+ * Runs every offline check over a batch of step definitions and returns the
+ * issues found, in check order. An empty array means the batch is clean.
+ */
+export declare function validateDefinitionSpecs(steps: readonly StepDefinitionSpec[]): DefinitionValidationIssue[];
+/**
+ * `validateDefinitionSpecs`, but throws a single aggregated error.
+ *
+ * Only counts and lists `severity: "error"` issues — `"warning"`-tier issues
+ * (an embed marker no platform can embed) never block a push and are dropped
+ * here. They're still present in `validateDefinitionSpecs`'s own return value
+ * for any caller that wants to surface them.
+ */
+export declare function assertValidDefinitionSpecs(steps: readonly StepDefinitionSpec[]): void;

package/dist/definitions/validation/validate-env.d.ts

@@ -0,0 +1,15 @@
+import type { StepDefinitionSpec } from "../steps/define-step";
+import { type DefinitionValidationIssue } from "./validation-issue";
+/**
+ * Checks a step's declared env vars:
+ *
+ * - they satisfy the `envVarsSchema` wire schema (names, reserved names,
+ *   secret rules, size caps). The authoring helpers (`Env`, `normalizeEnv`)
+ *   already guard the common mistakes at definition time; this catches
+ *   hand-built or generated specs that bypass them.
+ * - an inherit entry's `mcp` names a server in the step's `opencodeMcpJson`.
+ * - `applies: "setup"` or `"both"` only on a `workspace` step (a host step has
+ *   no container to set up) and never on an MCP variable (MCP servers run
+ *   inside the agent).
+ */
+export declare function checkEnv(steps: readonly StepDefinitionSpec[]): DefinitionValidationIssue[];

package/dist/definitions/validation/validate-repo.d.ts

@@ -0,0 +1,13 @@
+import type { StepDefinitionSpec } from "../steps/define-step";
+import type { DefinitionValidationIssue } from "./validation-issue";
+/**
+ * Check: a step's `repo` satisfies `repoConfigInputSchema` (shape, commit
+ * message length, single line, `{{input.…}}` / `{{result.…}}` tokens only) and
+ * suits its runtime: `readOnly` and `readWrite` need a clone, so they are
+ * rejected on a host (`no_workspace`) step, and `none` is rejected on a
+ * `workspace` step, which reads its devcontainer config from the clone. The
+ * authoring helpers (`Repo`, `compileRepo`) and `StepEnvironment`'s types
+ * already guard these at definition time; this catches hand-built or generated
+ * specs that bypass them.
+ */
+export declare function checkRepo(steps: readonly StepDefinitionSpec[]): DefinitionValidationIssue[];

package/dist/definitions/validation/validate-runtime.d.ts

@@ -0,0 +1,12 @@
+import type { StepDefinitionSpec } from "../steps/define-step";
+import type { DefinitionValidationIssue } from "./validation-issue";
+/**
+ * Check: a step's `devcontainerConfigPath` satisfies the shared path schema and
+ * is only set on a `workspace` step, a `code` step is not a host
+ * (`no_workspace`) step, and a step's `managedRuntime` is valid (see
+ * `checkManagedRuntime`). `Runtime` already makes host plus a config path
+ * unrepresentable and guards the path at definition time, and `codeStep`'s
+ * types exclude the host runtime; this catches hand-built or generated specs
+ * that bypass them.
+ */
+export declare function checkRuntime(steps: readonly StepDefinitionSpec[]): DefinitionValidationIssue[];

package/dist/definitions/validation/validation-issue.d.ts

@@ -0,0 +1,11 @@
+export type DefinitionValidationIssue = {
+    readonly check: "health-check-mcp-server" | "health-check-double-qualified" | "env-var" | "env-var-mcp" | "env-var-applies" | "runtime" | "repo" | "artifact-field" | "artifact-marker";
+    /**
+     * Whether this issue blocks a push. Only `assertValidDefinitionSpecs`
+     * treats the tiers differently: it blocks a push on `"error"` alone.
+     */
+    readonly severity: "error" | "warning" | "info";
+    readonly message: string;
+};
+/** Formats a path list for an error message, capped so it stays readable. */
+export declare function listPaths(paths: readonly string[], limit?: number): string;