@intentius/chant-lexicon-e2b 0.0.0-stage → 0.124.32

package/dist/okf/rules/E2B001.md

@@ -0,0 +1,15 @@
+---
+type: lint-rule
+title: E2B001
+description: A template's CPU and memory are sizes E2B accepts.
+id: E2B001
+severity: error
+category: correctness
+lexicon: e2b
+docs: https://intentius.io/chant/lexicons/e2b/rules/
+---
+A template's CPU and memory are sizes E2B accepts.
+
+## Applies to
+
+- [Template](/types/Template.md)

package/dist/okf/rules/E2B002.md

@@ -0,0 +1,15 @@
+---
+type: lint-rule
+title: E2B002
+description: A template's base image is pinned.
+id: E2B002
+severity: warning
+category: correctness
+lexicon: e2b
+docs: https://intentius.io/chant/lexicons/e2b/rules/
+---
+A template's base image is pinned.
+
+## Applies to
+
+- [Template](/types/Template.md)

package/dist/okf/rules/E2B011.md

@@ -0,0 +1,15 @@
+---
+type: post-synth-check
+title: E2B011
+description: A Template's name must be lowercase letters, digits, dashes and underscores, and unique
+id: E2B011
+severity: error
+category: post-synth
+lexicon: e2b
+docs: https://intentius.io/chant/lexicons/e2b/rules/
+---
+A Template's name must be lowercase letters, digits, dashes and underscores, and unique
+
+## Applies to
+
+- [Template](/types/Template.md)

package/dist/okf/rules/E2B012.md

@@ -0,0 +1,15 @@
+---
+type: post-synth-check
+title: E2B012
+description: A Template a steward runs on needs git and Node
+id: E2B012
+severity: error
+category: post-synth
+lexicon: e2b
+docs: https://intentius.io/chant/lexicons/e2b/rules/
+---
+A Template a steward runs on needs git and Node
+
+## Applies to
+
+- [Template](/types/Template.md)

package/dist/okf/types/Template.md

@@ -0,0 +1,16 @@
+---
+type: resource-type
+title: Template
+description: e2b resource type E2B::Template
+name: Template
+lexicon: e2b
+resource_type: E2B::Template
+---
+`E2B::Template`, a resource type of the e2b lexicon.
+
+## Governed by
+
+- [E2B001](/rules/E2B001.md): A template's CPU and memory are sizes E2B accepts.
+- [E2B002](/rules/E2B002.md): A template's base image is pinned.
+- [E2B011](/rules/E2B011.md): A Template's name must be lowercase letters, digits, dashes and underscores, and unique
+- [E2B012](/rules/E2B012.md): A Template a steward runs on needs git and Node

package/dist/op/runtime.d.ts

@@ -0,0 +1,119 @@
+/**
+ * The e2b `opRuntime` provider: `chant run <op> --on e2b`.
+ *
+ * A steward is one sandbox that outlives every run: it keeps a clone of the
+ * project and its installed tools on its disk, runs one op at a time, and
+ * sleeps paused between runs, which costs nothing and survives anything that
+ * doesn't delete it. Any API that speaks E2B's hosts one: hosted E2B, or a
+ * platform of your own that serves the same API (loam does).
+ *
+ * A run here is the run a person would have typed in that clone:
+ *
+ * 1. Find the steward's sandbox by its `chant/steward` metadata, or make it.
+ *    A sandbox already running an op is busy, and the run is refused rather
+ *    than queued, as fountain refuses a busy steward conversation.
+ * 2. Bring the clone to the commit this checkout is at (fetched from the
+ *    repository, so the commit must be pushed) and install the project's
+ *    dependencies when its lockfile changed.
+ * 3. Run `chant run <op> --on local --json --progress-json` there, streaming
+ *    each settled step back through `progress` and its stderr to ours. Gates,
+ *    leases and the run ledger are the local runtime's, unchanged: they live on
+ *    the repository's `chant/lifecycle` branch, which chant in the sandbox
+ *    fetches and pushes with the git token the profile names, so `chant
+ *    approve` on any checkout answers a gate a steward reached.
+ * 4. Pause the sandbox.
+ *
+ * `status`, `log` and `list` read the run ledger in the steward's clone, and
+ * report a run still in progress from the sandbox's process list. They wake
+ * the sandbox to do it and leave it to pause itself a few minutes later.
+ *
+ * Nothing here remembers anything between processes: the sandbox's metadata
+ * finds it, the ledger is the history, and the process list is what is running.
+ */
+import { type ChantConfig } from "@intentius/chant/config";
+import type { OpRunRecord, OpRunStartOptions, OpRunStatus, OpRuntimeProvider, StepRecord } from "@intentius/chant/op";
+import { type StewardSandboxes } from "./sandbox.js";
+/** How long a sandbox is held awake at a time while a run is going. Renewed at a third of it. */
+export declare const RUN_AWAKE_MS: number;
+/** How long a read (`status`, `log`, `list`) leaves a woken sandbox awake before it pauses itself. */
+export declare const READ_AWAKE_MS: number;
+/** The template a steward is made from when the profile names none. */
+export declare const DEFAULT_TEMPLATE = "base";
+/** Where the steward keeps its clone, under the sandbox user's home. */
+export declare const CLONE_DIR = "chant-steward";
+export interface E2bOpRuntimeOptions {
+    /** The project directory. Default `process.cwd()`. */
+    cwd?: string;
+    /** The project's chant config, when the caller already has it. */
+    config?: ChantConfig;
+    /** The sandbox provider. Default: the `e2b` SDK, connected per the profile. */
+    sandboxes?: StewardSandboxes;
+    /** Read the local checkout. Injectable so a test needs no repository. */
+    git?: (args: string[]) => Promise<string>;
+    /** Where the sandbox's stderr goes. Default `process.stderr`. */
+    stderr?: (chunk: string) => void;
+    env?: NodeJS.ProcessEnv;
+    now?: () => Date;
+}
+/** An ssh remote as the https URL a sandbox can fetch with a token. Anything else is returned as it is. */
+export declare function httpsRemote(url: string): string;
+/** The repository's name, from its URL: the steward's default name. */
+export declare function repoName(url: string): string;
+/** A word as one shell argument. */
+export declare function shellQuote(value: string): string;
+/**
+ * A bash function, `ledger_sync`, that leaves the clone's `chant/lifecycle`
+ * branch and the repository's the same, run in the clone after a fetch.
+ *
+ * chant pushes the facts other checkouts have to see (a gate's pending fact,
+ * an approval, a lease) as it writes them, but keeps each run record on the
+ * local branch only. A checkout that lives on, as a steward's does, therefore
+ * holds commits the repository lacks, and the first approval pushed from
+ * anywhere else leaves the two branches diverged; chant then refuses to read
+ * the ledger at all. So the steward reconciles before and after every run:
+ *
+ * - behind, or the same: nothing to do (chant fetches it itself);
+ * - ahead: push;
+ * - diverged: merge, then push. Every ledger file is append-only, so the
+ *   merge keeps the repository's tree and adds, for each `.jsonl` file, the
+ *   local lines it lacks after its own, and any file only the clone has. The
+ *   merge commit has both tips as parents, so neither side loses a commit.
+ *
+ * A push that fails (the repository moved again in between, or there is no
+ * token) is reported and left for the next run.
+ */
+export declare const LEDGER_SYNC_FN: string;
+/**
+ * The script that brings the steward's clone to `commit`: clone it the first
+ * time, fetch every branch after that, reconcile the ledger branch
+ * ({@link LEDGER_SYNC_FN}), check the commit out over whatever is there, and
+ * install dependencies when the lockfile changed. Ignored files
+ * (`node_modules`, tool caches) are kept, which is the point of a steward.
+ * The token, when there is one, reaches git through a credential helper that
+ * reads it from the environment, so it is never written to the sandbox's disk.
+ */
+export declare function prepareScript(repo: string, commit: string): string;
+/** Seconds a stopped run is given to end on SIGTERM before it is killed. */
+export declare const STOP_GRACE_S = 10;
+/** SIGTERM `pid`, wait for it to go, and exit non-zero if it is still there after the grace period. */
+export declare function stopScript(pid: number): string;
+/** After a run: fetch and reconcile the ledger branch, so the run's record reaches the repository. */
+export declare function finishScript(): string;
+/** The command line one run is, in the clone. `exec` so the process the sandbox lists is chant itself. */
+export declare function runScript(op: string, opts: Pick<OpRunStartOptions, "env" | "params" | "work">): string;
+/**
+ * The script that prints every run record the clone's ledger holds for `ops`
+ * (all of them when empty), one JSON line each, from every environment
+ * directory on `chant/lifecycle`. Root-level ledgers only: a workspace
+ * member's runs (`_members/<m>/...`) are not read.
+ */
+export declare function ledgerScript(ops: string[]): string;
+/** A ledger line, or a run's final `--json` line, as an {@link OpRunRecord}; anything else `undefined`. */
+export declare function asRunRecord(v: unknown): OpRunRecord | undefined;
+/** A `--progress-json` line as a {@link StepRecord}; anything else `undefined`. */
+export declare function asStepRecord(v: unknown): StepRecord | undefined;
+/** Every record in `text`, one JSON object per line, newest first. */
+export declare function parseLedger(text: string): OpRunRecord[];
+export declare function statusFromRecord(record: OpRunRecord): OpRunStatus;
+export declare function createE2bOpRuntime(opts?: E2bOpRuntimeOptions): OpRuntimeProvider;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/op/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/op/runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAmB,KAAK,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC5E,OAAO,KAAK,EAAyB,WAAW,EAAE,iBAAiB,EAAE,WAAW,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAG7I,OAAO,EAOL,KAAK,gBAAgB,EACtB,MAAM,WAAW,CAAC;AAEnB,iGAAiG;AACjG,eAAO,MAAM,YAAY,QAAc,CAAC;AAExC,sGAAsG;AACtG,eAAO,MAAM,aAAa,QAAa,CAAC;AAExC,uEAAuE;AACvE,eAAO,MAAM,gBAAgB,SAAS,CAAC;AAEvC,wEAAwE;AACxE,eAAO,MAAM,SAAS,kBAAkB,CAAC;AAEzC,MAAM,WAAW,mBAAmB;IAClC,sDAAsD;IACtD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,yEAAyE;IACzE,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1C,iEAAiE;IACjE,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAWD,2GAA2G;AAC3G,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAM/C;AAED,uEAAuE;AACvE,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAG5C;AAED,oCAAoC;AACpC,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,cAAc,QA4Bf,CAAC;AAEb;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CA0BlE;AAED,4EAA4E;AAC5E,eAAO,MAAM,YAAY,KAAK,CAAC;AAE/B,uGAAuG;AACvG,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAG9C;AAED,sGAAsG;AACtG,wBAAgB,YAAY,IAAI,MAAM,CAQrC;AAED,0GAA0G;AAC1G,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,iBAAiB,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC,GAAG,MAAM,CAUtG;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,CAWlD;AAMD,2GAA2G;AAC3G,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,GAAG,WAAW,GAAG,SAAS,CAI/D;AAED,mFAAmF;AACnF,wBAAgB,YAAY,CAAC,CAAC,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,CAI/D;AAED,sEAAsE;AACtE,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,EAAE,CAYvD;AAwBD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,GAAG,WAAW,CAWjE;AAeD,wBAAgB,kBAAkB,CAAC,IAAI,GAAE,mBAAwB,GAAG,iBAAiB,CAwPpF"}