@scarn/sdk 0.0.0-stage → 0.8.0

package/dist/pipelines/refs.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Placeholders at run time: Proxies that record the reference path they stand
+ * for. Reading a field gives a child placeholder. Coercing one (comparison,
+ * arithmetic, template string) throws, and every read is recorded so reads
+ * that never reach an arg, `over` or a condition can be reported.
+ */
+import type { JsonSchema } from "../contracts/pipeline-document";
+import { type SourceSite } from "./source";
+/** A work-item field a reference reads, collected into `workItemFields`. */
+export interface WorkItemFieldUse {
+    alias: string;
+    label: string;
+}
+/** A read of a placeholder field during compilation. */
+export interface ReadRecord {
+    readonly path: string;
+    readonly site: SourceSite | null;
+    readonly pointer: string;
+    readonly parent: ReadRecord | null;
+    used: boolean;
+    hasChildren: boolean;
+}
+export interface RefData {
+    /** The reference string, or a path relative to a list element. */
+    readonly path: string;
+    /** "element" refs live inside `some` / `every` / `none` / `count` / field selectors. */
+    readonly scope: "document" | "element";
+    /** The JSON Schema of the value, when known. */
+    readonly schema: JsonSchema | undefined;
+    readonly field: WorkItemFieldUse | undefined;
+    readonly record: ReadRecord | null;
+    /** The callback context that created it; null for refs valid anywhere. */
+    readonly owner: object | null;
+    /** The node a `nodes.<id>...` reach-back reads. */
+    readonly reach: string | undefined;
+}
+/** A reach-back used at `pointer`, checked once every node is placed. */
+export interface ReachUse {
+    node: string;
+    pointer: string;
+    site: SourceSite | null;
+}
+/** Collects reads while `definePipeline` runs the authoring callbacks. */
+export interface ReadTracker {
+    readonly records: ReadRecord[];
+    /** Work-item fields used, in order of first use. */
+    readonly fields: WorkItemFieldUse[];
+    readonly reaches: ReachUse[];
+    pointer: string;
+}
+/** Runs `run` with `owners` as the callback contexts whose refs may be used. */
+export declare function withOwners<T>(owners: readonly object[], run: () => T): T;
+export declare function withTracker<T>(tracker: ReadTracker, run: () => T): T;
+/** The current pointer of the active tracker, or "" outside compilation. */
+export declare function setTrackerPointer(pointer: string): void;
+export declare function makePlaceholder(data: RefData): object;
+/**
+ * A root placeholder for a reference such as `result` or `nodes.x.input`.
+ * Context objects create one per property read, so reading `r.result` alone
+ * is recorded too.
+ */
+export declare function rootPlaceholder(path: string, schema: JsonSchema | undefined, options?: {
+    scope?: "document" | "element";
+    field?: WorkItemFieldUse;
+    owner?: object | null;
+    reach?: string;
+}): object;
+/** The data behind a placeholder, or undefined for any other value. */
+export declare function refData(value: unknown): RefData | undefined;
+/** Marks a placeholder as used, so its read isn't reported. */
+export declare function markUsed(data: RefData): void;
+/**
+ * Uses a ref in an arg, `over` or a condition: marks it used and checks it
+ * belongs to the callback being compiled. `result` means a different value
+ * in every node's callback, so a ref from another callback would compile to
+ * the wrong reference.
+ */
+export declare function useRef(data: RefData): string;
+/** Reads of leaf paths that never reached an arg, `over` or a condition. */
+export declare function unusedReads(tracker: ReadTracker): ReadRecord[];

package/dist/pipelines/registry.d.ts

@@ -0,0 +1,12 @@
+import type { ChainData, EachData, NodeDef, TargetData } from "./model";
+/** Chains finished since the last `definePipeline`, to warn about ones left out of `flow`. */
+export declare const pendingChains: Set<ChainData>;
+export declare function registerNode<T extends object>(value: T, node: NodeDef): T;
+export declare function registerTarget<T extends object>(value: T, target: TargetData): T;
+export declare function registerEach<T extends object>(value: T, each: EachData): T;
+export declare function registerChain<T extends object>(value: T, chain: ChainData): T;
+export declare function nodeOf(value: unknown): NodeDef | undefined;
+export declare function targetOf(value: unknown): TargetData | undefined;
+export declare function eachOf(value: unknown): EachData | undefined;
+export declare function chainOf(value: unknown): ChainData | undefined;
+export declare function requireNode(value: unknown, what: string): NodeDef;

package/dist/pipelines/source.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Creation sites: where in the author's TypeScript a chain, target or ref was
+ * written, read from `new Error().stack`. Frames inside the SDK itself are
+ * skipped, so the site is the first frame in user code.
+ */
+/** A position in a source file. `file` is an absolute path or URL. */
+export interface SourceSite {
+    file: string;
+    line: number;
+    column: number;
+}
+/** Parses one stack frame line into a site, or null for native frames. */
+export declare function parseFrame(frame: string): SourceSite | null;
+/** The first frame of the current stack that is outside the SDK, if any. */
+export declare function captureSite(stack?: string | undefined): SourceSite | null;
+/** `file.ts:42`, with the file relative to the working directory when it's inside it. */
+export declare function formatSite(site: SourceSite | null): string;

package/dist/pipelines/types.d.ts

@@ -0,0 +1,160 @@
+/**
+ * The public types of handles, targets and chains. Each chain method returns
+ * a type that only has the methods allowed next (see the chain grammar in
+ * `docs/plans/pipeline-ts-sdk.md`), so an unfinished or misordered chain is
+ * a type error rather than a build error.
+ */
+import type { BUILT_IN_ERRORS, ToleratedFailures, WAIT_ERRORS } from "../contracts/pipeline-document";
+import type { StepRef } from "../definitions/steps/step-ref";
+import type { Condition } from "./condition-data";
+import type { Args, ErrorValue, JsonLiteral, Placeholder, Ref } from "./ref-types";
+export declare const targetBrand: unique symbol;
+export declare const eachBrand: unique symbol;
+export declare const partialBrand: unique symbol;
+export declare const chainBrand: unique symbol;
+export declare const terminalBrand: unique symbol;
+export type BuiltInError = (typeof BUILT_IN_ERRORS)[number];
+export type WaitError = (typeof WAIT_ERRORS)[number];
+/** "Go to this node with these args". */
+export interface Target {
+    readonly [targetBrand]: true;
+}
+/** An `each`: start one lane per item. Only valid as a `next` target. */
+export interface EachTarget {
+    readonly [eachBrand]: true;
+}
+/**
+ * "End this lane by contributing these args to the merge node": from
+ * `handle.partial(args)`. Only valid as a `next` target inside a lane.
+ */
+export interface PartialTarget {
+    readonly [partialBrand]: true;
+}
+/** A finished chain, for a pipeline's `flow`. */
+export interface FlowChain {
+    readonly [chainBrand]: "flow";
+}
+type NoKeys = Record<never, never>;
+/** The args a node is called with; anything goes when its input is untyped. */
+export type CallArgs<I> = unknown extends I ? Readonly<Record<string, Ref<unknown> | JsonLiteral>> : Args<I>;
+/** Calling a handle: args are optional only when the input has no required keys. */
+export type Call<I> = NoKeys extends I ? (args?: CallArgs<I>) => Target : (args: CallArgs<I>) => Target;
+/** A bare handle is a target only when its input has no required keys. */
+export interface Bare<I> {
+    readonly [targetBrand]: NoKeys extends I ? true : false;
+}
+/** Anything `r.node(...)` can reach back to: a step or wait handle. */
+export interface NodeHandle<I, R> {
+    readonly __input: I;
+    readonly __result: R;
+}
+export interface NodeValues<I, R> {
+    readonly result: Placeholder<R>;
+    readonly input: Placeholder<I>;
+}
+export interface Reach {
+    /** An earlier node's values, as `nodes.<id>.result` / `nodes.<id>.input`. */
+    node<I, R>(handle: NodeHandle<I, R>): NodeValues<I, R>;
+}
+/** `r` in the callbacks of `.next(...)`. */
+export interface NextContext<I, R> extends Reach, NodeValues<I, R> {
+}
+/** `r` in `.catch`: the error and the input, but no result. */
+export interface CatchContext<I> extends Reach {
+    readonly error: Placeholder<ErrorValue>;
+    readonly input: Placeholder<I>;
+}
+export type NextTarget = Target | EachTarget | PartialTarget;
+/** A target, or a callback receiving `r` that returns one. */
+export type TargetArg<C, T> = T | ((r: C) => T);
+/** One route of `.next({ routes })`: taken when `when` matches (or always, with no `when`). */
+export interface NextRoute<C> {
+    when?: (r: C) => Condition;
+    to: TargetArg<C, NextTarget>;
+}
+/**
+ * The routes of `.next(...)`. In `"first"` mode (the default) the first
+ * matching route is taken; in `"all"` mode every matching route is taken,
+ * each as a lane.
+ */
+export interface NextOptions<C> {
+    match?: "first" | "all";
+    routes: readonly [NextRoute<C>, ...NextRoute<C>[]];
+    /** Taken when no route with a `when` matched. With nothing taken, the path ends there. */
+    otherwise?: TargetArg<C, NextTarget>;
+}
+export interface Routable<C, Out> {
+    /** Where to go next: one target, or routes with conditions. Ends the chain. */
+    next(target: TargetArg<C, NextTarget> | NextOptions<C>): Out;
+}
+/** `.partial(args)` on a step or wait handle: a merge target taking some of the node's args. */
+export interface Mergeable<I> {
+    partial(args: Partial<CallArgs<I>>): PartialTarget;
+}
+/** The options of `each`. */
+export interface EachOptions {
+    maxConcurrency?: number;
+    /** How many lanes may fail before the run (or enclosing lane) fails. Defaults to `{ count: 0 }`. */
+    toleratedFailures?: ToleratedFailures;
+}
+type ErrorList<E extends string> = readonly [E, ...E[]];
+export interface StepSettings {
+    title?: string;
+    timeoutSeconds?: number;
+    heartbeatSeconds?: number;
+    maxRuns?: number;
+    maxTurns?: number;
+}
+export interface WaitSettings {
+    title?: string;
+    maxRuns?: number;
+}
+export interface RetryOptions<E extends string> {
+    on: ErrorList<BuiltInError | E>;
+    maxAttempts: number;
+}
+export interface StepAfterCatch<I, R, E extends string> extends Routable<NextContext<I, R>, FlowChain> {
+    catch(on: ErrorList<BuiltInError | E>, target: TargetArg<CatchContext<I>, Target>): StepAfterCatch<I, R, E>;
+}
+export interface StepAfterRetry<I, R, E extends string> extends StepAfterCatch<I, R, E> {
+    retry(options: RetryOptions<E>): StepAfterRetry<I, R, E>;
+}
+export interface StepChain<I, R, E extends string> extends StepAfterRetry<I, R, E> {
+    settings(settings: StepSettings): StepAfterRetry<I, R, E>;
+}
+/** A step in a pipeline: callable as a target, and the start of its chain. */
+export type PipelineStep<I, R, E extends string = string> = Call<I> & Bare<I> & StepRef<I, R, E> & StepChain<I, R, E> & Mergeable<I> & {
+    /** The same step as a second node, with id `id`. */
+    as(id: string): PipelineStep<I, R, E>;
+};
+export interface WaitAfterCatch<I, R> extends Routable<NextContext<I, R>, FlowChain> {
+    catch(on: ErrorList<WaitError>, target: TargetArg<CatchContext<I>, Target>): WaitAfterCatch<I, R>;
+}
+export interface WaitChain<I, R> extends WaitAfterCatch<I, R> {
+    settings(settings: WaitSettings): WaitAfterCatch<I, R>;
+}
+/** A `decision` or `reply` wait node. */
+export type WaitHandle<I, R> = Call<I> & Bare<I> & NodeHandle<I, R> & WaitChain<I, R> & Mergeable<I>;
+/** A `succeed` or `fail` node: a target with no chain. */
+export interface Terminal extends Target {
+    readonly [terminalBrand]: true;
+}
+/** The result of a `decision` wait: the chosen action's key, and the person's text or null. */
+export interface DecisionResult<K extends string = string> {
+    action: K;
+    body: string | null;
+}
+export interface ReplyInput {
+    questions: string[];
+}
+export interface ReplyResult {
+    replied: boolean;
+    body: string | null;
+    commentId: string | null;
+}
+/** The result of a conversation step: a step with no result schema. */
+export interface ConversationResult {
+    conversationId: string;
+    summary: string;
+}
+export {};

package/dist/push/code-step-lookup.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Shared step discovery: which steps a loaded module defines, and which
+ * function implements a given code step.
+ *
+ * Used by `collect-definitions.ts` to decide what to push and by the worker's
+ * code-step runner to decide what to run, so a step is runnable exactly when
+ * the collector could find it. Discovery works from the shape of a module's
+ * exports, never from shared module instances.
+ *
+ * Takes type-only imports so it carries no runtime dependency on the rest of
+ * the SDK and can be imported on its own (`@scarn/sdk/code-step-lookup`).
+ */
+import type { StepDefinitionSpec } from "../definitions/steps";
+type CodeStepFn = NonNullable<StepDefinitionSpec["entrypoint"]>["fn"];
+/**
+ * A step spec, or a step handle: `defineStep` and `codeStep` return a function
+ * carrying the spec's fields.
+ */
+export declare function isStepDefinitionSpec(value: unknown): value is StepDefinitionSpec;
+/**
+ * Every step spec a module defines: its named exports that are step specs.
+ * Deduped by reference, so a step exported under two names appears once.
+ */
+export declare function stepsInModule(mod: Readonly<Record<string, unknown>>): StepDefinitionSpec[];
+/**
+ * The function implementing the code step `key` in `mod`, or `undefined` when
+ * the module defines no such step. Throws when more than one distinct function
+ * is registered under `key`; the same function reachable twice is not
+ * ambiguous.
+ */
+export declare function findCodeStepInModule(mod: Readonly<Record<string, unknown>>, key: string): CodeStepFn | undefined;
+export {};

package/dist/push/code-step-lookup.js

@@ -0,0 +1,12 @@
+// @bun
+import {
+  findCodeStepInModule,
+  isStepDefinitionSpec,
+  stepsInModule
+} from "../chunk-ar6hcj1r.js";
+import"../chunk-y64skrwp.js";
+export {
+  findCodeStepInModule,
+  isStepDefinitionSpec,
+  stepsInModule
+};

package/dist/push/collect-definitions.d.ts

@@ -0,0 +1,70 @@
+import { type DefaultPipelineAssignmentSpec } from "../definitions/pipelines/define-default-pipeline-assignment";
+import type { StepDefinitionSpec } from "../definitions/steps";
+/**
+ * The fixed, repo-root-relative directory `scarn pipelines init` scaffolds
+ * and `scarn pipelines push`/`studio` always run from. `resolveCodeStepEntrypoint`
+ * uses this to record a `kind: "code"` step's `sourceFile` relative to the repo
+ * root (what the worker's `execute-code-step.ts` expects when it joins
+ * `sourceFile` onto the checked-out workspace root), regardless of what the
+ * collecting process's own `cwd` happens to be.
+ *
+ * Duplicated nowhere else — `@scarn/worker`'s own `PIPELINE_BUILDER_DIR`
+ * imports this one, so there's a single source of truth.
+ */
+export declare const PIPELINE_BUILDER_DIR = ".scarn/pipeline-builder";
+export type CollectedDefinitions = {
+    /** Deduped by `key@vN`. */
+    readonly steps: readonly StepDefinitionSpec[];
+    /** Present only when `default-pipeline-assignment.ts` exists in the directory. */
+    readonly defaultPipelineAssignment: DefaultPipelineAssignmentSpec | null;
+};
+/**
+ * One source file that failed to import —
+ * `collectDefinitionsFromDirectoryTolerant`'s per-file counterpart to a
+ * `collectDefinitionsFromDirectory` throw. `key` is the file's own basename
+ * (no extension).
+ */
+export type BrokenPipeline = {
+    readonly key: string;
+    readonly message: string;
+};
+export type TolerantCollectedDefinitions = CollectedDefinitions & {
+    readonly brokenPipelines: readonly BrokenPipeline[];
+};
+/** `.ts`/`.js` files in `dir` that declare definitions — excludes internal scripts and `default-pipeline-assignment.ts`. */
+export declare function listSourceFiles(absDir: string): string[];
+/**
+ * Imports every `.ts`/`.js` file in `dir` (except the push script itself and
+ * `default-pipeline-assignment.ts`) and collects the step definitions they
+ * export. The assignment file, when present, is imported and
+ * validated too but returned separately — syncing it needs the server.
+ *
+ * Designed to run on the user's native runtime (bun, node-with-tsx, deno), NOT
+ * inside a `bun --compile`'d binary — that runtime can't resolve scoped package
+ * `exports` field remappings from external user files. `scarn pipelines
+ * studio` works around this for its own compiled binary by never calling this
+ * function in-process: `collectDefinitionsViaSubprocess` (in
+ * `packages/worker/src/pipelines/pipeline-studio/infra/collect-definitions-via-subprocess.ts`)
+ * spawns a real bun/tsx/deno subprocess that calls this exact function from
+ * outside the compiled binary. Calling it directly, in-process, from inside a
+ * compiled binary is still unsupported.
+ *
+ * Throws on the first bad file — a syntax error, a step-definition error, a
+ * conflicting `codeStep` key — aborting the
+ * whole collection. That's the right behavior for `scarn pipelines push`
+ * (this function's only real caller besides its own tests): pushing a
+ * partially-collected directory would be worse than refusing to push at all.
+ * `scarn pipelines studio` wants the opposite trade-off — see
+ * `collectDefinitionsFromDirectoryTolerant` below.
+ */
+export declare function collectDefinitionsFromDirectory(dir: string): Promise<CollectedDefinitions>;
+/**
+ * `collectDefinitionsFromDirectory`'s tolerant sibling, built for `scarn
+ * pipelines studio`: one file failing to import (a syntax error, a
+ * step-definition error, a conflicting `codeStep` key, ...) is recorded as a
+ * `BrokenPipeline` entry instead of aborting collection — every *other*
+ * file's steps still come back usable, so one bad edit in the builder
+ * directory doesn't blank the whole designer (see
+ * `compute-studio-snapshot.ts`).
+ */
+export declare function collectDefinitionsFromDirectoryTolerant(dir: string): Promise<TolerantCollectedDefinitions>;

package/dist/push/collect-pipeline-documents.d.ts

@@ -0,0 +1,14 @@
+export type PipelineDocumentFile = {
+    /** The file name, relative to the builder directory. */
+    readonly file: string;
+    readonly key: string;
+    readonly title: string | undefined;
+    /** The parsed document, sent to the server as-is. */
+    readonly document: Record<string, unknown>;
+};
+/**
+ * Every `.json` file in `dir` that holds a pipeline document (an object with
+ * `nodes`), sorted by file name. Other JSON is skipped. Throws on a file that
+ * isn't valid JSON, a document without a `key`, or two files with one `key`.
+ */
+export declare function collectPipelineDocuments(dir: string): PipelineDocumentFile[];

package/dist/push/index.d.ts

@@ -0,0 +1,6 @@
+export { PIPELINE_BUILDER_DIR, collectDefinitionsFromDirectory, collectDefinitionsFromDirectoryTolerant, } from "./collect-definitions";
+export type { BrokenPipeline, CollectedDefinitions, TolerantCollectedDefinitions, } from "./collect-definitions";
+export { collectPipelineDocuments } from "./collect-pipeline-documents";
+export type { PipelineDocumentFile } from "./collect-pipeline-documents";
+export { pushFromDirectory } from "./push-from-directory";
+export type { PushFromDirectoryOptions, PushFromDirectoryResult, } from "./push-from-directory";