@davidorex/pi-context 0.26.0 → 0.28.0

package/dist/migrations-store.js

@@ -0,0 +1,206 @@
+/**
+ * migrations-store — substrate-managed read / write surface for
+ * `<resolveContextDir(cwd)>/migrations.json`.
+ *
+ * Mirrors the config / relations precedent in context.ts: load + AJV-validate
+ * via `validateFromFile` against the bundled migrations.schema.json; whole-file
+ * writes delegate to block-api's atomic `writeTypedFile` (tmp + rename) so a
+ * failed write leaves the prior file byte-identical.
+ *
+ * Three op-correct mutation helpers — append / replace / remove — wrap a
+ * load → JSON deep-clone → mutate → write pattern. Identity of a MigrationDecl
+ * is the (schemaName, fromVersion) pair, mirroring the registry's
+ * one-outgoing-edge-per-(schemaName, fromVersion) discipline from
+ * `schema-migrations.ts`:
+ *   - appendMigrationDecl requires the (schemaName, fromVersion) pair to be
+ *     ABSENT; collision throws with a descriptive message so an unintended
+ *     double-declaration surfaces at the write site rather than as silent
+ *     registry duplicate-registration at load time.
+ *   - replaceMigrationDecl requires the pair to be PRESENT; a missing target
+ *     throws (use append to introduce a new declaration).
+ *   - removeMigrationDecl requires the pair to be PRESENT; a missing target
+ *     throws.
+ *
+ * After each successful mutation the helper invokes
+ * `invalidateMigrationRegistry(cwd)` (migration-registry-loader.ts) so the
+ * next `getProjectMigrationRegistry(cwd)` consumer reads the fresh
+ * declarations without process restart. The store↔loader edge is mutually
+ * cyclic (loader reads from store; store writes invalidate loader cache);
+ * ESM tolerates the cycle because both imports are function-level uses, not
+ * top-level evaluations.
+ *
+ * MigrationDecl + TransformSpec + TransformOp types mirror the on-disk schema
+ * shape one-for-one. They live here (rather than schema-migrations.ts) because
+ * schema-migrations.ts is the in-memory registry abstraction (knows nothing of
+ * persistence); the persisted-shape vocabulary belongs at the substrate-store
+ * boundary.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { writeTypedFile } from "./block-api.js";
+import { migrationsPath, migrationsPathForDir, resolveContextDir } from "./context-dir.js";
+import { invalidateMigrationRegistry, invalidateMigrationRegistryForDir } from "./migration-registry-loader.js";
+import { validateFromFile } from "./schema-validator.js";
+/**
+ * Resolve the bundled migrations schema file. Mirrors the private
+ * `bundledSchemaPath` helper in context.ts — schemas live one directory up
+ * from both `src/` (under tsx --test) and `dist/` (after tsc).
+ */
+function bundledMigrationsSchemaPath() {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    return path.resolve(here, "..", "schemas", "migrations.schema.json");
+}
+/**
+ * Current schema_version emitted into newly-created migrations.json files.
+ * Tracks the `version` field of migrations.schema.json itself.
+ */
+export const MIGRATIONS_FILE_VERSION = "1.0.0";
+/**
+ * Load + AJV-validate migrations.json. Returns null when the file is absent
+ * (pre-write state is a normal condition, NOT an error — empty/missing yields
+ * an empty registry in the loader). Throws on read / parse / schema failure.
+ */
+export function loadMigrationsFileForDir(substrateDir) {
+    const p = migrationsPathForDir(substrateDir);
+    if (!fs.existsSync(p))
+        return null;
+    let raw;
+    try {
+        raw = fs.readFileSync(p, "utf-8");
+    }
+    catch (err) {
+        throw new Error(`loadMigrationsFile: failed to read ${p}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`loadMigrationsFile: invalid JSON in ${p}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    validateFromFile(bundledMigrationsSchemaPath(), data, `migrations.json (${p})`);
+    return data;
+}
+export function loadMigrationsFile(cwd) {
+    return loadMigrationsFileForDir(resolveContextDir(cwd));
+}
+/**
+ * Atomic, AJV-validated whole-file write of migrations.json. Delegates to
+ * block-api's writeTypedFile against the bundled migrations schema. `ctx` is
+ * accepted for call-site parity with the rest of the substrate write surface;
+ * the migrations schema declares no envelope author fields so stamping is a
+ * structural no-op today (the loader-cache invalidation upstream of this call
+ * is the side-effect that matters for read-after-write parity).
+ */
+export function writeMigrationsFile(cwd, file, ctx) {
+    writeMigrationsFileForDir(resolveContextDir(cwd), file, ctx);
+}
+/**
+ * Dir-targeted twin of {@link writeMigrationsFile} (Cycle-1 `*ForDir` pattern).
+ * Atomic, AJV-validated whole-file write of `<substrateDir>/migrations.json`
+ * against the bundled migrations schema — takes the ALREADY-RESOLVED substrate
+ * dir directly (no `.pi-context.json` pointer resolution). The cwd form is a
+ * thin wrapper resolving the active dir; behaviour is byte-identical when called
+ * via cwd. Same attestation-parity no-op semantics as the cwd form (the
+ * migrations schema declares no envelope author fields). Does NOT invalidate any
+ * loader cache — the cache-invalidation side-effect lives on the
+ * appendMigrationDecl mutation helpers, not the raw whole-file write.
+ */
+export function writeMigrationsFileForDir(substrateDir, file, ctx) {
+    writeTypedFile(migrationsPathForDir(substrateDir), bundledMigrationsSchemaPath(), file, ctx, "migrations.json");
+}
+/**
+ * Compose an initial empty migrations file shape — used by the append helper
+ * when the on-disk file is absent. Centralised so the `schema_version` token
+ * is sourced from one place.
+ */
+function emptyMigrationsFile() {
+    return { schema_version: MIGRATIONS_FILE_VERSION, migrations: [] };
+}
+/**
+ * Deep-clone via JSON round-trip. Sufficient for MigrationDecl shapes (no
+ * Date / Map / undefined values per the schema). Matches the amend-config
+ * load-clone-mutate-write precedent.
+ */
+function clone(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+/**
+ * Locate the index of a (schemaName, fromVersion) MigrationDecl within the
+ * file's `migrations[]` array; returns -1 when absent. Centralised so the
+ * three op-correct helpers cannot drift on identity-matching semantics.
+ */
+function findMigrationIndex(file, schemaName, fromVersion) {
+    return file.migrations.findIndex((m) => m.schemaName === schemaName && m.fromVersion === fromVersion);
+}
+/**
+ * Append a new MigrationDecl to the substrate. Op-correctness: the
+ * (schemaName, fromVersion) pair must be ABSENT on-disk; collision throws.
+ * Invalidates the loader cache for `cwd` after a successful write so the
+ * next registry consumer reads the fresh declaration.
+ */
+export function appendMigrationDecl(cwd, decl, ctx) {
+    appendMigrationDeclForDir(resolveContextDir(cwd), decl, ctx);
+}
+/**
+ * Dir-targeted twin of {@link appendMigrationDecl} (Cycle-1 `*ForDir` pattern).
+ * Append a new MigrationDecl to the substrate at `substrateDir`. Op-correctness:
+ * the (schemaName, fromVersion) pair must be ABSENT on-disk; collision throws.
+ * Invalidates the loader cache for `substrateDir` after a successful write so
+ * the next registry consumer reads the fresh declaration. The cwd form is a thin
+ * wrapper resolving the active dir; behaviour is byte-identical when called via
+ * cwd (resolveContextDir(cwd) → invalidateMigrationRegistry(cwd) routes through
+ * invalidateMigrationRegistryForDir on the same dir).
+ */
+export function appendMigrationDeclForDir(substrateDir, decl, ctx) {
+    const current = loadMigrationsFileForDir(substrateDir) ?? emptyMigrationsFile();
+    const idx = findMigrationIndex(current, decl.schemaName, decl.fromVersion);
+    if (idx >= 0) {
+        throw new Error(`appendMigrationDecl: collision — migration for schema '${decl.schemaName}' fromVersion '${decl.fromVersion}' already exists; use replaceMigrationDecl to overwrite`);
+    }
+    const next = clone(current);
+    next.migrations.push(decl);
+    writeMigrationsFileForDir(substrateDir, next, ctx);
+    invalidateMigrationRegistryForDir(substrateDir);
+}
+/**
+ * Replace an existing MigrationDecl identified by (schemaName, fromVersion).
+ * Op-correctness: target must be PRESENT; missing target throws. The whole
+ * decl is replaced (no per-field merge). Invalidates the loader cache after a
+ * successful write.
+ */
+export function replaceMigrationDecl(cwd, decl, ctx) {
+    const current = loadMigrationsFile(cwd);
+    if (current === null) {
+        throw new Error(`replaceMigrationDecl: migrations.json absent at ${migrationsPath(cwd)}; use appendMigrationDecl to create`);
+    }
+    const idx = findMigrationIndex(current, decl.schemaName, decl.fromVersion);
+    if (idx < 0) {
+        throw new Error(`replaceMigrationDecl: target missing — no migration declared for schema '${decl.schemaName}' fromVersion '${decl.fromVersion}'; use appendMigrationDecl to introduce`);
+    }
+    const next = clone(current);
+    next.migrations[idx] = decl;
+    writeMigrationsFile(cwd, next, ctx);
+    invalidateMigrationRegistry(cwd);
+}
+/**
+ * Remove an existing MigrationDecl identified by (schemaName, fromVersion).
+ * Op-correctness: target must be PRESENT; missing target throws. Invalidates
+ * the loader cache after a successful write.
+ */
+export function removeMigrationDecl(cwd, schemaName, fromVersion, ctx) {
+    const current = loadMigrationsFile(cwd);
+    if (current === null) {
+        throw new Error(`removeMigrationDecl: migrations.json absent at ${migrationsPath(cwd)}; nothing to remove`);
+    }
+    const idx = findMigrationIndex(current, schemaName, fromVersion);
+    if (idx < 0) {
+        throw new Error(`removeMigrationDecl: target missing — no migration declared for schema '${schemaName}' fromVersion '${fromVersion}'`);
+    }
+    const next = clone(current);
+    next.migrations.splice(idx, 1);
+    writeMigrationsFile(cwd, next, ctx);
+    invalidateMigrationRegistry(cwd);
+}
+//# sourceMappingURL=migrations-store.js.map

package/dist/migrations-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations-store.js","sourceRoot":"","sources":["../src/migrations-store.ts"],"names":[],"mappings":"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"}

package/dist/object-store.d.ts

@@ -0,0 +1,26 @@
+/**
+ * True when an object with `contentHash` already exists in the store.
+ * Asserts hash shape first (a malformed hash can never be present, but the
+ * guard keeps the surface uniform and rejects path-escape attempts at the
+ * boundary).
+ */
+export declare function hasObject(substrateDir: string, contentHash: string): boolean;
+/**
+ * Write `content` under `contentHash` if not already present.
+ *
+ * Idempotent: returns early when `hasObject` is true (content-addressed — the
+ * same hash implies the same bytes, so a re-put would rewrite identical
+ * content). On a fresh write, creates `<substrateDir>/objects/` if needed and
+ * writes `JSON.stringify(content, null, 2)` via atomic tmp+rename.
+ *
+ * `content` is expected to be the canonical content projection the caller
+ * hashed to obtain `contentHash`; this module does not re-derive or verify the
+ * hash (no dependency on content-hash.ts).
+ */
+export declare function putObject(substrateDir: string, contentHash: string, content: Record<string, unknown>): void;
+/**
+ * Parsed content stored under `contentHash`, or `null` when no such object
+ * exists. Asserts hash shape first.
+ */
+export declare function getObject(substrateDir: string, contentHash: string): Record<string, unknown> | null;
+//# sourceMappingURL=object-store.d.ts.map

package/dist/object-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"object-store.d.ts","sourceRoot":"","sources":["../src/object-store.ts"],"names":[],"mappings":"AAoDA;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAG5E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAqB3G;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAOnG"}

package/dist/object-store.js

@@ -0,0 +1,104 @@
+/**
+ * Content-addressed object store (Cycle 2, Phase B). A durable, append-only
+ * store keyed by a content hash: each distinct content projection is written
+ * once to `<substrateDir>/objects/<contentHash>.json` holding its JSON. This is
+ * the durable Merkle store that makes the OID/refname split actually
+ * content-addressed and gives later cycles real pinning + integrity.
+ *
+ * Dir-explicit (no pointer resolution), so it is independently testable and
+ * usable across substrate dirs. It takes a `contentHash` parameter rather than
+ * computing one — the caller supplies the hash from `computeContentHash` — so
+ * this module has ZERO dependency on `content-hash.ts`.
+ *
+ * No file lock: a write is keyed by its own content hash, so two writers of the
+ * same content produce byte-identical files at the same path (collision-free,
+ * idempotent). Atomic tmp+rename guards against a torn read of a partial file.
+ *
+ * `objects/` is tracked in git (it is the integrity store; gitignoring it would
+ * lose pinning). No `.gitignore` change accompanies this module.
+ *
+ * Dormant this cycle: nothing in any write path calls `putObject` yet (Cycle 3
+ * wiring / Cycle 10 backfill). Infrastructure module — not re-exported from
+ * `index.ts`.
+ */
+import fs from "node:fs";
+import path from "node:path";
+/** Lowercase 64-char hex (a SHA-256 digest). */
+const CONTENT_HASH_PATTERN = /^[0-9a-f]{64}$/;
+/**
+ * Guard the hash before it becomes a path segment. A content hash is a fixed
+ * lowercase-hex SHA-256 digest; anything else (wrong length, uppercase, path
+ * separators, `..`) is rejected so a malformed value cannot escape the
+ * `objects/` directory or name a non-canonical file. Analogous to
+ * `assertSubstrateName` for block names.
+ */
+function assertContentHash(contentHash) {
+    if (!CONTENT_HASH_PATTERN.test(contentHash)) {
+        throw new Error(`object-store: invalid contentHash ${JSON.stringify(contentHash)} — expected lowercase 64-char hex (SHA-256)`);
+    }
+}
+function objectsDirFor(substrateDir) {
+    return path.join(substrateDir, "objects");
+}
+function objectPathFor(substrateDir, contentHash) {
+    return path.join(objectsDirFor(substrateDir), `${contentHash}.json`);
+}
+/**
+ * True when an object with `contentHash` already exists in the store.
+ * Asserts hash shape first (a malformed hash can never be present, but the
+ * guard keeps the surface uniform and rejects path-escape attempts at the
+ * boundary).
+ */
+export function hasObject(substrateDir, contentHash) {
+    assertContentHash(contentHash);
+    return fs.existsSync(objectPathFor(substrateDir, contentHash));
+}
+/**
+ * Write `content` under `contentHash` if not already present.
+ *
+ * Idempotent: returns early when `hasObject` is true (content-addressed — the
+ * same hash implies the same bytes, so a re-put would rewrite identical
+ * content). On a fresh write, creates `<substrateDir>/objects/` if needed and
+ * writes `JSON.stringify(content, null, 2)` via atomic tmp+rename.
+ *
+ * `content` is expected to be the canonical content projection the caller
+ * hashed to obtain `contentHash`; this module does not re-derive or verify the
+ * hash (no dependency on content-hash.ts).
+ */
+export function putObject(substrateDir, contentHash, content) {
+    assertContentHash(contentHash);
+    if (hasObject(substrateDir, contentHash)) {
+        return;
+    }
+    const objectsDir = objectsDirFor(substrateDir);
+    fs.mkdirSync(objectsDir, { recursive: true });
+    const filePath = objectPathFor(substrateDir, contentHash);
+    const tmpPath = `${filePath}.object-store-${process.pid}.tmp`;
+    try {
+        fs.writeFileSync(tmpPath, JSON.stringify(content, null, 2), "utf-8");
+        fs.renameSync(tmpPath, filePath);
+    }
+    catch (err) {
+        try {
+            fs.unlinkSync(tmpPath);
+        }
+        catch {
+            /* ignore cleanup failure */
+        }
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`object-store: failed to write object ${contentHash}: ${msg}`);
+    }
+}
+/**
+ * Parsed content stored under `contentHash`, or `null` when no such object
+ * exists. Asserts hash shape first.
+ */
+export function getObject(substrateDir, contentHash) {
+    assertContentHash(contentHash);
+    const filePath = objectPathFor(substrateDir, contentHash);
+    if (!fs.existsSync(filePath)) {
+        return null;
+    }
+    return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+}
+//# sourceMappingURL=object-store.js.map

package/dist/object-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"object-store.js","sourceRoot":"","sources":["../src/object-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,gDAAgD;AAChD,MAAM,oBAAoB,GAAG,gBAAgB,CAAC;AAE9C;;;;;;GAMG;AACH,SAAS,iBAAiB,CAAC,WAAmB;IAC7C,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;QAC7C,MAAM,IAAI,KAAK,CACd,qCAAqC,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,6CAA6C,CAC7G,CAAC;IACH,CAAC;AACF,CAAC;AAED,SAAS,aAAa,CAAC,YAAoB;IAC1C,OAAO,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC;AAC3C,CAAC;AAED,SAAS,aAAa,CAAC,YAAoB,EAAE,WAAmB;IAC/D,OAAO,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,YAAY,CAAC,EAAE,GAAG,WAAW,OAAO,CAAC,CAAC;AACtE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,YAAoB,EAAE,WAAmB;IAClE,iBAAiB,CAAC,WAAW,CAAC,CAAC;IAC/B,OAAO,EAAE,CAAC,UAAU,CAAC,aAAa,CAAC,YAAY,EAAE,WAAW,CAAC,CAAC,CAAC;AAChE,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,SAAS,CAAC,YAAoB,EAAE,WAAmB,EAAE,OAAgC;IACpG,iBAAiB,CAAC,WAAW,CAAC,CAAC;IAC/B,IAAI,SAAS,CAAC,YAAY,EAAE,WAAW,CAAC,EAAE,CAAC;QAC1C,OAAO;IACR,CAAC;IACD,MAAM,UAAU,GAAG,aAAa,CAAC,YAAY,CAAC,CAAC;IAC/C,EAAE,CAAC,SAAS,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9C,MAAM,QAAQ,GAAG,aAAa,CAAC,YAAY,EAAE,WAAW,CAAC,CAAC;IAC1D,MAAM,OAAO,GAAG,GAAG,QAAQ,iBAAiB,OAAO,CAAC,GAAG,MAAM,CAAC;IAC9D,IAAI,CAAC;QACJ,EAAE,CAAC,aAAa,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;QACrE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IAClC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACd,IAAI,CAAC;YACJ,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QACxB,CAAC;QAAC,MAAM,CAAC;YACR,4BAA4B;QAC7B,CAAC;QACD,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC7D,MAAM,IAAI,KAAK,CAAC,wCAAwC,WAAW,KAAK,GAAG,EAAE,CAAC,CAAC;IAChF,CAAC;AACF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,YAAoB,EAAE,WAAmB;IAClE,iBAAiB,CAAC,WAAW,CAAC,CAAC;IAC/B,MAAM,QAAQ,GAAG,aAAa,CAAC,YAAY,EAAE,WAAW,CAAC,CAAC;IAC1D,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC9B,OAAO,IAAI,CAAC;IACb,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAA4B,CAAC;AAClF,CAAC"}

package/dist/ops-registry.d.ts

@@ -0,0 +1,44 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { type TSchema } from "typebox";
+/**
+ * One substrate operation. `run(cwd, params)` returns the text payload that
+ * registerAll places at `content[0].text`; everything else (param coercion,
+ * library calls, early returns, throws) lives in run verbatim. `parameters` is
+ * the typebox Type.Object schema published as the tool's parameter schema.
+ *
+ * `surface` partitions ops for the downstream CLI ("use" = read/write substrate
+ * ops; "process" reserved for lifecycle/dispatch ops). `authGated` flags ops
+ * the CLI should treat as requiring credentialed confirmation; it is carried
+ * for that consumer and is not the enforcement point (the pi-agent-dispatch
+ * auth-gate remains canonical).
+ */
+export interface OpDefinition<P = any> {
+    name: string;
+    label: string;
+    description: string;
+    promptSnippet?: string;
+    parameters: TSchema;
+    run(cwd: string, params: P): string | Promise<string>;
+    authGated?: boolean;
+    surface: "use" | "process";
+}
+export declare const ops: OpDefinition[];
+/**
+ * The pi-context-owned set of tool names that require human-authorization at
+ * the pi-agent-dispatch tool_call gate. Derived from the registry's authGated
+ * flags rather than hand-maintained, so a single source — the OpDefinition's
+ * authGated field — names both the CLI's credentialed-confirmation hint and the
+ * gate's aggregated allowlist. pi-agent-dispatch imports this via the `./ops`
+ * subpath and folds it into AUTH_REQUIRED_TOOLS alongside the other packages'
+ * owned sets. The gate at the pi-agent-dispatch layer remains the enforcement
+ * point; this list is the source of pi-context's contribution to it.
+ */
+export declare const gatedTools: string[];
+/**
+ * Register every op in `ops` as a pi tool. Each tool's execute body is the
+ * uniform wrapper around the op's run(): coerce params, await run, place the
+ * returned string at content[0].text. Behavior-identical to the prior inline
+ * registrations.
+ */
+export declare function registerAll(pi: ExtensionAPI): void;
+//# sourceMappingURL=ops-registry.d.ts.map

package/dist/ops-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ops-registry.d.ts","sourceRoot":"","sources":["../src/ops-registry.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAGX,YAAY,EAEZ,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,KAAK,OAAO,EAAQ,MAAM,SAAS,CAAC;AA4D7C;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC,GAAG,GAAG;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,OAAO,CAAC;IACpB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACtD,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,KAAK,GAAG,SAAS,CAAC;CAC3B;AA6BD,eAAO,MAAM,GAAG,EAAE,YAAY,EAqzC7B,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU,EAAE,MAAM,EAAsD,CAAC;AAYtF;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CAuBlD"}