@collage-dam/mcp-server 0.1.0

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

@@ -0,0 +1,13 @@
+export type { ChangeRecord, DryRunPlan, DryRunPreview, DryRunResponse, ExecuteResult, ItemLedgerEntry, PreviewRow, ProgressEvent, RiskFlag, RiskSeverity, } from './types.js';
+export { ChangeRecordSchema, DryRunPreviewSchema, ExecuteResultSchema, ItemLedgerEntrySchema, PreviewRowSchema, ProgressEventSchema, RiskFlagSchema, RiskSeveritySchema, dryRunPlanSchema, } from './types.js';
+export { renderDiff, DEFAULT_MAX_PREVIEW_ROWS } from './diff-renderer.js';
+export type { DiffRow, RenderDiffOptions, RenderDiffResult } from './diff-renderer.js';
+export { buildSummary, computeAggregates, detectOverwriteRisk } from './summary.js';
+export type { BuildSummaryArgs, SummaryResult, DetectOverwriteRiskOptions, OverwriteRiskResult } from './summary.js';
+export { batchExecute, DEFAULT_CHUNK_SIZE, MAX_CHUNK_SIZE, } from './batch-executor.js';
+export type { ApplyFn, ApplyResult, BatchExecuteOptions, BatchExecuteResult, } from './batch-executor.js';
+export { withDryRun } from './with-dry-run.js';
+export type { DryRunHandler, DryRunHandlerInput, PlanResult, WithDryRunConfig, } from './with-dry-run.js';
+export { MutatingTool } from './mutating-tool.js';
+export type { MutatingToolDeps } from './mutating-tool.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/conventions/dry-run/index.ts"],"names":[],"mappings":"AAIA,YAAY,EACV,YAAY,EACZ,UAAU,EACV,aAAa,EACb,cAAc,EACd,aAAa,EACb,eAAe,EACf,UAAU,EACV,aAAa,EACb,QAAQ,EACR,YAAY,GACb,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,gBAAgB,EAChB,mBAAmB,EACnB,cAAc,EACd,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,UAAU,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAC1E,YAAY,EAAE,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEvF,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACpF,YAAY,EAAE,gBAAgB,EAAE,aAAa,EAAE,0BAA0B,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAErH,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,cAAc,GACf,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,OAAO,EACP,WAAW,EACX,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,YAAY,EACV,aAAa,EACb,kBAAkB,EAClB,UAAU,EACV,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC"}

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

@@ -0,0 +1,10 @@
+// ── Dry-Run Framework — Public Barrel ────────────────────────────────
+// Single import surface for downstream tools. Anything not exported here is
+// considered internal and may change without a major version bump.
+export { ChangeRecordSchema, DryRunPreviewSchema, ExecuteResultSchema, ItemLedgerEntrySchema, PreviewRowSchema, ProgressEventSchema, RiskFlagSchema, RiskSeveritySchema, dryRunPlanSchema, } from './types.js';
+export { renderDiff, DEFAULT_MAX_PREVIEW_ROWS } from './diff-renderer.js';
+export { buildSummary, computeAggregates, detectOverwriteRisk } from './summary.js';
+export { batchExecute, DEFAULT_CHUNK_SIZE, MAX_CHUNK_SIZE, } from './batch-executor.js';
+export { withDryRun } from './with-dry-run.js';
+export { MutatingTool } from './mutating-tool.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/conventions/dry-run/index.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,4EAA4E;AAC5E,mEAAmE;AAcnE,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,gBAAgB,EAChB,mBAAmB,EACnB,cAAc,EACd,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,UAAU,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAG1E,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAGpF,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,cAAc,GACf,MAAM,qBAAqB,CAAC;AAQ7B,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAQ/C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/conventions/dry-run/mutating-tool.d.ts

@@ -0,0 +1,64 @@
+import type { EphemeralStateStore } from '../state-store.js';
+import type { ApplyFn } from './batch-executor.js';
+import type { PlanResult, DryRunHandler } from './with-dry-run.js';
+import type { DryRunPlan } from './types.js';
+export interface MutatingToolDeps<TInput> {
+    /** HMAC secret used to sign confirmation tokens. */
+    secret: string;
+    /** Ephemeral plan store (in-memory for stdio, Redis for HTTP). */
+    store: EphemeralStateStore<DryRunPlan<TInput>>;
+}
+/**
+ * Base class for every mutating MCP tool. Concrete subclasses provide the
+ * tool name and implement `plan()` (pure) plus `apply()` (per-item mutator).
+ * The framework guarantees:
+ *   1. No mutation can happen without a fresh, signed confirmation token.
+ *   2. Tokens are single-use (atomic get-and-delete on execute).
+ *   3. Failed items surface as `McpToolError` entries in the result ledger.
+ *
+ * To enforce that NO write code path bypasses the wrapper, this class is the
+ * only public way to construct a mutating handler — the type system makes
+ * `withDryRun()` direct usage discouraged via the `@internal` JSDoc marker
+ * and discouraged-but-not-blocked at the public surface; subclassing is the
+ * canonical pattern.
+ */
+export declare abstract class MutatingTool<TInput, TItemResult = unknown> {
+    protected readonly deps: MutatingToolDeps<TInput>;
+    /** Stable tool identifier (snake_case verb_noun). */
+    abstract readonly name: string;
+    /** Optional batch chunk size override. */
+    protected readonly chunkSize?: number;
+    /** Optional preview row cap override. */
+    protected readonly maxPreviewRows?: number;
+    /** Optional confirmation TTL override. */
+    protected readonly confirmationTtlMs?: number;
+    protected constructor(deps: MutatingToolDeps<TInput>);
+    /**
+     * Pure plan function. Must NOT perform writes. Returns the change list,
+     * optional risk flags, and optional tool-specific aggregates.
+     */
+    protected abstract plan(input: TInput): Promise<PlanResult> | PlanResult;
+    /**
+     * Per-item executor invoked by the batch runner during the execute phase.
+     * Receives a single `ChangeRecord` and returns success or a typed error.
+     */
+    protected abstract apply: ApplyFn<TItemResult>;
+    /**
+     * Build the dry-run-enforced handler. This is the ONLY way to obtain a
+     * callable for a mutating tool — it is final on purpose.
+     */
+    buildHandler(): DryRunHandler<TInput, TItemResult>;
+    /**
+     * Convenience adapter that stamps the response with `schema_version` and
+     * wraps the result in the standard `structuredContent` shape used by every
+     * tool in this server.
+     */
+    buildMcpHandler(): (args: {
+        input: TInput;
+        confirmation_token?: string;
+    }) => Promise<{
+        structuredContent: Record<string, unknown>;
+        isError?: boolean;
+    }>;
+}
+//# sourceMappingURL=mutating-tool.d.ts.map

package/dist/conventions/dry-run/mutating-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutating-tool.d.ts","sourceRoot":"","sources":["../../../src/conventions/dry-run/mutating-tool.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEnE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,MAAM,WAAW,gBAAgB,CAAC,MAAM;IACtC,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,KAAK,EAAE,mBAAmB,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;CAChD;AAED;;;;;;;;;;;;;GAaG;AACH,8BAAsB,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO;IAWxC,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC,MAAM,CAAC;IAVvE,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAE/B,0CAA0C;IAC1C,SAAS,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IACtC,yCAAyC;IACzC,SAAS,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IAC3C,0CAA0C;IAC1C,SAAS,CAAC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE9C,SAAS,aAAgC,IAAI,EAAE,gBAAgB,CAAC,MAAM,CAAC;IAEvE;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,GAAG,UAAU;IAExE;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IAE/C;;;OAGG;IACI,YAAY,IAAI,aAAa,CAAC,MAAM,EAAE,WAAW,CAAC;IAgBzD;;;;OAIG;IACI,eAAe,IAAI,CACxB,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;KAAE,KACjD,OAAO,CAAC;QAAE,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CA0BhF"}

package/dist/conventions/dry-run/mutating-tool.js

@@ -0,0 +1,88 @@
+// ── Abstract MutatingTool Base Class ─────────────────────────────────
+// The single sanctioned path for any tool that performs writes. Subclasses
+// implement `plan()` and `apply()`; the base class is the only thing that
+// constructs a handler, and the only handler it builds routes through
+// `withDryRun`. There is no public escape hatch: the handler factory is
+// `final` (TypeScript enforces this via the abstract methods + private
+// constructor wrapper).
+import { addSchemaVersion } from '../schema-version.js';
+import { withDryRun } from './with-dry-run.js';
+/**
+ * Base class for every mutating MCP tool. Concrete subclasses provide the
+ * tool name and implement `plan()` (pure) plus `apply()` (per-item mutator).
+ * The framework guarantees:
+ *   1. No mutation can happen without a fresh, signed confirmation token.
+ *   2. Tokens are single-use (atomic get-and-delete on execute).
+ *   3. Failed items surface as `McpToolError` entries in the result ledger.
+ *
+ * To enforce that NO write code path bypasses the wrapper, this class is the
+ * only public way to construct a mutating handler — the type system makes
+ * `withDryRun()` direct usage discouraged via the `@internal` JSDoc marker
+ * and discouraged-but-not-blocked at the public surface; subclassing is the
+ * canonical pattern.
+ */
+export class MutatingTool {
+    deps;
+    /** Optional batch chunk size override. */
+    chunkSize;
+    /** Optional preview row cap override. */
+    maxPreviewRows;
+    /** Optional confirmation TTL override. */
+    confirmationTtlMs;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * Build the dry-run-enforced handler. This is the ONLY way to obtain a
+     * callable for a mutating tool — it is final on purpose.
+     */
+    buildHandler() {
+        const config = {
+            tool: this.name,
+            secret: this.deps.secret,
+            store: this.deps.store,
+            plan: (input) => this.plan(input),
+            apply: (change) => this.apply(change),
+        };
+        if (this.chunkSize !== undefined)
+            config.chunkSize = this.chunkSize;
+        if (this.maxPreviewRows !== undefined)
+            config.maxPreviewRows = this.maxPreviewRows;
+        if (this.confirmationTtlMs !== undefined) {
+            config.confirmationTtlMs = this.confirmationTtlMs;
+        }
+        return withDryRun(config);
+    }
+    /**
+     * Convenience adapter that stamps the response with `schema_version` and
+     * wraps the result in the standard `structuredContent` shape used by every
+     * tool in this server.
+     */
+    buildMcpHandler() {
+        const handler = this.buildHandler();
+        return async (args) => {
+            const result = await handler(args);
+            if (!result.ok) {
+                return {
+                    isError: true,
+                    structuredContent: addSchemaVersion({
+                        error: result.error,
+                    }),
+                };
+            }
+            if (result.phase === 'plan') {
+                return {
+                    structuredContent: addSchemaVersion({
+                        ...result.response,
+                    }),
+                };
+            }
+            return {
+                structuredContent: addSchemaVersion({
+                    ...result.response,
+                }),
+            };
+        };
+    }
+}
+//# sourceMappingURL=mutating-tool.js.map

package/dist/conventions/dry-run/mutating-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutating-tool.js","sourceRoot":"","sources":["../../../src/conventions/dry-run/mutating-tool.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,2EAA2E;AAC3E,0EAA0E;AAC1E,sEAAsE;AACtE,wEAAwE;AACxE,uEAAuE;AACvE,wBAAwB;AAExB,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAIxD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAU/C;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAgB,YAAY;IAWS;IAPzC,0CAA0C;IACvB,SAAS,CAAU;IACtC,yCAAyC;IACtB,cAAc,CAAU;IAC3C,0CAA0C;IACvB,iBAAiB,CAAU;IAE9C,YAAyC,IAA8B;QAA9B,SAAI,GAAJ,IAAI,CAA0B;IAAG,CAAC;IAc3E;;;OAGG;IACI,YAAY;QACjB,MAAM,MAAM,GAA0D;YACpE,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM;YACxB,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK;YACtB,IAAI,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC;YACjC,KAAK,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;SACtC,CAAC;QACF,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS;YAAE,MAAM,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QACpE,IAAI,IAAI,CAAC,cAAc,KAAK,SAAS;YAAE,MAAM,CAAC,cAAc,GAAG,IAAI,CAAC,cAAc,CAAC;QACnF,IAAI,IAAI,CAAC,iBAAiB,KAAK,SAAS,EAAE,CAAC;YACzC,MAAM,CAAC,iBAAiB,GAAG,IAAI,CAAC,iBAAiB,CAAC;QACpD,CAAC;QACD,OAAO,UAAU,CAAsB,MAAM,CAAC,CAAC;IACjD,CAAC;IAED;;;;OAIG;IACI,eAAe;QAGpB,MAAM,OAAO,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;QACpC,OAAO,KAAK,EAAE,IAAI,EAAE,EAAE;YACpB,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;YACnC,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;gBACf,OAAO;oBACL,OAAO,EAAE,IAAI;oBACb,iBAAiB,EAAE,gBAAgB,CAAC;wBAClC,KAAK,EAAE,MAAM,CAAC,KAAK;qBACpB,CAAC;iBACH,CAAC;YACJ,CAAC;YACD,IAAI,MAAM,CAAC,KAAK,KAAK,MAAM,EAAE,CAAC;gBAC5B,OAAO;oBACL,iBAAiB,EAAE,gBAAgB,CAAC;wBAClC,GAAG,MAAM,CAAC,QAAQ;qBACnB,CAAC;iBACH,CAAC;YACJ,CAAC;YACD,OAAO;gBACL,iBAAiB,EAAE,gBAAgB,CAAC;oBAClC,GAAG,MAAM,CAAC,QAAQ;iBACnB,CAAC;aACH,CAAC;QACJ,CAAC,CAAC;IACJ,CAAC;CACF"}

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

@@ -0,0 +1,66 @@
+import type { ChangeRecord, RiskFlag, RiskSeverity } from './types.js';
+export interface BuildSummaryArgs {
+    tool: string;
+    changes: ChangeRecord[];
+    riskFlags: ReadonlyArray<RiskFlag>;
+    aggregates: Record<string, number>;
+}
+export interface SummaryResult {
+    summary: string;
+    aggregates: Record<string, number>;
+}
+/**
+ * Compute aggregate counts from a change list. Always returns the keys
+ * `total`, `creates`, `updates`, `deletes` so callers get a stable shape.
+ * Tool-specific aggregates can be merged on top via `extra`.
+ */
+export declare function computeAggregates(changes: ChangeRecord[], extra?: Record<string, number>): Record<string, number>;
+/**
+ * Build the deterministic summary string. Format:
+ *
+ *   `<tool>: will <verb> N records (C creates, U updates, D deletes). [risk: ...]`
+ */
+export declare function buildSummary(args: BuildSummaryArgs): SummaryResult;
+export interface DetectOverwriteRiskOptions {
+    /**
+     * Severity to use for the surfaced flag when overwrites are detected.
+     * Defaults to `'warning'`; tools that consider any overwrite catastrophic
+     * (e.g. `bulk_set_tags`) can pass `'critical'`.
+     */
+    severity?: RiskSeverity;
+    /** Override flag code. Defaults to `'overwrite_existing_values'`. */
+    code?: string;
+    /** Override flag message. The framework appends `(N)` count automatically. */
+    message?: string;
+    /**
+     * Only consider these field names. When omitted, every key on `before`/
+     * `after` is examined. Use this to scope the check to a single field
+     * (e.g. `['tags']`) on a record that carries other side-info.
+     */
+    fields?: ReadonlyArray<string>;
+    /**
+     * Predicate used to decide whether a value qualifies as "existing" (and
+     * therefore overwriteable). Defaults to: not `null`, not `undefined`, and
+     * not the empty string. Override for richer types (e.g. arrays).
+     */
+    isExistingValue?: (value: unknown) => boolean;
+}
+export interface OverwriteRiskResult {
+    /** Number of distinct change records where at least one field is being overwritten. */
+    records: number;
+    /** Total number of (record, field) pairs being overwritten. */
+    fields: number;
+    /** Risk flag suitable for surfacing on the preview, or null when nothing is at risk. */
+    flag: RiskFlag | null;
+}
+/**
+ * Walk a list of change records and report how many distinct records would
+ * have a non-empty existing value clobbered by the proposed `after` value.
+ *
+ * Deterministic: runs entirely off the plan, no I/O. Designed to be called
+ * from a tool's `plan()` so the resulting flag is included in the preview's
+ * `risk_flags` array via the standard pipeline — no fork of summary.ts
+ * required.
+ */
+export declare function detectOverwriteRisk(changes: ReadonlyArray<ChangeRecord>, opts?: DetectOverwriteRiskOptions): OverwriteRiskResult;
+//# sourceMappingURL=summary.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"summary.d.ts","sourceRoot":"","sources":["../../../src/conventions/dry-run/summary.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEvE,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,SAAS,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;IACnC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpC;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,YAAY,EAAE,EACvB,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GACjC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAgBxB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,gBAAgB,GAAG,aAAa,CAiClE;AA+BD,MAAM,WAAW,0BAA0B;IACzC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC/B;;;;OAIG;IACH,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;CAC/C;AAED,MAAM,WAAW,mBAAmB;IAClC,uFAAuF;IACvF,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;IACf,wFAAwF;IACxF,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAC;CACvB;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,aAAa,CAAC,YAAY,CAAC,EACpC,IAAI,GAAE,0BAA+B,GACpC,mBAAmB,CA4CrB"}

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

@@ -0,0 +1,185 @@
+// ── Deterministic Human Summary Generator ────────────────────────────
+// Renders a fixed-template human-readable summary from plan aggregates and
+// risk flags. Templating is purely string interpolation — no LLM call. The
+// same plan always produces the same summary string.
+//
+// Also exports `detectOverwriteRisk()` — a generic, deterministic walk over
+// change records that surfaces aggregate overwrite-risk flags ("this will
+// overwrite existing values on N assets / M fields") so individual tools
+// don't have to reinvent the analysis. Runs purely on the plan; no I/O.
+/**
+ * Compute aggregate counts from a change list. Always returns the keys
+ * `total`, `creates`, `updates`, `deletes` so callers get a stable shape.
+ * Tool-specific aggregates can be merged on top via `extra`.
+ */
+export function computeAggregates(changes, extra = {}) {
+    let creates = 0;
+    let updates = 0;
+    let deletes = 0;
+    for (const change of changes) {
+        if (change.operation === 'create')
+            creates++;
+        else if (change.operation === 'update')
+            updates++;
+        else if (change.operation === 'delete')
+            deletes++;
+    }
+    return {
+        total: changes.length,
+        creates,
+        updates,
+        deletes,
+        ...extra,
+    };
+}
+/**
+ * Build the deterministic summary string. Format:
+ *
+ *   `<tool>: will <verb> N records (C creates, U updates, D deletes). [risk: ...]`
+ */
+export function buildSummary(args) {
+    const { tool, changes, riskFlags, aggregates } = args;
+    const total = aggregates['total'] ?? changes.length;
+    const creates = aggregates['creates'] ?? 0;
+    const updates = aggregates['updates'] ?? 0;
+    const deletes = aggregates['deletes'] ?? 0;
+    const verb = pickVerb({ creates, updates, deletes });
+    const breakdown = [
+        `${creates} create${creates === 1 ? '' : 's'}`,
+        `${updates} update${updates === 1 ? '' : 's'}`,
+        `${deletes} delete${deletes === 1 ? '' : 's'}`,
+    ].join(', ');
+    const base = `${tool}: will ${verb} ${total} record${total === 1 ? '' : 's'} (${breakdown}).`;
+    const sortedFlags = [...riskFlags].sort(severityCompare);
+    if (sortedFlags.length === 0) {
+        return { summary: base, aggregates };
+    }
+    const riskSegment = sortedFlags
+        .map((flag) => {
+        const countSuffix = typeof flag.count === 'number' ? ` (${flag.count})` : '';
+        return `[${flag.severity}] ${flag.message}${countSuffix}`;
+    })
+        .join('; ');
+    return {
+        summary: `${base} ${riskSegment}`,
+        aggregates,
+    };
+}
+function pickVerb(args) {
+    const { creates, updates, deletes } = args;
+    const nonZero = [
+        creates > 0 ? 'create' : null,
+        updates > 0 ? 'update' : null,
+        deletes > 0 ? 'delete' : null,
+    ].filter((v) => v !== null);
+    if (nonZero.length === 0)
+        return 'modify';
+    if (nonZero.length === 1) {
+        const [verb] = nonZero;
+        return verb ?? 'modify';
+    }
+    return 'modify';
+}
+const SEVERITY_ORDER = {
+    critical: 0,
+    warning: 1,
+    info: 2,
+};
+function severityCompare(a, b) {
+    const sevDiff = SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity];
+    if (sevDiff !== 0)
+        return sevDiff;
+    return a.code.localeCompare(b.code);
+}
+/**
+ * Walk a list of change records and report how many distinct records would
+ * have a non-empty existing value clobbered by the proposed `after` value.
+ *
+ * Deterministic: runs entirely off the plan, no I/O. Designed to be called
+ * from a tool's `plan()` so the resulting flag is included in the preview's
+ * `risk_flags` array via the standard pipeline — no fork of summary.ts
+ * required.
+ */
+export function detectOverwriteRisk(changes, opts = {}) {
+    const isExisting = opts.isExistingValue ?? defaultIsExistingValue;
+    const fieldFilter = opts.fields !== undefined ? new Set(opts.fields) : null;
+    let records = 0;
+    let fields = 0;
+    for (const change of changes) {
+        if (change.operation !== 'update')
+            continue;
+        const before = change.before ?? {};
+        const after = change.after ?? {};
+        const keys = new Set([...Object.keys(before), ...Object.keys(after)]);
+        let recordHasOverwrite = false;
+        for (const key of keys) {
+            if (fieldFilter !== null && !fieldFilter.has(key))
+                continue;
+            const beforeVal = before[key];
+            const afterVal = after[key];
+            if (!isExisting(beforeVal))
+                continue;
+            if (deepEqualValue(beforeVal, afterVal))
+                continue;
+            // For the "overwrite" semantic, we only count when the after value
+            // is materially different and the before value was non-empty.
+            fields++;
+            recordHasOverwrite = true;
+        }
+        if (recordHasOverwrite)
+            records++;
+    }
+    if (records === 0) {
+        return { records: 0, fields: 0, flag: null };
+    }
+    const severity = opts.severity ?? 'warning';
+    const code = opts.code ?? 'overwrite_existing_values';
+    const message = opts.message ??
+        `will overwrite existing values on ${records} asset${records === 1 ? '' : 's'} (${fields} field${fields === 1 ? '' : 's'})`;
+    return {
+        records,
+        fields,
+        flag: { code, severity, message, count: records },
+    };
+}
+function defaultIsExistingValue(value) {
+    if (value === null || value === undefined)
+        return false;
+    if (typeof value === 'string')
+        return value !== '';
+    if (Array.isArray(value))
+        return value.length > 0;
+    return true;
+}
+function deepEqualValue(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null)
+        return false;
+    if (typeof a !== typeof b)
+        return false;
+    if (Array.isArray(a) && Array.isArray(b)) {
+        if (a.length !== b.length)
+            return false;
+        for (let i = 0; i < a.length; i++) {
+            if (!deepEqualValue(a[i], b[i]))
+                return false;
+        }
+        return true;
+    }
+    if (typeof a === 'object' && typeof b === 'object') {
+        const ao = a;
+        const bo = b;
+        const ak = Object.keys(ao);
+        const bk = Object.keys(bo);
+        if (ak.length !== bk.length)
+            return false;
+        for (const key of ak) {
+            if (!deepEqualValue(ao[key], bo[key]))
+                return false;
+        }
+        return true;
+    }
+    return false;
+}
+//# sourceMappingURL=summary.js.map

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

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