@orygn/opa-mcp 0.0.0 → 0.1.1

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,QAAA,MAAM,YAAY;IAChB,wEAAwE;;IAGxE,2EAA2E;;IAG3E,2DAA2D;;IAG3D,+DAA+D;;IAG/D,kEAAkE;;IAGlE,mDAAmD;;IAGnD;;;;;OAKG;;IAGH,uEAAuE;;IAGvE,qCAAqC;;IAGrC;;;;OAIG;;;;;;;;;;;;;;;;;;;;;;;;EAEH,CAAC;AAEH,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAWlD,wBAAgB,UAAU,IAAI,MAAM,CAuBnC"}

package/dist/config.js

@@ -0,0 +1,72 @@
+/**
+ * Centralized configuration loaded from environment variables.
+ *
+ * Environment variables are the only configuration surface — there is no
+ * config file, no flags. This matches how MCP clients (Claude Desktop,
+ * Cursor, VS Code) pass config via the `env` object in their JSON.
+ */
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { z } from 'zod';
+const ConfigSchema = z.object({
+    /** Base URL of a running OPA server (used by `opa_*` runtime tools). */
+    opaUrl: z.string().url().default('http://localhost:8181'),
+    /** Optional bearer token for OPA running with `--authentication=token`. */
+    opaToken: z.string().optional(),
+    /** Path to the `opa` binary. Defaults to `opa` on PATH. */
+    opaBinary: z.string().default('opa'),
+    /** Path to the `regal` binary. Defaults to `regal` on PATH. */
+    regalBinary: z.string().default('regal'),
+    /** Hard timeout in ms for any spawned subprocess (opa, regal). */
+    subprocessTimeoutMs: z.coerce.number().int().positive().default(30_000),
+    /** HTTP request timeout for OPA REST API calls. */
+    httpTimeoutMs: z.coerce.number().int().positive().default(15_000),
+    /**
+     * Allow-listed root directories for file path inputs. Tools that accept
+     * filesystem paths reject anything outside these roots. Empty by
+     * default — file-based tools refuse to read from disk until the
+     * operator explicitly opts in via `OPA_MCP_ALLOWED_PATHS`.
+     */
+    allowedPaths: z.array(z.string()).default([]),
+    /** Path to the log file. Defaults to OS tmpdir + orygn-opa-mcp.log. */
+    logFile: z.string().default(join(tmpdir(), 'orygn-opa-mcp.log')),
+    /** Log level for the file logger. */
+    logLevel: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
+    /**
+     * Maximum size in bytes for tool response payloads before truncation.
+     * Larger payloads are truncated with `truncated: true` and a hint to
+     * write to a file path the agent specifies.
+     */
+    maxResponseBytes: z.coerce.number().int().positive().default(100_000),
+});
+function parseAllowedPaths(raw) {
+    if (!raw)
+        return undefined;
+    const parts = raw
+        .split(/[;,]/)
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+    return parts.length > 0 ? parts : undefined;
+}
+export function loadConfig() {
+    const allowedPaths = parseAllowedPaths(process.env['OPA_MCP_ALLOWED_PATHS']);
+    const parsed = ConfigSchema.safeParse({
+        opaUrl: process.env['OPA_URL'],
+        opaToken: process.env['OPA_TOKEN'],
+        opaBinary: process.env['OPA_BINARY'],
+        regalBinary: process.env['REGAL_BINARY'],
+        subprocessTimeoutMs: process.env['OPA_MCP_TIMEOUT_MS'],
+        httpTimeoutMs: process.env['OPA_MCP_HTTP_TIMEOUT_MS'],
+        allowedPaths,
+        logFile: process.env['OPA_MCP_LOG_FILE'],
+        logLevel: process.env['OPA_MCP_LOG_LEVEL'],
+        maxResponseBytes: process.env['OPA_MCP_MAX_RESPONSE_BYTES'],
+    });
+    if (!parsed.success) {
+        console.error('Invalid orygn-opa-mcp configuration:');
+        console.error(JSON.stringify(parsed.error.format(), null, 2));
+        process.exit(2);
+    }
+    return parsed.data;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/lib/errors.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Helpers for building structured tool errors.
+ *
+ * Tools should never throw raw exceptions to the MCP layer — every failure
+ * mode returns a `ToolEnvelope` with `ok: false` and a structured `error`.
+ */
+import type { ToolEnvelope, ToolErrorCode } from '../types.js';
+export declare function err(code: ToolErrorCode, message: string, options?: {
+    hint?: string;
+    details?: unknown;
+}): ToolEnvelope<never>;
+export declare function ok<T>(data: T, warnings?: string[]): ToolEnvelope<T>;
+/**
+ * Wrap an unknown thrown value into a structured error. Used as the
+ * outermost catch in tool handlers.
+ */
+export declare function fromException(e: unknown): ToolEnvelope<never>;
+//# sourceMappingURL=errors.d.ts.map

package/dist/lib/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,YAAY,EAAa,aAAa,EAAE,MAAM,aAAa,CAAC;AAE1E,wBAAgB,GAAG,CACjB,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAC7C,YAAY,CAAC,KAAK,CAAC,CAKrB;AAED,wBAAgB,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,YAAY,CAAC,CAAC,CAAC,CAInE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,GAAG,YAAY,CAAC,KAAK,CAAC,CAK7D"}

package/dist/lib/errors.js

@@ -0,0 +1,25 @@
+export function err(code, message, options) {
+    const error = { code, message };
+    if (options?.hint !== undefined)
+        error.hint = options.hint;
+    if (options?.details !== undefined)
+        error.details = options.details;
+    return { ok: false, error };
+}
+export function ok(data, warnings) {
+    const envelope = { ok: true, data };
+    if (warnings && warnings.length > 0)
+        envelope.warnings = warnings;
+    return envelope;
+}
+/**
+ * Wrap an unknown thrown value into a structured error. Used as the
+ * outermost catch in tool handlers.
+ */
+export function fromException(e) {
+    if (e instanceof Error) {
+        return err('UNKNOWN_ERROR', e.message, { details: { stack: e.stack } });
+    }
+    return err('UNKNOWN_ERROR', 'An unknown error occurred', { details: e });
+}
+//# sourceMappingURL=errors.js.map

package/dist/lib/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"AAQA,MAAM,UAAU,GAAG,CACjB,IAAmB,EACnB,OAAe,EACf,OAA8C;IAE9C,MAAM,KAAK,GAAc,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAC3C,IAAI,OAAO,EAAE,IAAI,KAAK,SAAS;QAAE,KAAK,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAC3D,IAAI,OAAO,EAAE,OAAO,KAAK,SAAS;QAAE,KAAK,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IACpE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AAC9B,CAAC;AAED,MAAM,UAAU,EAAE,CAAI,IAAO,EAAE,QAAmB;IAChD,MAAM,QAAQ,GAAoB,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IACrD,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC;QAAE,QAAQ,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAClE,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,CAAU;IACtC,IAAI,CAAC,YAAY,KAAK,EAAE,CAAC;QACvB,OAAO,GAAG,CAAC,eAAe,EAAE,CAAC,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC1E,CAAC;IACD,OAAO,GAAG,CAAC,eAAe,EAAE,2BAA2B,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC;AAC3E,CAAC"}

package/dist/lib/logger.d.ts

@@ -0,0 +1,10 @@
+type Level = 'debug' | 'info' | 'warn' | 'error';
+export declare function initLogger(file: string, level: Level): void;
+export declare const logger: {
+    debug: (msg: string, ctx?: Record<string, unknown>) => void;
+    info: (msg: string, ctx?: Record<string, unknown>) => void;
+    warn: (msg: string, ctx?: Record<string, unknown>) => void;
+    error: (msg: string, ctx?: Record<string, unknown>) => void;
+};
+export {};
+//# sourceMappingURL=logger.d.ts.map

package/dist/lib/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/lib/logger.ts"],"names":[],"mappings":"AAWA,KAAK,KAAK,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAiBjD,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CAE3D;AAsBD,eAAO,MAAM,MAAM;iBACJ,MAAM,QAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,IAAI;gBAG7C,MAAM,QAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,IAAI;gBAG5C,MAAM,QAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,IAAI;iBAG3C,MAAM,QAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,IAAI;CAG1D,CAAC"}

package/dist/lib/logger.js

@@ -0,0 +1,57 @@
+/**
+ * File-only logger.
+ *
+ * Stdout is reserved for MCP protocol traffic — writing anywhere else
+ * would corrupt the JSON-RPC stream. This logger appends to a file with
+ * level filtering, and never touches stdout.
+ *
+ * Usage: `logger.info('message', { context })`
+ */
+import { appendFileSync } from 'node:fs';
+const LEVEL_PRIORITY = {
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40,
+};
+// Lazy-initialized so config can be loaded first.
+let state;
+export function initLogger(file, level) {
+    state = { file, minLevel: level };
+}
+function write(level, msg, ctx) {
+    // Pre-init logs are silently dropped. Only the entry point should produce
+    // logs before initLogger runs, and that's a tiny window.
+    if (!state)
+        return;
+    if (LEVEL_PRIORITY[level] < LEVEL_PRIORITY[state.minLevel])
+        return;
+    const entry = {
+        ts: new Date().toISOString(),
+        level,
+        msg,
+        ...(ctx ? { ctx } : {}),
+    };
+    try {
+        appendFileSync(state.file, `${JSON.stringify(entry)}\n`, 'utf8');
+    }
+    catch {
+        // Logging must never throw. If the log file is unreachable, drop the
+        // line silently — better than crashing the server.
+    }
+}
+export const logger = {
+    debug: (msg, ctx) => {
+        write('debug', msg, ctx);
+    },
+    info: (msg, ctx) => {
+        write('info', msg, ctx);
+    },
+    warn: (msg, ctx) => {
+        write('warn', msg, ctx);
+    },
+    error: (msg, ctx) => {
+        write('error', msg, ctx);
+    },
+};
+//# sourceMappingURL=logger.js.map

package/dist/lib/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/lib/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAIzC,MAAM,cAAc,GAA0B;IAC5C,KAAK,EAAE,EAAE;IACT,IAAI,EAAE,EAAE;IACR,IAAI,EAAE,EAAE;IACR,KAAK,EAAE,EAAE;CACV,CAAC;AAOF,kDAAkD;AAClD,IAAI,KAA8B,CAAC;AAEnC,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,KAAY;IACnD,KAAK,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;AACpC,CAAC;AAED,SAAS,KAAK,CAAC,KAAY,EAAE,GAAW,EAAE,GAA6B;IACrE,0EAA0E;IAC1E,yDAAyD;IACzD,IAAI,CAAC,KAAK;QAAE,OAAO;IACnB,IAAI,cAAc,CAAC,KAAK,CAAC,GAAG,cAAc,CAAC,KAAK,CAAC,QAAQ,CAAC;QAAE,OAAO;IAEnE,MAAM,KAAK,GAAG;QACZ,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QAC5B,KAAK;QACL,GAAG;QACH,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACxB,CAAC;IACF,IAAI,CAAC;QACH,cAAc,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACnE,CAAC;IAAC,MAAM,CAAC;QACP,qEAAqE;QACrE,mDAAmD;IACrD,CAAC;AACH,CAAC;AAED,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,KAAK,EAAE,CAAC,GAAW,EAAE,GAA6B,EAAQ,EAAE;QAC1D,KAAK,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IAC3B,CAAC;IACD,IAAI,EAAE,CAAC,GAAW,EAAE,GAA6B,EAAQ,EAAE;QACzD,KAAK,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IAC1B,CAAC;IACD,IAAI,EAAE,CAAC,GAAW,EAAE,GAA6B,EAAQ,EAAE;QACzD,KAAK,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IAC1B,CAAC;IACD,KAAK,EAAE,CAAC,GAAW,EAAE,GAA6B,EAAQ,EAAE;QAC1D,KAAK,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IAC3B,CAAC;CACF,CAAC"}

package/dist/lib/opa-cli.d.ts

@@ -0,0 +1,226 @@
+import type { Config } from '../config.js';
+import { type SpawnResult } from './subprocess.js';
+/** Input for the formatter. */
+export interface FmtInput {
+    /** Rego source code to format. */
+    source: string;
+}
+/** Input for `opa check`. */
+export interface CheckInput {
+    /** Inline Rego source. Mutually exclusive with `paths`. */
+    source?: string;
+    /** File or directory paths to check. */
+    paths?: string[];
+    /** Path to a capabilities JSON file (restrict allowed builtins). */
+    capabilities?: string;
+    /** Run in strict mode (fail on unused vars, deprecated builtins, etc.). */
+    strict?: boolean;
+    /** Schema directory for input/data validation. */
+    schemaDir?: string;
+}
+/** Input for `opa parse`. */
+export interface ParseInput {
+    /** Rego source to parse. */
+    source: string;
+}
+/** Input for `opa inspect`. */
+export interface InspectInput {
+    /** Path to a bundle archive, directory, or single Rego file. */
+    target: string;
+}
+/** Input for `opa capabilities`. */
+export interface CapabilitiesInput {
+    /** Print the capabilities of the running OPA instead of a named version. */
+    current?: boolean;
+    /** A specific capabilities version (e.g. "v0.50.0"). */
+    version?: string;
+}
+/** Input for `opa deps`. */
+export interface DepsInput {
+    /** Policy/data paths to load before computing dependencies. */
+    paths: string[];
+    /** Reference to compute dependencies for, e.g. "data.example.allow". */
+    ref: string;
+}
+/** Input for `opa eval`. */
+export interface EvalInput {
+    /** The query string, e.g. "data.example.allow" or "x := 1; x > 0". */
+    query: string;
+    /** Inline Rego source. Written to a temp file and added to `--data`. */
+    source?: string;
+    /** Policy / data file or directory paths. */
+    paths?: string[];
+    /** Inline input document. JSON-stringified and piped via `--stdin-input`. */
+    input?: unknown;
+    /** Path to an input JSON file. Mutually exclusive with `input`. */
+    inputPath?: string;
+    /** Add a trace at the requested level. */
+    explain?: 'full' | 'notes' | 'fails' | 'debug';
+    /** Add per-rule timing data. */
+    profile?: boolean;
+    /** Add per-line coverage data. */
+    coverage?: boolean;
+    /** Add evaluation metrics. */
+    metrics?: boolean;
+    /** Add detailed instrumentation. */
+    instrument?: boolean;
+    /** Run partial evaluation. */
+    partial?: boolean;
+    /** Refs treated as unknown during partial evaluation, e.g. ["input.user"]. */
+    unknowns?: string[];
+    /** Treat builtin errors as fatal instead of returning undefined. */
+    strictBuiltinErrors?: boolean;
+    /** Path to a capabilities JSON file. */
+    capabilities?: string;
+    /** Schema directory for input/data validation. */
+    schemaDir?: string;
+}
+/** Input for `opa test`. */
+export interface TestInput {
+    /** Test directories or files. Tests live in `*_test.rego` siblings. */
+    paths: string[];
+    /** Verbose output (per-test pass/fail details). */
+    verbose?: boolean;
+    /** Emit per-line coverage. */
+    coverage?: boolean;
+    /** Run only tests whose names match this regex. */
+    runPattern?: string;
+    /** Bench-style timing alongside test results. */
+    bench?: boolean;
+}
+/** Input for `opa bench`. */
+export interface BenchInput {
+    /** The query to benchmark. */
+    query: string;
+    /** Policy / data paths to load. */
+    paths?: string[];
+    /** Inline input document. JSON-stringified and piped via `--stdin-input`. */
+    input?: unknown;
+    /** Path to an input JSON file. */
+    inputPath?: string;
+    /** Number of benchmark iterations. */
+    count?: number;
+}
+/** Input for `opa build`. */
+export interface BuildInput {
+    /** Policy / data paths to bundle. */
+    paths: string[];
+    /** Output bundle path (typically `*.tar.gz`). */
+    output: string;
+    /** Optimization level (0 = none, 2 = aggressive). */
+    optimize?: 0 | 1 | 2;
+    /** Bundle revision string written to the manifest. */
+    revision?: string;
+    /** Build target (`rego` for source, `wasm` for compiled WASM). */
+    target?: 'rego' | 'wasm';
+    /** Entrypoint refs (required when `target=wasm` or `optimize > 0`). */
+    entrypoints?: string[];
+    /** Path to a signing key for inline signing. */
+    signingKey?: string;
+    /** Signing algorithm (e.g. `RS256`). */
+    signingAlg?: string;
+    /** Path to a claims file for inline signing. */
+    claimsFile?: string;
+    /** Path to a capabilities JSON file. */
+    capabilities?: string;
+}
+/** Input for `opa sign`. */
+export interface SignInput {
+    /** Path to a bundle directory or archive. */
+    bundle: string;
+    /** Path to the signing key. */
+    signingKey: string;
+    /** Signing algorithm (e.g. `RS256`). Defaults to `RS256` in OPA. */
+    signingAlg?: string;
+    /** Path to a claims file (extra signed claims). */
+    claimsFile?: string;
+}
+/**
+ * Wrapper around the local `opa` binary.
+ *
+ * Methods do not throw on `opa` errors — non-zero exit codes are
+ * surfaced on the returned `SpawnResult` so tools can map them to
+ * structured error envelopes at their layer. They DO throw on
+ * caller-side bugs (e.g. an empty `paths` array passed where one is
+ * required), since those represent contract violations.
+ */
+export declare class OpaCli {
+    private readonly config;
+    constructor(config: Config);
+    /**
+     * Verify the binary is present and report its version.
+     * Returns null if the binary is unreachable or output is malformed.
+     */
+    version(): Promise<string | null>;
+    /**
+     * Format Rego source. Stdout contains the formatted output. Reports
+     * `exitCode: 0` even when no changes are needed — callers compare
+     * input vs output to detect a no-op.
+     */
+    fmt(input: FmtInput): Promise<SpawnResult>;
+    /**
+     * Type-check Rego. Returns `exitCode: 0` and empty `stdout` when the
+     * policy is valid. On failure, `exitCode` is non-zero and the JSON
+     * error report is written to **stderr** (this is OPA's actual
+     * behavior — tools must read `stderr`, not `stdout`, for `check`
+     * diagnostics). Either inline `source` or one or more `paths` must be
+     * provided.
+     */
+    check(input: CheckInput): Promise<SpawnResult>;
+    /**
+     * Parse Rego source to a JSON AST. Stdout is the AST as JSON.
+     */
+    parse(input: ParseInput): Promise<SpawnResult>;
+    /**
+     * Inspect a bundle, directory, or single Rego file. Returns its
+     * packages, namespaces, manifest, and annotations as JSON on stdout.
+     */
+    inspect(input: InspectInput): Promise<SpawnResult>;
+    /**
+     * Print available capabilities. With `current=true`, prints the
+     * capabilities of the running OPA. With a `version`, prints those of
+     * a specific named version. Without either, lists available named
+     * versions.
+     */
+    capabilities(input?: CapabilitiesInput): Promise<SpawnResult>;
+    /**
+     * Static dependency analysis for a Rego ref. Stdout is JSON with the
+     * `base` and `virtual` document references the ref depends on.
+     */
+    deps(input: DepsInput): Promise<SpawnResult>;
+    /**
+     * Evaluate a query against a policy + input. Stdout is JSON with the
+     * standard `{result: [...]}` shape (plus optional explain, profile,
+     * coverage, and metrics sections).
+     */
+    eval(input: EvalInput): Promise<SpawnResult>;
+    /**
+     * Run Rego unit tests. Stdout is JSON with per-test pass/fail.
+     */
+    test(input: TestInput): Promise<SpawnResult>;
+    /**
+     * Benchmark a query. Stdout is JSON with iteration timing statistics.
+     */
+    bench(input: BenchInput): Promise<SpawnResult>;
+    /** Build a deployable bundle from policy + data paths. */
+    build(input: BuildInput): Promise<SpawnResult>;
+    /**
+     * Sign a bundle. Writes a `.signatures.json` next to the bundle
+     * directory.
+     */
+    sign(input: SignInput): Promise<SpawnResult>;
+    /**
+     * Run `opa` with the given argv and optional stdin. Tools should
+     * prefer the typed methods above, but this exists for the rare cases
+     * the typed surface does not yet cover.
+     */
+    run(args: string[], stdin?: string): Promise<SpawnResult>;
+    /**
+     * Write `source` to a uniquely named `.rego` file in the OS tmp dir,
+     * pass its path to `fn`, and remove it on completion (success or
+     * failure). The path is unique per call so concurrent invocations do
+     * not collide.
+     */
+    private withTempSource;
+}
+//# sourceMappingURL=opa-cli.d.ts.map

package/dist/lib/opa-cli.d.ts.map

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