@scarn/sdk 0.0.0-stage → 0.8.0

package/dist/push/index.js

@@ -0,0 +1,327 @@
+// @bun
+import {
+  assertValidDefinitionSpecs
+} from "../chunk-gds7w7zh.js";
+import {
+  isStepDefinitionSpec,
+  stepsInModule
+} from "../chunk-ar6hcj1r.js";
+import {
+  createStepDefinitionsClient,
+  toStepSpec
+} from "../chunk-3ctaaseb.js";
+import"../chunk-mz53r914.js";
+import"../chunk-5zsavw98.js";
+import"../chunk-4ggr8af6.js";
+import"../chunk-k4y5qt4y.js";
+import"../chunk-cdanncng.js";
+import"../chunk-e1h021kq.js";
+import"../chunk-63f90zky.js";
+import"../chunk-ngy1fdcx.js";
+import"../chunk-y2pv8d6a.js";
+import"../chunk-dp86pa6m.js";
+import {
+  DEFAULT_PIPELINE_ASSIGNMENT_FILENAME,
+  PipelineDefinitionsApiError,
+  createPipelineDefinitionsClient,
+  isDefaultPipelineAssignmentSpec,
+  serializeDefaultPipelineAssignment
+} from "../chunk-zm72ksz0.js";
+import {
+  Projects,
+  createClient
+} from "../chunk-vfeytkqx.js";
+import {
+  exports_external
+} from "../chunk-skzxcba3.js";
+import"../chunk-y64skrwp.js";
+
+// src/push/collect-definitions.ts
+import { existsSync, readdirSync } from "fs";
+import { join, relative, resolve } from "path";
+import { pathToFileURL } from "url";
+var INTERNAL_SCRIPT_NAMES = new Set([
+  "push.ts",
+  "push.mjs",
+  "push.js",
+  ".scarn-studio-collect.mjs",
+  ".scarn-build.ts"
+]);
+var PIPELINE_BUILDER_DIR = ".scarn/pipeline-builder";
+function createCollectionState() {
+  return { stepMap: new Map, codeSteps: new Map };
+}
+function registerCodeStep(state, spec, sourceFile) {
+  const fn = spec.entrypoint?.fn;
+  if (spec.kind !== "code" || !fn)
+    return;
+  const existing = state.codeSteps.get(spec.key);
+  if (!existing) {
+    state.codeSteps.set(spec.key, { version: spec.version, fn, sourceFile });
+    return;
+  }
+  if (existing.version !== spec.version) {
+    throw new Error(`Code step "${spec.key}" is defined with different versions ` + `(v${String(existing.version)} in ${existing.sourceFile}, v${String(spec.version)} in ${sourceFile}). ` + `A code step is found by key alone, so give each code step a unique key.`);
+  }
+  if (existing.fn !== fn) {
+    throw new Error(`Code step "${spec.key}" is defined with different fn references ` + `(${existing.sourceFile} and ${sourceFile}). ` + `A code step is found by key alone, so give each code step a unique key.`);
+  }
+}
+function resolveCodeStepEntrypoint(spec, absoluteFilePath, absDir) {
+  if (spec.kind !== "code")
+    return toStepSpec(spec);
+  if (!spec.entrypoint?.fn) {
+    throw new Error(`Code step "${spec.key}" (kind: "code") has no entrypoint.fn. ` + `Build it with codeStep({ fn, ... }) from "@scarn/sdk/definitions/steps".`);
+  }
+  const resolved = toStepSpec(spec);
+  delete resolved.entrypoint;
+  resolved.entrypointJson = {
+    sourceFile: join(PIPELINE_BUILDER_DIR, relative(absDir, absoluteFilePath))
+  };
+  return resolved;
+}
+async function importModule(path) {
+  return await import(pathToFileURL(path).href);
+}
+function listSourceFiles(absDir) {
+  const allFiles = readdirSync(absDir).filter((file) => file.endsWith(".ts") || file.endsWith(".js"));
+  return allFiles.filter((file) => !INTERNAL_SCRIPT_NAMES.has(file) && file !== DEFAULT_PIPELINE_ASSIGNMENT_FILENAME);
+}
+function fileNameWithoutExtension(file) {
+  return file.replace(/\.(ts|js)$/, "");
+}
+async function collectFile(absoluteFilePath, absDir, state) {
+  const mod = await importModule(absoluteFilePath);
+  for (const step of stepsInModule(mod)) {
+    registerCodeStep(state, step, absoluteFilePath);
+  }
+  for (const [exportName, value] of Object.entries(mod)) {
+    if (exportName === "default" || !isStepDefinitionSpec(value))
+      continue;
+    const resolved = resolveCodeStepEntrypoint(value, absoluteFilePath, absDir);
+    state.stepMap.set(`${resolved.key}@v${String(resolved.version)}`, resolved);
+  }
+}
+async function collectDefinitionsFromDirectory(dir) {
+  const absDir = resolve(dir);
+  const sourceFiles = listSourceFiles(absDir);
+  const state = createCollectionState();
+  for (const file of sourceFiles) {
+    await collectFile(join(absDir, file), absDir, state);
+  }
+  return {
+    steps: [...state.stepMap.values()],
+    defaultPipelineAssignment: await collectDefaultPipelineAssignment(absDir)
+  };
+}
+async function collectDefinitionsFromDirectoryTolerant(dir) {
+  const absDir = resolve(dir);
+  const sourceFiles = listSourceFiles(absDir);
+  const state = createCollectionState();
+  const brokenPipelines = [];
+  for (const file of sourceFiles) {
+    try {
+      await collectFile(join(absDir, file), absDir, state);
+    } catch (error) {
+      brokenPipelines.push({
+        key: fileNameWithoutExtension(file),
+        message: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+  let defaultPipelineAssignment = null;
+  try {
+    defaultPipelineAssignment = await collectDefaultPipelineAssignment(absDir);
+  } catch (error) {
+    brokenPipelines.push({
+      key: fileNameWithoutExtension(DEFAULT_PIPELINE_ASSIGNMENT_FILENAME),
+      message: error instanceof Error ? error.message : String(error)
+    });
+  }
+  return {
+    steps: [...state.stepMap.values()],
+    defaultPipelineAssignment,
+    brokenPipelines
+  };
+}
+async function collectDefaultPipelineAssignment(absDir) {
+  const path = join(absDir, DEFAULT_PIPELINE_ASSIGNMENT_FILENAME);
+  if (!existsSync(path))
+    return null;
+  const mod = await importModule(path);
+  const spec = mod["default"];
+  if (!isDefaultPipelineAssignmentSpec(spec)) {
+    throw new Error(`${DEFAULT_PIPELINE_ASSIGNMENT_FILENAME} must have a default export produced by defaultPipelineAssignment(({ assign, skip, ... }) => ({ default: ..., rules: [...] })). Got: ${typeof spec}`);
+  }
+  return spec;
+}
+// src/push/collect-pipeline-documents.ts
+import { readdirSync as readdirSync2, readFileSync } from "fs";
+import { join as join2, resolve as resolve2 } from "path";
+var NON_PIPELINE_JSON = new Set([
+  "package.json",
+  "package-lock.json",
+  "tsconfig.json",
+  "jsconfig.json",
+  "deno.json"
+]);
+var pipelineDocumentSchema = exports_external.looseObject({ nodes: exports_external.unknown() });
+var documentHeaderSchema = exports_external.object({
+  key: exports_external.string().min(1),
+  title: exports_external.string().optional()
+});
+function collectPipelineDocuments(dir) {
+  const absDir = resolve2(dir);
+  const files = readdirSync2(absDir).filter((file) => file.endsWith(".json") && !NON_PIPELINE_JSON.has(file)).sort();
+  const byKey = new Map;
+  for (const file of files) {
+    const parsed = pipelineDocumentSchema.safeParse(parseJsonFile(join2(absDir, file), file));
+    if (!parsed.success)
+      continue;
+    const document = parsed.data;
+    const header = documentHeaderSchema.safeParse(document);
+    if (!header.success) {
+      throw new Error(`${file} has no "key": every pipeline document names the pipeline it publishes to.`);
+    }
+    const { key, title } = header.data;
+    const existing = byKey.get(key);
+    if (existing) {
+      throw new Error(`${existing.file} and ${file} are both pipeline "${key}". Delete the stale one and build again.`);
+    }
+    byKey.set(key, { file, key, title, document });
+  }
+  return [...byKey.values()];
+}
+function parseJsonFile(path, file) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    throw new Error(`${file} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+  }
+}
+// src/push/push-from-directory.ts
+async function pushFromDirectory(dir, opts) {
+  const log = opts.log ?? ((msg) => {
+    console.warn(msg);
+  });
+  const headers = { Authorization: `Bearer ${opts.accessToken}` };
+  const collected = await collectDefinitionsFromDirectory(dir);
+  const { steps } = collected;
+  const documents = collectPipelineDocuments(dir);
+  log(`Found ${String(steps.length)} step(s) and ${String(documents.length)} pipeline document(s).`);
+  assertValidDefinitionSpecs(steps);
+  const stepsClient = createStepDefinitionsClient(opts.baseUrl);
+  for (const spec of steps) {
+    await stepsClient.upsertFromSpec(opts.projectId, spec, { headers });
+    log(`\u2713 step ${spec.key} v${String(spec.version)} \u2192 upserted`);
+  }
+  const pipelinesClient = createPipelineDefinitionsClient(opts.baseUrl);
+  const publishedPipelines = [];
+  const unchangedPipelines = [];
+  if (documents.length > 0) {
+    const serverPipelines = await pipelinesClient.listByProjectId(opts.projectId, { headers });
+    const idByKey = new Map(serverPipelines.map((p) => [p.key, p.id]));
+    for (const document of documents) {
+      const published = await publishPipelineDocument(document, idByKey.get(document.key), opts.projectId, headers, pipelinesClient, log);
+      (published ? publishedPipelines : unchangedPipelines).push(document.key);
+    }
+  }
+  const syncedDefaultPipelineAssignment = collected.defaultPipelineAssignment ? await syncDefaultPipelineAssignment(collected.defaultPipelineAssignment, opts, headers, pipelinesClient, log) : false;
+  return {
+    pushedSteps: steps.length,
+    publishedPipelines,
+    unchangedPipelines,
+    syncedDefaultPipelineAssignment
+  };
+}
+async function publishPipelineDocument({ file, key, title, document }, pipelineDefinitionId, projectId, headers, pipelinesClient, log) {
+  try {
+    if (pipelineDefinitionId === undefined) {
+      await pipelinesClient.create({ projectId, key, name: title ?? key, document }, { headers });
+      log(`\u2713 pipeline ${key} \u2192 created and published (${file})`);
+      return true;
+    }
+    const result = await pipelinesClient.publishVersion(pipelineDefinitionId, document, { headers });
+    const version = String(result.version.version);
+    log(result.published ? `\u2713 pipeline ${key} v${version} \u2192 published (${file})` : `\u2713 pipeline ${key} v${version} \u2192 unchanged (${file})`);
+    return result.published;
+  } catch (error) {
+    if (error instanceof PipelineDefinitionsApiError) {
+      const issues = error.issues.map((issue) => issue.hint === undefined ? `  ${issue.path || "/"}: ${issue.message}` : `  ${issue.path || "/"}: ${issue.message}. ${issue.hint}`);
+      throw new Error([`Could not publish ${file}: ${error.message}`, ...issues].join(`
+`), { cause: error });
+    }
+    throw error;
+  }
+}
+async function syncDefaultPipelineAssignment(spec, opts, headers, pipelinesClient, log) {
+  const serialized = serializeDefaultPipelineAssignment(spec);
+  const serverPipelines = await pipelinesClient.listByProjectId(opts.projectId, {
+    headers
+  });
+  const pipelineKeyToId = new Map(serverPipelines.map((p) => [p.key, p.id]));
+  const referencedKeys = new Set;
+  referencedKeys.add(serialized.pipelineDefinitionKey);
+  for (const rule of serialized.rulesJson.rules) {
+    if (rule.event.type === "assign" && typeof rule.event.params?.["pipelineKey"] === "string") {
+      referencedKeys.add(rule.event.params["pipelineKey"]);
+    }
+  }
+  for (const key of referencedKeys) {
+    if (!pipelineKeyToId.has(key)) {
+      throw new Error(`${DEFAULT_PIPELINE_ASSIGNMENT_FILENAME} references pipeline "${key}", ` + `but no pipeline with that key was found on the server. ` + `Run \`scarn pipelines build\` to write ${key}.json next to its source, then push again.`);
+    }
+  }
+  const pipelineDefinitionId = pipelineKeyToId.get(serialized.pipelineDefinitionKey);
+  if (!pipelineDefinitionId) {
+    throw new Error(`Pipeline key "${serialized.pipelineDefinitionKey}" was not found on the server.`);
+  }
+  const resolvedRules = serialized.rulesJson.rules.map((rule) => {
+    if (rule.event.type === "assign" && typeof rule.event.params?.["pipelineKey"] === "string") {
+      const pKey = rule.event.params["pipelineKey"];
+      const pId = pipelineKeyToId.get(pKey);
+      if (!pId) {
+        throw new Error(`${DEFAULT_PIPELINE_ASSIGNMENT_FILENAME} assign() references pipeline "${pKey}" ` + `which was not found on the server.`);
+      }
+      return {
+        ...rule,
+        event: {
+          ...rule.event,
+          params: {
+            ...rule.event.params,
+            pipelineDefinitionId: pId
+          }
+        }
+      };
+    }
+    return rule;
+  });
+  const projectsClient = new Projects({
+    client: createClient({ baseUrl: opts.baseUrl })
+  });
+  const result = await projectsClient.updateProjectDefaultPipelineAssignment({
+    path: { projectId: opts.projectId },
+    body: {
+      defaultPipelineAssignment: {
+        pipelineDefinitionId,
+        rulesJson: { rules: resolvedRules },
+        defaultEventType: serialized.defaultEventType,
+        defaultEventParamsJson: serialized.defaultEventParamsJson,
+        allowedEventTypes: serialized.allowedEventTypes
+      }
+    },
+    headers
+  });
+  if (result.error) {
+    throw new Error(`Failed to update project default pipeline assignment: ${JSON.stringify(result.error)}`);
+  }
+  log(`\u2713 default pipeline assignment \u2192 synced (primary pipeline: ${serialized.pipelineDefinitionKey})`);
+  return true;
+}
+export {
+  PIPELINE_BUILDER_DIR,
+  collectDefinitionsFromDirectory,
+  collectDefinitionsFromDirectoryTolerant,
+  collectPipelineDocuments,
+  pushFromDirectory
+};

package/dist/push/push-from-directory.d.ts

@@ -0,0 +1,37 @@
+export interface PushFromDirectoryOptions {
+    baseUrl: string;
+    projectId: string;
+    accessToken: string;
+    /** Override the logger; defaults to console.log. */
+    log?: (message: string) => void;
+}
+export interface PushFromDirectoryResult {
+    pushedSteps: number;
+    /** Keys of the pipelines that got a new active version. */
+    publishedPipelines: string[];
+    /** Keys of the pipelines whose document matched their latest version. */
+    unchangedPipelines: string[];
+    /** true if the default pipeline assignment was synced to the server. */
+    syncedDefaultPipelineAssignment: boolean;
+}
+/**
+ * Pushes a pipeline-builder directory to the server, in three passes:
+ *
+ * 1. Upserts every step exported from the `.ts`/`.js` files (except the push
+ *    script itself and `default-pipeline-assignment.ts`).
+ * 2. Publishes every built pipeline document (`<key>.json`, from
+ *    `scarn pipelines build`), creating the pipeline when its key is new.
+ *    The server pins each document to the steps just pushed; a document
+ *    identical to its latest version publishes nothing.
+ * 3. Syncs `default-pipeline-assignment.ts`, when present, as the project
+ *    default pipeline assignment. Every pipeline it assigns must exist by now.
+ *
+ * Collection (`collectDefinitionsFromDirectory`, `collectPipelineDocuments`)
+ * and step validation (`validateDefinitionSpecs`) are offline and run before
+ * the first mutating request, so an invalid batch fails without half-pushing.
+ *
+ * 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.
+ */
+export declare function pushFromDirectory(dir: string, opts: PushFromDirectoryOptions): Promise<PushFromDirectoryResult>;

package/dist/repo-config.d.ts

@@ -0,0 +1,80 @@
+import { z } from "zod";
+/**
+ * Wire schema for a step's repository access (`repo`): what the worker does
+ * with the clone.
+ *
+ * - `none`: no repository. The worker does not clone, branch, commit or push.
+ * - `readOnly`: clones and checks out the base branch, but creates no work
+ *   branch, commits nothing and pushes nothing.
+ * - `readWrite`: creates a work branch, commits and pushes. `message` is the
+ *   commit message template (`{{input.…}}` and `{{result.…}}` tokens only) and
+ *   `onPushFailure` picks whether a failed push fails the step.
+ *
+ * Two shapes of the same data. `RepoConfigInput` is what an author or API client
+ * sends and may leave things out; `RepoConfig` is what is stored, returned and
+ * handed to the worker, fully resolved by `resolveRepoConfig`. A resolved
+ * `RepoConfig` is also a valid `RepoConfigInput`, so a client can send back what
+ * it read (hence a `null` message is accepted on input).
+ *
+ * Which modes each runtime accepts is `REPO_RUNTIME_SUPPORT`; a new runtime adds
+ * a row there instead of changing the schema.
+ */
+export declare const MAX_REPO_COMMIT_MESSAGE_LENGTH = 500;
+export declare const REPO_COMMIT_MESSAGE_TOKEN_ROOTS: readonly string[];
+export type RepoMode = "none" | "readOnly" | "readWrite";
+export type RepoOnPushFailure = "fail" | "warn";
+export type RepoExecutionMode = "workspace" | "no_workspace";
+/**
+ * The root segment of every `{{…}}` token in `message` that is not one of
+ * `REPO_COMMIT_MESSAGE_TOKEN_ROOTS`, in order of appearance. Tokens are parsed
+ * the way `renderPromptTemplate` renders them.
+ */
+export declare function findDisallowedCommitMessageTokenRoots(message: string): string[];
+export declare const repoCommitMessageSchema: z.ZodString;
+export declare const repoConfigInputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    mode: z.ZodLiteral<"none">;
+}, z.core.$strict>, z.ZodObject<{
+    mode: z.ZodLiteral<"readOnly">;
+}, z.core.$strict>, z.ZodObject<{
+    mode: z.ZodLiteral<"readWrite">;
+    message: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    onPushFailure: z.ZodOptional<z.ZodEnum<{
+        warn: "warn";
+        fail: "fail";
+    }>>;
+}, z.core.$strict>], "mode">;
+export declare const repoConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    mode: z.ZodLiteral<"none">;
+}, z.core.$strict>, z.ZodObject<{
+    mode: z.ZodLiteral<"readOnly">;
+}, z.core.$strict>, z.ZodObject<{
+    mode: z.ZodLiteral<"readWrite">;
+    message: z.ZodNullable<z.ZodString>;
+    onPushFailure: z.ZodEnum<{
+        warn: "warn";
+        fail: "fail";
+    }>;
+}, z.core.$strict>], "mode">;
+export type RepoConfigInput = z.input<typeof repoConfigInputSchema>;
+export type RepoConfig = z.output<typeof repoConfigSchema>;
+type RepoRuntimeSupport = {
+    readonly modes: readonly RepoMode[];
+    readonly default: RepoMode;
+    /** Why the modes outside `modes` are rejected. */
+    readonly unsupportedBecause: string;
+};
+/** Which `repo` modes each execution mode accepts, and its default. */
+export declare const REPO_RUNTIME_SUPPORT: Record<RepoExecutionMode, RepoRuntimeSupport>;
+/**
+ * Why `mode` cannot be used with `executionMode`, or `null` when the pair is
+ * valid.
+ */
+export declare function repoRuntimeMismatch(executionMode: RepoExecutionMode, mode: RepoMode): string | null;
+/**
+ * Fills what an author left out: an omitted `repo` becomes the runtime's default
+ * (`readWrite` for `workspace`, `none` for `no_workspace`), an omitted
+ * `onPushFailure` becomes `"fail"` and an omitted `message` becomes `null`.
+ * Does not check the runtime pairing; that is the caller's invariant.
+ */
+export declare function resolveRepoConfig(executionMode: RepoExecutionMode, input?: RepoConfigInput | null): RepoConfig;
+export {};

package/dist/repo-config.js

@@ -0,0 +1,25 @@
+// @bun
+import {
+  MAX_REPO_COMMIT_MESSAGE_LENGTH,
+  REPO_COMMIT_MESSAGE_TOKEN_ROOTS,
+  REPO_RUNTIME_SUPPORT,
+  findDisallowedCommitMessageTokenRoots,
+  repoCommitMessageSchema,
+  repoConfigInputSchema,
+  repoConfigSchema,
+  repoRuntimeMismatch,
+  resolveRepoConfig
+} from "./chunk-cdanncng.js";
+import"./chunk-skzxcba3.js";
+import"./chunk-y64skrwp.js";
+export {
+  MAX_REPO_COMMIT_MESSAGE_LENGTH,
+  REPO_COMMIT_MESSAGE_TOKEN_ROOTS,
+  REPO_RUNTIME_SUPPORT,
+  findDisallowedCommitMessageTokenRoots,
+  repoCommitMessageSchema,
+  repoConfigInputSchema,
+  repoConfigSchema,
+  repoRuntimeMismatch,
+  resolveRepoConfig
+};

package/dist/scarn-config-parser.d.ts

@@ -0,0 +1,29 @@
+export declare const SCARN_CONFIG_RELATIVE_PATH = ".scarn/scarn.jsonc";
+export type ScarnCommandDefinition = {
+    name: string;
+    description: string;
+    run: string;
+    cwd: string | null;
+};
+export type ScarnServiceDefinition = {
+    name: string;
+    description: string;
+    run: string;
+    cwd: string | null;
+    dependsOn: string[];
+    expose: {
+        targetPort: number;
+        protocol: string;
+    };
+};
+export type ScarnConfig = {
+    commands: ScarnCommandDefinition[];
+    services: ScarnServiceDefinition[];
+};
+export type ParseScarnConfigResult = {
+    found: false;
+} | {
+    found: true;
+    config: ScarnConfig;
+};
+export declare function parseScarnConfig(workspacePath: string): Promise<ParseScarnConfigResult>;

package/dist/scarn-config-parser.js

@@ -0,0 +1,10 @@
+// @bun
+import {
+  SCARN_CONFIG_RELATIVE_PATH,
+  parseScarnConfig
+} from "./chunk-0y2fy5en.js";
+import"./chunk-y64skrwp.js";
+export {
+  SCARN_CONFIG_RELATIVE_PATH,
+  parseScarnConfig
+};