@scarn/sdk 0.0.0-stage → 0.8.0

package/dist/contracts/pipeline-document/step-contract.d.ts

@@ -0,0 +1,11 @@
+/** What a pipeline document needs to know about the steps it uses. */
+import type { JsonSchema } from "./json";
+/** What the validator needs to know about a step definition. */
+export interface StepContract {
+    inputSchema: JsonSchema;
+    /** null: a conversation step, whose result is `CONVERSATION_RESULT_SCHEMA`. */
+    resultSchema: JsonSchema | null;
+    /** Error names the step declares, which `retry.on` and `catch.on` may use. */
+    errors: readonly string[];
+}
+export type StepCatalog = Readonly<Record<string, StepContract>>;

package/dist/contracts/step-artifact-submissions.d.ts

@@ -0,0 +1,71 @@
+import { type ArtifactField, type ArtifactJsonSchemaNode } from "./artifacts";
+export declare const STEP_ARTIFACTS_RELATIVE_DIR = ".scarn/step-artifacts";
+export declare const STEP_ARTIFACT_SUBMISSIONS_RELATIVE_PATH = ".scarn/current-execution/artifacts.json";
+export type SubmittedArtifact = {
+    /** Path relative to the step-artifacts folder. */
+    readonly stored: string;
+    /** The path the agent submitted, as given. */
+    readonly sourcePath: string;
+    readonly sizeBytes: number;
+};
+export type StepArtifactSubmissions = {
+    readonly fields: Readonly<Record<string, SubmittedArtifact>>;
+    readonly extra: readonly SubmittedArtifact[];
+};
+export declare const EMPTY_STEP_ARTIFACT_SUBMISSIONS: StepArtifactSubmissions;
+/** Declared artifact fields that can be filled in; v1 skips fields inside arrays. */
+export declare function findSubmittableArtifactFields(schema: ArtifactJsonSchemaNode | null | undefined): ArtifactField[];
+export declare function buildStepArtifactsDir(workspacePath: string): string;
+export declare function buildStepArtifactSubmissionsPath(workspacePath: string): string;
+/** Reads `artifacts.json`; a missing file means nothing was submitted. */
+export declare function readStepArtifactSubmissions(workspacePath: string): Promise<StepArtifactSubmissions>;
+export declare function writeStepArtifactSubmissions(workspacePath: string, submissions: StepArtifactSubmissions): Promise<void>;
+/** A step's findings as parsed JSON. */
+export type StepFindingsJson = string | number | boolean | null | StepFindingsJson[] | {
+    [key: string]: StepFindingsJson;
+};
+export type ApplyArtifactSubmissionsMode = 
+/**
+ * The plugin: a value the agent wrote in an artifact field is rejected, and
+ * every field is filled in from the submissions.
+ */
+"fill"
+/**
+ * The worker: the findings were already filled in, so each artifact field
+ * must equal what the submissions record.
+ */
+ | "verify";
+export type ApplyArtifactSubmissionsResult = {
+    /** The findings with every artifact field filled in (a copy). */
+    readonly findings: StepFindingsJson;
+    readonly problems: readonly string[];
+};
+/**
+ * Fills each declared artifact field from `submissions`: the stored name when
+ * the field was submitted, `null` when it wasn't and the field is nullable,
+ * and a problem when it wasn't and the field is required. Collects every
+ * problem rather than stopping at the first.
+ */
+export declare function applyArtifactSubmissions(input: {
+    readonly findings: StepFindingsJson;
+    readonly fields: readonly ArtifactField[];
+    readonly submissions: StepArtifactSubmissions;
+    readonly mode: ApplyArtifactSubmissionsMode;
+}): ApplyArtifactSubmissionsResult;
+/** Checks every submitted field's stored file is still a non-empty file. */
+export declare function checkSubmittedArtifactFiles(input: {
+    readonly workspacePath: string;
+    readonly fields: readonly ArtifactField[];
+    readonly submissions: StepArtifactSubmissions;
+}): Promise<string[]>;
+/**
+ * Checks the artifact fields a code step returned (`Artifact.path(...)`
+ * values): each must be a path inside the step-artifacts folder naming a
+ * non-empty file with an accepted extension. `null` and absent values are
+ * left to the schema check.
+ */
+export declare function checkReturnedArtifactPaths(input: {
+    readonly workspacePath: string;
+    readonly fields: readonly ArtifactField[];
+    readonly findings: StepFindingsJson;
+}): Promise<string[]>;

package/dist/contracts/step-artifact-submissions.js

@@ -0,0 +1,171 @@
+// @bun
+import {
+  artifactAcceptsFile,
+  artifactFileExtension,
+  findArtifactFields
+} from "../chunk-y2pv8d6a.js";
+import {
+  exports_external
+} from "../chunk-skzxcba3.js";
+import"../chunk-y64skrwp.js";
+
+// src/contracts/step-artifact-submissions.ts
+import { mkdir, readFile, stat, writeFile } from "fs/promises";
+import path from "path";
+var STEP_ARTIFACTS_RELATIVE_DIR = ".scarn/step-artifacts";
+var STEP_ARTIFACT_SUBMISSIONS_RELATIVE_PATH = ".scarn/current-execution/artifacts.json";
+var EMPTY_STEP_ARTIFACT_SUBMISSIONS = {
+  fields: {},
+  extra: []
+};
+function findSubmittableArtifactFields(schema) {
+  return findArtifactFields(schema).filter((field) => !field.inArray);
+}
+var submittedArtifactSchema = exports_external.object({
+  stored: exports_external.string().min(1),
+  sourcePath: exports_external.string(),
+  sizeBytes: exports_external.number()
+});
+var stepArtifactSubmissionsSchema = exports_external.object({
+  fields: exports_external.record(exports_external.string(), submittedArtifactSchema),
+  extra: exports_external.array(submittedArtifactSchema)
+});
+function buildStepArtifactsDir(workspacePath) {
+  return path.join(workspacePath, STEP_ARTIFACTS_RELATIVE_DIR);
+}
+function buildStepArtifactSubmissionsPath(workspacePath) {
+  return path.join(workspacePath, STEP_ARTIFACT_SUBMISSIONS_RELATIVE_PATH);
+}
+async function readStepArtifactSubmissions(workspacePath) {
+  let raw;
+  try {
+    raw = await readFile(buildStepArtifactSubmissionsPath(workspacePath), "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return EMPTY_STEP_ARTIFACT_SUBMISSIONS;
+    }
+    throw error;
+  }
+  const parsed = stepArtifactSubmissionsSchema.safeParse(JSON.parse(raw));
+  if (!parsed.success) {
+    throw new Error(`${STEP_ARTIFACT_SUBMISSIONS_RELATIVE_PATH} is malformed: ${parsed.error.message}`);
+  }
+  return parsed.data;
+}
+async function writeStepArtifactSubmissions(workspacePath, submissions) {
+  const filePath = buildStepArtifactSubmissionsPath(workspacePath);
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, `${JSON.stringify(submissions, null, 2)}
+`, "utf8");
+}
+function isJsonObject(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function readPath(root, segments) {
+  let current = root;
+  for (const segment of segments) {
+    if (!isJsonObject(current))
+      return;
+    current = current[segment];
+  }
+  return current;
+}
+function writePath(root, segments, value) {
+  let current = root;
+  for (const segment of segments.slice(0, -1)) {
+    const next = current[segment];
+    if (isJsonObject(next)) {
+      current = next;
+      continue;
+    }
+    if (value === null || next !== undefined)
+      return;
+    const created = {};
+    current[segment] = created;
+    current = created;
+  }
+  const last = segments.at(-1);
+  if (last !== undefined)
+    current[last] = value;
+}
+function submitHint(field) {
+  return `call \`scarn-submit-artifact\` with \`field: "${field}"\``;
+}
+function applyArtifactSubmissions(input) {
+  const findings = structuredClone(input.findings);
+  const problems = [];
+  if (!isJsonObject(findings))
+    return { findings, problems };
+  for (const field of input.fields) {
+    const segments = field.path.split(".");
+    const current = readPath(findings, segments);
+    const submitted = input.submissions.fields[field.path];
+    const expected = submitted?.stored ?? null;
+    if (input.mode === "fill" && current !== undefined && current !== null) {
+      problems.push(`\`${field.path}\` is filled in from submitted artifacts. Remove it and ${submitHint(field.path)}.`);
+    }
+    if (input.mode === "verify" && (current ?? null) !== expected && (submitted || field.nullable)) {
+      problems.push(`\`${field.path}\` is ${JSON.stringify(current ?? null)} in the findings, but the submitted artifacts record ${JSON.stringify(expected)}.`);
+    }
+    if (!submitted && !field.nullable) {
+      problems.push(`\`${field.path}\` is required. Save the file and ${submitHint(field.path)} first.`);
+      continue;
+    }
+    writePath(findings, segments, expected);
+  }
+  return { findings, problems };
+}
+async function checkSubmittedArtifactFiles(input) {
+  const artifactsDir = buildStepArtifactsDir(input.workspacePath);
+  const problems = [];
+  for (const field of input.fields) {
+    const submitted = input.submissions.fields[field.path];
+    if (!submitted)
+      continue;
+    const relativePath = path.posix.join(STEP_ARTIFACTS_RELATIVE_DIR, submitted.stored);
+    const stats = await stat(path.join(artifactsDir, submitted.stored)).catch(() => null);
+    if (!stats?.isFile() || stats.size === 0) {
+      problems.push(`\`${field.path}\` was submitted as ${submitted.stored}, but ${relativePath} is missing or empty. Save the file again and ${submitHint(field.path)}.`);
+    }
+  }
+  return problems;
+}
+function isInsideArtifactsDir(value) {
+  const normalized = path.posix.normalize(value);
+  return normalized === value && !value.includes("\\") && !path.posix.isAbsolute(value) && value !== "." && value !== ".." && !value.startsWith("../") && !value.endsWith("/");
+}
+async function checkReturnedArtifactPaths(input) {
+  const artifactsDir = buildStepArtifactsDir(input.workspacePath);
+  const problems = [];
+  for (const field of input.fields) {
+    const value = readPath(input.findings, field.path.split("."));
+    if (value === undefined || value === null)
+      continue;
+    if (typeof value !== "string" || !isInsideArtifactsDir(value)) {
+      problems.push(`\`${field.path}\` must be a path relative to ${STEP_ARTIFACTS_RELATIVE_DIR} (use \`Artifact.path("<name>")\`), got ${JSON.stringify(value)}.`);
+      continue;
+    }
+    const stats = await stat(path.join(artifactsDir, value)).catch(() => null);
+    if (!stats?.isFile() || stats.size === 0) {
+      problems.push(`\`${field.path}\` is ${value}, but ${path.posix.join(STEP_ARTIFACTS_RELATIVE_DIR, value)} is missing or empty.`);
+      continue;
+    }
+    if (!artifactAcceptsFile(field.accept, value)) {
+      problems.push(`\`${field.path}\` accepts ${field.accept.join(", ")}, but ${value} has ${artifactFileExtension(value) || "no extension"}.`);
+    }
+  }
+  return problems;
+}
+export {
+  EMPTY_STEP_ARTIFACT_SUBMISSIONS,
+  STEP_ARTIFACTS_RELATIVE_DIR,
+  STEP_ARTIFACT_SUBMISSIONS_RELATIVE_PATH,
+  applyArtifactSubmissions,
+  buildStepArtifactSubmissionsPath,
+  buildStepArtifactsDir,
+  checkReturnedArtifactPaths,
+  checkSubmittedArtifactFiles,
+  findSubmittableArtifactFields,
+  readStepArtifactSubmissions,
+  writeStepArtifactSubmissions
+};

package/dist/defaults/atomic-json-file.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Writes `data` as pretty-printed JSON to `filePath` atomically: serialize to
+ * a pid+timestamp-suffixed temp file in the same directory, then rename it
+ * over the target so a concurrent reader never observes a partially-written
+ * file. Creates the parent directory if it doesn't exist yet, and
+ * best-effort restricts both the temp file and the final path to
+ * owner-read/write (0o600). Shared by `auth-file.ts`'s `writeAuthFile` and
+ * `config-file.ts`'s `writeConfigFile` — the dance is identical for both.
+ */
+export declare function writeJsonFileAtomically(filePath: string, data: unknown): void;

package/dist/defaults/auth-file.d.ts

@@ -0,0 +1,14 @@
+export interface AuthProfile {
+    accessToken: string;
+    userId?: string;
+    email?: string;
+    name?: string;
+}
+export interface AuthFile {
+    profiles: Record<string, AuthProfile>;
+}
+export declare const getAuthFilePath: () => string;
+export declare const loadAuthFile: () => AuthFile;
+export declare const loadAuthProfile: (baseUrl: string) => AuthProfile | null;
+export declare const saveAuthProfile: (baseUrl: string, profile: AuthProfile) => void;
+export declare const deleteAuthProfile: (baseUrl: string) => void;

package/dist/defaults/base-url.d.ts

@@ -0,0 +1 @@
+export declare const resolveScarnBaseUrl: (value?: string | null) => string;

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

@@ -0,0 +1,46 @@
+export declare const DEFAULT_ARTIFACT_LOCAL_MAX_BYTES: number;
+export declare const DEFAULT_ARTIFACT_LOCAL_MAX_AGE_DAYS = 14;
+export interface ArtifactRetentionSettings {
+    localMaxBytes: number;
+    localMaxAgeDays: number;
+}
+export interface ConfigFile {
+    /**
+     * A random id generated on first read and persisted here — it identifies
+     * this machine/install before any account exists, so pre-auth CLI
+     * telemetry (init started, requirements verified) has a stable distinct
+     * id to key events to. See `getOrCreateAnonymousId`.
+     */
+    anonymousId?: string;
+    /**
+     * User-level telemetry opt-out, set via `scarn telemetry disable` (or
+     * the `SCARN_TELEMETRY_DISABLED` env var, checked separately at the
+     * call site). Global — unlike auth profiles, it is not scoped to a
+     * `baseUrl`.
+     */
+    telemetryDisabled?: boolean;
+    artifacts: ArtifactRetentionSettings;
+}
+export declare const getConfigFilePath: () => string;
+/**
+ * See the matching comment in `auth-file.ts`: both modules must trigger
+ * `migrateLegacyConfigIfNeeded` from their own `loadX`, but neither may
+ * import the other, so `auth.jsonc`'s path is mirrored here rather than
+ * imported from `auth-file.ts`. `auth-file.ts` is the source of truth for
+ * that path string; if it ever changes, update both call sites.
+ */
+export declare const loadConfigFile: () => ConfigFile;
+/**
+ * The persisted pre-auth distinct id for this machine/install, creating and
+ * persisting one the first time it is read. Stable across every command
+ * invocation until `~/.scarn/config.jsonc` is deleted or edited by hand —
+ * unlike `auth.jsonc`, nothing in this package deletes `config.jsonc`
+ * automatically (telemetry settings survive `scarn auth logout`, matching
+ * today's behavior).
+ */
+export declare const getOrCreateAnonymousId: () => string;
+/** The persisted telemetry opt-out flag. Defaults to `false` (enabled). */
+export declare const isTelemetryDisabled: () => boolean;
+/** Persist the telemetry opt-out flag, leaving everything else intact. */
+export declare const setTelemetryDisabled: (disabled: boolean) => void;
+export declare const getArtifactRetentionSettings: () => ArtifactRetentionSettings;

package/dist/defaults/home-dir.d.ts

@@ -0,0 +1,3 @@
+/** Test-only. Redirects every read/write path derived from `resolveHomeDir`. */
+export declare function setHomeDirForTests(dir: string | undefined): void;
+export declare function resolveHomeDir(): string;

package/dist/defaults/index.d.ts

@@ -0,0 +1,12 @@
+export { deleteAuthProfile, getAuthFilePath, loadAuthFile, loadAuthProfile, saveAuthProfile, } from "./auth-file";
+export type { AuthFile, AuthProfile } from "./auth-file";
+export { getArtifactRetentionSettings, getConfigFilePath, getOrCreateAnonymousId, isTelemetryDisabled, loadConfigFile, setTelemetryDisabled, } from "./config-file";
+export type { ArtifactRetentionSettings, ConfigFile } from "./config-file";
+export { setHomeDirForTests } from "./home-dir";
+export { resolveScarnBaseUrl } from "./base-url";
+export { formatProjectRef, isProjectRef, loadProjectConfig, parseProjectRef, PROJECT_CONFIG_RELATIVE_PATH, } from "./project-config";
+export type { ProjectConfig, ProjectRef } from "./project-config";
+export { PROJECT_REF_FORMAT_HINT, ProjectRefError, resolveProjectRef, } from "./project-ref";
+export type { ProjectRefErrorKind, ResolvedProjectRef, ResolveProjectRefOptions, } from "./project-ref";
+export { loadPushDefaults } from "./load-push-defaults";
+export type { LoadPushDefaultsOptions, PushDefaults, } from "./load-push-defaults";