@arnilo/prism 0.1.6 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [0.2.0] - 2026-08-13
+
+### Changed
+- **Release 0.2.0 (plan 020)** is the first cut of the 0.2.x review-remediation line — fail-closed runtime and sandbox security, closing the three blockers from the 2026-08-12 comprehensive review. API surface **additive-only** vs 0.1.7 (plain compat gate at 0.2.0: 0 breaking deltas; no `--allow-break`), three documented security-motivated behavior tightenings in `docs/migration.md` `0.1.7 → 0.2.0`: (1) **durable-resume input validation** (`resume-validation`, core) — `assertValidAgentRunResume` runs once at the top of `prepareAgentRunResume` before any state claim/checkpoint write/tool execution, covering all four public resume entrypoints; unknown legacy decisions (`"sideways"`), malformed batches, oversized reasons/elicitation, and duplicate approval ids fail closed with stable `ERR_PRISM_DECISION_*` codes, version untouched, zero tool calls; the server parser stays defense in depth. (2) **work-tool environment isolation** (`work-tools-env`, `@arnilo/prism-work-tools`) — `createCliRunner` children no longer inherit ambient host env: fixed base allow-list (PATH/LANG/LC_ALL/TZ + Windows system keys), explicit validated `env`, forced HOME/telemetry controls, late-bound per-identity tokens, 64-name/64-KiB caps (`ERR_PRISM_WORK_ENV`), absolute `binary`/`configDir` required, linear output capture (single final `Buffer.concat`). (3) **explicit sandbox capabilities** (`sandbox-capabilities`, `@arnilo/prism-coding-security`) — `SandboxAdapter.capabilities` (`workspaceCoherent`/`filesystemIsolated`/`networkIsolated`/`processIsolated`/`privilegeIsolated`/`egressRestricted`); omission/malformed metadata resolves all isolation `false`; `SandboxCodingComposition.capabilities` resolved from real wiring + validated adapter metadata; `containmentClaim` retained as `@deprecated` conservative projection (`workspaceCoherent && filesystemIsolated && networkIsolated && processIsolated`); Docker reports only verified controls, native reports filesystem/process/privilege `false`; authorization reads individual capabilities (docs/coding-security.md capability table + docs/host-security.md). New regression surface: `scripts/phase20-security.test.mjs` (public built entrypoints, all three blockers + gate accounting, wired into `security:threat-suites`), packed plain-JS consumer regressions in install-smoke, and the sandbox-browser workflow now records Docker/native capability evidence with a fail-loud 0.2.0 blocker gate (never a passing skip). Release graph stays **50** publishable manifests (root + 49 workspace packages) at exact **0.2.0**; zero new runtime dependency names (dependency fingerprint unchanged). Store compatibility with 0.1.7: **compatible, no migration** (no persisted-shape change). Exit gate green (core + script gates incl. phase20-freeze done-phase, `sdk:ready`, audit 0 moderate, pack dry-run 50/50 twice byte-identical, plain reviewed compat gate at 0.2.0, Docker daemon + native netns protected evidence, evidence in `scripts/phase20-baseline.json`). **Publication remains the operator handoff** (`docs/release-and-install.md` `0.2.0 publish handoff` — signed `v0.2.0` tag + npm OIDC).
+
+## [0.1.7] - 2026-08-12
+
+### Changed
+- **Release 0.1.7 (plan 019)** is the performance-and-DX patch on the frozen 0.1.x line — additive-only vs 0.1.6 (freeze manifest `scripts/phase19-freeze-manifest.json`; every task's diff stayed inside its allowed files, enforced by the phase19 freeze machine; the async `AgUiProjection` item is a verification closeout, not new code). (1) **Prompt-cache telemetry surface** (`cache-telemetry`): dependency-free `createCacheTelemetry()` aggregator in core — host-activated (nothing subscribes by import), consumes `Usage` + `ModelConfig` pairs from the usage `ProviderEvent` or run-ledger records, and reports per-provider/model request counts, aggregate hit rate via the existing `cacheHitRate` math, cache-read/write token totals, and estimated savings via `cacheSavings` when cost metadata exists; bounded cardinality (default cap 256 distinct provider/model keys, overflow collapses into the `CACHE_TELEMETRY_OVERFLOW_KEY` `__overflow__` bucket with an `overflowed` flag, ponytail ceiling named — host-configurable caps or LRU eviction only if a real deployment exceeds it); reports carry token counters/rates only — never prompt content, cache keys, or identity; `record()` is O(1) with validated finite non-negative inputs; no OTel metric emission (demand-gated follow-up). (2) **Model-router selection policies** (`router-selection`): additive `selection` hook on `CreateModelRouterOptions` — `ModelRouterSelectionPolicy` (`name`/`rank`/`observe`); default ordered behavior byte-identical (regression test); reference `createCostLatencySelection` ranks candidates by `ModelCost` (input/output/cacheRead with per-million normalization) then in-memory EMA latency fed from `recordOutcome`'s new optional `latencyMs` (`latencyWeight` 0–1, default 0.5; pure-cost order on cold start); the policy is a permutation-only reorder of already-allowed candidates so it cannot widen allow-list/residency/budget decisions, and any drop/add/duplicate misbehavior fails closed with `ERR_PRISM_MODEL_ROUTER_POLICY`; policy name rides the still-redacted diagnostics; durable latency stats are a demand-gated follow-up requiring a `ModelRouterStateStore` contract change. (3) **Async AgUiProjection closeout** (`async-hooks`): plan 009 Task 15 surface verified with evidence — hooks are typed `Awaitable<T>` (17 hooks), `getMessages` accepts `() => readonly AgUiMessage[] | Promise<...>` so `messagesFromSession` can call async host APIs like `session.entries()`, snapshots are awaited strictly in event order (never `Promise.all`), rejection fails closed per event with sibling hooks still projected, caps apply to awaited values; evidence in `scripts/phase19-baseline.json` `asyncHooks` (`verified: true`, `gapFound: false`). (4) **`prism providers add <name>` scaffold** (`provider-scaffold`): new CLI subcommand (stdlib-only, mirrors `prism init`) scaffolds an OpenAI-compatible provider package into `./<name>` — `package.json` (peer dep `@arnilo/prism`, `sideEffects: false`, publish metadata), `tsconfig.json`, `README.md`, `CHANGELOG.md`, `src/index.ts` (`defineProviderPackage` + `api_key` auth-method registration), `src/provider.ts` (built on `createOpenAICompatibleProvider`), `src/models.ts` (starter `ModelConfig` list), `src/cache.ts` (cache-hint mapping via the shared core helpers), `src/__tests__/provider.test.ts` (offline conformance: stream shape + usage, header ownership, tool-call delta reconstruction, serialized-content coverage, secret-leak redaction), and `docs/providers/<name>.md` stub; flags `--base-url` (http(s) validated), `--env-key` (shell-safe identifier), `--model`, `--force`; npm package-name validation, path-traversal and symlink-escape refusal (nothing can land outside the destination), usage errors exit 2 with nothing written, generated code contains placeholders only — never secrets; scaffold output is host-chosen and never auto-registered into repo workspaces or resolvers; a fixture test proves the generated package typechecks and passes its conformance test offline against the repo build. Release graph stays **50** publishable manifests (root + 49 workspace packages — 14 provider adapters, 9 `prism-*` family/profile, 26 capability incl. `@arnilo/prism-document-reader`) at exact **0.1.7**. Exit gate green (core tests + script gates incl. phase19-freeze done-phase, `sdk:ready`, audit 0 moderate, pack dry-run 50/50 twice byte-identical, plain compat gate at 0.1.7 with 0 breaking deltas then version-literal baseline refresh — no `--allow-break` anywhere, evidence in `scripts/phase19-baseline.json`). Store compatibility with 0.1.6: **compatible, no migration** (additive-only; no persisted-shape change; `docs/migration.md` gains no entries). **Publication remains the operator handoff** (`docs/release-and-install.md` `0.1.7 publish handoff` — signed `v0.1.7` tag + npm OIDC). **CI hardening after the exit gate** (same day): the release `verify` job now runs the sdk:ready legs phase-by-phase (explicit rc per leg so a silent failure still names the failing phase) and uploads `sdk-ready.log` as an artifact on failure; the examples demo test compiles the demos in place with the repo tsc before spawning them, so the spawned children are plain JS instead of loading the amaro type-stripping WASM module (whose large per-process virtual reservation fails with `WebAssembly.Instance(): Out of memory` on memory-constrained CI runners); emitted .js files are removed in a finally block.
+
 ## [0.1.6] - 2026-08-11
 
 ### Changed

package/dist/agent-approval.d.ts

@@ -1,8 +1,17 @@
 import type { StoredAgentRunState } from "./agent-run-state.js";
-import { Agent, AgentRunState, AgentRunStateOptions, DecisionScope, NestedRunOutcome, PendingDecision, RunDecision, StickyDecision, ToolResult } from "./contracts.js";
+import { Agent, AgentRunResume, AgentRunState, AgentRunStateOptions, DecisionScope, NestedRunOutcome, PendingDecision, RunDecision, StickyDecision, ToolResult } from "./contracts.js";
 import type { AgentIdentity } from "./identity.js";
 /** Pending decisions of a suspended state, synthesizing the legacy single-approval shape. */
 export declare function pendingDecisionsOf(state: StoredAgentRunState): readonly PendingDecision[] | undefined;
+/**
+ * Transport-neutral shape validation for the complete `AgentRunResume` input (plan 020 Task 2).
+ * Runs before any checkpoint read/write, agent resolution, subscription, or tool execution so
+ * untyped callers (plain JavaScript, `as any`) cannot make resume fall through to approval or
+ * crash with raw TypeErrors. State-dependent checks (foreign/stale/duplicate ids, scope,
+ * schema, policy) stay in {@link resolveRunDecisions}. Errors never include tool arguments,
+ * elicitation payloads, credentials, or foreign approval details.
+ */
+export declare function assertValidAgentRunResume(resume: AgentRunResume): void;
 interface ResolvedRunDecisions {
     readonly decisionsById: ReadonlyMap<string, RunDecision>;
     readonly stickyDecisions: readonly StickyDecision[];

package/dist/agent-approval.js

@@ -21,6 +21,87 @@ export function pendingDecisionsOf(state) {
     }
     return undefined;
 }
+/**
+ * Transport-neutral shape validation for the complete `AgentRunResume` input (plan 020 Task 2).
+ * Runs before any checkpoint read/write, agent resolution, subscription, or tool execution so
+ * untyped callers (plain JavaScript, `as any`) cannot make resume fall through to approval or
+ * crash with raw TypeErrors. State-dependent checks (foreign/stale/duplicate ids, scope,
+ * schema, policy) stay in {@link resolveRunDecisions}. Errors never include tool arguments,
+ * elicitation payloads, credentials, or foreign approval details.
+ */
+export function assertValidAgentRunResume(resume) {
+    const invalid = (message) => new AgentDecisionError("ERR_PRISM_DECISION_INVALID", message);
+    if (resume === null || typeof resume !== "object" || Array.isArray(resume)) {
+        throw invalid("Resume must be a non-null object");
+    }
+    if (!Number.isSafeInteger(resume.expectedVersion) || resume.expectedVersion <= 0) {
+        throw invalid("Resume expectedVersion must be a positive safe integer");
+    }
+    const hasDecision = resume.decision !== undefined;
+    const hasDecisions = resume.decisions !== undefined;
+    if (hasDecision && hasDecisions)
+        throw invalid("Resume accepts exactly one of decision or decisions");
+    if (!hasDecision && !hasDecisions)
+        throw invalid("Resume requires a decision or decisions");
+    if (hasDecision) {
+        if (resume.decision !== "approve" && resume.decision !== "deny") {
+            throw invalid("Unknown legacy decision");
+        }
+        return;
+    }
+    const decisions = resume.decisions;
+    if (!Array.isArray(decisions))
+        throw invalid("Decision batch must be an array");
+    if (decisions.length === 0)
+        throw invalid("Decision batch must not be empty");
+    if (decisions.length > HARD_MAX_PENDING_DECISIONS) {
+        throw new AgentDecisionError("ERR_PRISM_DECISION_LIMIT", `Decision batch exceeds ${HARD_MAX_PENDING_DECISIONS} entries`);
+    }
+    const seen = new Set();
+    for (const decision of decisions) {
+        if (decision === null || typeof decision !== "object" || Array.isArray(decision)) {
+            throw invalid("Decision batch entries must be objects");
+        }
+        if (typeof decision.approvalId !== "string" || decision.approvalId.length === 0 || decision.approvalId.length > 128) {
+            throw invalid("Decision approvalId must be a bounded non-empty string");
+        }
+        if (seen.has(decision.approvalId)) {
+            throw new AgentDecisionError("ERR_PRISM_DECISION_DUPLICATE", "Duplicate approval decision in batch");
+        }
+        seen.add(decision.approvalId);
+        if (decision.outcome !== "allow_once" &&
+            decision.outcome !== "allow_for_run" &&
+            decision.outcome !== "reject_once" &&
+            decision.outcome !== "reject_for_run") {
+            throw invalid("Unknown approval outcome");
+        }
+        if (decision.reason !== undefined) {
+            if (typeof decision.reason !== "string")
+                throw invalid("Decision reason must be a string");
+            if (Buffer.byteLength(decision.reason, "utf8") > MAX_DECISION_REASON_BYTES) {
+                throw new AgentDecisionError("ERR_PRISM_DECISION_LIMIT", `Decision reason exceeds ${MAX_DECISION_REASON_BYTES} bytes`);
+            }
+        }
+        for (const key of ["modifiedArguments", "elicitation"]) {
+            const payload = decision[key];
+            if (payload === undefined)
+                continue;
+            if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
+                throw invalid(`Decision ${key} must be a JSON object`);
+            }
+            let text;
+            try {
+                text = JSON.stringify(payload);
+            }
+            catch {
+                throw invalid(`Decision ${key} must be a JSON object`);
+            }
+            if (text === undefined || Buffer.byteLength(text, "utf8") > MAX_ELICITATION_BYTES) {
+                throw new AgentDecisionError("ERR_PRISM_DECISION_LIMIT", `Decision ${key} exceeds ${MAX_ELICITATION_BYTES} bytes`);
+            }
+        }
+    }
+}
 /**
  * Validate one decision batch against the suspended state. Fail-closed and atomic: any
  * invalid entry rejects the whole batch before any CAS, leaving state and version untouched.

package/dist/agent-run-lifecycle.js

@@ -1,6 +1,6 @@
 import { agentFingerprint, loadAgentRunState, publicState, saveAgentRunState } from "./agent-run-state.js";
-import { AgentDecisionError, AgentRunStateError } from "./contracts.js";
-import { pendingDecisionsOf, resolveRunDecisions } from "./agent-approval.js";
+import { AgentRunStateError } from "./contracts.js";
+import { assertValidAgentRunResume, pendingDecisionsOf, resolveRunDecisions } from "./agent-approval.js";
 import { RuntimeAgentSession, throwIfAbortedSignal } from "./agent-session.js";
 function assertAgentId(actual, expected) {
     if (expected !== undefined && actual !== expected)
@@ -82,6 +82,10 @@ export async function* resumeAgentRunStream(agent, ref, resume, options) {
 }
 async function prepareAgentRunResume(agent, ref, resume, options, signal) {
     throwIfAbortedSignal(signal);
+    // Plan 020 Task 2: one shared shape assertion before any checkpoint read/write, agent
+    // resolution, subscription, or tool execution. Unknown legacy decisions (e.g. "sideways")
+    // and malformed untyped batches fail closed here instead of falling through to approval.
+    assertValidAgentRunResume(resume);
     const { record, state } = await loadAgentRunState(options.checkpoints, ref, options.ownership);
     if (state.definitionRevision !== options.definitionRevision ||
         state.agentId !== (agent.config.id ?? agent.config.name) ||
@@ -102,9 +106,6 @@ async function prepareAgentRunResume(agent, ref, resume, options, signal) {
     if (options.persistSessionState && options.includeSkillBodies && state.sessionState?.loadedSkillBodies) {
         session.restoreLoadedSkillBodies(state.sessionState.loadedSkillBodies);
     }
-    if (resume.decision !== undefined && resume.decisions !== undefined) {
-        throw new AgentDecisionError("ERR_PRISM_DECISION_INVALID", "Resume accepts exactly one of decision or decisions");
-    }
     const pendingDecisions = pendingDecisionsOf(state);
     // Legacy approve maps to allow-once on every pending decision; legacy deny keeps its
     // terminal-denied behavior. Batch decisions are validated and applied atomically below.
@@ -118,9 +119,6 @@ async function prepareAgentRunResume(agent, ref, resume, options, signal) {
                 signal,
             })
             : undefined;
-    if (resume.decision === undefined && resume.decisions === undefined) {
-        throw new AgentDecisionError("ERR_PRISM_DECISION_INVALID", "Resume requires a decision or decisions");
-    }
     if (resolved && resolved.remaining.length > 0) {
         throwIfAbortedSignal(signal);
         const single = resolved.remaining.length === 1 ? resolved.remaining[0] : undefined;

package/dist/cache-telemetry.d.ts

@@ -0,0 +1,58 @@
+import type { ModelConfig, Usage } from "./contracts-core.js";
+/**
+ * Prompt-cache telemetry surface (0.1.7, plan 019 Task 2).
+ *
+ * Dependency-free aggregator hosts attach to their `usage` `ProviderEvent`
+ * stream (or run-ledger usage records) to get per-provider/model cache
+ * statistics for tuning the `cache_aware` input layout. Explicit activation:
+ * nothing subscribes by import — the host calls `record()`.
+ */
+/** Single provider/model statistics sample. */
+export interface CacheTelemetrySample {
+    readonly provider: string;
+    readonly model: string;
+    readonly requests: number;
+    readonly cacheReadTokens: number;
+    readonly cacheWriteTokens: number;
+    readonly inputTokens: number;
+    /** Cached-input ratio across the sample (`cacheHitRate` math, aggregated). */
+    readonly hitRate?: number;
+    /** Estimated read-token savings via `cacheSavings` math; present only when
+     *  the sample's model carries cost metadata (`ModelCost.input`/`cacheRead`). */
+    readonly estimatedSavings?: number;
+    readonly currency?: string;
+}
+/** Aggregated report. Samples are sorted by provider then model. */
+export interface CacheTelemetryReport {
+    readonly samples: readonly CacheTelemetrySample[];
+    readonly overflowed: boolean;
+    readonly totalRequests: number;
+    readonly totalCacheReadTokens: number;
+    readonly totalCacheWriteTokens: number;
+}
+export interface CacheTelemetryOptions {
+    /** Distinct provider/model keys before excess keys collapse into the
+     *  `__overflow__` bucket. Default {@link DEFAULT_CACHE_TELEMETRY_CAP}. */
+    readonly maxKeys?: number;
+}
+export interface CacheTelemetry {
+    /** Aggregate one usage record attributed to `model` (or an unknown bucket
+     *  when no model is supplied). Rejects non-finite/negative token counts
+     *  with {@link CacheTelemetryError}; validates before mutating. */
+    record(usage: Usage, model?: ModelConfig): void;
+    /** Snapshot of all samples (O(keys)); never throws. */
+    report(): CacheTelemetryReport;
+    /** Clear all samples (host rotation / long-run reset). */
+    reset(): void;
+    /** Number of distinct provider/model keys held (excluding the overflow bucket). */
+    readonly size: number;
+}
+/** Cardinality ceiling: keys beyond this collapse into `__overflow__`. */
+export declare const DEFAULT_CACHE_TELEMETRY_CAP = 256;
+/** Sample bucket key for provider/model keys beyond the cap. */
+export declare const CACHE_TELEMETRY_OVERFLOW_KEY = "__overflow__";
+export declare class CacheTelemetryError extends Error {
+    readonly code = "ERR_PRISM_CACHE_TELEMETRY";
+    constructor(message: string);
+}
+export declare function createCacheTelemetry(options?: CacheTelemetryOptions): CacheTelemetry;

package/dist/cache-telemetry.js

@@ -0,0 +1,102 @@
+import { cacheHitRate, cacheSavings } from "./cache-helpers.js";
+/** Cardinality ceiling: keys beyond this collapse into `__overflow__`. */
+export const DEFAULT_CACHE_TELEMETRY_CAP = 256;
+/** Sample bucket key for provider/model keys beyond the cap. */
+export const CACHE_TELEMETRY_OVERFLOW_KEY = "__overflow__";
+export class CacheTelemetryError extends Error {
+    code = "ERR_PRISM_CACHE_TELEMETRY";
+    constructor(message) {
+        super(message);
+        this.name = "CacheTelemetryError";
+    }
+}
+function validateTokens(name, value) {
+    if (value === undefined)
+        return;
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new CacheTelemetryError(`${name} must be a non-negative safe integer, got ${value}`);
+    }
+}
+function sampleFor(usage, model) {
+    if (model)
+        return { provider: model.provider, model: model.model };
+    // Provider-only aggregation: no model supplied, attribute to the unknown bucket.
+    return { provider: "unknown", model: "unknown" };
+}
+export function createCacheTelemetry(options = {}) {
+    const maxKeys = options.maxKeys ?? DEFAULT_CACHE_TELEMETRY_CAP;
+    if (!Number.isSafeInteger(maxKeys) || maxKeys < 1) {
+        throw new CacheTelemetryError(`maxKeys must be a positive safe integer, got ${options.maxKeys}`);
+    }
+    // ponytail: fixed per-provider/model key cap with a single __overflow__ bucket;
+    // if real deployments exceed it, upgrade to host-configurable caps or LRU eviction.
+    const samples = new Map();
+    let overflow = false;
+    let overflowSample;
+    function bucket(provider, model) {
+        const key = `${provider}\u0000${model}`;
+        let sample = samples.get(key);
+        if (sample)
+            return sample;
+        if (samples.size >= maxKeys) {
+            overflow = true;
+            if (!overflowSample) {
+                overflowSample = {
+                    provider: CACHE_TELEMETRY_OVERFLOW_KEY,
+                    model: CACHE_TELEMETRY_OVERFLOW_KEY,
+                    requests: 0,
+                    cacheReadTokens: 0,
+                    cacheWriteTokens: 0,
+                    inputTokens: 0,
+                };
+            }
+            return overflowSample;
+        }
+        sample = { provider, model, requests: 0, cacheReadTokens: 0, cacheWriteTokens: 0, inputTokens: 0 };
+        samples.set(key, sample);
+        return sample;
+    }
+    return {
+        record(usage, model) {
+            // Validate everything before mutating: a bad record mutates nothing.
+            validateTokens("usage.cacheReadTokens", usage.cacheReadTokens);
+            validateTokens("usage.cacheWriteTokens", usage.cacheWriteTokens);
+            validateTokens("usage.inputTokens", usage.inputTokens);
+            const { provider, model: modelName } = sampleFor(usage, model);
+            const sample = bucket(provider, modelName);
+            sample.requests += 1;
+            sample.cacheReadTokens += usage.cacheReadTokens ?? 0;
+            sample.cacheWriteTokens += usage.cacheWriteTokens ?? 0;
+            sample.inputTokens += usage.inputTokens ?? 0;
+            sample.hitRate = cacheHitRate({
+                cacheReadTokens: sample.cacheReadTokens,
+                inputTokens: sample.inputTokens,
+            });
+            if (model?.cost) {
+                // cacheSavings depends only on read tokens + cost metadata, so the
+                // aggregate equals the sum of per-call savings; feed it the totals
+                // to reuse the exact cache-helpers math rather than reimplementing it.
+                const savings = cacheSavings({ cacheReadTokens: sample.cacheReadTokens }, model);
+                sample.estimatedSavings = savings;
+                sample.currency = model.cost.currency;
+            }
+        },
+        report() {
+            const samplesAll = [...samples.values()].sort((a, b) => a.provider === b.provider ? a.model.localeCompare(b.model) : a.provider.localeCompare(b.provider));
+            const listed = overflowSample ? [...samplesAll, overflowSample] : samplesAll;
+            const totalRequests = listed.reduce((sum, s) => sum + s.requests, 0);
+            const totalCacheReadTokens = listed.reduce((sum, s) => sum + s.cacheReadTokens, 0);
+            const totalCacheWriteTokens = listed.reduce((sum, s) => sum + s.cacheWriteTokens, 0);
+            return { samples: listed, overflowed: overflow, totalRequests, totalCacheReadTokens, totalCacheWriteTokens };
+        },
+        reset() {
+            samples.clear();
+            overflow = false;
+            overflowSample = undefined;
+        },
+        get size() {
+            return samples.size;
+        },
+    };
+}
+//# sourceMappingURL=cache-telemetry.js.map

package/dist/cli-provider-add.d.ts

@@ -0,0 +1,37 @@
+import type { Writable } from "node:stream";
+export declare class ProviderAddUsageError extends Error {
+}
+export interface ProviderAddOptions {
+    /** npm-validated provider/package name; also the target directory name. */
+    readonly name: string;
+    readonly baseUrl: string;
+    /** Shell-safe identifier, e.g. `ACME_API_KEY`. Never a secret value. */
+    readonly envKey: string;
+    readonly model: string;
+    readonly force: boolean;
+    readonly help: boolean;
+}
+export interface ProviderAddRuntime {
+    readonly stdout: Writable;
+    readonly stderr: Writable;
+    /** Override template root (tests). Defaults to package `templates/provider`. */
+    readonly templatesRoot?: string;
+    /** Override package version stamped into the generated package.json. */
+    readonly packageVersion?: string;
+    /** Working directory used to resolve relative destinations. Defaults to process.cwd(). */
+    readonly cwd?: string;
+}
+export interface ProviderAddResult {
+    readonly targetDir: string;
+    readonly writtenFiles: readonly string[];
+    readonly name: string;
+    readonly totalBytes: number;
+}
+export declare function getProviderAddUsage(): string;
+export declare const providerAddUsage: string;
+export declare function parseProviderAddArgs(argv: readonly string[]): ProviderAddOptions;
+export declare function runProviderAddCommand(argv: readonly string[], runtime: ProviderAddRuntime): Promise<number>;
+export declare function createProviderProject(options: ProviderAddOptions, runtime?: ProviderAddRuntime): Promise<ProviderAddResult>;
+export declare function defaultProviderTemplatesRoot(): string;
+/** npm package-name rules plus traversal refusal. Throws `ProviderAddUsageError` on violation. */
+export declare function validateProviderName(name: string): void;

package/dist/cli-provider-add.js

@@ -0,0 +1,293 @@
+import { accessSync, constants as fsConstants } from "node:fs";
+import { access, mkdir, readdir, readFile, realpath, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+export class ProviderAddUsageError extends Error {
+}
+const NPM_NAME_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
+const ENV_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const MAX_NAME_LENGTH = 214;
+const DEFAULT_BASE_URL = "https://api.example.com/v1";
+export function getProviderAddUsage() {
+    return `Usage: prism providers add <name> [options]
+
+Scaffold an OpenAI-compatible provider package (manifest, provider, models, cache
+helpers, conformance test, docs stub) into ./<name>.
+
+Arguments:
+  <name>                       npm-validated package/provider name (lowercase)
+
+Options:
+  --base-url <url>             Default Chat Completions base URL (default: ${DEFAULT_BASE_URL})
+  --env-key <name>             Credential environment-var identifier (default: <NAME>_API_KEY)
+  --model <id>                 Starter model id (default: <name>-large)
+  --force                      Overwrite existing generated files
+  -h, --help                   Show this help
+
+Examples:
+  prism providers add acme --base-url https://api.acme.example/v1 --env-key ACME_API_KEY --model acme-large
+`;
+}
+export const providerAddUsage = getProviderAddUsage();
+export function parseProviderAddArgs(argv) {
+    let name;
+    let baseUrl = DEFAULT_BASE_URL;
+    let envKey;
+    let model;
+    let force = false;
+    let help = false;
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "-h" || arg === "--help") {
+            help = true;
+            continue;
+        }
+        if (arg === "--force") {
+            force = true;
+            continue;
+        }
+        if (arg === "--base-url" || arg === "--env-key" || arg === "--model") {
+            const value = argv[i + 1];
+            if (value === undefined || value.startsWith("-")) {
+                throw new ProviderAddUsageError(`Missing value for ${arg}`);
+            }
+            i += 1;
+            if (arg === "--base-url") {
+                baseUrl = value;
+            }
+            else if (arg === "--env-key") {
+                envKey = value;
+            }
+            else {
+                model = value;
+            }
+            continue;
+        }
+        if (arg.startsWith("-")) {
+            throw new ProviderAddUsageError(`Unknown flag: ${arg}`);
+        }
+        if (name !== undefined) {
+            throw new ProviderAddUsageError(`Unexpected argument: ${arg}`);
+        }
+        name = arg;
+    }
+    if (!help && name === undefined) {
+        throw new ProviderAddUsageError("Missing provider name");
+    }
+    return {
+        name: name ?? "provider",
+        baseUrl,
+        envKey: envKey ?? `${(name ?? "provider").replace(/[^a-z0-9]+/gi, "_").toUpperCase()}_API_KEY`,
+        model: model ?? `${name ?? "provider"}-large`,
+        force,
+        help,
+    };
+}
+export async function runProviderAddCommand(argv, runtime) {
+    let options;
+    try {
+        options = parseProviderAddArgs(argv);
+    }
+    catch (error) {
+        write(runtime.stderr, `${error instanceof Error ? error.message : String(error)}\n${getProviderAddUsage()}`);
+        return 2;
+    }
+    if (options.help) {
+        write(runtime.stdout, getProviderAddUsage());
+        return 0;
+    }
+    try {
+        validateProviderName(options.name);
+        validateBaseUrl(options.baseUrl);
+        if (!ENV_KEY_PATTERN.test(options.envKey)) {
+            throw new ProviderAddUsageError(`Invalid --env-key: ${options.envKey} (must be a shell-safe identifier)`);
+        }
+        const result = await createProviderProject(options, runtime);
+        write(runtime.stdout, [
+            `Scaffolded provider package in ${result.targetDir}`,
+            `  name: ${result.name}`,
+            `  files: ${result.writtenFiles.length}`,
+            `  bytes: ${result.totalBytes}`,
+            "",
+            "Next:",
+            `  cd ${result.name}`,
+            "  npm install",
+            "  npm test",
+            "  Replace the starter model metadata and docs stub with docs-verified values before publishing.",
+            "",
+        ].join("\n"));
+        return 0;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (error instanceof ProviderAddUsageError) {
+            write(runtime.stderr, `${message}\n${getProviderAddUsage()}`);
+            return 2;
+        }
+        write(runtime.stderr, `${message}\n`);
+        return 1;
+    }
+}
+export async function createProviderProject(options, runtime = {
+    stdout: process.stdout,
+    stderr: process.stderr,
+}) {
+    validateProviderName(options.name);
+    const cwd = runtime.cwd ?? process.cwd();
+    const targetDir = resolve(cwd, options.name);
+    const templatesRoot = runtime.templatesRoot ?? defaultProviderTemplatesRoot();
+    const version = runtime.packageVersion ?? (await readPackageVersion());
+    await assertDestinationWritable(targetDir, options.force);
+    const tokens = buildTokens({ ...options, version });
+    const planned = planProviderFiles(templatesRoot, options.name);
+    if (!options.force) {
+        for (const file of planned) {
+            const dest = join(targetDir, file.relativePath);
+            if (await exists(dest)) {
+                throw new ProviderAddUsageError(`Refusing to overwrite existing file: ${file.relativePath} (pass --force to overwrite)`);
+            }
+        }
+    }
+    const writtenFiles = [];
+    let totalBytes = 0;
+    for (const file of planned) {
+        const dest = join(targetDir, file.relativePath);
+        assertPathInside(targetDir, dest);
+        const raw = await readFile(file.sourcePath, "utf8");
+        const content = applyTokens(raw, tokens);
+        await mkdir(dirname(dest), { recursive: true });
+        await assertNoSymlinkEscape(targetDir, dirname(dest));
+        await writeFile(dest, content, "utf8");
+        writtenFiles.push(file.relativePath);
+        totalBytes += Buffer.byteLength(content, "utf8");
+    }
+    return {
+        targetDir,
+        writtenFiles,
+        name: options.name,
+        totalBytes,
+    };
+}
+export function defaultProviderTemplatesRoot() {
+    return join(dirname(fileURLToPath(import.meta.url)), "..", "templates", "provider");
+}
+/** npm package-name rules plus traversal refusal. Throws `ProviderAddUsageError` on violation. */
+export function validateProviderName(name) {
+    if (name.length === 0)
+        throw new ProviderAddUsageError("Missing provider name");
+    if (name.includes("\0"))
+        throw new ProviderAddUsageError("Invalid provider name");
+    if (name.length > MAX_NAME_LENGTH) {
+        throw new ProviderAddUsageError(`Invalid provider name: ${name} (max ${MAX_NAME_LENGTH} chars)`);
+    }
+    if (!NPM_NAME_PATTERN.test(name) || name.includes("..")) {
+        throw new ProviderAddUsageError(`Invalid provider name: ${name} (npm names are lowercase, start with a letter/digit, and contain only letters, digits, -, _, .)`);
+    }
+}
+function validateBaseUrl(baseUrl) {
+    let parsed;
+    try {
+        parsed = new URL(baseUrl);
+    }
+    catch {
+        throw new ProviderAddUsageError(`Invalid --base-url: ${baseUrl} (must be an http(s) URL)`);
+    }
+    if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+        throw new ProviderAddUsageError(`Invalid --base-url: ${baseUrl} (must be an http(s) URL)`);
+    }
+}
+function buildTokens(input) {
+    const pascal = input.name
+        .split(/[^a-z0-9]+/i)
+        .filter(Boolean)
+        .map((part) => part[0].toUpperCase() + part.slice(1))
+        .join("");
+    return {
+        __PROVIDER_ID__: input.name,
+        __PROVIDER_UPPER__: input.name.replace(/[^a-z0-9]+/gi, "_").toUpperCase(),
+        __PROVIDER_PASCAL__: pascal,
+        __PACKAGE_NAME__: input.name,
+        __PRISM_VERSION__: input.version,
+        __BASE_URL__: input.baseUrl.replace(/\/+$/, ""),
+        __ENV_KEY__: input.envKey,
+        __MODEL_ID__: input.model,
+    };
+}
+function planProviderFiles(templatesRoot, name) {
+    const files = [
+        { relativePath: "package.json", sourcePath: join(templatesRoot, "package.json.tmpl") },
+        { relativePath: "tsconfig.json", sourcePath: join(templatesRoot, "tsconfig.json.tmpl") },
+        { relativePath: "README.md", sourcePath: join(templatesRoot, "README.md.tmpl") },
+        { relativePath: "CHANGELOG.md", sourcePath: join(templatesRoot, "CHANGELOG.md.tmpl") },
+        { relativePath: "src/index.ts", sourcePath: join(templatesRoot, "src/index.ts.tmpl") },
+        { relativePath: "src/provider.ts", sourcePath: join(templatesRoot, "src/provider.ts.tmpl") },
+        { relativePath: "src/models.ts", sourcePath: join(templatesRoot, "src/models.ts.tmpl") },
+        { relativePath: "src/cache.ts", sourcePath: join(templatesRoot, "src/cache.ts.tmpl") },
+        { relativePath: "src/__tests__/provider.test.ts", sourcePath: join(templatesRoot, "src/tests/provider.test.ts.tmpl") },
+        { relativePath: `docs/providers/${name}.md`, sourcePath: join(templatesRoot, "docs/providers/NAME.md.tmpl") },
+    ];
+    for (const file of files) {
+        try {
+            accessSync(file.sourcePath, fsConstants.R_OK);
+        }
+        catch {
+            throw new Error(`Missing provider template: ${file.sourcePath}`);
+        }
+    }
+    return files;
+}
+function applyTokens(template, tokens) {
+    let out = template;
+    for (const [token, value] of Object.entries(tokens)) {
+        out = out.split(token).join(value);
+    }
+    if (/__[A-Z0-9_]+__/.test(out)) {
+        const leftover = out.match(/__[A-Z0-9_]+__/g) ?? [];
+        throw new Error(`Unresolved provider template tokens: ${Array.from(new Set(leftover)).join(", ")}`);
+    }
+    return out;
+}
+async function readPackageVersion() {
+    const pkgPath = join(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+    const pkg = JSON.parse(await readFile(pkgPath, "utf8"));
+    if (!pkg.version)
+        throw new Error(`Missing version in ${pkgPath}`);
+    return pkg.version;
+}
+async function assertDestinationWritable(targetDir, force) {
+    if (!(await exists(targetDir))) {
+        await mkdir(targetDir, { recursive: true });
+        return;
+    }
+    const entries = await readdir(targetDir);
+    if (entries.length > 0 && !force) {
+        throw new ProviderAddUsageError(`Destination is not empty: ${targetDir} (pass --force to overwrite generated files)`);
+    }
+}
+function assertPathInside(root, candidate) {
+    const rel = relative(root, candidate);
+    if (rel === "" || (!rel.startsWith("..") && !isAbsolute(rel)))
+        return;
+    throw new ProviderAddUsageError(`Refusing to write outside destination: ${candidate}`);
+}
+/** Refuse writes whose real parent directory escapes the real target (symlinked dirs). */
+async function assertNoSymlinkEscape(targetDir, parentDir) {
+    const realTarget = await realpath(targetDir);
+    const realParent = await realpath(parentDir);
+    if (realParent !== realTarget && !realParent.startsWith(realTarget + sep)) {
+        throw new ProviderAddUsageError(`Refusing to write through a symlinked directory: ${parentDir}`);
+    }
+}
+async function exists(path) {
+    try {
+        await access(path, fsConstants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function write(stream, text) {
+    stream.write(text);
+}
+//# sourceMappingURL=cli-provider-add.js.map