@scarn/sdk 0.0.0-stage → 0.0.0

package/dist/task-plane-client.d.ts

@@ -0,0 +1,489 @@
+import { TaskRuns } from "./generated/sdk.gen";
+import type { GetApiTaskRunsByTaskRunIdLogsData, PostApiTaskRunsByTaskRunIdArtifactFailuresData, PostApiTaskRunsByTaskRunIdArtifactUploadUrlData, PostApiTaskRunsByTaskRunIdArtifactsData, PostApiTaskRunsByTaskRunIdCompletionsData, PostApiTaskRunsByTaskRunIdLogsData, PostApiTaskRunsByTaskRunIdSessionUploadUrlData, PostApiTaskRunsByTaskRunIdYieldsData, PostApiTaskRunsClaimsData } from "./generated/types.gen";
+type TaskRunRef = {
+    taskRunId: string;
+};
+type CompletionBody = PostApiTaskRunsByTaskRunIdCompletionsData["body"];
+export type TaskPlaneClientOptions = {
+    headers?: Record<string, string> | undefined;
+};
+/**
+ * Worker-facing client for the task-run plane (`/api/task-runs/...`): claiming,
+ * heartbeating, context, logs (writing, and reading another task run's), artifacts,
+ * completion and yielding. Headers given here
+ * (typically the worker's bearer token) are sent with every request.
+ */
+export declare function createTaskPlaneClient(baseUrl: string, options?: TaskPlaneClientOptions): ReturnType<typeof buildTaskPlaneClient>;
+declare const buildTaskPlaneClient: (taskRuns: TaskRuns) => {
+    claimTaskRuns: (input: PostApiTaskRunsClaimsData["body"]) => Promise<{
+        task: {
+            id: string;
+            taskId: string;
+            number: number;
+            reason: "initial" | "retry" | "continuation";
+            projectId: string;
+            workItemId: string;
+            taskExecutionConfigId: string | unknown;
+            name: string | unknown;
+            kind: "agent" | "code";
+            previousTaskRunId: string | unknown;
+            baseBranch: string | unknown;
+            heartbeatSeconds: number | unknown;
+            status: "pending" | "queued" | "running" | "succeeded" | "failed" | "timeout" | "abandoned" | "cancelled" | "skipped" | "yielded";
+            inputJson: unknown;
+            claimedBy: string | unknown;
+            claimedAt: string | unknown;
+            lastHeartbeatAt: string | unknown;
+            leaseExpiresAt: string | unknown;
+            executionTimeoutSeconds: number | unknown;
+            executionDeadlineAt: string | unknown;
+            startedAt: string | unknown;
+            completedAt: string | unknown;
+            resultJson: unknown;
+            errorJson: unknown;
+            workBranch: string | unknown;
+            createdFromBranch: string | unknown;
+            sessionRestored: boolean | unknown;
+            createdAt: string;
+            updatedAt: string;
+        };
+        claimToken: string;
+    }[]>;
+    heartbeatTaskRun: ({ taskRunId, ...body }: TaskRunRef & {
+        claimToken: string;
+        leaseDurationSeconds: number;
+    }) => Promise<void>;
+    getTaskRun: ({ taskRunId }: TaskRunRef) => Promise<{
+        id: string;
+        taskId: string;
+        number: number;
+        reason: "initial" | "retry" | "continuation";
+        projectId: string;
+        workItemId: string;
+        taskExecutionConfigId: string | unknown;
+        name: string | unknown;
+        kind: "agent" | "code";
+        previousTaskRunId: string | unknown;
+        baseBranch: string | unknown;
+        heartbeatSeconds: number | unknown;
+        status: "pending" | "queued" | "running" | "succeeded" | "failed" | "timeout" | "abandoned" | "cancelled" | "skipped" | "yielded";
+        inputJson: unknown;
+        claimedBy: string | unknown;
+        claimedAt: string | unknown;
+        lastHeartbeatAt: string | unknown;
+        leaseExpiresAt: string | unknown;
+        executionTimeoutSeconds: number | unknown;
+        executionDeadlineAt: string | unknown;
+        startedAt: string | unknown;
+        completedAt: string | unknown;
+        resultJson: unknown;
+        errorJson: unknown;
+        workBranch: string | unknown;
+        createdFromBranch: string | unknown;
+        sessionRestored: boolean | unknown;
+        createdAt: string;
+        updatedAt: string;
+    }>;
+    /** Not unwrapped: callers read `error.status` (e.g. a 402 read quota). */
+    getTaskLogArchive: ({ taskRunId }: TaskRunRef) => Promise<({
+        data: {
+            url: string | unknown;
+            sizeBytes: number;
+        };
+        error: undefined;
+    } | {
+        data: undefined;
+        error: {
+            type: string;
+            title: string;
+            status: number;
+            detail?: string;
+            instance?: string;
+            code?: string;
+            errors?: Array<{
+                path: string;
+                message: string;
+                summary?: string;
+            }>;
+            meta?: {
+                [key: string]: unknown;
+            };
+        } | {
+            type: string;
+            title: string;
+            status: number;
+            detail?: string;
+            instance?: string;
+            code?: string;
+            errors?: Array<{
+                path: string;
+                message: string;
+                summary?: string;
+            }>;
+            meta?: {
+                [key: string]: unknown;
+            };
+        } | {
+            type: string;
+            title: string;
+            status: number;
+            detail?: string;
+            instance?: string;
+            code?: string;
+            errors?: Array<{
+                path: string;
+                message: string;
+                summary?: string;
+            }>;
+            meta?: {
+                [key: string]: unknown;
+            };
+        } | {
+            type: string;
+            title: string;
+            status: number;
+            detail?: string;
+            instance?: string;
+            code?: string;
+            errors?: Array<{
+                path: string;
+                message: string;
+                summary?: string;
+            }>;
+            meta?: {
+                [key: string]: unknown;
+            };
+        } | {
+            type: string;
+            title: string;
+            status: number;
+            detail?: string;
+            instance?: string;
+            code?: string;
+            errors?: Array<{
+                path: string;
+                message: string;
+                summary?: string;
+            }>;
+            meta?: {
+                [key: string]: unknown;
+            };
+        } | {
+            type: string;
+            title: string;
+            status: number;
+            detail?: string;
+            instance?: string;
+            code?: string;
+            errors?: Array<{
+                path: string;
+                message: string;
+                summary?: string;
+            }>;
+            meta?: {
+                [key: string]: unknown;
+            };
+        };
+    }) & {
+        request: Request;
+        response: Response;
+    }>;
+    /** Not unwrapped: callers read `error.status`. */
+    readTaskLogs: ({ taskRunId, ...query }: TaskRunRef & GetApiTaskRunsByTaskRunIdLogsData["query"]) => Promise<({
+        data: {
+            lines: Array<{
+                seq: number;
+                stream: "worker" | "ai-server" | "conversation";
+                ts: string;
+                content: string;
+                level: "debug" | "info" | "warn" | "error";
+            }>;
+            nextOffset: number;
+            complete: boolean;
+        };
+        error: undefined;
+    } | {
+        data: undefined;
+        error: {
+            type: string;
+            title: string;
+            status: number;
+            detail?: string;
+            instance?: string;
+            code?: string;
+            errors?: Array<{
+                path: string;
+                message: string;
+                summary?: string;
+            }>;
+            meta?: {
+                [key: string]: unknown;
+            };
+        } | {
+            type: string;
+            title: string;
+            status: number;
+            detail?: string;
+            instance?: string;
+            code?: string;
+            errors?: Array<{
+                path: string;
+                message: string;
+                summary?: string;
+            }>;
+            meta?: {
+                [key: string]: unknown;
+            };
+        } | {
+            type: string;
+            title: string;
+            status: number;
+            detail?: string;
+            instance?: string;
+            code?: string;
+            errors?: Array<{
+                path: string;
+                message: string;
+                summary?: string;
+            }>;
+            meta?: {
+                [key: string]: unknown;
+            };
+        } | {
+            type: string;
+            title: string;
+            status: number;
+            detail?: string;
+            instance?: string;
+            code?: string;
+            errors?: Array<{
+                path: string;
+                message: string;
+                summary?: string;
+            }>;
+            meta?: {
+                [key: string]: unknown;
+            };
+        } | {
+            type: string;
+            title: string;
+            status: number;
+            detail?: string;
+            instance?: string;
+            code?: string;
+            errors?: Array<{
+                path: string;
+                message: string;
+                summary?: string;
+            }>;
+            meta?: {
+                [key: string]: unknown;
+            };
+        };
+    }) & {
+        request: Request;
+        response: Response;
+    }>;
+    getTaskRunWorkerContext: ({ taskRunId, ...body }: TaskRunRef & {
+        claimToken: string;
+    }) => Promise<{
+        projectId: string;
+        gitUrl: string;
+        baseWorkBranch: string | unknown;
+        projectOpencodeConfig: {
+            relativePath: string;
+            present: boolean;
+            commands: Array<{
+                name: string;
+                description: string;
+                run: string;
+                cwd: string | unknown;
+            }>;
+            services: Array<{
+                name: string;
+                description: string;
+                run: string;
+                cwd: string | unknown;
+                dependsOn: Array<string>;
+                expose: {
+                    targetPort: number;
+                    protocol: "tcp" | "http";
+                };
+            }>;
+        };
+        task: {
+            id: string;
+            status: "pending" | "queued" | "running" | "succeeded" | "failed" | "timeout" | "abandoned" | "cancelled" | "skipped" | "yielded";
+            kind: "agent" | "code";
+            key: string;
+            name: string;
+            inputJson: unknown;
+            executionTimeoutSeconds: number | unknown;
+            prompt: string | unknown;
+            entrypointJson: {
+                sourceFile: string;
+            } | unknown;
+            resultSchemaJson: {
+                [key: string]: unknown;
+            } | unknown;
+            turnsRemaining: number | unknown;
+        };
+        runtime: {
+            executionMode: "workspace" | "no_workspace";
+            devcontainerConfigPath: string | unknown;
+            managedRuntime: "bun1" | "node24" | unknown;
+            repo: {
+                mode: string;
+            } | {
+                mode: string;
+            } | {
+                mode: string;
+                message: string | unknown;
+                onPushFailure: "fail" | "warn";
+            };
+            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;
+            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;
+            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;
+        };
+        agentPrompt: {
+            sessionTitle: string;
+            promptText: string;
+            instructionsPlaceholder: string;
+        };
+        previousRun: {
+            taskRunId: string;
+            status: "pending" | "queued" | "running" | "succeeded" | "failed" | "timeout" | "abandoned" | "cancelled" | "skipped" | "yielded";
+            transcriptRelativePath: string;
+            findingsRelativePath: string;
+            findingsJson: unknown;
+        } | unknown;
+        restoreSession: {
+            downloadUrl: string;
+            message: string;
+        } | unknown;
+    }>;
+    completeTaskRun: ({ taskRunId, ...body }: TaskRunRef & Omit<CompletionBody, "status">) => Promise<void>;
+    failTaskRun: ({ taskRunId, ...body }: TaskRunRef & Omit<CompletionBody, "status" | "workBranch" | "createdFromBranch">) => Promise<void>;
+    yieldTaskRun: ({ taskRunId, ...body }: TaskRunRef & PostApiTaskRunsByTaskRunIdYieldsData["body"]) => Promise<void>;
+    appendTaskLogs: ({ taskRunId, ...body }: TaskRunRef & PostApiTaskRunsByTaskRunIdLogsData["body"]) => Promise<{
+        nextOffset: number;
+    }>;
+    createArtifactUploadUrl: ({ taskRunId, ...body }: TaskRunRef & PostApiTaskRunsByTaskRunIdArtifactUploadUrlData["body"]) => Promise<{
+        uploadUrl: string;
+        storeRef: string;
+        objectKey: string;
+        expiresInSeconds: number;
+    }>;
+    createSessionUploadUrl: ({ taskRunId, ...body }: TaskRunRef & PostApiTaskRunsByTaskRunIdSessionUploadUrlData["body"]) => Promise<{
+        uploadUrl: string;
+        objectKey: string;
+        expiresInSeconds: number;
+    }>;
+    recordArtifact: ({ taskRunId, ...body }: TaskRunRef & PostApiTaskRunsByTaskRunIdArtifactsData["body"]) => Promise<void>;
+    recordArtifactFailure: ({ taskRunId, ...body }: TaskRunRef & PostApiTaskRunsByTaskRunIdArtifactFailuresData["body"]) => Promise<void>;
+    listTaskArtifacts: ({ taskRunId }: TaskRunRef) => Promise<{
+        id: string;
+        taskRunId: string;
+        projectId: string;
+        relativeStorePath: string;
+        storeRef: string | unknown;
+        objectKey: string | unknown;
+        sizeBytes: number | unknown;
+        contentType: string | unknown;
+        kind: "generic" | "playwright-trace" | "video" | "image";
+        createdAt: string;
+    }[]>;
+    getArtifactDownloadUrl: ({ taskRunId, artifactId, }: TaskRunRef & {
+        artifactId: string;
+    }) => Promise<{
+        url: string | unknown;
+        sizeBytes: number;
+        contentType: string | unknown;
+        relativeStorePath: string;
+    }>;
+};
+export {};

package/dist/z.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Plain Zod plus Scarn's schema helpers, so step files can write
+ * `z.artifact(...)` next to `z.object(...)`. Every helper here is also
+ * exported on its own; plain `zod` works the same way.
+ */
+export * from "zod";
+export { artifact } from "./definitions/artifacts/artifact";

package/package.json

@@ -1,6 +1,134 @@
 {
+  "$schema": "https://json.schemastore.org/package.json",
   "name": "@scarn/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./client": {
+      "import": "./dist/client.js",
+      "types": "./dist/client.d.ts"
+    },
+    "./contracts/artifacts": {
+      "import": "./dist/contracts/artifacts.js",
+      "types": "./dist/contracts/artifacts.d.ts"
+    },
+    "./contracts/artifact-markers": {
+      "import": "./dist/contracts/artifact-markers.js",
+      "types": "./dist/contracts/artifact-markers.d.ts"
+    },
+    "./contracts/step-artifact-submissions": {
+      "import": "./dist/contracts/step-artifact-submissions.js",
+      "types": "./dist/contracts/step-artifact-submissions.d.ts"
+    },
+    "./contracts/pipeline-document": {
+      "import": "./dist/contracts/pipeline-document/index.js",
+      "types": "./dist/contracts/pipeline-document/index.d.ts"
+    },
+    "./definitions/steps": {
+      "import": "./dist/definitions/steps/index.js",
+      "types": "./dist/definitions/steps/index.d.ts"
+    },
+    "./definitions/pipelines": {
+      "import": "./dist/definitions/pipelines/index.js",
+      "types": "./dist/definitions/pipelines/index.d.ts"
+    },
+    "./pipelines": {
+      "import": "./dist/pipelines/index.js",
+      "types": "./dist/pipelines/index.d.ts"
+    },
+    "./eslint": {
+      "import": "./dist/eslint.js",
+      "types": "./dist/eslint.d.ts"
+    },
+    "./definitions/validation": {
+      "import": "./dist/definitions/validation/index.js",
+      "types": "./dist/definitions/validation/index.d.ts"
+    },
+    "./defaults": {
+      "import": "./dist/defaults/index.js",
+      "types": "./dist/defaults/index.d.ts"
+    },
+    "./push": {
+      "import": "./dist/push/index.js",
+      "types": "./dist/push/index.d.ts"
+    },
+    "./code-step-lookup": {
+      "import": "./dist/push/code-step-lookup.js",
+      "types": "./dist/push/code-step-lookup.d.ts"
+    },
+    "./opencode-mcp": {
+      "import": "./dist/opencode-mcp.js",
+      "types": "./dist/opencode-mcp.d.ts"
+    },
+    "./health-checks": {
+      "import": "./dist/health-checks.js",
+      "types": "./dist/health-checks.d.ts"
+    },
+    "./env-vars": {
+      "import": "./dist/env-vars.js",
+      "types": "./dist/env-vars.d.ts"
+    },
+    "./devcontainer-config-path": {
+      "import": "./dist/devcontainer-config-path.js",
+      "types": "./dist/devcontainer-config-path.d.ts"
+    },
+    "./managed-runtimes": {
+      "import": "./dist/managed-runtimes.js",
+      "types": "./dist/managed-runtimes.d.ts"
+    },
+    "./repo-config": {
+      "import": "./dist/repo-config.js",
+      "types": "./dist/repo-config.d.ts"
+    },
+    "./git-url": {
+      "import": "./dist/git-url/git-repo-identity.js",
+      "types": "./dist/git-url/git-repo-identity.d.ts"
+    },
+    "./jsonc": {
+      "import": "./dist/jsonc.js",
+      "types": "./dist/jsonc.d.ts"
+    },
+    "./scarn-config-parser": {
+      "import": "./dist/scarn-config-parser.js",
+      "types": "./dist/scarn-config-parser.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/scarn-io/scarn"
+  },
+  "scripts": {
+    "generate": "openapi-ts",
+    "build": "bun run script/build.ts",
+    "link:local": "bun link",
+    "pack:local": "bun run script/pack-local.ts",
+    "test": "bun test test",
+    "typecheck": "tsgo -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "jsonc-parser": "^3.3.1"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0",
+    "eslint": "^9.0.0"
+  },
+  "peerDependenciesMeta": {
+    "eslint": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@hey-api/openapi-ts": "^0.90.10",
+    "@opencode/client": "2.1.4",
+    "bun-types": "^1.4.0",
+    "zod": "^4.3.6"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.