@sanoma-ai/workflows 0.1.0 → 0.2.0

package/src/resources.ts

@@ -3,6 +3,7 @@ import { dirname, join, relative, resolve, sep } from "node:path";
 import { parsed } from "./ast.ts";
 import { rootOf, type SanomaConfig } from "./config.ts";
 import { type DataFile, type DataFileExport, type DataValue, readDataFile, Reference } from "./datafile.ts";
+import { type Binding, type Bindings, LOCKFILE, readLockfile } from "./lockfile.ts";
 import { type Connector, VENDOR } from "./op.ts";
 import type { Span } from "./outline.ts";
 import { type Declared, type Resource, resourceTypesOf } from "./resource.ts";
@@ -16,8 +17,12 @@ export interface DeclaredResource {
   file: string;
   vendor: string;
   type: string;
-  /** Its import id: what the type's `find` makes of its fields. */
+  /** What people call it: its identity, else its export's name. */
   name: string;
+  /** The import id that finds it unbound: what its type's `find` makes of its fields; absent when the type has none. */
+  identity?: string;
+  /** The vendor's id of the object the lockfile binds it to (`LOCKFILE`); absent when unbound. */
+  binding?: string;
   /** Its `export const` statement, as UTF-16 offsets into the file's text. */
   span: Span;
   /** Its fields, as its type checked them: each resource it names as that resource's `name`. */
@@ -43,10 +48,14 @@ export interface ResourceProblem {
   message: string;
 }
 
-/** What the data files declare: each resource read without problems, and the problems. */
+/** What the data files declare: each resource read without problems, the lockfile's bindings, and the problems. */
 export interface DataFiles {
   /** By file and then in file order, less any with a problem, and any that names one. */
   resources: DeclaredResource[];
+  /** The lockfile's bindings, by key (`<file>#<export>`), as read: none when it is missing or has a problem. */
+  bindings: Bindings;
+  /** Each binding whose key no data file declares, by key. */
+  orphans: (Binding & { key: string })[];
   /** By file, line and column. */
   problems: ResourceProblem[];
 }
@@ -82,7 +91,11 @@ interface FileEntry {
  *
  * Problems: anything outside the subset, a constructor or data file the config does not know, a
  * type the connector does not declare, a value the type refuses (a reference where its type
- * takes none among them), a reference cycle, and two resources of one type with one name.
+ * takes none among them), a reference cycle, and two resources of one type with one identity.
+ *
+ * Each declaration is joined to its binding in the lockfile (`readLockfile`) by its key,
+ * `<file>#<export>`; a binding no export declares is an orphan. Problems: the lockfile's, a
+ * binding of another type than its declaration's, and two declarations bound to one object.
  */
 export function readDataFiles(
   root: string | undefined,
@@ -95,8 +108,10 @@ export function readDataFiles(
       message:
         "The config has no root, so its data files cannot be found: make it with defineConfig, which records its file, or set its `root`",
     });
-    return { resources: [], problems };
+    return { resources: [], bindings: {}, orphans: [], problems };
   }
+  const lock = readLockfile(root);
+  problems.push(...lock.problems);
 
   const files = new Map<string, FileEntry>();
   for (const path of dataFilesUnder(join(root, "resources"))) {
@@ -175,7 +190,7 @@ export function readDataFiles(
     visiting.push(id);
     const result = build(file, exp);
     visiting.pop();
-    if (result) {
+    if (result?.declared.name !== undefined) {
       const { vendor, type, name } = result.declared;
       const key = `${vendor}.${type} ${JSON.stringify(name)}`;
       const first = byName.get(key);
@@ -231,18 +246,58 @@ export function readDataFiles(
     }
   }
 
+  // Each binding against its declaration: of its type, and the only one bound to its object.
+  const boundBy = new Map<string, string>();
+  for (const [id, { file, exp }] of declarations) {
+    const binding = lock.bindings[id];
+    // An unknown constructors import was reported with the import.
+    const vendor = vendors.get(file)!.get(exp.vendor);
+    if (binding === undefined || vendor === undefined) continue;
+    const type = `${vendor}.${exp.type}`;
+    const object = `${binding.type} ${binding.id}`;
+    const first = boundBy.get(object);
+    const why =
+      binding.type !== type
+        ? `${id} is bound to a ${binding.type} in ${LOCKFILE}, but declares a ${type}`
+        : first !== undefined
+          ? `${id} is bound to the same ${object} as ${first} in ${LOCKFILE}: bind each object once`
+          : undefined;
+    if (why === undefined) boundBy.set(object, id);
+    else {
+      // Left out, as any declaration with a problem, and so is any that names it.
+      file.problem(exp.start, why);
+      done.set(id, undefined);
+    }
+  }
+  const keys = new Set([...files.values()].flatMap((f) => f.data.declared.map((name) => `${f.rel}#${name}`)));
+  const orphans = Object.entries(lock.bindings)
+    .filter(([key]) => !keys.has(key))
+    .map(([key, binding]) => ({ key, ...binding }));
+
   const resources: DeclaredResource[] = [];
   for (const [id, { file, exp }] of declarations) {
     const result = declare(id);
     if (!result) continue;
-    const { vendor, type, name, desired } = result.declared;
-    resources.push({ id, file: file.rel, vendor, type, name, span: [exp.start, exp.end], desired, refs: result.refs });
+    const { vendor, type, name: identity, desired } = result.declared;
+    const binding = lock.bindings[id]?.id;
+    resources.push({
+      id,
+      file: file.rel,
+      vendor,
+      type,
+      name: identity ?? exp.name,
+      ...(identity !== undefined && { identity }),
+      ...(binding !== undefined && { binding }),
+      span: [exp.start, exp.end],
+      desired,
+      refs: result.refs,
+    });
   }
   problems.sort(
     (a, b) =>
       (a.file ?? "").localeCompare(b.file ?? "") || (a.line ?? 0) - (b.line ?? 0) || (a.column ?? 0) - (b.column ?? 0),
   );
-  return { resources, problems };
+  return { resources, bindings: lock.bindings, orphans, problems };
 }
 
 /** The data files under `dir`, sorted: regular `.ts` files, less tests, declarations and `node_modules`; none when `dir` is not a directory. */

package/src/run.ts

@@ -1,3 +1,4 @@
+import { AsyncLocalStorage } from "node:async_hooks";
 import type { ApprovalState, Principal, WorkflowDefinition } from "./define.ts";
 import type { Fake } from "./fake.ts";
 import type { LedgerStore } from "./ledger.ts";
@@ -5,6 +6,8 @@ import type { DriverFn, Op } from "./op.ts";
 import type { CallNode } from "./outline.ts";
 import type { Policy } from "./policy.ts";
 import type { Resource } from "./resource.ts";
+import type { Secrets } from "./secret.ts";
+import type { Source } from "./source.ts";
 import type { Steps } from "./steps.ts";
 
 /** What the DBOS workflow receives: the workflow's input, who started the run, and for a sandbox run its scenario. */
@@ -31,11 +34,15 @@ export interface WorkerState {
   fakes: Map<string, () => Fake<any, any>>;
   /** Where sandbox runs' scenarios are, the resource types their steps may name, and the steps the connectors ship. */
   scenarios?: URL;
+  /** The worker's `source`, when it was given one. */
+  source?: Source;
   types: ReadonlyMap<string, Resource>;
   steps: readonly Steps[];
   /** Its `version`, when it has one, is recorded with each of its decisions. */
   policy: Policy;
   ledger: LedgerStore;
+  /** The stored secrets, for a live run's drivers (`CallContext.secrets`). */
+  secrets: Secrets;
   /**
    * The config's workflows by name, the built-in `drift` among them. A run takes its definition
    * from here, by the name it was registered under: a process registers each name with DBOS once,
@@ -62,6 +69,8 @@ export interface Run {
   sandbox?: string;
   /** A sandbox run's own fakes' functions, by operation id, from `seedSandbox`; unset for a live run. */
   fakeDrivers?: Map<string, DriverFn>;
+  /** A sandbox run's own secrets, in memory, from `seedSandbox`; unset for a live run. */
+  fakeSecrets?: Secrets;
   approvals: ApprovalState[];
   /** The next ledger `seq`. Advanced only outside steps, so a replay counts the same way. */
   seq: number;
@@ -89,3 +98,9 @@ export interface WorkflowOutline {
   lineStarts: readonly number[];
   calls: readonly CallNode[];
 }
+
+/**
+ * The run whose workflow body is running: what a built-in's own steps read of it (who started
+ * it, whether it is a sandbox run, the worker's source and policy), as no `ctx` member gives them.
+ */
+export const currentRun = new AsyncLocalStorage<Run>();

package/src/sandbox.ts

@@ -6,6 +6,7 @@ import type { Fake, ResourceFake } from "./fake.ts";
 import { entry, type LedgerRecord, write } from "./ledger.ts";
 import type { DriverFn } from "./op.ts";
 import type { Run } from "./run.ts";
+import { memorySecrets } from "./secret.ts";
 import { type Given, loadScenarios, type Scenario } from "./scenario.ts";
 import { errorMessage } from "./shared.ts";
 
@@ -90,6 +91,8 @@ export function seedResource(
 export async function seedSandbox(run: Run, name: string): Promise<void> {
   const { state } = run;
   let copies: Map<string, DriverFn> | undefined;
+  // The run's secrets, in memory as its fakes are: seeding and its calls share them.
+  const secrets = memorySecrets();
   const { seeds } = await DBOS.runStep(
     async () => {
       // Read in the step, so a recovered run never reads a feature file edited or renamed since.
@@ -126,7 +129,7 @@ export async function seedSandbox(run: Run, name: string): Promise<void> {
       for (const [i, given] of scenario.given.entries()) {
         if ("fault" in given) continue;
         if ("op" in given) {
-          const call = { idempotencyKey: `${run.id}:seed:${i}`, runId: run.id, opId: given.op, attempt: 1 };
+          const call = { idempotencyKey: `${run.id}:seed:${i}`, runId: run.id, opId: given.op, attempt: 1, secrets };
           const output = await drivers.get(given.op)!(given.input, call);
           seeded.push({ op: given.op, input: given.input, output });
           continue;
@@ -153,5 +156,6 @@ export async function seedSandbox(run: Run, name: string): Promise<void> {
     );
   }
   run.fakeDrivers = copies;
+  run.fakeSecrets = secrets;
   await write(run, entry(run, { type: "scenario.seeded", scenario: name, seeds }));
 }

package/src/scenario.ts

@@ -32,7 +32,16 @@ import { fill, isBug, seedFrom, shapeOf } from "./fill.ts";
 import type { LedgerRecord } from "./ledger.ts";
 import type { Driver, Op } from "./op.ts";
 import { type OutlineNode, outlineWorkflow } from "./outline.ts";
-import { DRIFT_WORKFLOW, errorMessage, fitsOp, flatten, isEnded } from "./shared.ts";
+import { memorySecrets } from "./secret.ts";
+import {
+  APPLY_WORKFLOW,
+  BUILT_IN_WORKFLOWS,
+  DRIFT_WORKFLOW,
+  errorMessage,
+  fitsOp,
+  flatten,
+  isEnded,
+} from "./shared.ts";
 import type { Call, RunView, Seed } from "./steps.ts";
 
 /*
@@ -89,8 +98,9 @@ export interface Decision {
 /**
  * What the run should do: call an operation (with at least this input) or not, run the step
  * `name`d in the workflow's outline or not, or a number of `times`, have the policy deny an
- * operation (`denied`) or hold one for an approver (`held`), end a certain way, or, for a drift
- * run, report the resource `declared` (`<file>#<export>`) clean, gone, or drifted in a field.
+ * operation (`denied`) or hold one for an approver (`held`), end a certain way, for a drift
+ * run, report the resource `declared` (`<file>#<export>`) clean, gone, absent, or drifted in a
+ * field, or for an apply run, create it, or leave it bound to an object (`bound`, its vendor's id).
  * A step whose own code checks the run (a connector's or the company's, or an operation's own
  * test's) is `custom`, with what it is about.
  */
@@ -101,8 +111,10 @@ export type Expectation =
   | { step: string; op: string; decision: "denied" }
   | { step: string; op: string; decision: "held"; approver: string }
   | { step: string; outcome: "finished" | "failed"; code?: string }
-  | { step: string; declared: string; status: "clean" | "gone" }
+  | { step: string; declared: string; status: "clean" | "gone" | "absent" }
   | { step: string; declared: string; status: "drifted"; field: string }
+  | { step: string; declared: string; created: true }
+  | { step: string; declared: string; bound: string }
   | { step: string; custom: true; op?: string; called?: boolean };
 
 export interface Scenario {
@@ -314,6 +326,8 @@ function builtFor(scope: Scope): Built {
   return built;
 }
 
+/** The built-in workflows, whose input is never made up: each field is optional, and left out unless given. */
+
 /** A `Then` step of the generic steps: its expectation, checked against the run's records. */
 const expecting = (expect: CoreExpectation): Then => ({ expect, verify: (run) => detailOf(expect, run.records) });
 
@@ -376,13 +390,21 @@ function rulesOf(scope: Scope): { rules: Rule[]; parameterTypes: ParameterTypeSp
       takes: TAKES_OBJECT,
       read: ([name], pickle) => {
         const { input } = workflowOf(name);
-        return { workflow: name as string, input: fill(input, fieldsFrom(pickle, input, inputOf(name))) };
+        const given = fieldsFrom(pickle, input, inputOf(name));
+        return {
+          workflow: name as string,
+          input: BUILT_IN_WORKFLOWS.has(name as string) ? input.parse(given) : fill(input, given),
+        };
       },
     },
     {
       kind: "when",
       source: "{workflow} runs",
-      read: ([name]) => ({ workflow: name as string, input: fill(workflowOf(name).input, {}) }),
+      // A built-in's input is optional throughout: what is not given is left out, not made up.
+      read: ([name]) => ({
+        workflow: name as string,
+        input: BUILT_IN_WORKFLOWS.has(name as string) ? {} : fill(workflowOf(name).input, {}),
+      }),
     },
     // An operation's own test: a call made to its driver, or its fake, directly.
     {
@@ -469,11 +491,21 @@ function rulesOf(scope: Scope): { rules: Rule[]; parameterTypes: ParameterTypeSp
       read: ([declared, field]) =>
         expecting({ declared: declared as string, status: "drifted", field: field as string }),
     },
-    ...(["clean", "gone"] as const).map((status): Rule => ({
+    ...(["clean", "gone", "absent"] as const).map((status): Rule => ({
       kind: "then",
       source: `{declared} is ${status}`,
       read: ([declared]) => expecting({ declared: declared as string, status }),
     })),
+    {
+      kind: "then",
+      source: "apply creates {declared}",
+      read: ([declared]) => expecting({ declared: declared as string, created: true }),
+    },
+    {
+      kind: "then",
+      source: "{declared} is bound to {string}",
+      read: ([declared, id]) => expecting({ declared: declared as string, bound: id as string }),
+    },
     { kind: "then", source: "the run succeeds", read: () => expecting({ outcome: "finished" }) },
     { kind: "then", source: "the run fails", read: () => expecting({ outcome: "failed" }) },
     {
@@ -879,6 +911,8 @@ function testWorld(built: Built, { driver, fake }: FeatureTarget) {
     const values = new Map<string, unknown>();
     const records: LedgerRecord[] = [];
     let runId = "";
+    // The test's own secrets, in memory: a driver resolves `secret()` markers against them.
+    const secrets = memorySecrets();
     /** A record of the test, as a run's ledger would hold it. */
     const record = (body: Record<string, unknown>) => {
       const seq = records.length;
@@ -892,7 +926,7 @@ function testWorld(built: Built, { driver, fake }: FeatureTarget) {
       const input = op.input.parse(resolve(given, values));
       const fn = driver.ops[`${op.resource}.${op.name}`];
       if (!fn) throw new Error(`the driver under test does not implement ${id}`);
-      const context = { idempotencyKey: `${runId}:${records.length}`, runId, opId: id, attempt: 1 };
+      const context = { idempotencyKey: `${runId}:${records.length}`, runId, opId: id, attempt: 1, secrets };
       return { op, input, output: () => fn(input, context) };
     };
     return {
@@ -1092,11 +1126,14 @@ async function compile(scope: Scope, dir: string, files: string[]): Promise<Load
               `${where}: scenario "${name}" has no When: say which workflow runs, such as "When <workflow> runs with"`,
             );
           }
-          const drift = spec.expect.find((e) => "declared" in e);
-          if (drift && workflow !== DRIFT_WORKFLOW) {
-            throw new Error(
-              `${where}: "${drift.step}" reads a drift report, so the scenario must run ${DRIFT_WORKFLOW}, not ${workflow}`,
-            );
+          // A step about a declared resource reads the report of the built-in it is about.
+          for (const e of spec.expect) {
+            const reads: string = "declared" in e ? ("status" in e ? DRIFT_WORKFLOW : APPLY_WORKFLOW) : workflow;
+            if (reads !== workflow) {
+              throw new Error(
+                `${where}: "${e.step}" reads ${reads === DRIFT_WORKFLOW ? "a drift" : "an apply"} report, so the scenario must run ${reads}, not ${workflow}`,
+              );
+            }
           }
           inFile.push({
             ...spec,

package/src/secret.ts

@@ -0,0 +1,92 @@
+import { randomBytes } from "node:crypto";
+import { DriverError } from "./op.ts";
+
+// Secrets are named, never written: `secret("NAME")` in a data file is a marker for a value in
+// the company's secrets store (the credentials table), allowed only at a write-only field. The
+// marker is what declarations, checkpoints and the ledger hold; a driver resolves it
+// (`resolveSecrets`) just before the vendor call. The `./resources` entry, which data files import
+// `secret` from (`sanoma/resources` re-exports it).
+
+/** What `secret()` makes: a plain object, so it reads the same as JSON and across copies of this package. */
+export interface Secret {
+  readonly $secret: string;
+  /** When none is stored, apply makes the value (`generateSecret`) and stores it before the vendor call. */
+  readonly generate?: true;
+}
+
+/** A secret's name: an environment variable's, upper case. */
+export const SECRET_NAME = /^[A-Z][A-Z0-9_]*$/;
+
+/**
+ * True for one of sanoma's own secrets (`SANOMA_…`, its key and database URLs among them): only a
+ * host, which runs the company, is given them, at its `secrets` input (`HostSpec`); never a vendor.
+ */
+export const isSanomaSecret = (name: string) => name.startsWith("SANOMA_");
+
+/**
+ * Names a stored secret for a write-only field of a data file: `secret("SUPABASE_DB_PASSWORD",
+ * { generate: true })`. With `generate`, apply makes the value when none is stored.
+ */
+export function secret(name: string, options?: { generate: true }): Secret {
+  if (!SECRET_NAME.test(name)) {
+    throw new Error(`secret("${name}"): a secret's name is an environment variable's, upper case: A-Z, 0-9 and _`);
+  }
+  return Object.freeze(options?.generate ? { $secret: name, generate: true as const } : { $secret: name });
+}
+
+/** True for a secret marker, `{ $secret: "NAME" }`. */
+export const isSecret = (value: unknown): value is Secret =>
+  typeof value === "object" && value !== null && typeof (value as { $secret?: unknown }).$secret === "string";
+
+/** The secrets store, as a driver sees it (`CallContext.secrets`). */
+export interface Secrets {
+  /** The stored value, or undefined when there is none. */
+  get(name: string): Promise<string | undefined>;
+  /** The stored value; when there is none, `make()`'s, stored first. */
+  ensure(name: string, make: () => string): Promise<string>;
+}
+
+/** A value for a secret with `generate`: 32 random bytes, base64url. */
+export const generateSecret = (): string => randomBytes(32).toString("base64url");
+
+/** `T` with each secret marker's place holding its value: what `resolveSecrets` returns. */
+export type Resolved<T> = T extends Secret
+  ? string
+  : T extends readonly (infer I)[]
+    ? Resolved<I>[]
+    : T extends object
+      ? { [K in keyof T]: Resolved<T[K]> }
+      : T;
+
+/**
+ * `value` with each secret marker in it replaced by the stored value: generated and stored first
+ * for one with `generate` and none stored. A marker naming nothing stored fails the call, for good.
+ */
+export async function resolveSecrets<T>(value: T, secrets: Secrets): Promise<Resolved<T>> {
+  const resolve = async (v: unknown): Promise<unknown> => {
+    if (isSecret(v)) {
+      const stored = v.generate ? await secrets.ensure(v.$secret, generateSecret) : await secrets.get(v.$secret);
+      if (stored === undefined) {
+        throw new DriverError(`The secret ${v.$secret} is not set: store it before applying`, { retryable: false });
+      }
+      return stored;
+    }
+    if (Array.isArray(v)) return Promise.all(v.map(resolve));
+    if (typeof v !== "object" || v === null) return v;
+    const entries = await Promise.all(Object.entries(v).map(async ([k, item]) => [k, await resolve(item)] as const));
+    return Object.fromEntries(entries);
+  };
+  return (await resolve(value)) as Resolved<T>;
+}
+
+/** A secrets store in memory, for fakes, sandbox runs and tests. */
+export function memorySecrets(initial: Record<string, string> = {}): Secrets {
+  const values = new Map(Object.entries(initial));
+  return {
+    get: async (name) => values.get(name),
+    async ensure(name, make) {
+      if (!values.has(name)) values.set(name, make());
+      return values.get(name)!;
+    },
+  };
+}

package/src/shared.ts

@@ -15,6 +15,7 @@ export type {
 } from "./resource.ts";
 export type { DeclaredResource, ResourceProblem } from "./resources.ts";
 export type { DriftField, DriftReport, DriftResult, DriftStatus } from "./drift.ts";
+export type { ApplyPlan, ApplyReport, ApplyResult, PlanAnswer, PlanStep } from "./apply.ts";
 export type { CredentialStatus } from "./env.ts";
 
 // What a UI in the browser may use from the runtime, besides types: `@sanoma-ai/workflows/shared`.
@@ -30,6 +31,15 @@ export const DEFAULT_SLEEP_NAME = "Sleep";
 /** The built-in drift workflow's name, which a config's own workflows may not take; a UI and the scenarios name its runs by it. */
 export const DRIFT_WORKFLOW = "drift";
 
+/**
+ * The built-in apply workflow's name: the only workflow that may call a writable resource type's
+ * change operations (`create`, `update`, `delete`).
+ */
+export const APPLY_WORKFLOW = "apply";
+
+/** The workflows the runtime adds itself, which a config's own may not be named: drift and apply. */
+export const BUILT_IN_WORKFLOWS: ReadonlySet<string> = new Set([DRIFT_WORKFLOW, APPLY_WORKFLOW]);
+
 /**
  * Every run status, in the order a run may pass through them: waiting on the queue, running,
  * waiting for an approval, or ended. `waiting` is `running` with an approval pending.

package/src/source.ts

@@ -0,0 +1,82 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { z } from "zod";
+import { defineConnector, defineDriver, DriverError } from "./op.ts";
+
+// Where a company's files live, and how a change to them is recorded: a git repository on this
+// machine, or one a host cloned. The runtime's writers (the app's Adopt, apply's lockfile) change
+// files under `root`, then commit them through it. The launcher makes one; a config without one
+// writes the files and commits nothing.
+
+/** A company's repository, as the runtime writes to it. */
+export interface Source {
+  /** The repository's root directory. */
+  root: string;
+  /**
+   * Records the files at `paths`, relative to `root`, as one change by `author` (who made it, as
+   * the app names them: a login or a typed name). Its revision; undefined when nothing changed.
+   */
+  commit(change: {
+    paths: string[];
+    message: string;
+    author: string;
+  }): { revision: string } | undefined | Promise<{ revision: string } | undefined>;
+  /** The revision `ref` names, the checked-out one by default. */
+  head(ref?: string): string | Promise<string>;
+  /** Pushes `ref` to the repository at `url`, signed in with `token`. */
+  push?(target: { url: string; token: string; ref: string }): void | Promise<void>;
+}
+
+/**
+ * The built-in operation `sanoma.source.resolve`: the commit `ref` names in the repository at
+ * `url` now, by `git ls-remote` (a branch first, then a tag, peeled; a full commit id is itself).
+ * Apply calls it to fill a host's revision before it plans, and drift to see a merge. `resolveConfig`
+ * registers it when a connector declares a host type.
+ */
+export const sourceOps = defineConnector("sanoma", {
+  source: {
+    resolve: {
+      effect: "read",
+      idempotent: true,
+      description: "Resolve a branch or tag of a git repository to the commit it names now",
+      input: z.object({ url: z.string().min(1), ref: z.string().min(1) }),
+      output: z.object({ revision: z.string() }),
+      target: ({ url, ref }: { url: string; ref: string }) => `${url}#${ref}`,
+    },
+  },
+});
+
+export const SOURCE_RESOLVE = "sanoma.source.resolve" satisfies typeof sourceOps.source.resolve.id;
+
+/** The driver of `sanoma.source.resolve`: git on this machine, with its own credential helpers. */
+export const sourceDriver = defineDriver(sourceOps, {
+  source: { resolve: async ({ url, ref }) => ({ revision: await resolveRevision(url, ref) }) },
+});
+
+const COMMIT = /^[0-9a-f]{40}([0-9a-f]{24})?$/;
+
+/** The commit `ref` (a branch, a tag, `HEAD`, a full ref or a commit id) names in the repository at `url`. */
+export async function resolveRevision(url: string, ref: string): Promise<string> {
+  if (COMMIT.test(ref)) return ref;
+  const { stdout } = await promisify(execFile)("git", ["ls-remote", "--", url, ref, `${ref}^{}`], {
+    // Never a prompt for credentials: a repository that needs them and has none fails.
+    env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+    timeout: 30_000,
+  }).catch((err: { stderr?: string; message: string }) => {
+    throw new DriverError(`git ls-remote ${url} failed: ${err.stderr?.trim() || err.message}`, {
+      retryable: true,
+      cause: err,
+    });
+  });
+  const refs = new Map(
+    stdout.split("\n").flatMap((line) => {
+      const [sha, name] = line.split("\t");
+      return sha && name ? [[name, sha] as const] : [];
+    }),
+  );
+  for (const name of [`refs/heads/${ref}`, `refs/tags/${ref}^{}`, `refs/tags/${ref}`, ref]) {
+    const sha = refs.get(name);
+    if (sha) return sha;
+  }
+  throw new DriverError(`${url} has no branch or tag ${ref}`, { retryable: false, vendorCode: "no_such_ref" });
+}

package/src/version.ts

@@ -6,7 +6,7 @@ import { jsonSchemaOf, opIdsOf, type WorkflowDefinition } from "./define.ts";
 import { upFrom } from "./paths.ts";
 
 /** This package's version. A unit test keeps it equal to package.json. */
-export const RUNTIME_VERSION = "0.1.0";
+export const RUNTIME_VERSION = "0.2.0";
 
 /**
  * The sequence of DBOS calls the runtime makes around each `ctx` call: policy step, approval

package/src/worker.ts

@@ -2,8 +2,8 @@ import { DBOS } from "@dbos-inc/dbos-sdk";
 import { buildCtx, isInfrastructureError } from "./call.ts";
 import { dbosStatusesOf } from "./client.ts";
 import { type ResolvedConfig, resolveConfig, type SanomaConfig } from "./config.ts";
-import { watchCredentials } from "./credentials.ts";
-import { DBOS_DATABASE_OPTIONS, prepareDatabase } from "./db.ts";
+import { storedSecrets, watchCredentials } from "./credentials.ts";
+import { DBOS_DATABASE_OPTIONS, lazyPool, prepareDatabase } from "./db.ts";
 import type { WorkflowDefinition } from "./define.ts";
 import { credentialsOf, unconfigured, unconfiguredSummary } from "./env.ts";
 import { errorInfo, parseOrThrow } from "./errors.ts";
@@ -11,7 +11,8 @@ import { entry, ownedLedger, skipped, write, writeFailure } from "./ledger.ts";
 import { dbosLogger, quietIfSandbox, setLogLevel, warn } from "./log.ts";
 import { lineStartsOf, readSource } from "./ast.ts";
 import { callsOf, outlineWithSource } from "./outline.ts";
-import type { Run, RunArgs, WorkerState, WorkflowOutline } from "./run.ts";
+import { currentRun, type Run, type RunArgs, type WorkerState, type WorkflowOutline } from "./run.ts";
+import type { Source } from "./source.ts";
 import { errorMessage } from "./shared.ts";
 
 export interface Worker {
@@ -45,6 +46,8 @@ export interface WorkerOptions {
    * restarting during a rolling deploy would otherwise take the new workers' runs.
    */
   promote?: boolean;
+  /** The company's repository, which apply commits the lockfile to; the launcher passes its checkout. */
+  source?: Source;
 }
 
 /**
@@ -60,16 +63,19 @@ export async function startWorker(config: SanomaConfig, options: WorkerOptions =
   setLogLevel(options.logLevel);
   // The config's own, or a Postgres store made for this worker, which `stop` then closes.
   const ledger = ownedLedger(resolved);
+  const secrets = lazyPool(resolved.databaseUrl, "secrets");
   const state: WorkerState = {
     app: resolved.appName,
     ops: resolved.ops,
     drivers: resolved.drivers,
     fakes: resolved.fakes,
     ...(resolved.scenarios && { scenarios: resolved.scenarios }),
+    ...(options.source && { source: options.source }),
     types: resolved.types,
     steps: resolved.steps,
     policy: resolved.policy,
     ledger: ledger.store,
+    secrets: storedSecrets(() => secrets.db(), "sanoma"),
     workflows: resolved.workflows,
     outlines: new Map([...resolved.workflows].map(([name, wf]) => [name, outlineOf(wf)])),
     stopped: false,
@@ -83,7 +89,12 @@ export async function startWorker(config: SanomaConfig, options: WorkerOptions =
       state.stopped = true;
       // Each is closed whatever the one before did; the first failure is what stop throws.
       let failed: { error: unknown } | undefined;
-      for (const close of [() => DBOS.shutdown(), () => credentials.close(), () => ledger.close()]) {
+      for (const close of [
+        () => DBOS.shutdown(),
+        () => credentials.close(),
+        () => secrets.close(),
+        () => ledger.close(),
+      ]) {
         await close().catch((error: unknown) => (failed ??= { error }));
       }
       if (failed) throw failed.error;
@@ -237,7 +248,7 @@ async function runWorkflow(name: string, { input, startedBy, sandbox }: RunArgs)
         const { seedSandbox } = await import("./sandbox.ts");
         await seedSandbox(run, sandbox);
       }
-      output = await wf.run(buildCtx(wf, run), parsed);
+      output = await currentRun.run(run, () => wf.run(buildCtx(wf, run), parsed));
     } finally {
       // Before the outcome is written: a call still queued must find the run ended.
       run.ended = true;