@compaction/cli 0.1.4 → 0.3.0

package/dist/core/gateway/apply-policy.js

@@ -0,0 +1,221 @@
+/**
+ * Compaction Gateway DETERMINISTIC APPLY policy (PUBLIC CLI/SDK core — engine-free). Charter run-17.2.
+ *
+ * The FIRST real Compaction apply layer. It is **deterministic only** — NO model call, NO paraphrase, NO
+ * semantic summary, NO LCM. The single policy is `deterministic-dedupe`: within a known-safe text field,
+ * remove EXACT-duplicate LARGE blocks (preserve the first occurrence, never reorder). It fails CLOSED on
+ * any request shape it does not explicitly understand, and it never touches system/developer instructions,
+ * tool schemas, auth/config fields, or short strings.
+ *
+ * This module is PURE (no I/O): it takes the request endpoint + body text and returns a plan describing
+ * whether a safe mutation is possible, the mutated body (only when something actually changed), and a
+ * LOCAL-ESTIMATE model-visible-input reduction. The server decides what to do with the plan.
+ */
+/** The only policy implemented in run-17.2. */
+export const DEDUPE_POLICY = "deterministic-dedupe";
+/** Blocks shorter than this are NEVER dedupe candidates (short strings are never touched). */
+export const DEFAULT_MIN_BLOCK_CHARS = 512;
+/** Chat roles we recognize. An unrecognized role → fail closed (role/order semantics uncertain). */
+const KNOWN_ROLES = new Set(["system", "developer", "user", "assistant", "tool"]);
+/** Only these roles' text is EVER a dedupe candidate. System/developer/assistant/tool are never touched. */
+const DEDUPE_ROLES = new Set(["user"]);
+/** Presence of any of these top-level fields makes the request a more complex shape → fail closed. */
+const COMPLEX_FIELDS = ["tools", "functions", "tool_choice", "function_call", "response_format"];
+/** chars/4 — the repo's local-estimate token convention. NEVER provider-reported. */
+export function estimateTokens(chars) {
+    return Math.round(chars / 4);
+}
+/**
+ * Remove EXACT-duplicate large blocks from a single text field. Blocks are paragraphs split on runs of
+ * 2+ newlines. A block is a candidate only when it is >= `minBlockChars`; the FIRST occurrence is always
+ * kept, later byte-identical occurrences are dropped. Order is never changed; nothing is paraphrased.
+ *
+ * When nothing is removed the ORIGINAL string is returned unchanged (byte-exact). When blocks are removed
+ * the kept blocks are re-joined with a normalized `\n\n` separator (only ever in the mutated path).
+ */
+export function dedupeTextField(text, minBlockChars) {
+    if (typeof text !== "string" || text.length === 0)
+        return { text, removed: 0 };
+    const parts = text.split(/(\n{2,})/); // even indices = blocks, odd = separators
+    const blocks = [];
+    for (let i = 0; i < parts.length; i += 2)
+        blocks.push(parts[i]);
+    const seen = new Set();
+    const kept = [];
+    let removed = 0;
+    for (const block of blocks) {
+        if (block.length >= minBlockChars) {
+            if (seen.has(block)) {
+                removed++;
+                continue; // drop later exact duplicate; first occurrence already kept
+            }
+            seen.add(block);
+        }
+        kept.push(block);
+    }
+    if (removed === 0)
+        return { text, removed: 0 }; // byte-exact: never mutate when nothing to remove
+    return { text: kept.join("\n\n"), removed };
+}
+function failClosed(shape, reason) {
+    return {
+        policy: DEDUPE_POLICY,
+        shape,
+        supported: false,
+        changed: false,
+        failClosedReason: reason,
+        removedBlocks: 0,
+        charsBefore: 0,
+        charsAfter: 0,
+        estTokensBefore: 0,
+        estTokensAfter: 0,
+        reductionPercent: 0
+    };
+}
+/** endpoint family from the request path (e.g. `/v1/responses`, `/responses`). */
+function endpointFamily(endpoint) {
+    const p = endpoint.split("?")[0];
+    if (p.endsWith("/responses"))
+        return "responses";
+    if (p.endsWith("/chat/completions"))
+        return "chat";
+    return "other";
+}
+function reductionPercent(before, after) {
+    if (before <= 0)
+        return 0;
+    return Math.round((1 - after / before) * 1000) / 10;
+}
+/**
+ * Plan a deterministic-dedupe apply for one request. PURE — no I/O. Fails CLOSED (supported:false) on any
+ * shape not explicitly handled: non-JSON, unknown endpoint, multimodal/array content, tool-bearing
+ * requests, unknown roles, or missing safe fields. The caller forwards the ORIGINAL body whenever this
+ * plan is not `changed` (fail-closed or nothing-to-remove both mean byte-identical passthrough).
+ */
+export function planDeterministicDedupe(endpoint, bodyText, opts = {}) {
+    const minBlockChars = opts.minBlockChars ?? DEFAULT_MIN_BLOCK_CHARS;
+    let obj;
+    try {
+        const parsed = JSON.parse(bodyText);
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            return failClosed("unsupported", "request body is not a JSON object");
+        }
+        obj = parsed;
+    }
+    catch {
+        return failClosed("unsupported", "request body is not valid JSON — fail closed (never mutate an unknown shape)");
+    }
+    const family = endpointFamily(endpoint);
+    if (family === "other") {
+        return failClosed("unsupported", `endpoint '${endpoint}' is not a supported apply shape (only /v1/responses and /v1/chat/completions)`);
+    }
+    // Any tool/function schema or structured-output field → a more complex shape we deliberately do not
+    // touch in run-17.2 (never modify tool schemas; fail closed rather than guess).
+    for (const f of COMPLEX_FIELDS) {
+        if (obj[f] !== undefined) {
+            return failClosed(family === "responses" ? "responses-string" : "chat-messages", `request contains '${f}' (tool/function/structured-output shape) — fail closed (never touch tool schemas)`);
+        }
+    }
+    if (family === "responses") {
+        const input = obj.input;
+        if (typeof input !== "string") {
+            return failClosed("unsupported", "responses.input is not a simple string (arrays/multimodal/other shapes fail closed)");
+        }
+        const before = input.length;
+        const { text: newInput, removed } = dedupeTextField(input, minBlockChars);
+        const after = newInput.length;
+        if (removed === 0) {
+            return {
+                policy: DEDUPE_POLICY,
+                shape: "responses-string",
+                supported: true,
+                changed: false,
+                removedBlocks: 0,
+                charsBefore: before,
+                charsAfter: before,
+                estTokensBefore: estimateTokens(before),
+                estTokensAfter: estimateTokens(before),
+                reductionPercent: 0
+            };
+        }
+        const mutated = { ...obj, input: newInput };
+        return {
+            policy: DEDUPE_POLICY,
+            shape: "responses-string",
+            supported: true,
+            changed: true,
+            mutatedBody: JSON.stringify(mutated),
+            removedBlocks: removed,
+            charsBefore: before,
+            charsAfter: after,
+            estTokensBefore: estimateTokens(before),
+            estTokensAfter: estimateTokens(after),
+            reductionPercent: reductionPercent(before, after)
+        };
+    }
+    // family === "chat": messages[].content string, user role only.
+    const messages = obj.messages;
+    if (!Array.isArray(messages) || messages.length === 0) {
+        return failClosed("unsupported", "chat.completions.messages is missing or not a non-empty array");
+    }
+    // Validate EVERY message first — any non-string content or unknown role → fail closed (never guess).
+    for (const m of messages) {
+        if (typeof m !== "object" || m === null || Array.isArray(m)) {
+            return failClosed("chat-messages", "a message is not an object — fail closed");
+        }
+        const role = m.role;
+        const content = m.content;
+        if (typeof role !== "string" || !KNOWN_ROLES.has(role)) {
+            return failClosed("chat-messages", `a message has an unknown/missing role — fail closed (role/order semantics uncertain)`);
+        }
+        if (typeof content !== "string") {
+            // multimodal content array / null / object → fail closed (never touch non-string content)
+            return failClosed("chat-messages", "a message has non-string content (multimodal/array) — fail closed");
+        }
+    }
+    let before = 0;
+    let after = 0;
+    let removedTotal = 0;
+    const newMessages = messages.map((m) => {
+        const msg = m;
+        if (!DEDUPE_ROLES.has(msg.role)) {
+            before += msg.content.length;
+            after += msg.content.length;
+            return m; // system/developer/assistant/tool text is NEVER touched
+        }
+        before += msg.content.length;
+        const { text: newContent, removed } = dedupeTextField(msg.content, minBlockChars);
+        after += newContent.length;
+        removedTotal += removed;
+        return removed === 0 ? m : { ...msg, content: newContent };
+    });
+    if (removedTotal === 0) {
+        return {
+            policy: DEDUPE_POLICY,
+            shape: "chat-messages",
+            supported: true,
+            changed: false,
+            removedBlocks: 0,
+            charsBefore: before,
+            charsAfter: before,
+            estTokensBefore: estimateTokens(before),
+            estTokensAfter: estimateTokens(before),
+            reductionPercent: 0
+        };
+    }
+    const mutated = { ...obj, messages: newMessages };
+    return {
+        policy: DEDUPE_POLICY,
+        shape: "chat-messages",
+        supported: true,
+        changed: true,
+        mutatedBody: JSON.stringify(mutated),
+        removedBlocks: removedTotal,
+        charsBefore: before,
+        charsAfter: after,
+        estTokensBefore: estimateTokens(before),
+        estTokensAfter: estimateTokens(after),
+        reductionPercent: reductionPercent(before, after)
+    };
+}
+//# sourceMappingURL=apply-policy.js.map

package/dist/core/gateway/apply-receipt.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Compaction Gateway APPLY receipt builder (PUBLIC CLI/SDK core — engine-free). Charter run-17.2.
+ *
+ * Builds the content-free before/after receipt for an apply / dry-run pass. It REUSES the record receipt
+ * builder for the provider's after-call usage (provider-reported token/cache axis) and overlays the apply
+ * axis: request_mutated, the LOCAL-ESTIMATE model-visible input before/after, the recovery pointer, and a
+ * fail_closed_reason when nothing was applied. The model-visible-input reduction is claimed ONLY when the
+ * request body was actually changed; otherwise no reduction is asserted. The response is NEVER changed.
+ */
+import { type GatewayReceipt } from "./receipt.js";
+import type { OpenAiUsageBreakdown } from "./openai-usage.js";
+import type { DedupePlan } from "./apply-policy.js";
+import type { ApplyActivation } from "./apply-activation.js";
+export declare const applyLabelMutated: (pct: number) => string;
+export declare const APPLY_LABEL_NOOP = "apply requested but the request was forwarded UNCHANGED (no safe duplicate to remove / fail closed). No model-visible input reduction is claimed.";
+export declare const dryRunLabelCandidate: (pct: number) => string;
+export declare const DRYRUN_LABEL_NONE = "dry-run (deterministic-dedupe): no safe deterministic mutation is available for this request; the original was forwarded unchanged.";
+/**
+ * Build ONE content-free apply/dry-run receipt. `applied` is true only when the body was actually changed
+ * (apply path); dry-run always forwards the original (applied=false, candidate flagged from the plan).
+ */
+export declare function buildApplyReceipt(params: {
+    provider: string;
+    endpoint: string;
+    upstreamStatus: number;
+    usage: OpenAiUsageBreakdown;
+    requestModel?: string;
+    proofRunId?: string;
+    activation: ApplyActivation;
+    plan?: DedupePlan;
+    applied: boolean;
+    recoveryId?: string;
+    failClosedReason?: string;
+    now?: () => string;
+    id?: () => string;
+}): GatewayReceipt;

package/dist/core/gateway/apply-receipt.js

@@ -0,0 +1,75 @@
+/**
+ * Compaction Gateway APPLY receipt builder (PUBLIC CLI/SDK core — engine-free). Charter run-17.2.
+ *
+ * Builds the content-free before/after receipt for an apply / dry-run pass. It REUSES the record receipt
+ * builder for the provider's after-call usage (provider-reported token/cache axis) and overlays the apply
+ * axis: request_mutated, the LOCAL-ESTIMATE model-visible input before/after, the recovery pointer, and a
+ * fail_closed_reason when nothing was applied. The model-visible-input reduction is claimed ONLY when the
+ * request body was actually changed; otherwise no reduction is asserted. The response is NEVER changed.
+ */
+import { buildGatewayReceipt } from "./receipt.js";
+export const applyLabelMutated = (pct) => `apply (deterministic-dedupe): model-visible input reduced by ${pct}% by a deterministic policy (exact-duplicate large blocks removed); the original request is retained locally. No output-token, cost, provider-billing, or semantic-compaction claim.`;
+export const APPLY_LABEL_NOOP = "apply requested but the request was forwarded UNCHANGED (no safe duplicate to remove / fail closed). No model-visible input reduction is claimed.";
+export const dryRunLabelCandidate = (pct) => `dry-run (deterministic-dedupe): a deterministic mutation is AVAILABLE (estimated -${pct}% model-visible input, local-estimate); the ORIGINAL request was forwarded unchanged. No applied-reduction claim is made.`;
+export const DRYRUN_LABEL_NONE = "dry-run (deterministic-dedupe): no safe deterministic mutation is available for this request; the original was forwarded unchanged.";
+/**
+ * Build ONE content-free apply/dry-run receipt. `applied` is true only when the body was actually changed
+ * (apply path); dry-run always forwards the original (applied=false, candidate flagged from the plan).
+ */
+export function buildApplyReceipt(params) {
+    const base = buildGatewayReceipt({
+        provider: params.provider,
+        endpoint: params.endpoint,
+        mode: "apply",
+        upstreamStatus: params.upstreamStatus,
+        usage: params.usage,
+        ...(params.requestModel ? { requestModel: params.requestModel } : {}),
+        ...(params.proofRunId ? { proofRunId: params.proofRunId } : {}),
+        ...(params.now ? { now: params.now } : {}),
+        ...(params.id ? { id: params.id } : {})
+    });
+    const isDryRun = params.activation.mode === "dry-run";
+    const plan = params.plan;
+    const hasEstimate = Boolean(plan && plan.supported);
+    // approval_status: reflects an ACTUAL apply + its explicit source; dry-run is its own label; when nothing
+    // was applied nothing was approved/executed → not-required (the fail_closed_reason carries the detail).
+    let approval = "not-required";
+    if (params.applied)
+        approval = params.activation.activation === "explicit-header" ? "explicit-header" : "explicit-mode";
+    else if (isDryRun)
+        approval = "explicit-dry-run";
+    // apply label — a model-visible reduction is asserted ONLY when the body actually changed.
+    let applyLabel;
+    if (params.applied && plan)
+        applyLabel = applyLabelMutated(plan.reductionPercent);
+    else if (isDryRun)
+        applyLabel = plan?.changed ? dryRunLabelCandidate(plan.reductionPercent) : DRYRUN_LABEL_NONE;
+    else
+        applyLabel = APPLY_LABEL_NOOP;
+    const failReason = params.failClosedReason ?? plan?.failClosedReason;
+    return {
+        ...base,
+        // Override the inherited record label: an apply receipt must NOT claim "forwarded byte-for-byte /
+        // model-visible bytes unchanged" when it actually mutated. The apply label is the honest one here.
+        label: applyLabel,
+        model_visible_bytes_changed: params.applied, // TRUE only when the request body was actually changed
+        approval_status: approval,
+        policy: params.activation.policy ?? plan?.policy ?? "deterministic-dedupe",
+        request_mutated: params.applied,
+        response_mutated: false,
+        ...(isDryRun ? { candidate_available: Boolean(plan?.changed) } : {}),
+        ...(hasEstimate
+            ? {
+                estimated_input_tokens_before: plan.estTokensBefore,
+                estimated_input_tokens_after: params.applied ? plan.estTokensAfter : plan.estTokensBefore,
+                estimated_model_visible_input_reduction_percent: params.applied || isDryRun ? plan.reductionPercent : 0,
+                token_source_before: "local-estimate",
+                token_source_after: base.token_source
+            }
+            : {}),
+        ...(params.recoveryId ? { recovery_id: params.recoveryId } : {}),
+        ...(failReason ? { fail_closed_reason: failReason } : {}),
+        apply_label: applyLabel
+    };
+}
+//# sourceMappingURL=apply-receipt.js.map

package/dist/core/gateway/cache-proof.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Compaction Gateway CACHE PROOF pairing/summary (PUBLIC CLI/SDK code — engine-free). Charter run-16.
+ *
+ * Run-16 is a PROOF run using record mode (NOT cache mode). It pairs two or more content-free gateway
+ * receipts from one manual proof run and surfaces the wedge:
+ *   "Same model-visible bytes, provider-backed cached input tokens, lower fresh/billed input tokens."
+ *
+ * CONTENT-FREE by construction: it operates ONLY on receipts (which already carry counts/labels, never
+ * content). It computes the provider-backed fresh/billed input reduction from the provider's own reported
+ * cached-input accounting. It makes NO cost-savings, NO model-visible input reduction, and NO output-token
+ * reduction claim. When no receipt reports cached tokens → the reduction is UNAVAILABLE (never a zero
+ * "savings"). No proxy-side cache injection happens anywhere here — this only reads receipts.
+ */
+import type { GatewayReceipt } from "./receipt.js";
+import { type FreshBilledInputReduction } from "./receipt.js";
+/** One request's content-free view for the proof table. */
+export interface CacheProofRequest {
+    promptInput?: number;
+    cachedInput?: number;
+    /** Fresh/billed input = prompt - cached (the receipt's billed_fresh_input). */
+    freshInput?: number;
+    output?: number;
+    tokenSource: string;
+    modelVisibleBytesChanged: boolean;
+}
+export interface CacheProofSummary {
+    requests: CacheProofRequest[];
+    /** True only when EVERY paired receipt left model-visible bytes unchanged (record mode always does). */
+    modelVisibleBytesUnchanged: boolean;
+    /** The BEST provider-backed fresh/billed input reduction across the requests, or unavailable. */
+    bestReduction: FreshBilledInputReduction;
+}
+/** Filter receipts to one proof run (by the client-set `proof_run_id`). */
+export declare function receiptsForProofRun(receipts: GatewayReceipt[], proofRunId: string): GatewayReceipt[];
+/**
+ * Summarize a set of receipts into a cache proof. The best reduction is the largest provider-backed
+ * fresh/billed input reduction among the requests (typically the cached request beats the cold one).
+ */
+export declare function summarizeCacheProof(receipts: GatewayReceipt[]): CacheProofSummary;
+/**
+ * Render the content-free proof table (charter run-16 §B). Shows each request's provider-reported
+ * breakdown, then the honest claim line. When cached tokens are absent the reduction line reads
+ * "unavailable" with the reason — NEVER a zero "savings" presented as proof.
+ */
+export declare function formatCacheProof(summary: CacheProofSummary): string;

package/dist/core/gateway/cache-proof.js

@@ -0,0 +1,65 @@
+import { freshBilledInputReduction } from "./receipt.js";
+/** Filter receipts to one proof run (by the client-set `proof_run_id`). */
+export function receiptsForProofRun(receipts, proofRunId) {
+    return receipts.filter((r) => r.proof_run_id === proofRunId);
+}
+/**
+ * Summarize a set of receipts into a cache proof. The best reduction is the largest provider-backed
+ * fresh/billed input reduction among the requests (typically the cached request beats the cold one).
+ */
+export function summarizeCacheProof(receipts) {
+    const requests = receipts.map((r) => ({
+        ...(r.tokens.prompt_input !== undefined ? { promptInput: r.tokens.prompt_input } : {}),
+        ...(r.tokens.cached_input !== undefined ? { cachedInput: r.tokens.cached_input } : {}),
+        ...(r.tokens.billed_fresh_input !== undefined ? { freshInput: r.tokens.billed_fresh_input } : {}),
+        ...(r.tokens.output !== undefined ? { output: r.tokens.output } : {}),
+        tokenSource: r.token_source,
+        modelVisibleBytesChanged: r.model_visible_bytes_changed
+    }));
+    const modelVisibleBytesUnchanged = receipts.length > 0 && receipts.every((r) => r.model_visible_bytes_changed === false);
+    // Best = the highest available fresh/billed reduction across the receipts.
+    let bestReduction = {
+        available: false,
+        note: "no receipt reported provider cached input tokens — fresh/billed input reduction unavailable"
+    };
+    for (const r of receipts) {
+        const red = freshBilledInputReduction({
+            ...(r.tokens.prompt_input !== undefined ? { promptInputTokens: r.tokens.prompt_input } : {}),
+            ...(r.tokens.cached_input !== undefined ? { cachedInputTokens: r.tokens.cached_input } : {})
+        });
+        if (red.available && (!bestReduction.available || (red.pct ?? 0) > (bestReduction.pct ?? 0))) {
+            bestReduction = red;
+        }
+    }
+    return { requests, modelVisibleBytesUnchanged, bestReduction };
+}
+function n(value) {
+    return value === undefined ? "unavailable" : value.toLocaleString("en-US");
+}
+/**
+ * Render the content-free proof table (charter run-16 §B). Shows each request's provider-reported
+ * breakdown, then the honest claim line. When cached tokens are absent the reduction line reads
+ * "unavailable" with the reason — NEVER a zero "savings" presented as proof.
+ */
+export function formatCacheProof(summary) {
+    const lines = ["COMPACTION CACHE PROOF", ""];
+    summary.requests.forEach((req, i) => {
+        lines.push(`request ${i + 1}`);
+        lines.push(`  prompt input tokens   ${n(req.promptInput).padStart(12)}`);
+        lines.push(`  cached input tokens   ${n(req.cachedInput).padStart(12)}`);
+        lines.push(`  fresh input tokens    ${n(req.freshInput).padStart(12)}`);
+        lines.push(`  output tokens         ${n(req.output).padStart(12)}`);
+        lines.push("");
+    });
+    lines.push(summary.modelVisibleBytesUnchanged ? "model-visible bytes unchanged" : "model-visible bytes: (mixed — check receipts)");
+    if (summary.bestReduction.available) {
+        lines.push(`fresh/billed input reduction: -${summary.bestReduction.pct}%`);
+        lines.push("claim: provider-backed cached-input accounting");
+    }
+    else {
+        lines.push("fresh/billed input reduction: unavailable");
+        lines.push("reason: provider did not report cached input tokens");
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=cache-proof.js.map

package/dist/core/gateway/configure.d.ts

@@ -0,0 +1,50 @@
+/** The env var we set to route an OpenAI-compatible client through the gateway. */
+export declare const CONFIGURE_ENV_VAR = "OPENAI_BASE_URL";
+export interface ProjectDetection {
+    /** `.env` / `.env.local` files that exist in the project root. */
+    envFiles: string[];
+    hasPackageJson: boolean;
+    /** True when package.json lists the `openai` SDK as a dependency. */
+    usesOpenAiSdk: boolean;
+    /** An already-configured base URL, if any (OPENAI_BASE_URL or OPENAI_API_BASE), and where. */
+    existingBaseUrl?: {
+        file: string;
+        var: string;
+        value: string;
+    };
+}
+/** Detect the project's OpenAI-config surface WITHOUT modifying anything. */
+export declare function detectProject(cwd: string): ProjectDetection;
+export type ConfigureAction = "create" | "append" | "conflict";
+export interface ConfigurePlan {
+    /** The file (relative) we would write. */
+    targetFile: string;
+    action: ConfigureAction;
+    /** The base URL we would set (already includes /v1). */
+    baseUrl: string;
+    /** Unified-ish diff preview (content-free — env var + gateway URL only). */
+    diff: string;
+    /** Where the `.bak` backup would go, when the target already exists. */
+    backupFile?: string;
+    detection: ProjectDetection;
+    /** Human-readable note about why apply is/should be gated. */
+    note: string;
+}
+/**
+ * Build a configure plan for pointing this project's OpenAI client at `baseUrl` (the gateway `/v1` URL).
+ * Never writes. If a base URL is already configured, the plan action is "conflict" and apply requires force.
+ */
+export declare function planGatewayConfigure(cwd: string, baseUrl: string): ConfigurePlan;
+export interface ApplyResult {
+    wrote: boolean;
+    targetFile: string;
+    backupFile?: string;
+    reason?: string;
+}
+/**
+ * Apply a configure plan: write a `.bak` backup (when the target exists), then create/append the base-URL
+ * line. Refuses a "conflict" plan unless `force` is set. This is the ONLY function here that writes.
+ */
+export declare function applyGatewayConfigure(cwd: string, plan: ConfigurePlan, force?: boolean): ApplyResult;
+/** Render a configure plan as plain content-free lines (for the CLI preview). */
+export declare function formatConfigurePlan(plan: ConfigurePlan): string[];

package/dist/core/gateway/configure.js

@@ -0,0 +1,169 @@
+/**
+ * Gateway project configure (PUBLIC CLI core). Charter run-17.1.
+ *
+ * Approval-gated: this module only ever PLANS a change (detect the project, propose adding an
+ * OPENAI_BASE_URL pointing at the local gateway, and render an exact diff). It writes NOTHING unless the
+ * caller explicitly applies the plan, and even then it creates a `.bak` backup first and refuses to
+ * overwrite an existing provider base URL without an explicit force. No auto-write, ever.
+ */
+import fs from "node:fs";
+import path from "node:path";
+/** The env var we set to route an OpenAI-compatible client through the gateway. */
+export const CONFIGURE_ENV_VAR = "OPENAI_BASE_URL";
+const ENV_CANDIDATES = [".env", ".env.local"];
+const BASE_URL_VARS = ["OPENAI_BASE_URL", "OPENAI_API_BASE"];
+function readIfExists(p) {
+    try {
+        return fs.readFileSync(p, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+/** Find an existing base-URL assignment in a dotenv-style body. Returns the var + value, or null. */
+function findBaseUrlAssignment(body) {
+    for (const line of body.split(/\r?\n/)) {
+        const m = line.match(/^\s*(?:export\s+)?([A-Z0-9_]+)\s*=\s*(.*)\s*$/);
+        if (!m)
+            continue;
+        if (BASE_URL_VARS.includes(m[1])) {
+            return { var: m[1], value: m[2].replace(/^["']|["']$/g, "") };
+        }
+    }
+    return null;
+}
+/** Detect the project's OpenAI-config surface WITHOUT modifying anything. */
+export function detectProject(cwd) {
+    const envFiles = [];
+    let existingBaseUrl;
+    for (const name of ENV_CANDIDATES) {
+        const body = readIfExists(path.join(cwd, name));
+        if (body === null)
+            continue;
+        envFiles.push(name);
+        if (!existingBaseUrl) {
+            const found = findBaseUrlAssignment(body);
+            if (found)
+                existingBaseUrl = { file: name, var: found.var, value: found.value };
+        }
+    }
+    let hasPackageJson = false;
+    let usesOpenAiSdk = false;
+    const pkgBody = readIfExists(path.join(cwd, "package.json"));
+    if (pkgBody !== null) {
+        hasPackageJson = true;
+        try {
+            const pkg = JSON.parse(pkgBody);
+            usesOpenAiSdk = Boolean(pkg.dependencies?.openai || pkg.devDependencies?.openai);
+        }
+        catch {
+            /* malformed package.json — leave usesOpenAiSdk false */
+        }
+    }
+    return { envFiles, hasPackageJson, usesOpenAiSdk, ...(existingBaseUrl ? { existingBaseUrl } : {}) };
+}
+/**
+ * Build a configure plan for pointing this project's OpenAI client at `baseUrl` (the gateway `/v1` URL).
+ * Never writes. If a base URL is already configured, the plan action is "conflict" and apply requires force.
+ */
+export function planGatewayConfigure(cwd, baseUrl) {
+    const detection = detectProject(cwd);
+    const targetFile = detection.envFiles.includes(".env.local")
+        ? ".env.local"
+        : detection.envFiles.includes(".env")
+            ? ".env"
+            : ".env";
+    const targetPath = path.join(cwd, targetFile);
+    const existing = readIfExists(targetPath);
+    const newLine = `${CONFIGURE_ENV_VAR}=${baseUrl}`;
+    let action;
+    let diff;
+    let note;
+    if (detection.existingBaseUrl) {
+        action = "conflict";
+        diff =
+            `- ${detection.existingBaseUrl.var}=${detection.existingBaseUrl.value}   (in ${detection.existingBaseUrl.file})\n` +
+                `+ ${newLine}`;
+        note =
+            `${detection.existingBaseUrl.file} already sets ${detection.existingBaseUrl.var}. ` +
+                "Compaction will NOT overwrite an existing provider base URL without explicit confirmation (--force).";
+    }
+    else if (existing === null) {
+        action = "create";
+        diff = `+ ${newLine}`;
+        note = `${targetFile} does not exist yet. Apply would create it with just the gateway base URL line.`;
+    }
+    else {
+        action = "append";
+        diff = `  (existing ${targetFile} unchanged)\n+ ${newLine}`;
+        note = `Apply would append one line to ${targetFile} (a .bak backup is written first).`;
+    }
+    return {
+        targetFile,
+        action,
+        baseUrl,
+        diff,
+        ...(existing !== null ? { backupFile: `${targetFile}.bak` } : {}),
+        detection,
+        note
+    };
+}
+/**
+ * Apply a configure plan: write a `.bak` backup (when the target exists), then create/append the base-URL
+ * line. Refuses a "conflict" plan unless `force` is set. This is the ONLY function here that writes.
+ */
+export function applyGatewayConfigure(cwd, plan, force = false) {
+    if (plan.action === "conflict" && !force) {
+        return { wrote: false, targetFile: plan.targetFile, reason: "existing provider base URL present; re-run with --force to overwrite" };
+    }
+    const targetPath = path.join(cwd, plan.targetFile);
+    const existing = readIfExists(targetPath);
+    const newLine = `${CONFIGURE_ENV_VAR}=${plan.baseUrl}`;
+    let backupFile;
+    if (existing !== null) {
+        backupFile = `${plan.targetFile}.bak`;
+        fs.writeFileSync(path.join(cwd, backupFile), existing, "utf8");
+    }
+    let next;
+    if (plan.action === "conflict" && existing !== null) {
+        // Replace the existing base-URL assignment line in place.
+        next = existing
+            .split(/\r?\n/)
+            .map((line) => {
+            const m = line.match(/^\s*(?:export\s+)?([A-Z0-9_]+)\s*=/);
+            return m && BASE_URL_VARS.includes(m[1]) ? newLine : line;
+        })
+            .join("\n");
+    }
+    else if (existing !== null) {
+        next = existing.endsWith("\n") ? `${existing}${newLine}\n` : `${existing}\n${newLine}\n`;
+    }
+    else {
+        next = `${newLine}\n`;
+    }
+    fs.writeFileSync(targetPath, next, "utf8");
+    return { wrote: true, targetFile: plan.targetFile, ...(backupFile ? { backupFile } : {}) };
+}
+/** Render a configure plan as plain content-free lines (for the CLI preview). */
+export function formatConfigurePlan(plan) {
+    const lines = [];
+    lines.push("compaction gateway configure — proposed change (nothing is written yet)");
+    lines.push(`  target file:  ${plan.targetFile}   (${plan.action})`);
+    lines.push(`  detected:     ${describeDetection(plan.detection)}`);
+    lines.push("  diff:");
+    for (const d of plan.diff.split("\n"))
+        lines.push(`    ${d}`);
+    lines.push(`  note:         ${plan.note}`);
+    lines.push("");
+    lines.push("  to apply:     compaction gateway configure --apply" + (plan.action === "conflict" ? " --force" : ""));
+    return lines;
+}
+function describeDetection(d) {
+    const bits = [];
+    bits.push(d.envFiles.length ? `env files: ${d.envFiles.join(", ")}` : "no .env files");
+    bits.push(d.hasPackageJson ? (d.usesOpenAiSdk ? "openai SDK in package.json" : "package.json (no openai dep)") : "no package.json");
+    if (d.existingBaseUrl)
+        bits.push(`existing ${d.existingBaseUrl.var} in ${d.existingBaseUrl.file}`);
+    return bits.join("; ");
+}
+//# sourceMappingURL=configure.js.map