@collage-dam/mcp-server 0.1.0

package/dist/conventions/dry-run/types.js

@@ -0,0 +1,108 @@
+// ── Dry-Run Framework Types ──────────────────────────────────────────
+// Generic types describing the three-phase dry-run pattern used by every
+// mutating tool: plan (pure) → preview (rendered diff) → execute (after
+// explicit confirmation). All structures are JSON-serialisable so they can
+// be persisted in the ephemeral state store (in-memory or Redis) and
+// returned over both stdio and streamable HTTP transports unchanged.
+import { z } from 'zod';
+import { McpToolErrorSchema } from '../errors.js';
+// ── Risk Flags ───────────────────────────────────────────────────────
+/**
+ * Severity classifier for risk flags surfaced in the preview.
+ * `info` is purely informational, `warning` is recoverable, `critical`
+ * indicates the operation will overwrite data or affect many records.
+ */
+export const RiskSeveritySchema = z.enum(['info', 'warning', 'critical']);
+export const RiskFlagSchema = z.object({
+    code: z.string().min(1),
+    severity: RiskSeveritySchema,
+    message: z.string().min(1),
+    count: z.number().int().nonnegative().optional(),
+});
+// ── Per-Item Change Records ──────────────────────────────────────────
+/**
+ * A single proposed change. `before` and `after` are arbitrary JSON
+ * projections of the field(s) that will mutate. `id` is a stable identifier
+ * for the underlying record so the per-item ledger can correlate failures
+ * back to the planned change.
+ */
+export const ChangeRecordSchema = z.object({
+    id: z.string().min(1),
+    operation: z.enum(['create', 'update', 'delete']),
+    before: z.record(z.unknown()).nullable(),
+    after: z.record(z.unknown()).nullable(),
+    /** Tool-specific metadata copied through to the executor. */
+    metadata: z.record(z.unknown()).optional(),
+});
+// ── Plan ─────────────────────────────────────────────────────────────
+/**
+ * The serialisable change-script produced by the `plan` phase. This is the
+ * single artefact that flows through the state store and into the executor.
+ *
+ * Generic over the tool-specific input shape so consumers can recover the
+ * original arguments at execute time without re-deriving them.
+ */
+export const dryRunPlanSchema = (inputSchema) => z.object({
+    tool: z.string().min(1),
+    input: inputSchema,
+    changes: z.array(ChangeRecordSchema),
+    risk_flags: z.array(RiskFlagSchema),
+    aggregates: z.record(z.number()),
+    /** ISO timestamp the plan was generated. */
+    generated_at: z.string().datetime(),
+});
+// ── Preview ──────────────────────────────────────────────────────────
+/**
+ * Tabular row produced by the preview renderer. Cells are stringified for
+ * deterministic display; structured data lives in `DryRunPlan.changes`.
+ */
+export const PreviewRowSchema = z.object({
+    id: z.string(),
+    operation: z.enum(['create', 'update', 'delete']),
+    field: z.string(),
+    before: z.string(),
+    after: z.string(),
+});
+export const DryRunPreviewSchema = z.object({
+    rows: z.array(PreviewRowSchema),
+    /** Column headers in order. */
+    columns: z.array(z.string()),
+    summary: z.string().min(1),
+    risk_flags: z.array(RiskFlagSchema),
+    aggregates: z.record(z.number()),
+    /** True if `rows` was truncated for display. */
+    truncated: z.boolean(),
+    /** Total row count before truncation. */
+    total_rows: z.number().int().nonnegative(),
+});
+// ── Execute Result ───────────────────────────────────────────────────
+export const ItemLedgerEntrySchema = z.object({
+    id: z.string(),
+    operation: z.enum(['create', 'update', 'delete']),
+    ok: z.boolean(),
+    error: McpToolErrorSchema.optional(),
+    /** Optional opaque result payload (e.g. updated record id). */
+    result: z.unknown().optional(),
+});
+export const ProgressEventSchema = z.object({
+    type: z.literal('progress'),
+    completed: z.number().int().nonnegative(),
+    total: z.number().int().nonnegative(),
+    /** Wall-clock timestamp for the event. */
+    ts: z.string().datetime(),
+});
+export const ExecuteResultSchema = z.object({
+    tool: z.string().min(1),
+    confirmation_id: z.string().min(1),
+    ledger: z.array(ItemLedgerEntrySchema),
+    totals: z.object({
+        attempted: z.number().int().nonnegative(),
+        succeeded: z.number().int().nonnegative(),
+        failed: z.number().int().nonnegative(),
+    }),
+    /** Rolled-up progress events when streaming is unavailable (HTTP transport). */
+    progress: z.array(ProgressEventSchema),
+    started_at: z.string().datetime(),
+    completed_at: z.string().datetime(),
+});
+//# sourceMappingURL=types.js.map

package/dist/conventions/dry-run/types.js.map

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

package/dist/conventions/dry-run/with-dry-run.d.ts

@@ -0,0 +1,66 @@
+import { type McpToolError } from '../errors.js';
+import type { EphemeralStateStore } from '../state-store.js';
+import { type ApplyFn } from './batch-executor.js';
+import type { ChangeRecord, DryRunPlan, DryRunResponse, ExecuteResult, ProgressEvent, RiskFlag } from './types.js';
+export interface PlanResult {
+    changes: ChangeRecord[];
+    riskFlags?: RiskFlag[];
+    /** Tool-specific aggregate counts merged with framework defaults. */
+    extraAggregates?: Record<string, number>;
+}
+export interface DryRunHandlerInput<TInput> {
+    /** Tool-specific arguments after Zod validation. */
+    input: TInput;
+    /** Optional confirmation token. When supplied, execute phase is invoked. */
+    confirmation_token?: string;
+}
+export interface WithDryRunConfig<TInput, TItemResult = unknown> {
+    /** Stable tool identifier (e.g. `rename_asset`). */
+    tool: string;
+    /** HMAC secret used to sign confirmation tokens. */
+    secret: string;
+    /** Ephemeral store for pending plans (5-min TTL). */
+    store: EphemeralStateStore<DryRunPlan<TInput>>;
+    /** Pure plan function — returns proposed changes without performing them. */
+    plan: (input: TInput) => Promise<PlanResult> | PlanResult;
+    /** Per-item executor invoked once per change in the execute phase. */
+    apply: ApplyFn<TItemResult>;
+    /** Override default batch size (25, capped at 500). */
+    chunkSize?: number;
+    /** Override max rendered preview rows (default 100). */
+    maxPreviewRows?: number;
+    /** Confirmation token TTL in milliseconds (default 5 minutes). */
+    confirmationTtlMs?: number;
+    /** Stream progress events (stdio transport). HTTP transport leaves this off. */
+    onProgress?: (event: ProgressEvent) => void;
+}
+export type DryRunHandler<TInput, TItemResult = unknown> = (args: DryRunHandlerInput<TInput>) => Promise<{
+    ok: true;
+    phase: 'plan';
+    response: DryRunResponse<TInput>;
+} | {
+    ok: true;
+    phase: 'execute';
+    response: ExecuteResult<TItemResult>;
+} | {
+    ok: false;
+    error: McpToolError;
+}>;
+/** Compact summary of a plan included in CONFIRMATION_STATE_DIVERGED errors. */
+export interface PlanSummary {
+    fingerprint: string;
+    changes: number;
+    generated_at: string;
+}
+/**
+ * Build a dry-run-enforced handler from a tool-specific plan/apply pair.
+ *
+ * Behaviour:
+ *  - With no `confirmation_token` → runs `plan`, persists it under a fresh
+ *    HMAC ULID, returns `{ phase: 'plan', response: { plan, preview, ... } }`.
+ *  - With a `confirmation_token` → verifies HMAC, atomically retrieves the
+ *    plan from the store (single-use), and invokes the batch executor.
+ *  - Stale, missing, or replayed tokens return typed `McpToolError`.
+ */
+export declare function withDryRun<TInput, TItemResult = unknown>(config: WithDryRunConfig<TInput, TItemResult>): DryRunHandler<TInput, TItemResult>;
+//# sourceMappingURL=with-dry-run.d.ts.map

package/dist/conventions/dry-run/with-dry-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-dry-run.d.ts","sourceRoot":"","sources":["../../../src/conventions/dry-run/with-dry-run.ts"],"names":[],"mappings":"AAeA,OAAO,EAAmB,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AAElE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAEL,KAAK,OAAO,EAGb,MAAM,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EACV,YAAY,EACZ,UAAU,EAEV,cAAc,EACd,aAAa,EACb,aAAa,EACb,QAAQ,EACT,MAAM,YAAY,CAAC;AAIpB,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC;IACvB,qEAAqE;IACrE,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,kBAAkB,CAAC,MAAM;IACxC,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,gBAAgB,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO;IAC7D,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,KAAK,EAAE,mBAAmB,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;IAC/C,6EAA6E;IAC7E,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,GAAG,UAAU,CAAC;IAC1D,sEAAsE;IACtE,KAAK,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IAC5B,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kEAAkE;IAClE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gFAAgF;IAChF,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;CAC7C;AAED,MAAM,MAAM,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,IAAI,CACzD,IAAI,EAAE,kBAAkB,CAAC,MAAM,CAAC,KAC7B,OAAO,CACR;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,cAAc,CAAC,MAAM,CAAC,CAAA;CAAE,GAC7D;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,aAAa,CAAC,WAAW,CAAC,CAAA;CAAE,GACpE;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,YAAY,CAAA;CAAE,CACrC,CAAC;AAEF,gFAAgF;AAChF,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;CACtB;AAYD;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,EACtD,MAAM,EAAE,gBAAgB,CAAC,MAAM,EAAE,WAAW,CAAC,GAC5C,aAAa,CAAC,MAAM,EAAE,WAAW,CAAC,CAOpC"}

package/dist/conventions/dry-run/with-dry-run.js

@@ -0,0 +1,219 @@
+// ── withDryRun() Higher-Order Wrapper ────────────────────────────────
+// Wraps a mutating tool handler so every invocation is forced through the
+// three phases: plan (pure), preview (rendered diff), execute (only after
+// explicit confirmation token). The wrapper is the only path through which
+// a mutation may reach the upstream API — concrete tools embed their domain
+// logic in the `plan` and `apply` callbacks.
+import { createConfirmationToken, fingerprintChanges, signConfirmation, verifyConfirmation, DEFAULT_TTL_MS, MEMO_TTL_MS, } from '../confirmation.js';
+import { createToolError } from '../errors.js';
+import { logger } from '../logger.js';
+import { batchExecute, DEFAULT_CHUNK_SIZE, } from './batch-executor.js';
+import { renderDiff, DEFAULT_MAX_PREVIEW_ROWS } from './diff-renderer.js';
+import { buildSummary, computeAggregates } from './summary.js';
+function summarisePlan(plan) {
+    return {
+        fingerprint: plan.fingerprint,
+        changes: plan.changes.length,
+        generated_at: plan.generated_at,
+    };
+}
+// ── Wrapper ──────────────────────────────────────────────────────────
+/**
+ * Build a dry-run-enforced handler from a tool-specific plan/apply pair.
+ *
+ * Behaviour:
+ *  - With no `confirmation_token` → runs `plan`, persists it under a fresh
+ *    HMAC ULID, returns `{ phase: 'plan', response: { plan, preview, ... } }`.
+ *  - With a `confirmation_token` → verifies HMAC, atomically retrieves the
+ *    plan from the store (single-use), and invokes the batch executor.
+ *  - Stale, missing, or replayed tokens return typed `McpToolError`.
+ */
+export function withDryRun(config) {
+    return async ({ input, confirmation_token }) => {
+        if (confirmation_token === undefined || confirmation_token === '') {
+            return runPlanPhase(config, input);
+        }
+        return runExecutePhase(config, confirmation_token, input);
+    };
+}
+// ── Plan Phase ───────────────────────────────────────────────────────
+async function runPlanPhase(config, input) {
+    let planResult;
+    try {
+        planResult = await config.plan(input);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            error: createToolError('INTERNAL', `plan() failed: ${message}`),
+        };
+    }
+    const aggregates = computeAggregates(planResult.changes, planResult.extraAggregates ?? {});
+    const riskFlags = planResult.riskFlags ?? [];
+    // Soft TTL on the token (visible to the caller in `expires_at`); long
+    // memo TTL on the plan record so an expired-token execute can recover
+    // the prior fingerprint and auto-refresh.
+    const tokenTtlMs = config.confirmationTtlMs ?? DEFAULT_TTL_MS;
+    const token = createConfirmationToken(config.secret, tokenTtlMs);
+    const plan = {
+        tool: config.tool,
+        input,
+        changes: planResult.changes,
+        risk_flags: riskFlags,
+        aggregates,
+        generated_at: new Date().toISOString(),
+        fingerprint: fingerprintChanges(planResult.changes),
+        token_expires_at: token.expires_at,
+    };
+    const diff = renderDiff(plan.changes, {
+        maxRows: config.maxPreviewRows ?? DEFAULT_MAX_PREVIEW_ROWS,
+    });
+    const { summary } = buildSummary({
+        tool: config.tool,
+        changes: plan.changes,
+        riskFlags,
+        aggregates,
+    });
+    const preview = {
+        rows: diff.rows,
+        columns: diff.columns,
+        summary,
+        risk_flags: riskFlags,
+        aggregates,
+        truncated: diff.truncated,
+        total_rows: diff.total_rows,
+    };
+    await config.store.set(token.confirmation_id, plan, MEMO_TTL_MS);
+    return {
+        ok: true,
+        phase: 'plan',
+        response: {
+            dry_run: true,
+            plan,
+            preview,
+            confirmation: token,
+        },
+    };
+}
+// ── Execute Phase ────────────────────────────────────────────────────
+async function runExecutePhase(config, signedToken, input) {
+    const { valid, confirmationId } = verifyConfirmation(signedToken, config.secret);
+    if (!valid || confirmationId === null) {
+        return {
+            ok: false,
+            error: createToolError('CONFIRMATION_MISSING', 'Confirmation token is invalid or could not be verified.'),
+        };
+    }
+    // Atomically pop the plan from the memo store. If absent, the memo TTL
+    // (1h by default) has elapsed — true hard expiry.
+    const priorPlan = await config.store.getAndDelete(confirmationId);
+    if (priorPlan === undefined) {
+        return {
+            ok: false,
+            error: createToolError('CONFIRMATION_STALE', 'Confirmation token is expired or has already been used.'),
+        };
+    }
+    if (priorPlan.tool !== config.tool) {
+        // Cross-tool token reuse — possible only if state stores are shared.
+        return {
+            ok: false,
+            error: createToolError('CONFIRMATION_STALE', `Confirmation token belongs to tool '${priorPlan.tool}', not '${config.tool}'.`),
+        };
+    }
+    // Soft expiry check: if the token's `expires_at` has passed, run the
+    // auto-refresh path before consuming the plan. Re-plan from the user's
+    // input, fingerprint the result, and compare against the prior
+    // fingerprint. Match → continue with the prior plan (intent unchanged).
+    // Mismatch → return CONFIRMATION_STATE_DIVERGED so the user can re-confirm.
+    let plan = priorPlan;
+    const nowMs = Date.now();
+    const softExpiryMs = Date.parse(priorPlan.token_expires_at);
+    if (Number.isFinite(softExpiryMs) && nowMs > softExpiryMs) {
+        let refreshed;
+        try {
+            refreshed = await config.plan(input);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                ok: false,
+                error: createToolError('INTERNAL', `auto-refresh plan() failed: ${message}`),
+            };
+        }
+        const newFingerprint = fingerprintChanges(refreshed.changes);
+        if (newFingerprint === priorPlan.fingerprint) {
+            const newToken = signConfirmation(confirmationId, config.secret);
+            logger.info({
+                tool: config.tool,
+                confirmation_id: confirmationId,
+                prior_token_id: signedToken.slice(0, 8) + '…',
+                new_token_id: newToken.slice(0, 8) + '…',
+                fingerprint: priorPlan.fingerprint,
+            }, 'dry_run.auto_refresh');
+            // Continue with the prior plan; the user already confirmed it.
+        }
+        else {
+            const newAggregates = computeAggregates(refreshed.changes, refreshed.extraAggregates ?? {});
+            const newPlan = {
+                tool: config.tool,
+                input,
+                changes: refreshed.changes,
+                risk_flags: refreshed.riskFlags ?? [],
+                aggregates: newAggregates,
+                generated_at: new Date().toISOString(),
+                fingerprint: newFingerprint,
+                token_expires_at: priorPlan.token_expires_at,
+            };
+            logger.warn({
+                tool: config.tool,
+                confirmation_id: confirmationId,
+                prior_fingerprint: priorPlan.fingerprint,
+                new_fingerprint: newFingerprint,
+            }, 'dry_run.state_diverged');
+            return {
+                ok: false,
+                error: createToolError('CONFIRMATION_STATE_DIVERGED', `The plan you confirmed no longer matches the current workspace state. Re-run the preview to see what changed.`, {
+                    cause: {
+                        prior_plan: summarisePlan(priorPlan),
+                        new_plan: summarisePlan(newPlan),
+                    },
+                }),
+            };
+        }
+    }
+    const startedAt = new Date().toISOString();
+    let batch;
+    try {
+        const batchOpts = {
+            changes: plan.changes,
+            apply: config.apply,
+            chunkSize: config.chunkSize ?? DEFAULT_CHUNK_SIZE,
+        };
+        if (config.onProgress)
+            batchOpts.onProgress = config.onProgress;
+        batch = await batchExecute(batchOpts);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            error: createToolError('INTERNAL', `batch executor failed: ${message}`),
+        };
+    }
+    const completedAt = new Date().toISOString();
+    return {
+        ok: true,
+        phase: 'execute',
+        response: {
+            tool: config.tool,
+            confirmation_id: confirmationId,
+            ledger: batch.ledger,
+            totals: batch.totals,
+            progress: batch.progress,
+            started_at: startedAt,
+            completed_at: completedAt,
+        },
+    };
+}
+//# sourceMappingURL=with-dry-run.js.map

package/dist/conventions/dry-run/with-dry-run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-dry-run.js","sourceRoot":"","sources":["../../../src/conventions/dry-run/with-dry-run.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,0EAA0E;AAC1E,0EAA0E;AAC1E,2EAA2E;AAC3E,4EAA4E;AAC5E,6CAA6C;AAE7C,OAAO,EACL,uBAAuB,EACvB,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,cAAc,EACd,WAAW,GACZ,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,eAAe,EAAqB,MAAM,cAAc,CAAC;AAClE,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAEtC,OAAO,EACL,YAAY,EAGZ,kBAAkB,GACnB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,UAAU,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AA+D/D,SAAS,aAAa,CAAS,IAAwB;IACrD,OAAO;QACL,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM;QAC5B,YAAY,EAAE,IAAI,CAAC,YAAY;KAChC,CAAC;AACJ,CAAC;AAED,wEAAwE;AAExE;;;;;;;;;GASG;AACH,MAAM,UAAU,UAAU,CACxB,MAA6C;IAE7C,OAAO,KAAK,EAAE,EAAE,KAAK,EAAE,kBAAkB,EAAE,EAAE,EAAE;QAC7C,IAAI,kBAAkB,KAAK,SAAS,IAAI,kBAAkB,KAAK,EAAE,EAAE,CAAC;YAClE,OAAO,YAAY,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QACrC,CAAC;QACD,OAAO,eAAe,CAAC,MAAM,EAAE,kBAAkB,EAAE,KAAK,CAAC,CAAC;IAC5D,CAAC,CAAC;AACJ,CAAC;AAED,wEAAwE;AAExE,KAAK,UAAU,YAAY,CACzB,MAA6C,EAC7C,KAAa;IAKb,IAAI,UAAsB,CAAC;IAC3B,IAAI,CAAC;QACH,UAAU,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACxC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,OAAO;YACL,EAAE,EAAE,KAAK;YACT,KAAK,EAAE,eAAe,CAAC,UAAU,EAAE,kBAAkB,OAAO,EAAE,CAAC;SAChE,CAAC;IACJ,CAAC;IAED,MAAM,UAAU,GAAG,iBAAiB,CAAC,UAAU,CAAC,OAAO,EAAE,UAAU,CAAC,eAAe,IAAI,EAAE,CAAC,CAAC;IAC3F,MAAM,SAAS,GAAG,UAAU,CAAC,SAAS,IAAI,EAAE,CAAC;IAE7C,sEAAsE;IACtE,sEAAsE;IACtE,0CAA0C;IAC1C,MAAM,UAAU,GAAG,MAAM,CAAC,iBAAiB,IAAI,cAAc,CAAC;IAC9D,MAAM,KAAK,GAAG,uBAAuB,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAEjE,MAAM,IAAI,GAAuB;QAC/B,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,KAAK;QACL,OAAO,EAAE,UAAU,CAAC,OAAO;QAC3B,UAAU,EAAE,SAAS;QACrB,UAAU;QACV,YAAY,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACtC,WAAW,EAAE,kBAAkB,CAAC,UAAU,CAAC,OAAO,CAAC;QACnD,gBAAgB,EAAE,KAAK,CAAC,UAAU;KACnC,CAAC;IAEF,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE;QACpC,OAAO,EAAE,MAAM,CAAC,cAAc,IAAI,wBAAwB;KAC3D,CAAC,CAAC;IACH,MAAM,EAAE,OAAO,EAAE,GAAG,YAAY,CAAC;QAC/B,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,SAAS;QACT,UAAU;KACX,CAAC,CAAC;IAEH,MAAM,OAAO,GAAkB;QAC7B,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,OAAO;QACP,UAAU,EAAE,SAAS;QACrB,UAAU;QACV,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,UAAU,EAAE,IAAI,CAAC,UAAU;KAC5B,CAAC;IAEF,MAAM,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,eAAe,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC;IAEjE,OAAO;QACL,EAAE,EAAE,IAAI;QACR,KAAK,EAAE,MAAM;QACb,QAAQ,EAAE;YACR,OAAO,EAAE,IAAI;YACb,IAAI;YACJ,OAAO;YACP,YAAY,EAAE,KAAK;SACpB;KACF,CAAC;AACJ,CAAC;AAED,wEAAwE;AAExE,KAAK,UAAU,eAAe,CAC5B,MAA6C,EAC7C,WAAmB,EACnB,KAAa;IAKb,MAAM,EAAE,KAAK,EAAE,cAAc,EAAE,GAAG,kBAAkB,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IACjF,IAAI,CAAC,KAAK,IAAI,cAAc,KAAK,IAAI,EAAE,CAAC;QACtC,OAAO;YACL,EAAE,EAAE,KAAK;YACT,KAAK,EAAE,eAAe,CACpB,sBAAsB,EACtB,yDAAyD,CAC1D;SACF,CAAC;IACJ,CAAC;IAED,uEAAuE;IACvE,kDAAkD;IAClD,MAAM,SAAS,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC,cAAc,CAAC,CAAC;IAClE,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,OAAO;YACL,EAAE,EAAE,KAAK;YACT,KAAK,EAAE,eAAe,CACpB,oBAAoB,EACpB,yDAAyD,CAC1D;SACF,CAAC;IACJ,CAAC;IAED,IAAI,SAAS,CAAC,IAAI,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC;QACnC,qEAAqE;QACrE,OAAO;YACL,EAAE,EAAE,KAAK;YACT,KAAK,EAAE,eAAe,CACpB,oBAAoB,EACpB,uCAAuC,SAAS,CAAC,IAAI,WAAW,MAAM,CAAC,IAAI,IAAI,CAChF;SACF,CAAC;IACJ,CAAC;IAED,qEAAqE;IACrE,uEAAuE;IACvE,+DAA+D;IAC/D,wEAAwE;IACxE,4EAA4E;IAC5E,IAAI,IAAI,GAAG,SAAS,CAAC;IACrB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACzB,MAAM,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,gBAAgB,CAAC,CAAC;IAC5D,IAAI,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,KAAK,GAAG,YAAY,EAAE,CAAC;QAC1D,IAAI,SAAS,CAAC;QACd,IAAI,CAAC;YACH,SAAS,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACvC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACjE,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,KAAK,EAAE,eAAe,CACpB,UAAU,EACV,+BAA+B,OAAO,EAAE,CACzC;aACF,CAAC;QACJ,CAAC;QACD,MAAM,cAAc,GAAG,kBAAkB,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAC7D,IAAI,cAAc,KAAK,SAAS,CAAC,WAAW,EAAE,CAAC;YAC7C,MAAM,QAAQ,GAAG,gBAAgB,CAAC,cAAc,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;YACjE,MAAM,CAAC,IAAI,CACT;gBACE,IAAI,EAAE,MAAM,CAAC,IAAI;gBACjB,eAAe,EAAE,cAAc;gBAC/B,cAAc,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,GAAG;gBAC7C,YAAY,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,GAAG;gBACxC,WAAW,EAAE,SAAS,CAAC,WAAW;aACnC,EACD,sBAAsB,CACvB,CAAC;YACF,+DAA+D;QACjE,CAAC;aAAM,CAAC;YACN,MAAM,aAAa,GAAG,iBAAiB,CACrC,SAAS,CAAC,OAAO,EACjB,SAAS,CAAC,eAAe,IAAI,EAAE,CAChC,CAAC;YACF,MAAM,OAAO,GAAuB;gBAClC,IAAI,EAAE,MAAM,CAAC,IAAI;gBACjB,KAAK;gBACL,OAAO,EAAE,SAAS,CAAC,OAAO;gBAC1B,UAAU,EAAE,SAAS,CAAC,SAAS,IAAI,EAAE;gBACrC,UAAU,EAAE,aAAa;gBACzB,YAAY,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;gBACtC,WAAW,EAAE,cAAc;gBAC3B,gBAAgB,EAAE,SAAS,CAAC,gBAAgB;aAC7C,CAAC;YACF,MAAM,CAAC,IAAI,CACT;gBACE,IAAI,EAAE,MAAM,CAAC,IAAI;gBACjB,eAAe,EAAE,cAAc;gBAC/B,iBAAiB,EAAE,SAAS,CAAC,WAAW;gBACxC,eAAe,EAAE,cAAc;aAChC,EACD,wBAAwB,CACzB,CAAC;YACF,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,KAAK,EAAE,eAAe,CACpB,6BAA6B,EAC7B,+GAA+G,EAC/G;oBACE,KAAK,EAAE;wBACL,UAAU,EAAE,aAAa,CAAC,SAAS,CAAC;wBACpC,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC;qBACjC;iBACF,CACF;aACF,CAAC;QACJ,CAAC;IACH,CAAC;IAED,MAAM,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC3C,IAAI,KAAsC,CAAC;IAC3C,IAAI,CAAC;QACH,MAAM,SAAS,GAAoD;YACjE,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,SAAS,EAAE,MAAM,CAAC,SAAS,IAAI,kBAAkB;SAClD,CAAC;QACF,IAAI,MAAM,CAAC,UAAU;YAAE,SAAS,CAAC,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC;QAChE,KAAK,GAAG,MAAM,YAAY,CAAc,SAAS,CAAC,CAAC;IACrD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,OAAO;YACL,EAAE,EAAE,KAAK;YACT,KAAK,EAAE,eAAe,CAAC,UAAU,EAAE,0BAA0B,OAAO,EAAE,CAAC;SACxE,CAAC;IACJ,CAAC;IACD,MAAM,WAAW,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAE7C,OAAO;QACL,EAAE,EAAE,IAAI;QACR,KAAK,EAAE,SAAS;QAChB,QAAQ,EAAE;YACR,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,eAAe,EAAE,cAAc;YAC/B,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,UAAU,EAAE,SAAS;YACrB,YAAY,EAAE,WAAW;SAC1B;KACF,CAAC;AACJ,CAAC"}

package/dist/conventions/env.d.ts

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+/**
+ * Read a required environment variable. Throws a descriptive error if the
+ * variable is missing or empty.
+ */
+export declare function getRequiredEnv(name: string): string;
+/**
+ * Read an optional environment variable, returning `defaultValue` when the
+ * variable is missing or empty.
+ */
+export declare function getOptionalEnv(name: string, defaultValue: string): string;
+declare const ConfigSchema: z.ZodObject<{
+    collageApiKey: z.ZodString;
+    collageWorkspaceId: z.ZodString;
+    collageApiUrl: z.ZodString;
+    collageSearchBase: z.ZodString;
+    confirmationSecret: z.ZodString;
+    maxRps: z.ZodNumber;
+    redisUrl: z.ZodOptional<z.ZodString>;
+    logLevel: z.ZodEnum<["debug", "info", "warn", "error"]>;
+}, "strip", z.ZodTypeAny, {
+    collageApiKey: string;
+    collageWorkspaceId: string;
+    collageApiUrl: string;
+    collageSearchBase: string;
+    confirmationSecret: string;
+    maxRps: number;
+    logLevel: "debug" | "info" | "warn" | "error";
+    redisUrl?: string | undefined;
+}, {
+    collageApiKey: string;
+    collageWorkspaceId: string;
+    collageApiUrl: string;
+    collageSearchBase: string;
+    confirmationSecret: string;
+    maxRps: number;
+    logLevel: "debug" | "info" | "warn" | "error";
+    redisUrl?: string | undefined;
+}>;
+export type AppConfig = z.infer<typeof ConfigSchema>;
+/**
+ * Load and validate the full application config from environment variables.
+ *
+ * Secret fields are redacted in `toJSON()` / `toString()` to prevent
+ * accidental leakage in logs or error messages.
+ */
+export declare function loadConfig(): AppConfig;
+export {};
+//# sourceMappingURL=env.d.ts.map

package/dist/conventions/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/conventions/env.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CASnD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAMzE;AAID,QAAA,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;EAShB,CAAC;AAEH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AA4BrD;;;;;GAKG;AACH,wBAAgB,UAAU,IAAI,SAAS,CA2BtC"}

package/dist/conventions/env.js

@@ -0,0 +1,84 @@
+import { z } from 'zod';
+/**
+ * Read a required environment variable. Throws a descriptive error if the
+ * variable is missing or empty.
+ */
+export function getRequiredEnv(name) {
+    const value = process.env[name];
+    if (value === undefined || value === '') {
+        throw new Error(`Missing required environment variable: ${name}. ` +
+            `Set it in your .env file or export it before starting the server.`);
+    }
+    return value;
+}
+/**
+ * Read an optional environment variable, returning `defaultValue` when the
+ * variable is missing or empty.
+ */
+export function getOptionalEnv(name, defaultValue) {
+    const value = process.env[name];
+    if (value === undefined || value === '') {
+        return defaultValue;
+    }
+    return value;
+}
+const LogLevelSchema = z.enum(['debug', 'info', 'warn', 'error']);
+const ConfigSchema = z.object({
+    collageApiKey: z.string().min(1),
+    collageWorkspaceId: z.string().min(1),
+    collageApiUrl: z.string().url(),
+    collageSearchBase: z.string().url(),
+    confirmationSecret: z.string().min(1),
+    maxRps: z.number().int().positive(),
+    redisUrl: z.string().optional(),
+    logLevel: LogLevelSchema,
+});
+/** Fields whose values must never appear in serialised output. */
+const SECRET_FIELDS = new Set([
+    'collageApiKey',
+    'confirmationSecret',
+]);
+/**
+ * Build a config object that redacts secrets from `toJSON()` and
+ * `toString()` so they never leak into logs or error messages.
+ */
+function withRedaction(config) {
+    const redactedJson = {};
+    for (const [key, value] of Object.entries(config)) {
+        redactedJson[key] = SECRET_FIELDS.has(key) ? '[REDACTED]' : value;
+    }
+    return Object.assign(Object.create(null), config, {
+        toJSON() {
+            return { ...redactedJson };
+        },
+        toString() {
+            return JSON.stringify(redactedJson);
+        },
+    });
+}
+/**
+ * Load and validate the full application config from environment variables.
+ *
+ * Secret fields are redacted in `toJSON()` / `toString()` to prevent
+ * accidental leakage in logs or error messages.
+ */
+export function loadConfig() {
+    const raw = {
+        collageApiKey: getRequiredEnv('COLLAGE_API_KEY'),
+        collageWorkspaceId: getRequiredEnv('COLLAGE_WORKSPACE_ID'),
+        collageApiUrl: getOptionalEnv('COLLAGE_API_URL', 'https://damapi.collage.inc/api/v1/'),
+        collageSearchBase: getOptionalEnv('COLLAGE_SEARCH_BASE', 'https://app.collage.inc'),
+        confirmationSecret: getRequiredEnv('MCP_CONFIRMATION_SECRET'),
+        maxRps: Number(getOptionalEnv('COLLAGE_MAX_RPS', '10')),
+        redisUrl: process.env['REDIS_URL'] || undefined,
+        logLevel: getOptionalEnv('LOG_LEVEL', 'info'),
+    };
+    const validated = ConfigSchema.parse(raw);
+    if (validated.confirmationSecret.length < 32) {
+        process.stderr.write('WARN: MCP_CONFIRMATION_SECRET is shorter than 32 characters. ' +
+            'Use at least 32 high-entropy bytes (e.g. `openssl rand -hex 32`) ' +
+            'so HMAC tokens are not feasibly forgeable.\n');
+    }
+    return withRedaction(validated);
+}
+//# sourceMappingURL=env.js.map

package/dist/conventions/env.js.map

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

package/dist/conventions/errors.d.ts

@@ -0,0 +1,68 @@
+import { z } from 'zod';
+export declare const ErrorCodeSchema: z.ZodEnum<["UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION", "RATE_LIMITED", "UPSTREAM", "CONFIRMATION_STALE", "CONFIRMATION_MISSING", "CONFIRMATION_STATE_DIVERGED", "ENTITLEMENT", "INTERNAL"]>;
+export type ErrorCode = z.infer<typeof ErrorCodeSchema>;
+export declare const McpToolErrorCauseSchema: z.ZodObject<{
+    upstream_status: z.ZodOptional<z.ZodNumber>;
+    request_id: z.ZodOptional<z.ZodString>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    upstream_status: z.ZodOptional<z.ZodNumber>;
+    request_id: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    upstream_status: z.ZodOptional<z.ZodNumber>;
+    request_id: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">>;
+export declare const McpToolErrorSchema: z.ZodObject<{
+    code: z.ZodEnum<["UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION", "RATE_LIMITED", "UPSTREAM", "CONFIRMATION_STALE", "CONFIRMATION_MISSING", "CONFIRMATION_STATE_DIVERGED", "ENTITLEMENT", "INTERNAL"]>;
+    message: z.ZodString;
+    retriable: z.ZodBoolean;
+    cause: z.ZodOptional<z.ZodObject<{
+        upstream_status: z.ZodOptional<z.ZodNumber>;
+        request_id: z.ZodOptional<z.ZodString>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        upstream_status: z.ZodOptional<z.ZodNumber>;
+        request_id: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        upstream_status: z.ZodOptional<z.ZodNumber>;
+        request_id: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">>>;
+}, "strip", z.ZodTypeAny, {
+    code: "UNAUTHORIZED" | "FORBIDDEN" | "NOT_FOUND" | "VALIDATION" | "RATE_LIMITED" | "UPSTREAM" | "CONFIRMATION_STALE" | "CONFIRMATION_MISSING" | "CONFIRMATION_STATE_DIVERGED" | "ENTITLEMENT" | "INTERNAL";
+    message: string;
+    retriable: boolean;
+    cause?: z.objectOutputType<{
+        upstream_status: z.ZodOptional<z.ZodNumber>;
+        request_id: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough"> | undefined;
+}, {
+    code: "UNAUTHORIZED" | "FORBIDDEN" | "NOT_FOUND" | "VALIDATION" | "RATE_LIMITED" | "UPSTREAM" | "CONFIRMATION_STALE" | "CONFIRMATION_MISSING" | "CONFIRMATION_STATE_DIVERGED" | "ENTITLEMENT" | "INTERNAL";
+    message: string;
+    retriable: boolean;
+    cause?: z.objectInputType<{
+        upstream_status: z.ZodOptional<z.ZodNumber>;
+        request_id: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough"> | undefined;
+}>;
+export type McpToolError = z.infer<typeof McpToolErrorSchema>;
+/**
+ * Returns whether the given error code is retriable by default.
+ */
+export declare function isRetriable(code: ErrorCode): boolean;
+interface CreateToolErrorOpts {
+    retriable?: boolean;
+    cause?: {
+        upstream_status?: number;
+        request_id?: string;
+        [key: string]: unknown;
+    };
+}
+/**
+ * Create a validated McpToolError.
+ * If `retriable` is not provided, it defaults based on the error code.
+ */
+export declare function createToolError(code: ErrorCode, message: string, opts?: CreateToolErrorOpts): McpToolError;
+/**
+ * Map an HTTP status code to the corresponding McpToolError code.
+ */
+export declare function mapHttpStatusToErrorCode(status: number): ErrorCode;
+export {};
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/conventions/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA4BxB,eAAO,MAAM,eAAe,yMAAsB,CAAC;AACnD,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD,eAAO,MAAM,uBAAuB;;;;;;;;;gCAKpB,CAAC;AAEjB,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAK7B,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAEpD;AAED,UAAU,mBAAmB;IAC3B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE;QACN,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;CACH;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,mBAAmB,GACzB,YAAY,CAQd;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAmBlE"}