@ref0/sdk 0.0.0-stage → 0.6.0

package/dist/index.d.mts

@@ -0,0 +1,341 @@
+import { B as GateOwn, Ct as SandboxPushAnswer, Ht as VersionFile, Jt as WorkflowAskClosed, Kt as WorkflowAnswerer, On as WorkflowRequestRefusal, at as PasskeyFrom$1, h as ChangeAuthor, jn as WorkflowText, mt as Ref0Owned, ot as PasskeyRefusal, qt as WorkflowAsk, wt as SandboxSize } from "./index-CJGX88qF.mjs";
+import { $ as StartActor, A as ForkOptions, B as WorkflowContext, C as Comment, D as EventWorkflow, E as EventOf, F as StepConfig, G as CalledWorkflow, H as text, I as StepContext, J as TreeEntry, K as JsonValue, L as ThreadStart, M as PullRequestAnswer, N as PullRequestOptions, O as EventWorkflowSpec, P as Ref0Actions, Q as Refusal, R as WaitType, S as CheckRunEnded, T as Duration, U as workflow, V as WorkflowStep, W as CalledRunFailed, X as Allow, Y as TreeRead, Z as CalledRun, _ as ActionAnswer, a as CheckRunOptions, at as allow, b as CalledContext, c as CheckRunResult, ct as Need, d as OneOfValues, et as StartContext, f as OutputResult, g as oneOf, h as check, i as CheckResult, it as StartRun, j as NeedAddOptions, k as ForkAnswer, l as CheckSpec, m as Step, n as Check, nt as StartOutput, o as CheckRunReference, ot as refuse, p as OutputSchema, q as Tree, r as CheckContext, rt as StartRule, s as CheckRunRefused, st as CheckNeed, t as Browser, tt as StartItem, u as DurationText, v as CallAnswer, w as ConnectionsOf, x as CalledWorkflowSpec, y as CallEnded, z as WaitedEvent } from "./browse-DHgV6DTF.mjs";
+//#region src/ask.d.ts
+/**
+ * `ask`, ref0's leaf that asks someone a question and waits in the run for the answer, as a
+ * repo's `.ref0/workflows/` code imports it from `@ref0/sdk`. It has only `.run`: `await
+ * ask.run(step, { … })`. The workflow's `permissions.ask` names whom it may ask, and each ask
+ * spends from its `asks` budget.
+ */
+type Text = (typeof WorkflowText)['Encoded'];
+/** One answer an ask offers: its key, which the run reads, and its title and detail, which the decider reads. */
+interface AskAnswerOption<K extends string = string> {
+  readonly key: K;
+  readonly title: Text;
+  readonly detail: Text;
+}
+/**
+ * What `ask.run` asks: whom, the accountable person or the agent of a session in the run's
+ * `sessions`, by its index; its key, which names the ask in its run, so a run asks with each key
+ * once; the question; two to five answers; the lean, one of them, which the deadline answers; and
+ * the deadline, from a minute to a day. ref0 brings the deadline in to what the run has left.
+ */
+interface AskOptions<K extends string> {
+  readonly to: (typeof WorkflowAsk)['Encoded']['to'];
+  readonly key: string;
+  readonly question: Text;
+  readonly answers: ReadonlyArray<AskAnswerOption<K>>;
+  readonly lean: NoInfer<K>;
+  readonly deadline: DurationText;
+}
+/** Who answered an ask: the accountable person, or an agent by its handle. */
+type Answerer = (typeof WorkflowAnswerer)['Encoded'];
+type Answered = Extract<(typeof WorkflowAskClosed)['Encoded'], {
+  readonly kind: 'answered';
+}>;
+/**
+ * An ask's answer: its key, one of the ask's answers'; who answered, `via: 'decider'`, or at the
+ * deadline, the lean, with no `by` and `via: 'deadline'`; and when, in ISO 8601.
+ */
+type AskAnswer<K extends string = string> = Answered extends (infer Each) ? Each extends Answered ? Omit<Each, 'kind' | 'key'> & {
+  readonly key: K;
+} : never : never;
+/**
+ * ref0 refused an ask, as it refuses an action, and never opened it; `duplicate` when the same
+ * words went to the same decider within the hour; or `withdrawn`, opened, then closed with no
+ * answer when its thread closed. A refusal is kept as its step's result, so a replay throws it
+ * again and asks nothing.
+ */
+export declare class AskRefused extends Error {
+  readonly why: WorkflowRequestRefusal | 'duplicate' | 'withdrawn';
+  constructor(key: string, why: AskRefused['why']);
+}
+/**
+ * Asks once, in a step of its own, then waits in the run for the ask's close, `ask-<key>`. The
+ * ask's step name carries its key and a digest of what it asks, since Workflows tells steps of
+ * one name apart only by the order they're reached in: a replay finds the same ask, and two asks
+ * with one key never take each other's answers, as ref0 opens only the first.
+ */
+declare const run$1: <const K extends string>(step: WorkflowStep, options: AskOptions<K>) => Promise<AskAnswer<K>>;
+/**
+ * ref0's ask: `ask.run(step, { to, key, question, answers, lean, deadline })` asks, then waits
+ * in the run for `{ key, by, via, at }`, the answer, or the lean at the deadline.
+ */
+export declare const ask: {
+  readonly run: typeof run$1;
+};
+//#endregion
+//#region src/gate.d.ts
+/** What the gate returns: needs, with `false`, `null` and `undefined` skipped and lists flattened. */
+type Needs = ReadonlyArray<Need | Needs | false | null | undefined>;
+/** One changed file, from Git, never as the agent reports it. */
+type ChangedFile = (typeof VersionFile)['Encoded'];
+/** What the change does, as ref0 worked it out from Git. */
+interface Change {
+  /** Every changed file, unless `complete` is false. */
+  readonly files: ReadonlyArray<ChangedFile>;
+  /** Whether `files` holds every changed file: false past 5,000 files or 1 MB. */
+  readonly complete: boolean;
+  /** The built-in permissions its paths touch, whose approval ref0's floor asks for anyway. */
+  readonly permissions: ReadonlyArray<string>;
+  /** Lines added and removed, over every changed file. */
+  readonly lines: {
+    readonly added: number;
+    readonly removed: number;
+  };
+  /**
+   * Whether any changed file, either end of a rename, matches a pattern: `src/billing/**`,
+   * `**\/*.sql`. In a segment `*` is any run of characters and `?` any one; a whole segment `**`
+   * is any number of segments.
+   */
+  readonly touches: (...patterns: ReadonlyArray<string>) => boolean;
+  /** Whether every changed file matches a pattern, as for a docs-only change. */
+  readonly only: (...patterns: ReadonlyArray<string>) => boolean;
+  /** Who wrote it: a member of the owner or a contributor, an agent or a person. */
+  readonly author: (typeof ChangeAuthor)['Encoded'];
+  /**
+   * The tree the change is made on, its base's, as a check reads its own. A decision reads at
+   * most 200 objects of both trees, each folder on a read's way among them, each at most 1 MiB
+   * and 8 MiB in all; past any, the decision fails, as a gate that throws does. ref0 keeps each
+   * read with the version, so `ref0 gate` shows what the gate read.
+   */
+  readonly before: Tree;
+  /** The tree the change makes, the version's expected tree, read as `before` is. */
+  readonly after: Tree;
+}
+/** What the gate is given about the change it decides for. */
+interface GateContext {
+  readonly change: Change;
+  /** The thread's accepted plan, by its version, or `null`. */
+  readonly plan: {
+    readonly version: number;
+  } | null;
+}
+/**
+ * The gate, as `.ref0/gate.ts`'s default export, with what ref0 calls on it in its isolate, as
+ * `GateOwn` in `@ref0/contracts` says.
+ */
+interface Gate extends Ref0Owned<GateOwn> {
+  readonly decide: (context: GateContext) => Needs | Promise<Needs>;
+}
+/** The gate: given a change, what it needs. Export it as `.ref0/gate.ts`'s default. */
+export declare const gate: (decide: Gate['decide']) => Gate;
+/**
+ * An approval from someone holding that repo permission: `approval('billing')`. Admins hold every
+ * permission.
+ */
+export declare const approval: (permission: string) => Need;
+/** A whole review covering the change, with no blocking finding open. ref0's floor has one. */
+export declare const review: () => Need;
+/**
+ * A check's need that a local run meets too: `local(unit())`. A run of the same check-run
+ * identity, the check's code, its params and the version's expected tree, run with `ref0 run
+ * --local` on an attached machine of the thread's and reported, meets each of its parts, and ref0
+ * runs none of them on the change, unless another need for the part doesn't take local. ref0's
+ * failure of a part still stands, the merge queue's tip still runs the check as ref0's own, and
+ * when ref0's runs of a local success's identity fail twice, its machine stops answering the
+ * check until an admin restores it. It takes a check's need, never a check or another need.
+ */
+export declare const local: (need: CheckNeed) => CheckNeed;
+//#endregion
+//#region src/passkey.d.ts
+/**
+ * `passkey`, as code imports it from `@ref0/sdk`. In a workflow, `passkey.run` asks a person for
+ * their yes to one statement, given with their passkey in their approving browser, and waits for
+ * it: `await passkey.run(step, { from: 'accountable', statement: text`Deploy ${sha}`, deadline:
+ * '1 hour' })`. In a gate, `passkey.check(e2e())` is a check's need whose result counts only once
+ * a person said yes to it the same way. Only that browser answers, never an agent, a session's
+ * token or the CLI, and a yes to one statement stands for no other.
+ */
+/**
+ * Who a request asks, as `PasskeyFrom` in `@ref0/contracts` says: the run's accountable person; a
+ * person by their name; or anyone holding one of the repo's permissions, the first of whom to
+ * answer decides. The workflow's `permissions.ask` names each kind it asks. An ask's `by` passes
+ * as it is: `'accountable'`, or an agent, which is refused `agent`, since an agent has no passkey.
+ */
+type PasskeyFrom = (typeof PasskeyFrom$1)['Encoded'] | {
+  readonly agent: string;
+};
+/** What `passkey.run` asks. */
+interface PasskeyRunOptions {
+  readonly from: PasskeyFrom;
+  /** The statement, written with `text`, so its words are the code's own and its values quoted. */
+  readonly statement: (typeof WorkflowText)['Encoded'];
+  /**
+   * From a minute to a day: it ends there, or a minute before the run's day does, whichever is
+   * first, with a no.
+   */
+  readonly deadline: DurationText;
+}
+/**
+ * How a request ended: yes or no, who answered, by their name, and when, as an ISO time. A
+ * deadline answers no, with nobody's name.
+ */
+interface PasskeyAnswer {
+  readonly approved: boolean;
+  readonly by?: string;
+  readonly at: string;
+}
+/**
+ * ref0 asked nobody, and why, as `PasskeyRefusal` in `@ref0/contracts` says. A refusal is
+ * kept as its step's result, so a replay throws it again and asks nobody; `agent` is refused
+ * before any step.
+ */
+export declare class PasskeyRequestRefused extends Error {
+  readonly why: (typeof PasskeyRefusal)['Encoded'];
+  constructor(why: (typeof PasskeyRefusal)['Encoded']);
+}
+/**
+ * Asks for a passkey's yes to `statement`, then waits for the answer. The request is one step,
+ * named `ref0: passkey` and told from the run's others by its count, so it's reached in the order
+ * the code asks: a replay waits on the same request, and one that asks something else there
+ * throws `changed`. Then each round reads the request in a step and waits for its end, until its
+ * deadline or an hour, whichever is first, and a wait that times out reads again.
+ */
+declare const run: (step: WorkflowStep, options: PasskeyRunOptions) => Promise<PasskeyAnswer>;
+/** What `passkey.check` asks beside its need. */
+interface PasskeyCheckOptions {
+  /**
+   * Who says yes: by default the person behind the run that meets the need, a local run's
+   * signer's person, or the version's accountable person for a run of ref0's own.
+   */
+  readonly from?: (typeof PasskeyFrom$1)['Encoded'];
+}
+/**
+ * A check's need whose result counts only once a person said yes to it with their passkey:
+ * `passkey.check(local(e2e()))`, or `passkey.check(e2e(), { from: { permission: 'qa' } })` to ask
+ * someone else. For each part, ref0 asks for a yes to a statement that names the run that meets it,
+ * its check-run identity, its conclusion and its outputs' hash, and the part waits for that yes. A
+ * newer run that counts asks again. A no or the request's day ending waits for a newer local run;
+ * on a run of ref0's, or from a person who can't be asked, the check needs an admin's override.
+ * When ref0's runs of an identity someone said yes over fail twice, their yes stops answering the
+ * check until an admin restores them. It takes a check's need, never a check or another need, and wraps it
+ * once, before or after `local`.
+ */
+declare const check$1: (need: CheckNeed, options?: PasskeyCheckOptions) => CheckNeed;
+export declare const passkey: {
+  run: typeof run;
+  check: typeof check$1;
+};
+//#endregion
+//#region src/sandbox.d.ts
+/**
+ * `sandbox()`, as a repo's `.ref0/sandboxes/` files write one, and what an import of one is. A
+ * sandbox's file is a declaration: ref0 reads every key from its literals and never runs it, and
+ * ref0's bundler swaps an import of it for a handle by its name, `sandboxHandle('node')`. A
+ * handle's `run` opens it in a step of a check run, through the opener ref0 gives the step's
+ * attempt, or in a workflow's step. Either way, a sandbox with `setup` opens from its snapshot,
+ * and one without from its image.
+ */
+/** A command, as `exec` takes one: a string, run by `sh -c`, or an argv, run with no shell. */
+type SandboxCommand = string | ReadonlyArray<string>;
+/** What `sandbox()` takes, every key written out as a literal. */
+interface SandboxSpec {
+  /** An image from ref0's catalog, by its name: `'node-24'`. */
+  readonly image: string;
+  /** `'standard-1'` unless it says. */
+  readonly size?: SandboxSize;
+  /** The paths from the repo's root its snapshot is keyed by. */
+  readonly cache?: {
+    readonly inputs: ReadonlyArray<string>;
+  };
+  /** Commands run in order when its snapshot is made, at most 16. */
+  readonly setup?: ReadonlyArray<string>;
+  /** The hosts setup may reach, and only setup: code judging a tree has no network. */
+  readonly egress?: {
+    readonly setup: ReadonlyArray<string>;
+  };
+}
+/**
+ * What a command run in a sandbox answers: a failing command isn't an error. Each stream keeps
+ * its last 256 KB. It's JSON, so a step may return it.
+ */
+interface Exec {
+  readonly exitCode: number;
+  readonly stdout: string;
+  readonly stderr: string;
+  /** When it started, as an ISO 8601 time in UTC. */
+  readonly startedAt: string;
+  readonly durationMs: number;
+}
+/**
+ * What a push answers: the commit now on the fork's branch; `nothing`, when nothing changed; or
+ * why ref0 refused it. It's JSON, so a step may return it.
+ */
+type PushAnswer = (typeof SandboxPushAnswer)['Encoded'];
+/**
+ * A serve's port, ready: `url` is the plain `http://` URL a browser of the same step reaches it
+ * at. The URL confers nothing: only the session's own browser is routed to it.
+ */
+interface Served {
+  readonly port: number;
+  readonly url: string;
+}
+/** A sandbox, open for as long as the function given it runs. */
+interface SandboxSession {
+  readonly exec: (command: SandboxCommand, options?: {
+    readonly cwd?: string;
+    readonly env?: Readonly<Record<string, string>>;
+    readonly timeout?: DurationText;
+  }) => Promise<Exec>;
+  /**
+   * In a workflow's sandbox on a fork: commits what changed against the tree, as the workflow,
+   * and has ref0 push it to the fork, replacing its branch with a commit on `main`. A change
+   * under `.ref0/` is refused. Each call counts once against the run's `pushes`, and a step's
+   * retry pushes again from its new sandbox without counting again.
+   */
+  readonly push: (options: {
+    readonly message: string;
+  }) => Promise<PushAnswer>;
+  /**
+   * Starts a command in the background, left running on `port` until the sandbox closes, and
+   * answers once the port answers HTTP while the command holds it, within `ready`, 30 seconds
+   * unless it says. At most 4 a sandbox, each on a port of its own from 1024 up. One that exits
+   * or isn't ready in time throws, with the end of what it said, and closes the sandbox.
+   */
+  readonly serve: (command: SandboxCommand, options: {
+    readonly port: number;
+    readonly cwd?: string;
+    readonly env?: Readonly<Record<string, string>>;
+    readonly ready?: DurationText;
+  }) => Promise<Served>;
+  /**
+   * Lends `fn` a browser, a fresh Browser Run session that reaches only this sandbox's serves
+   * that are ready now, and closes it when `fn` ends: `fn`'s value. Only a check that imports
+   * `@ref0/sdk/browser` browses, one browser at a time.
+   */
+  readonly browse: <T>(fn: (browser: Browser) => Promise<T>) => Promise<T>;
+}
+/**
+ * What opening a sandbox takes: in a check run, the paths of its run's tree the sandbox sees, all
+ * of it unless given, since a check run's tree is always its own; a size at least its own; and
+ * its step's `timeout` and `retries`, 10 minutes and 2 unless given. A retry waits 10 seconds,
+ * then 20. In a workflow, `tree` is `'main'` or a fork `forks.create` answered, and both hold
+ * `main`'s tree at the commit the run read, as a one-commit Git history in `/src`; it takes no
+ * `paths`, and the step's `timeout` cuts its deadline, which is otherwise the run's
+ * `sandboxMinutes` left.
+ */
+interface SandboxRunOptions {
+  /** A workflow's alone, and it must give one. */
+  readonly tree?: string | ForkAnswer;
+  readonly paths?: ReadonlyArray<string>;
+  readonly size?: SandboxSize;
+  readonly timeout?: DurationText;
+  readonly retries?: number;
+}
+/** A sandbox, as code that imports its file sees it: `import node from '../sandboxes/node'`. */
+interface Sandbox {
+  /**
+   * Opens it for one step, puts the tree's paths in it, and stops it when `work` ends. The step's
+   * result is `work`'s, kept as any step's is.
+   */
+  readonly run: <T>(step: Step, name: string, options: SandboxRunOptions, work: (sandbox: SandboxSession) => Promise<T>) => Promise<T>;
+}
+/**
+ * A sandbox: its image, size, cached setup, and the hosts setup may reach. Export it as its
+ * file's default, `.ref0/sandboxes/<name>.ts`, named by its file.
+ */
+export declare const sandbox: (_spec: SandboxSpec) => Sandbox;
+//#endregion
+export { type ActionAnswer, type Allow, type Answerer, type AskAnswer, type AskAnswerOption, type AskOptions, type CallAnswer, type CallEnded, type CalledContext, type CalledRun, CalledRunFailed, type CalledWorkflow, type CalledWorkflowSpec, type Change, type ChangedFile, type Check, type CheckContext, type CheckNeed, type CheckResult, type CheckRunEnded, type CheckRunOptions, type CheckRunReference, CheckRunRefused, type CheckRunResult, type CheckSpec, type Comment, type ConnectionsOf, type Duration, type DurationText, type EventOf, type EventWorkflow, type EventWorkflowSpec, type Exec, type ForkAnswer, type ForkOptions, type Gate, type GateContext, type JsonValue, type Need, type NeedAddOptions, type Needs, type OneOfValues, type OutputResult, type OutputSchema, type PasskeyAnswer, type PasskeyCheckOptions, type PasskeyFrom, type PasskeyRunOptions, type PullRequestAnswer, type PullRequestOptions, type PushAnswer, type Ref0Actions, type Refusal, type Sandbox, type SandboxCommand, type SandboxRunOptions, type SandboxSession, type SandboxSpec, type Served, type StartActor, type StartContext, type StartItem, type StartOutput, type StartRule, type StartRun, type Step, type StepConfig, type StepContext, type ThreadStart, type Tree, type TreeEntry, type TreeRead, type WaitType, type WaitedEvent, type WorkflowContext, type WorkflowStep, allow, check, oneOf, refuse, text, workflow };
+//# sourceMappingURL=index.d.mts.map