@scarn/sdk 0.0.0-stage → 0.8.0

package/dist/git-url/git-remote.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Internal remote-URL parsing shared by the `git-url` helpers. Not exported
+ * from the SDK entry. No `node:` imports: Next client components use it.
+ *
+ * Scp form (`git@host:path`), `ssh://`, `git+ssh://`, `ssh+git://`, `git://`,
+ * `http://` and `https://` are accepted; local paths, `file://` and anything
+ * else unrecognised yield `null`. The host is lowercased; the path is kept
+ * verbatim apart from dropping any query and fragment.
+ *
+ * Parsing follows `packages/worker/src/runtime/runtime-service/domain/git-mirror-key.ts`,
+ * which deliberately keeps the scheme and is not shared.
+ */
+export declare const DEFAULT_PORTS: Readonly<Record<string, string>>;
+export type ParsedRemote = {
+    scheme: string;
+    host: string;
+    port: string | null;
+    path: string;
+};
+export type UrlFormParts = {
+    scheme: string;
+    prefix: string;
+    userinfo: string | null;
+    hostPort: string;
+    remainder: string;
+};
+export declare function parseRemote(rawUrl: string): ParsedRemote | null;
+export declare function hasDefaultPort(remote: ParsedRemote): boolean;
+export declare function splitUrlForm(value: string): UrlFormParts | null;
+export declare function normalisePath(path: string): string;

package/dist/git-url/git-repo-identity.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Pure helpers for comparing and displaying git remote URLs. No `node:`
+ * imports: Next client components use this module.
+ *
+ * A repository's **identity key** is `host[:port]/path`, so every spelling of
+ * the same remote compares equal:
+ *  - scp form (`git@host:path`), `ssh://`, `git+ssh://`, `ssh+git://`,
+ *    `git://`, `http://` and `https://` are accepted;
+ *  - the scheme, userinfo, query, fragment and default ports are dropped;
+ *  - the host is lowercased, and a trailing `/` and `.git` are stripped;
+ *  - the path is lowercased for `github.com` only, whose paths are
+ *    case-insensitive;
+ *  - local paths, `file://` and anything else unrecognised yield `null`.
+ *
+ * The identity key is for comparison only. A stored `gitUrl` is never
+ * rewritten to it, because workers clone the stored URL verbatim.
+ */
+export { parseGitHost } from "./parse-git-host";
+export type { GitHost, GitHostKind } from "./parse-git-host";
+/**
+ * The identity key for `rawUrl` (e.g. `"github.com/acme/repo"`), or `null`
+ * when it is a local path, a `file://` URL, or not a recognised remote.
+ */
+export declare function gitRepoIdentity(rawUrl: string): string | null;
+/**
+ * Whether two remote URLs point at the same repository: their identity keys
+ * match, or — when either has no identity key — the raw strings are equal.
+ */
+export declare function isSameGitRepo(a: string, b: string): boolean;
+/**
+ * `rawUrl` with any credential removed, safe to print or put in a link. For
+ * `http(s)` the whole userinfo goes, since a bare username there is often a
+ * token; for other URL schemes only a `:password` part goes, keeping an
+ * ssh-style `git@`. Anything not in URL form is returned unchanged.
+ */
+export declare function stripGitUrlCredentials(rawUrl: string): string;
+/**
+ * The GitHub `owner`/`name` of `rawUrl`, in the casing the URL uses, or `null`
+ * when it is not a `github.com/<owner>/<name>` remote.
+ */
+export declare function parseGitHubRepo(rawUrl: string): {
+    owner: string;
+    name: string;
+} | null;

package/dist/git-url/git-repo-identity.js

@@ -0,0 +1,161 @@
+// @bun
+import"../chunk-y64skrwp.js";
+
+// src/git-url/git-remote.ts
+var DEFAULT_PORTS = {
+  http: "80",
+  https: "443",
+  ssh: "22",
+  "git+ssh": "22",
+  "ssh+git": "22",
+  git: "9418"
+};
+var URL_FORM = /^([a-zA-Z][a-zA-Z0-9+.-]*):\/\/(.*)$/s;
+var SCP_FORM = /^(?:([^@/:\s]+)@)?([^@/:\s[\]]+):(?!:)(.+)$/;
+var HOST_PORT = /^(\[[^\]]+\]|[^:[\]]+)(?::(\d*))?$/;
+function parseRemote(rawUrl) {
+  const trimmed = rawUrl.trim();
+  if (trimmed === "") {
+    return null;
+  }
+  const urlForm = splitUrlForm(trimmed);
+  if (urlForm !== null) {
+    return parseUrlForm(urlForm);
+  }
+  if (URL_FORM.test(trimmed) || trimmed.startsWith("/")) {
+    return null;
+  }
+  return parseScpForm(trimmed);
+}
+function hasDefaultPort(remote) {
+  return remote.port === null || remote.port === DEFAULT_PORTS[remote.scheme];
+}
+function splitUrlForm(value) {
+  const match = URL_FORM.exec(value);
+  if (!match) {
+    return null;
+  }
+  const [, rawScheme = "", rest = ""] = match;
+  const scheme = rawScheme.toLowerCase();
+  if (!(scheme in DEFAULT_PORTS)) {
+    return null;
+  }
+  const authorityEnd = rest.search(/[/?#]/);
+  const authority = authorityEnd === -1 ? rest : rest.slice(0, authorityEnd);
+  const remainder = authorityEnd === -1 ? "" : rest.slice(authorityEnd);
+  const at = authority.lastIndexOf("@");
+  return {
+    scheme,
+    prefix: `${rawScheme}://`,
+    userinfo: at === -1 ? null : authority.slice(0, at),
+    hostPort: at === -1 ? authority : authority.slice(at + 1),
+    remainder
+  };
+}
+function normalisePath(path) {
+  return path.replace(/^\/+/, "").replace(/\/+$/, "").replace(/\.git$/, "").replace(/\/+$/, "");
+}
+function parseUrlForm(parts) {
+  const match = HOST_PORT.exec(parts.hostPort);
+  if (!match) {
+    return null;
+  }
+  const [, host = "", port = ""] = match;
+  return {
+    scheme: parts.scheme,
+    host: host.toLowerCase(),
+    port: port === "" ? null : port,
+    path: parts.remainder.replace(/[?#].*$/s, "")
+  };
+}
+function parseScpForm(value) {
+  const match = SCP_FORM.exec(value);
+  if (!match) {
+    return null;
+  }
+  const [, , host = "", path = ""] = match;
+  if (host.length === 1) {
+    return null;
+  }
+  return { scheme: "ssh", host: host.toLowerCase(), port: null, path };
+}
+
+// src/git-url/parse-git-host.ts
+var OTHER = { host: "other" };
+function parseGitHost(rawUrl) {
+  const parsed = parseRemote(rawUrl);
+  if (parsed === null || !hasDefaultPort(parsed)) {
+    return OTHER;
+  }
+  const segments = normalisePath(parsed.path).split("/");
+  if (segments.length !== 2) {
+    return OTHER;
+  }
+  const [first = "", second = ""] = segments;
+  if (first === "" || second === "") {
+    return OTHER;
+  }
+  switch (parsed.host) {
+    case "github.com":
+      return {
+        host: "github",
+        owner: first,
+        name: second,
+        webUrl: `https://github.com/${first}/${second}`
+      };
+    case "bitbucket.org":
+      return {
+        host: "bitbucket",
+        workspace: first,
+        slug: second,
+        webUrl: `https://bitbucket.org/${first}/${second}`
+      };
+    default:
+      return OTHER;
+  }
+}
+
+// src/git-url/git-repo-identity.ts
+var HTTP_SCHEMES = new Set(["http", "https"]);
+var CASE_INSENSITIVE_PATH_HOSTS = new Set(["github.com"]);
+function gitRepoIdentity(rawUrl) {
+  const parsed = parseRemote(rawUrl);
+  if (parsed === null) {
+    return null;
+  }
+  const path = normalisePath(parsed.path);
+  if (path === "") {
+    return null;
+  }
+  const port = parsed.port === null || hasDefaultPort(parsed) ? "" : `:${parsed.port}`;
+  const caseFoldedPath = CASE_INSENSITIVE_PATH_HOSTS.has(parsed.host) ? path.toLowerCase() : path;
+  return `${parsed.host}${port}/${caseFoldedPath}`;
+}
+function isSameGitRepo(a, b) {
+  const left = gitRepoIdentity(a);
+  const right = gitRepoIdentity(b);
+  if (left === null || right === null) {
+    return a === b;
+  }
+  return left === right;
+}
+function stripGitUrlCredentials(rawUrl) {
+  const parts = splitUrlForm(rawUrl.trim());
+  if (parts === null || parts.userinfo === null) {
+    return rawUrl;
+  }
+  const keptUser = HTTP_SCHEMES.has(parts.scheme) ? "" : parts.userinfo.split(":")[0] ?? "";
+  const userPart = keptUser === "" ? "" : `${keptUser}@`;
+  return `${parts.prefix}${userPart}${parts.hostPort}${parts.remainder}`;
+}
+function parseGitHubRepo(rawUrl) {
+  const repo = parseGitHost(rawUrl);
+  return repo.host === "github" ? { owner: repo.owner, name: repo.name } : null;
+}
+export {
+  gitRepoIdentity,
+  isSameGitRepo,
+  parseGitHost,
+  parseGitHubRepo,
+  stripGitUrlCredentials
+};

package/dist/git-url/parse-git-host.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Detects which supported repo host a git remote URL points at. No `node:`
+ * imports: Next client components use this module.
+ *
+ * Only `github.com/<owner>/<name>` and `bitbucket.org/<workspace>/<slug>` on
+ * the default port are recognised; every other remote, local path or
+ * unparseable string is `other`. Path segments keep the casing the URL uses.
+ */
+export type GitHost = {
+    host: "github";
+    owner: string;
+    name: string;
+    webUrl: string;
+} | {
+    host: "bitbucket";
+    workspace: string;
+    slug: string;
+    webUrl: string;
+} | {
+    host: "other";
+};
+export type GitHostKind = GitHost["host"];
+export declare function parseGitHost(rawUrl: string): GitHost;

package/dist/health-checks.d.ts

@@ -0,0 +1,169 @@
+import { z } from "zod";
+/**
+ * Severity of a step-declared health check.
+ *
+ * `required` (default) fails the step immediately if the check fails.
+ * `warn` is advisory — it is reported but never fails the step.
+ */
+export declare const healthCheckSeverityValues: readonly ["required", "warn"];
+export type HealthCheckSeverity = (typeof healthCheckSeverityValues)[number];
+/**
+ * A health check verified by forcing a real OpenCode tool call against the
+ * launched environment before the agent starts working.
+ *
+ * `tool` is a bare tool name when `mcp` is set (resolved at runtime to
+ * `${mcp}_${tool}`, matching OpenCode's MCP tool-naming convention), or a flat
+ * tool id otherwise (plugin tools, standalone tools, built-ins already share
+ * one flat namespace, so no qualifier applies).
+ */
+export declare const toolHealthCheckSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    severity: z.ZodDefault<z.ZodEnum<{
+        required: "required";
+        warn: "warn";
+    }>>;
+    timeoutSeconds: z.ZodDefault<z.ZodNumber>;
+    serialGroup: z.ZodOptional<z.ZodString>;
+    kind: z.ZodDefault<z.ZodLiteral<"tool">>;
+    tool: z.ZodString;
+    mcp: z.ZodOptional<z.ZodString>;
+    args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;
+/**
+ * A health check verified by running a command through OpenCode's `bash`
+ * tool inside the step's actual execution environment, and reading the real
+ * exit code back out of the tool result (not just call-completion status —
+ * see `force-and-verify-cli-health-check.ts`).
+ */
+export declare const cliHealthCheckSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    severity: z.ZodDefault<z.ZodEnum<{
+        required: "required";
+        warn: "warn";
+    }>>;
+    timeoutSeconds: z.ZodDefault<z.ZodNumber>;
+    serialGroup: z.ZodOptional<z.ZodString>;
+    kind: z.ZodLiteral<"cli">;
+    command: z.ZodArray<z.ZodString>;
+    expectExitCode: z.ZodDefault<z.ZodInt>;
+}, z.core.$strict>;
+export declare const healthCheckSchema: z.ZodPreprocess<z.ZodDiscriminatedUnion<[z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    severity: z.ZodDefault<z.ZodEnum<{
+        required: "required";
+        warn: "warn";
+    }>>;
+    timeoutSeconds: z.ZodDefault<z.ZodNumber>;
+    serialGroup: z.ZodOptional<z.ZodString>;
+    kind: z.ZodDefault<z.ZodLiteral<"tool">>;
+    tool: z.ZodString;
+    mcp: z.ZodOptional<z.ZodString>;
+    args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>, z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    severity: z.ZodDefault<z.ZodEnum<{
+        required: "required";
+        warn: "warn";
+    }>>;
+    timeoutSeconds: z.ZodDefault<z.ZodNumber>;
+    serialGroup: z.ZodOptional<z.ZodString>;
+    kind: z.ZodLiteral<"cli">;
+    command: z.ZodArray<z.ZodString>;
+    expectExitCode: z.ZodDefault<z.ZodInt>;
+}, z.core.$strict>], "kind">>;
+/**
+ * The full value of a step's `healthChecks` field.
+ */
+export declare const healthChecksSchema: z.ZodArray<z.ZodPreprocess<z.ZodDiscriminatedUnion<[z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    severity: z.ZodDefault<z.ZodEnum<{
+        required: "required";
+        warn: "warn";
+    }>>;
+    timeoutSeconds: z.ZodDefault<z.ZodNumber>;
+    serialGroup: z.ZodOptional<z.ZodString>;
+    kind: z.ZodDefault<z.ZodLiteral<"tool">>;
+    tool: z.ZodString;
+    mcp: z.ZodOptional<z.ZodString>;
+    args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>, z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    severity: z.ZodDefault<z.ZodEnum<{
+        required: "required";
+        warn: "warn";
+    }>>;
+    timeoutSeconds: z.ZodDefault<z.ZodNumber>;
+    serialGroup: z.ZodOptional<z.ZodString>;
+    kind: z.ZodLiteral<"cli">;
+    command: z.ZodArray<z.ZodString>;
+    expectExitCode: z.ZodDefault<z.ZodInt>;
+}, z.core.$strict>], "kind">>>;
+export type ToolHealthCheck = z.infer<typeof toolHealthCheckSchema>;
+export type CliHealthCheck = z.infer<typeof cliHealthCheckSchema>;
+export type HealthCheck = z.infer<typeof healthCheckSchema>;
+export type HealthChecks = z.infer<typeof healthChecksSchema>;
+/**
+ * The pre-parse authoring shape of a single health check — what a step
+ * author actually writes in `defineStep({ healthChecks: [...] })` — as
+ * opposed to `HealthCheck`, the post-parse output shape `packages/worker`'s
+ * runner narrows on (`kind` always present, defaulted).
+ *
+ * Derived from the two arm schemas directly (`z.input<typeof
+ * toolHealthCheckSchema | typeof cliHealthCheckSchema>`), not from
+ * `healthCheckSchema`/`healthChecksSchema` — those are `z.preprocess`-wrapped,
+ * and a preprocessed schema's `z.input` type collapses to `unknown` (the
+ * preprocess function's own input is unconstrained), so it can't back a
+ * real authoring-time type. `kind` is optional on the tool arm (it
+ * defaults to `"tool"` — decision ledger #2's "omit `kind` for a tool
+ * check" ergonomics apply at the authoring layer too, not just to legacy
+ * persisted rows) and a required literal `"cli"` on the cli arm (no
+ * default exists for it).
+ */
+export type HealthCheckInput = z.input<typeof toolHealthCheckSchema> | z.input<typeof cliHealthCheckSchema>;
+/** The pre-parse authoring shape of a step's `healthChecks` field. */
+export type HealthChecksInput = HealthCheckInput[];
+/**
+ * A `tool` check as written in `defineStep({ healthChecks })`: a plugin or
+ * built-in tool, never an MCP tool. MCP health checks are declared on the
+ * server with `defineMcp`, which compiles them to wire checks carrying `mcp`.
+ */
+export declare const stepToolHealthCheckSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    kind: z.ZodDefault<z.ZodLiteral<"tool">>;
+    severity: z.ZodDefault<z.ZodEnum<{
+        required: "required";
+        warn: "warn";
+    }>>;
+    timeoutSeconds: z.ZodDefault<z.ZodNumber>;
+    serialGroup: z.ZodOptional<z.ZodString>;
+    tool: z.ZodString;
+}, z.core.$strict>;
+/** The value of `defineStep({ healthChecks })`: `cli` and non-MCP `tool` checks. */
+export declare const stepHealthChecksInputSchema: z.ZodArray<z.ZodPreprocess<z.ZodDiscriminatedUnion<[z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    kind: z.ZodDefault<z.ZodLiteral<"tool">>;
+    severity: z.ZodDefault<z.ZodEnum<{
+        required: "required";
+        warn: "warn";
+    }>>;
+    timeoutSeconds: z.ZodDefault<z.ZodNumber>;
+    serialGroup: z.ZodOptional<z.ZodString>;
+    tool: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    severity: z.ZodDefault<z.ZodEnum<{
+        required: "required";
+        warn: "warn";
+    }>>;
+    timeoutSeconds: z.ZodDefault<z.ZodNumber>;
+    serialGroup: z.ZodOptional<z.ZodString>;
+    kind: z.ZodLiteral<"cli">;
+    command: z.ZodArray<z.ZodString>;
+    expectExitCode: z.ZodDefault<z.ZodInt>;
+}, z.core.$strict>], "kind">>>;
+/** The pre-parse authoring shape of one `defineStep({ healthChecks })` entry. */
+export type StepHealthCheckInput = z.input<typeof stepToolHealthCheckSchema> | z.input<typeof cliHealthCheckSchema>;
+/** The pre-parse authoring shape of `defineStep({ healthChecks })`. */
+export type StepHealthChecksInput = StepHealthCheckInput[];

package/dist/health-checks.js

@@ -0,0 +1,21 @@
+// @bun
+import {
+  cliHealthCheckSchema,
+  healthCheckSchema,
+  healthCheckSeverityValues,
+  healthChecksSchema,
+  stepHealthChecksInputSchema,
+  stepToolHealthCheckSchema,
+  toolHealthCheckSchema
+} from "./chunk-63f90zky.js";
+import"./chunk-skzxcba3.js";
+import"./chunk-y64skrwp.js";
+export {
+  cliHealthCheckSchema,
+  healthCheckSchema,
+  healthCheckSeverityValues,
+  healthChecksSchema,
+  stepHealthChecksInputSchema,
+  stepToolHealthCheckSchema,
+  toolHealthCheckSchema
+};

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export * as z from "./z";
+export * from "./client";
+export * from "./contracts/artifacts";
+export * from "./contracts/artifact-markers";
+export * from "./definitions/steps";
+export * from "./definitions/pipelines";
+export * from "./pipelines";
+export type { PipelineDefinition } from "./pipelines";
+export * from "./opencode-mcp";
+export * from "./jsonc";
+export * from "./scarn-config-parser";