@scarn/sdk 0.0.0-stage → 0.8.0

package/dist/defaults/legacy-config-migration.d.ts

@@ -0,0 +1,27 @@
+/**
+ * One-time, idempotent: if either new file is still missing, find the old
+ * combined file (`.scarn.json`, falling back to the even older bare
+ * `.scarn`), split it, and delete it. Safe to call redundantly from both
+ * `auth-file.ts` and `config-file.ts` — whichever loads first does the work;
+ * the other's own `existsSync` check on its own new path short-circuits.
+ *
+ * Only checks the outer shape of `profiles`/`anonymousId`/`telemetryDisabled`
+ * (object / string / boolean) before handing them off — it deliberately does
+ * not deep-validate individual profiles the way `auth-file.ts`'s
+ * `isAuthFile` does on every read. That deeper check already runs the next
+ * time `auth.jsonc` is loaded (corrupt/invalid content there already falls
+ * back to empty, same as today), so duplicating it here would only catch
+ * corruption one call earlier, at the cost of this module importing
+ * `auth-file.ts`'s validation — which it must not do, since both
+ * `auth-file.ts` and `config-file.ts` import this module and must not import
+ * each other.
+ */
+export declare function migrateLegacyConfigIfNeeded(input: {
+    authFileExists: () => boolean;
+    configFileExists: () => boolean;
+    writeAuthFile: (profiles: Record<string, unknown>) => void;
+    writeConfigFile: (fields: {
+        anonymousId?: string;
+        telemetryDisabled?: boolean;
+    }) => void;
+}): void;

package/dist/defaults/load-push-defaults.d.ts

@@ -0,0 +1,25 @@
+export interface PushDefaults {
+    baseUrl: string;
+    projectId: string | undefined;
+    accessToken: string | undefined;
+}
+export interface LoadPushDefaultsOptions {
+    /**
+     * Directory the script is running from. The project config (`.scarn/scarn.jsonc`)
+     * is searched for in this directory and each ancestor directory.
+     */
+    dir: string;
+}
+/**
+ * Reads the conventional defaults for a `scarn pipelines push` run:
+ * - `baseUrl`: from `SCARN_BASE_URL` env var or the built-in default.
+ * - `accessToken`: from `SCARN_ACCESS_TOKEN` env var or the saved auth
+ *   profile for the resolved `baseUrl`.
+ * - `projectId`: from `SCARN_PROJECT_ID` env var (a project id, which
+ *   `scarn pipelines push` sets after resolving the ref), or else the
+ *   `"project"` ref in the nearest ancestor `.scarn/scarn.jsonc` of
+ *   `opts.dir`, resolved against the server. Resolution needs `accessToken`;
+ *   without one `projectId` is left undefined. A ref the server rejects throws
+ *   a `ProjectRefError` naming the ref.
+ */
+export declare function loadPushDefaults(opts: LoadPushDefaultsOptions): Promise<PushDefaults>;

package/dist/defaults/project-config.d.ts

@@ -0,0 +1,32 @@
+export interface ProjectConfig {
+    /**
+     * The project this repo belongs to, as `<owner>/<slug>` — the owner's
+     * username and the project slug, the same pair as the project's web URL.
+     */
+    project: string;
+    /**
+     * Optional prefix for the per-step work branch name. The worker creates
+     * branches named `<branchPrefix>/<stepKey>-<taskId>`. Defaults to
+     * `scarn` when omitted or invalid.
+     */
+    branchPrefix?: string;
+    /**
+     * Optional base branch the FIRST step's work branch is created off of. The
+     * worker clones the repo's default HEAD, then checks out this branch before
+     * branching. Overridden by the `SCARN_BASE_WORK_BRANCH` env var in
+     * `.scarn/.env`. Ignored for later steps, which are always created off the
+     * predecessor step's work branch. Defaults to the repo's default branch when
+     * omitted or invalid.
+     */
+    baseWorkBranch?: string;
+}
+export interface ProjectRef {
+    owner: string;
+    slug: string;
+}
+/** Parses `<owner>/<slug>`, or returns `null` when either half breaks the rules. */
+export declare function parseProjectRef(ref: string): ProjectRef | null;
+export declare function isProjectRef(ref: string): boolean;
+export declare function formatProjectRef(ref: ProjectRef): string;
+export declare const PROJECT_CONFIG_RELATIVE_PATH: string;
+export declare function loadProjectConfig(rootDir?: string): Promise<ProjectConfig | null>;

package/dist/defaults/project-ref.d.ts

@@ -0,0 +1,34 @@
+import type { ScarnClient } from "../generated";
+export interface ResolvedProjectRef {
+    id: string;
+    owner: string;
+    slug: string;
+}
+export type ProjectRefErrorKind = "invalid" | "not_found" | "forbidden" | "unauthenticated" | "failed";
+/**
+ * A failure to turn `owner/slug` into a project. The message names the ref and
+ * the denied action, never a UUID, so it can be shown as-is.
+ */
+export declare class ProjectRefError extends Error {
+    readonly kind: ProjectRefErrorKind;
+    readonly ref: string;
+    constructor(kind: ProjectRefErrorKind, ref: string, message: string);
+}
+export interface ResolveProjectRefOptions {
+    headers: {
+        Authorization: string;
+    };
+    /**
+     * What the caller is about to do, phrased to complete "You don't have
+     * permission to …" — e.g. `"push pipelines to"`, `"run work for"`.
+     * Defaults to `"view"`.
+     */
+    action?: string;
+}
+export declare const PROJECT_REF_FORMAT_HINT = "Expected \"<owner>/<project-slug>\", e.g. \"acme/web-app\".";
+/**
+ * Resolves a `owner/slug` project ref to its id via
+ * `GET /api/projects/resolve`. Every command that takes a project calls this
+ * once, up front, and passes the id downstream.
+ */
+export declare function resolveProjectRef(client: ScarnClient, ref: string, { headers, action }: ResolveProjectRefOptions): Promise<ResolvedProjectRef>;

package/dist/definitions/artifacts/artifact.d.ts

@@ -0,0 +1,62 @@
+import { z } from "zod";
+export declare const ARTIFACT_BRAND = "ScarnArtifact";
+export type ArtifactBrand = typeof ARTIFACT_BRAND;
+/** The value an artifact field holds: a path relative to `artifactsDir`. */
+export type ArtifactPath = string & z.$brand<ArtifactBrand>;
+export type ArtifactSchema = z.core.$ZodBranded<z.ZodString, ArtifactBrand>;
+/**
+ * Extension presets for `artifact({ accept })`. They expand to plain
+ * extension lists when the step is defined; the server never sees the names.
+ */
+export declare const ArtifactTypes: {
+    readonly video: readonly [".mp4", ".webm", ".mov"];
+    readonly image: readonly [".png", ".jpg", ".jpeg", ".gif", ".svg"];
+};
+export type ArtifactOptions = {
+    /**
+     * File extensions the field accepts, e.g. `[".mp4", ".webm"]` or
+     * `[...ArtifactTypes.video, ".gif"]`. Omitted or empty accepts any file.
+     */
+    readonly accept?: readonly string[];
+};
+/**
+ * Validates and normalises an `accept` list: every entry must be a
+ * lower-case extension with a leading dot. Duplicates are dropped and order
+ * is kept.
+ */
+export declare function normalizeArtifactAccept(accept: readonly string[] | undefined): string[];
+/**
+ * A result field holding a file the step produced. The field's value is the
+ * file's path relative to `artifactsDir`; agents fill it with
+ * `scarn-submit-artifact` and code steps return `Artifact.path(...)`.
+ *
+ * Serialises to `{ "type": "string", "x-scarn-artifact": { "accept": [...] } }`.
+ */
+export declare function artifact(options?: ArtifactOptions): ArtifactSchema;
+/** An artifact field in a step's result: `path` is its dotted result path. */
+export type StepArtifactRef = {
+    readonly step: {
+        readonly key: string;
+    };
+    readonly path: string;
+};
+/**
+ * What an artifact marker points at: an artifact field in a step's result
+ * (required) or a name/glob relative to `artifactsDir` (optional).
+ */
+export type ArtifactMarkerTarget = StepArtifactRef | string;
+export declare const Artifact: {
+    /** Brands a path relative to `artifactsDir` for a code step's artifact field. */
+    readonly path: (relativePath: string) => ArtifactPath;
+    /**
+     * A marker that shows the artifact inline in a work item comment where the
+     * platform can, and links to it otherwise. Put it in its own paragraph.
+     */
+    readonly embed: (target: ArtifactMarkerTarget, options: {
+        caption: string;
+    }) => string;
+    /** A marker that links to the artifact. Put it in its own paragraph. */
+    readonly link: (target: ArtifactMarkerTarget, options: {
+        label: string;
+    }) => string;
+};

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

@@ -0,0 +1 @@
+export * from "./artifact";

package/dist/definitions/pipelines/define-default-pipeline-assignment.d.ts

@@ -0,0 +1,263 @@
+import type { PipelineDefinition } from "../../pipelines/define-pipeline";
+import { type WorkItemTopLevelField, type WorkItemTopLevelFieldTypeMap } from "./work-item-fields";
+/**
+ * The reserved filename for the default pipeline assignment file.
+ * This file is NOT treated as a pipeline definition by the push scanner.
+ */
+export declare const DEFAULT_PIPELINE_ASSIGNMENT_FILENAME = "default-pipeline-assignment.ts";
+type ConditionOperator = "equal" | "notEqual" | "lessThan" | "lessThanInclusive" | "greaterThan" | "greaterThanInclusive" | "in" | "notIn" | "contains" | "doesNotContain";
+type LeafCondition = {
+    readonly _tag: "leaf";
+    /** Top-level fact name: "workItem" or "context". */
+    readonly fact: string;
+    /** JSONPath within the fact value, e.g. "$.fields.status". */
+    readonly path?: string;
+    readonly operator: ConditionOperator;
+    readonly value: unknown;
+};
+type GroupCondition = {
+    readonly _tag: "group";
+    readonly mode: "all" | "any";
+    readonly conditions: AssignmentCondition[];
+};
+type AssignmentCondition = LeafCondition | GroupCondition;
+export type AssignOutcome = {
+    readonly _tag: "assign";
+    readonly pipelineKey: string;
+};
+/** What `assign(...)` accepts: a pipeline key, or a `definePipeline` value. */
+export type AssignablePipeline = string | Pick<PipelineDefinition, "_tag" | "key">;
+export type SkipOutcome = {
+    readonly _tag: "skip";
+};
+export type DefaultPipelineAssignmentOutcome = AssignOutcome | SkipOutcome;
+export type AssignmentRule = {
+    readonly _tag: "assignment_rule";
+    readonly conditions: AssignmentCondition[];
+    readonly mode: "all" | "any";
+    readonly outcome: DefaultPipelineAssignmentOutcome;
+};
+/** A leaf condition; nestable in a group or terminable with `.then()`. */
+export interface AssignmentLeaf {
+    then(outcome: DefaultPipelineAssignmentOutcome): AssignmentRule;
+    /** @internal */
+    readonly _condition: AssignmentCondition;
+}
+/** A group condition (`all`/`any`); nestable or terminable with `.then()`. */
+export interface AssignmentGroup {
+    then(outcome: DefaultPipelineAssignmentOutcome): AssignmentRule;
+    /** @internal */
+    readonly _condition: AssignmentCondition;
+}
+type AssignmentNestable = AssignmentLeaf | AssignmentGroup;
+/**
+ * `.gt`/`.gte`/`.lt`/`.lte` are only ever meaningful for numeric fields.
+ * Intersected onto `AssignmentFieldRef<T>` only when `T` is (or includes)
+ * `number`, so e.g. `workItem.title.gt(...)` doesn't even type-check, let
+ * alone appear in autocomplete.
+ */
+type NumericComparators = {
+    gt(value: number): AssignmentLeaf;
+    gte(value: number): AssignmentLeaf;
+    lt(value: number): AssignmentLeaf;
+    lte(value: number): AssignmentLeaf;
+};
+/**
+ * Comparator-bound reference to a work-item field or context fact.
+ *
+ * `T` is the field's value type (defaulting to `unknown`, which preserves
+ * the pre-generic behavior for any caller that doesn't otherwise constrain
+ * it). `.contains`/`.doesNotContain` narrow to the array element type when
+ * `T` is an array — json-rules-engine's `contains`/`doesNotContain`
+ * operators check array-membership (or substring-membership for strings)
+ * against the fact's actual runtime shape, so an array-typed field's
+ * `.contains(...)` should accept one element, not the whole array.
+ */
+export type AssignmentFieldRef<T = unknown> = {
+    eq(value: T): AssignmentLeaf;
+    ne(value: T): AssignmentLeaf;
+    in(values: ReadonlyArray<T>): AssignmentLeaf;
+    notIn(values: ReadonlyArray<T>): AssignmentLeaf;
+    contains(value: T extends ReadonlyArray<infer U> ? U : T): AssignmentLeaf;
+    doesNotContain(value: T extends ReadonlyArray<infer U> ? U : T): AssignmentLeaf;
+} & (T extends number ? NumericComparators : Record<string, never>);
+/** Comparator-bound accessor for the work item passed to `defaultPipelineAssignment`. */
+export type WorkItemAssignmentAccessor = {
+    [K in WorkItemTopLevelField]: AssignmentFieldRef<WorkItemTopLevelFieldTypeMap[K]>;
+} & {
+    /**
+     * Accessor for a platform-specific field (Jira custom field, GitHub label,
+     * etc.) stored in the work item's `fields` bag. Since `fields` keys and
+     * value shapes are platform- and project-dependent, there is no static
+     * schema to check either against by default.
+     *
+     * Two independent, optional type parameters:
+     *  - `TName` constrains the `name` argument itself — pass a literal union
+     *    of known field names (e.g. the `WorkItemFieldName` type
+     *    `scarn pipelines pull` generates into `work-item-fields.ts`) to get
+     *    compile-time validation and autocomplete on the field name.
+     *  - `TValue` types the comparator (`.eq`/`.gte`/etc.) argument, exactly
+     *    like the top-level accessors above — pass it for a known-shaped
+     *    custom field (e.g. a numeric one).
+     * Both default to permissive types, so `workItem.field(name)` with no
+     * type arguments keeps working exactly as before.
+     *
+     * @example
+     * workItem.field("issueType").eq("bug")
+     * workItem.field("labels").contains("regression")
+     * workItem.field<WorkItemFieldName>("issueType").eq("bug")
+     * workItem.field<WorkItemFieldName, number>("storyPoints").gte(3)
+     */
+    field<TName extends string = string, TValue = unknown>(name: TName): AssignmentFieldRef<TValue>;
+};
+export type DefaultPipelineAssignmentCtx = {
+    /**
+     * Work-item accessor: top-level properties (`workItem.title`,
+     * `workItem.platform`, `workItem.url`, ...) plus `workItem.field(name)`
+     * for the platform-specific `fields` bag.
+     *
+     * @example
+     * workItem.field("issueType").eq("bug").then(assign("bug-triage"))
+     * workItem.field("labels").contains("regression").then(assign("regression-review"))
+     * workItem.field("status").eq("resolved").then(skip())
+     * workItem.platform.eq("github").then(assign("github-triage"))
+     * workItem.title.contains("[urgent]").then(assign("urgent-triage"))
+     */
+    workItem: WorkItemAssignmentAccessor;
+    /**
+     * Context facts for the current ingestion event.
+     * `context.isNew` is `true` when the work item is being created for the first time.
+     *
+     * @example
+     * context.isNew.eq(true).then(assign("onboarding"))
+     */
+    context: {
+        isNew: AssignmentFieldRef<boolean>;
+    };
+    /**
+     * Outcome: assign the work item to the given pipeline, by key or by the
+     * `definePipeline` value a pipeline file default-exports.
+     * Used in both `rules` (via `.then(assign(...))`) and `default`.
+     *
+     * @example
+     * workItem.field("issueType").eq("bug").then(assign("bug-triage"))
+     */
+    assign: (pipeline: AssignablePipeline) => AssignOutcome;
+    /**
+     * Outcome: do not assign any pipeline to this work item.
+     * Used in both `rules` (via `.then(skip())`) and `default`.
+     *
+     * @example
+     * workItem.field("status").eq("resolved").then(skip())
+     */
+    skip: () => SkipOutcome;
+    /**
+     * All nested conditions must match.
+     *
+     * @example
+     * all(
+     *   workItem.field("issueType").eq("bug"),
+     *   workItem.field("priority").eq("high"),
+     * ).then(assign("bug-triage"))
+     */
+    all: (...refs: AssignmentNestable[]) => AssignmentGroup;
+    /**
+     * Any nested condition must match.
+     *
+     * @example
+     * any(
+     *   workItem.field("status").eq("resolved"),
+     *   workItem.field("status").eq("closed"),
+     * ).then(skip())
+     */
+    any: (...refs: AssignmentNestable[]) => AssignmentGroup;
+};
+export type DefaultPipelineAssignmentInput = {
+    /**
+     * The outcome when no rule matches. Use `assign(pipeline)` to assign a
+     * specific pipeline, or `skip()` to do nothing.
+     */
+    default: DefaultPipelineAssignmentOutcome;
+    /**
+     * Ordered list of rules evaluated against each incoming work item.
+     * First match wins; unmatched work items fall through to `default`.
+     */
+    rules: AssignmentRule[];
+};
+export type DefaultPipelineAssignmentSpec = {
+    readonly _tag: "default_pipeline_assignment";
+    readonly default: DefaultPipelineAssignmentOutcome;
+    readonly rules: AssignmentRule[];
+};
+/**
+ * Define a default pipeline assignment policy for this project.
+ *
+ * Pass a callback that receives a context object with `workItem`, `context`,
+ * `assign`, `skip`, `all`, and `any`. Return an object with `default` and
+ * `rules`.
+ *
+ * `default` is the outcome when no rule matches — either `assign(key)`
+ * or `skip()`.
+ *
+ * `rules` is an ordered list; the first matching rule wins.
+ *
+ * @example
+ * import { defaultPipelineAssignment } from "@scarn/sdk/definitions/pipelines";
+ *
+ * export default defaultPipelineAssignment(({ workItem, any, assign, skip }) => ({
+ *   default: assign("bug-triage"),
+ *   rules: [
+ *     any(
+ *       workItem.field("status").eq("resolved"),
+ *       workItem.field("status").eq("manual support"),
+ *     ).then(skip()),
+ *     workItem.field("issueType").eq("bug").then(assign("bug-triage")),
+ *   ],
+ * }));
+ */
+export declare function defaultPipelineAssignment(callback: (ctx: DefaultPipelineAssignmentCtx) => DefaultPipelineAssignmentInput): DefaultPipelineAssignmentSpec;
+type SerializedLeafCondition = {
+    fact: string;
+    path?: string;
+    operator: string;
+    value: unknown;
+};
+type SerializedConditionGroup = {
+    all?: SerializedConditionNode[];
+    any?: SerializedConditionNode[];
+};
+type SerializedConditionNode = SerializedLeafCondition | SerializedConditionGroup;
+type SerializedAssignmentRule = {
+    conditions: SerializedConditionGroup;
+    event: {
+        type: string;
+        params?: Record<string, unknown>;
+    };
+};
+export type SerializedDefaultPipelineAssignment = {
+    /**
+     * Pipeline key for the primary assign pipeline; resolved to a
+     * `pipelineDefinitionId` by the push layer. Null when `default`
+     * is `skip()` and no rule assigns a pipeline (push will reject this).
+     */
+    pipelineDefinitionKey: string;
+    rulesJson: {
+        rules: SerializedAssignmentRule[];
+    };
+    defaultEventType: "assign" | "skip";
+    defaultEventParamsJson: Record<string, unknown> | null;
+    allowedEventTypes: Array<"assign" | "skip">;
+};
+/**
+ * Serialize a `DefaultPipelineAssignmentSpec` to the wire format.
+ *
+ * `pipelineDefinitionKey` is the key of the primary assign pipeline —
+ * taken from `default` if it's `assign(...)`, otherwise from the first rule
+ * that assigns a pipeline. The push layer rejects specs with no assign outcome.
+ */
+export declare function serializeDefaultPipelineAssignment(spec: DefaultPipelineAssignmentSpec): SerializedDefaultPipelineAssignment;
+/**
+ * Type guard: returns true if `value` is a `DefaultPipelineAssignmentSpec`.
+ */
+export declare function isDefaultPipelineAssignmentSpec(value: unknown): value is DefaultPipelineAssignmentSpec;
+export {};

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

@@ -0,0 +1,3 @@
+export * from "./pipeline-definitions-client";
+export * from "./define-default-pipeline-assignment";
+export * from "./work-item-fields";

package/dist/definitions/pipelines/index.js

@@ -0,0 +1,26 @@
+// @bun
+import {
+  DEFAULT_PIPELINE_ASSIGNMENT_FILENAME,
+  PipelineDefinitionsApiError,
+  WORK_ITEM_FIELDS_PATH_PREFIX,
+  WORK_ITEM_TOP_LEVEL_FIELDS,
+  createPipelineDefinitionsClient,
+  defaultPipelineAssignment,
+  isDefaultPipelineAssignmentSpec,
+  resolveWorkItemFieldPath,
+  serializeDefaultPipelineAssignment
+} from "../../chunk-zm72ksz0.js";
+import"../../chunk-vfeytkqx.js";
+import"../../chunk-skzxcba3.js";
+import"../../chunk-y64skrwp.js";
+export {
+  DEFAULT_PIPELINE_ASSIGNMENT_FILENAME,
+  PipelineDefinitionsApiError,
+  WORK_ITEM_FIELDS_PATH_PREFIX,
+  WORK_ITEM_TOP_LEVEL_FIELDS,
+  createPipelineDefinitionsClient,
+  defaultPipelineAssignment,
+  isDefaultPipelineAssignmentSpec,
+  resolveWorkItemFieldPath,
+  serializeDefaultPipelineAssignment
+};