@se-studio/contentful-cms 0.0.0-next16-20260822103555

package/dist/telemetry/factory.js

@@ -0,0 +1,44 @@
+import { AxiomTelemetryWriter } from './axiom.js';
+import { CompositeTelemetryWriter } from './composite.js';
+import { isHostedMcpMode } from './enrich.js';
+import { LocalFileTelemetryWriter } from './local.js';
+import { NoOpTelemetryWriter } from './noop.js';
+function isTelemetryExplicitlyDisabled() {
+    const value = process.env['CMS_EDIT_TELEMETRY'];
+    return value === '0' || value === 'false';
+}
+function isTelemetryExplicitlyEnabled() {
+    const value = process.env['CMS_EDIT_TELEMETRY'];
+    return value === '1' || value === 'true';
+}
+function hasAxiomConfig() {
+    return Boolean(process.env['AXIOM_TOKEN']?.trim() && process.env['AXIOM_DATASET']?.trim());
+}
+/**
+ * Returns the default telemetry writer for this environment.
+ * Opt in with CMS_EDIT_TELEMETRY=1; opt out with CMS_EDIT_TELEMETRY=0.
+ * Hosted (Vercel): Axiom only when configured. Local: file log.
+ */
+export function createTelemetryWriter() {
+    if (isTelemetryExplicitlyDisabled()) {
+        return new NoOpTelemetryWriter();
+    }
+    if (!isTelemetryExplicitlyEnabled()) {
+        return new NoOpTelemetryWriter();
+    }
+    const writers = [];
+    if (!isHostedMcpMode()) {
+        writers.push(new LocalFileTelemetryWriter());
+    }
+    if (hasAxiomConfig()) {
+        writers.push(new AxiomTelemetryWriter());
+    }
+    if (writers.length === 0) {
+        return new NoOpTelemetryWriter();
+    }
+    if (writers.length === 1) {
+        return writers[0];
+    }
+    return new CompositeTelemetryWriter(writers);
+}
+//# sourceMappingURL=factory.js.map

package/dist/telemetry/factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../src/telemetry/factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAGhD,SAAS,6BAA6B;IACpC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC;IAChD,OAAO,KAAK,KAAK,GAAG,IAAI,KAAK,KAAK,OAAO,CAAC;AAC5C,CAAC;AAED,SAAS,4BAA4B;IACnC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC;IAChD,OAAO,KAAK,KAAK,GAAG,IAAI,KAAK,KAAK,MAAM,CAAC;AAC3C,CAAC;AAED,SAAS,cAAc;IACrB,OAAO,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,EAAE,IAAI,EAAE,IAAI,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;AAC7F,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB;IACnC,IAAI,6BAA6B,EAAE,EAAE,CAAC;QACpC,OAAO,IAAI,mBAAmB,EAAE,CAAC;IACnC,CAAC;IAED,IAAI,CAAC,4BAA4B,EAAE,EAAE,CAAC;QACpC,OAAO,IAAI,mBAAmB,EAAE,CAAC;IACnC,CAAC;IAED,MAAM,OAAO,GAAsB,EAAE,CAAC;IAEtC,IAAI,CAAC,eAAe,EAAE,EAAE,CAAC;QACvB,OAAO,CAAC,IAAI,CAAC,IAAI,wBAAwB,EAAE,CAAC,CAAC;IAC/C,CAAC;IAED,IAAI,cAAc,EAAE,EAAE,CAAC;QACrB,OAAO,CAAC,IAAI,CAAC,IAAI,oBAAoB,EAAE,CAAC,CAAC;IAC3C,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,IAAI,mBAAmB,EAAE,CAAC;IACnC,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,OAAO,CAAC,CAAC,CAAE,CAAC;IACrB,CAAC;IAED,OAAO,IAAI,wBAAwB,CAAC,OAAO,CAAC,CAAC;AAC/C,CAAC"}

package/dist/telemetry/index.d.ts

@@ -0,0 +1,10 @@
+export { AxiomTelemetryWriter } from './axiom.js';
+export { CompositeTelemetryWriter } from './composite.js';
+export { enrichTelemetryEvent, getTelemetryMode, isHostedMcpMode } from './enrich.js';
+export { createTelemetryWriter } from './factory.js';
+export { LocalFileTelemetryWriter } from './local.js';
+export { NoOpTelemetryWriter } from './noop.js';
+export { beginTelemetryCommand, flushTelemetry, getTelemetryWriter, recordOAuthTelemetryFailure, recordOAuthTelemetryOutcome, recordOAuthTelemetrySuccess, recordTelemetryOutcome, resetTelemetryStateForTests, } from './record.js';
+export { getContentfulRequestStats, incrementCmaRequests, incrementCpaRequests, runWithContentfulRequestStats, setIndexSyncMode, } from './request-stats.js';
+export type { TelemetryEvent, TelemetryWriter } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/telemetry/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/telemetry/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACtF,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,EACL,qBAAqB,EACrB,cAAc,EACd,kBAAkB,EAClB,2BAA2B,EAC3B,2BAA2B,EAC3B,2BAA2B,EAC3B,sBAAsB,EACtB,2BAA2B,GAC5B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,yBAAyB,EACzB,oBAAoB,EACpB,oBAAoB,EACpB,6BAA6B,EAC7B,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC"}

package/dist/telemetry/index.js

@@ -0,0 +1,9 @@
+export { AxiomTelemetryWriter } from './axiom.js';
+export { CompositeTelemetryWriter } from './composite.js';
+export { enrichTelemetryEvent, getTelemetryMode, isHostedMcpMode } from './enrich.js';
+export { createTelemetryWriter } from './factory.js';
+export { LocalFileTelemetryWriter } from './local.js';
+export { NoOpTelemetryWriter } from './noop.js';
+export { beginTelemetryCommand, flushTelemetry, getTelemetryWriter, recordOAuthTelemetryFailure, recordOAuthTelemetryOutcome, recordOAuthTelemetrySuccess, recordTelemetryOutcome, resetTelemetryStateForTests, } from './record.js';
+export { getContentfulRequestStats, incrementCmaRequests, incrementCpaRequests, runWithContentfulRequestStats, setIndexSyncMode, } from './request-stats.js';
+//# sourceMappingURL=index.js.map

package/dist/telemetry/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/telemetry/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACtF,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,EACL,qBAAqB,EACrB,cAAc,EACd,kBAAkB,EAClB,2BAA2B,EAC3B,2BAA2B,EAC3B,2BAA2B,EAC3B,sBAAsB,EACtB,2BAA2B,GAC5B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,yBAAyB,EACzB,oBAAoB,EACpB,oBAAoB,EACpB,6BAA6B,EAC7B,gBAAgB,GACjB,MAAM,oBAAoB,CAAC"}

package/dist/telemetry/local.d.ts

@@ -0,0 +1,9 @@
+import type { TelemetryEvent, TelemetryWriter } from './types.js';
+/**
+ * Appends telemetry events as newline-delimited JSON to ~/.contentful-cms/telemetry.log.
+ * Errors are silently swallowed so telemetry never affects CLI behaviour.
+ */
+export declare class LocalFileTelemetryWriter implements TelemetryWriter {
+    record(event: TelemetryEvent): void;
+}
+//# sourceMappingURL=local.d.ts.map

package/dist/telemetry/local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../src/telemetry/local.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAIlE;;;GAGG;AACH,qBAAa,wBAAyB,YAAW,eAAe;IAC9D,MAAM,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI;CASpC"}

package/dist/telemetry/local.js

@@ -0,0 +1,21 @@
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+const LOG_PATH = path.join(os.homedir(), '.contentful-cms', 'telemetry.log');
+/**
+ * Appends telemetry events as newline-delimited JSON to ~/.contentful-cms/telemetry.log.
+ * Errors are silently swallowed so telemetry never affects CLI behaviour.
+ */
+export class LocalFileTelemetryWriter {
+    record(event) {
+        try {
+            const dir = path.dirname(LOG_PATH);
+            fs.mkdirSync(dir, { recursive: true });
+            fs.appendFileSync(LOG_PATH, `${JSON.stringify(event)}\n`, 'utf-8');
+        }
+        catch {
+            // Intentionally swallowed — telemetry must not break the CLI
+        }
+    }
+}
+//# sourceMappingURL=local.js.map

package/dist/telemetry/local.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local.js","sourceRoot":"","sources":["../../src/telemetry/local.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAGlC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,iBAAiB,EAAE,eAAe,CAAC,CAAC;AAE7E;;;GAGG;AACH,MAAM,OAAO,wBAAwB;IACnC,MAAM,CAAC,KAAqB;QAC1B,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;YACnC,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YACvC,EAAE,CAAC,cAAc,CAAC,QAAQ,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACrE,CAAC;QAAC,MAAM,CAAC;YACP,6DAA6D;QAC/D,CAAC;IACH,CAAC;CACF"}

package/dist/telemetry/noop.d.ts

@@ -0,0 +1,7 @@
+import type { TelemetryEvent, TelemetryWriter } from './types.js';
+/** Discards events when telemetry is disabled. */
+export declare class NoOpTelemetryWriter implements TelemetryWriter {
+    record(_event: TelemetryEvent): void;
+    flush(): Promise<void>;
+}
+//# sourceMappingURL=noop.d.ts.map

package/dist/telemetry/noop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"noop.d.ts","sourceRoot":"","sources":["../../src/telemetry/noop.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElE,kDAAkD;AAClD,qBAAa,mBAAoB,YAAW,eAAe;IACzD,MAAM,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAE9B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAC7B"}

package/dist/telemetry/noop.js

@@ -0,0 +1,6 @@
+/** Discards events when telemetry is disabled. */
+export class NoOpTelemetryWriter {
+    record(_event) { }
+    async flush() { }
+}
+//# sourceMappingURL=noop.js.map

package/dist/telemetry/noop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"noop.js","sourceRoot":"","sources":["../../src/telemetry/noop.ts"],"names":[],"mappings":"AAEA,kDAAkD;AAClD,MAAM,OAAO,mBAAmB;IAC9B,MAAM,CAAC,MAAsB,IAAS,CAAC;IAEvC,KAAK,CAAC,KAAK,KAAmB,CAAC;CAChC"}

package/dist/telemetry/record.d.ts

@@ -0,0 +1,14 @@
+import type { TelemetryWriter } from './types.js';
+export declare function getTelemetryWriter(): TelemetryWriter;
+/** @internal Test helper — resets module singleton state. */
+export declare function resetTelemetryStateForTests(): void;
+export declare function beginTelemetryCommand(cmd: string, sub?: string): void;
+export declare function recordTelemetryOutcome(outcome: 'success' | 'error' | 'exit', opts?: {
+    exitCode?: number;
+    errorName?: string;
+}): void;
+export declare function recordOAuthTelemetryOutcome(route: string, outcome: 'success' | 'error', errorName?: string): void;
+export declare function recordOAuthTelemetrySuccess(route: string): void;
+export declare function recordOAuthTelemetryFailure(route: string, reason: string): void;
+export declare function flushTelemetry(): Promise<void>;
+//# sourceMappingURL=record.d.ts.map

package/dist/telemetry/record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../../src/telemetry/record.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AASlD,wBAAgB,kBAAkB,IAAI,eAAe,CAKpD;AAED,6DAA6D;AAC7D,wBAAgB,2BAA2B,IAAI,IAAI,CAMlD;AAED,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAKrE;AAED,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,SAAS,GAAG,OAAO,GAAG,MAAM,EACrC,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GACnD,IAAI,CAeN;AAED,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,SAAS,GAAG,OAAO,EAC5B,SAAS,CAAC,EAAE,MAAM,GACjB,IAAI,CAWN;AAED,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAE/D;AAED,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAE/E;AAED,wBAAsB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAEpD"}

package/dist/telemetry/record.js

@@ -0,0 +1,61 @@
+import { enrichTelemetryEvent } from './enrich.js';
+import { createTelemetryWriter } from './factory.js';
+let writerInstance;
+let command;
+let subcommand;
+let startMs;
+let recorded = false;
+export function getTelemetryWriter() {
+    if (!writerInstance) {
+        writerInstance = createTelemetryWriter();
+    }
+    return writerInstance;
+}
+/** @internal Test helper — resets module singleton state. */
+export function resetTelemetryStateForTests() {
+    writerInstance = undefined;
+    command = undefined;
+    subcommand = undefined;
+    startMs = undefined;
+    recorded = false;
+}
+export function beginTelemetryCommand(cmd, sub) {
+    command = cmd;
+    subcommand = sub;
+    startMs = Date.now();
+    recorded = false;
+}
+export function recordTelemetryOutcome(outcome, opts = {}) {
+    if (recorded || !command)
+        return;
+    recorded = true;
+    getTelemetryWriter().record(enrichTelemetryEvent({
+        timestamp: new Date().toISOString(),
+        command,
+        subcommand,
+        outcome,
+        exit_code: opts.exitCode,
+        error_name: opts.errorName,
+        duration_ms: startMs !== undefined ? Date.now() - startMs : 0,
+    }));
+}
+export function recordOAuthTelemetryOutcome(route, outcome, errorName) {
+    getTelemetryWriter().record(enrichTelemetryEvent({
+        timestamp: new Date().toISOString(),
+        command: 'oauth',
+        subcommand: route,
+        outcome,
+        error_name: errorName,
+        duration_ms: 0,
+    }));
+}
+export function recordOAuthTelemetrySuccess(route) {
+    recordOAuthTelemetryOutcome(route, 'success');
+}
+export function recordOAuthTelemetryFailure(route, reason) {
+    recordOAuthTelemetryOutcome(route, 'error', reason);
+}
+export async function flushTelemetry() {
+    await getTelemetryWriter().flush?.();
+}
+//# sourceMappingURL=record.js.map

package/dist/telemetry/record.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"record.js","sourceRoot":"","sources":["../../src/telemetry/record.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAGrD,IAAI,cAA2C,CAAC;AAEhD,IAAI,OAA2B,CAAC;AAChC,IAAI,UAA8B,CAAC;AACnC,IAAI,OAA2B,CAAC;AAChC,IAAI,QAAQ,GAAG,KAAK,CAAC;AAErB,MAAM,UAAU,kBAAkB;IAChC,IAAI,CAAC,cAAc,EAAE,CAAC;QACpB,cAAc,GAAG,qBAAqB,EAAE,CAAC;IAC3C,CAAC;IACD,OAAO,cAAc,CAAC;AACxB,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,2BAA2B;IACzC,cAAc,GAAG,SAAS,CAAC;IAC3B,OAAO,GAAG,SAAS,CAAC;IACpB,UAAU,GAAG,SAAS,CAAC;IACvB,OAAO,GAAG,SAAS,CAAC;IACpB,QAAQ,GAAG,KAAK,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,GAAW,EAAE,GAAY;IAC7D,OAAO,GAAG,GAAG,CAAC;IACd,UAAU,GAAG,GAAG,CAAC;IACjB,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACrB,QAAQ,GAAG,KAAK,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,sBAAsB,CACpC,OAAqC,EACrC,OAAkD,EAAE;IAEpD,IAAI,QAAQ,IAAI,CAAC,OAAO;QAAE,OAAO;IACjC,QAAQ,GAAG,IAAI,CAAC;IAEhB,kBAAkB,EAAE,CAAC,MAAM,CACzB,oBAAoB,CAAC;QACnB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,OAAO;QACP,UAAU;QACV,OAAO;QACP,SAAS,EAAE,IAAI,CAAC,QAAQ;QACxB,UAAU,EAAE,IAAI,CAAC,SAAS;QAC1B,WAAW,EAAE,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;KAC9D,CAAC,CACH,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,2BAA2B,CACzC,KAAa,EACb,OAA4B,EAC5B,SAAkB;IAElB,kBAAkB,EAAE,CAAC,MAAM,CACzB,oBAAoB,CAAC;QACnB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,OAAO,EAAE,OAAO;QAChB,UAAU,EAAE,KAAK;QACjB,OAAO;QACP,UAAU,EAAE,SAAS;QACrB,WAAW,EAAE,CAAC;KACf,CAAC,CACH,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,2BAA2B,CAAC,KAAa;IACvD,2BAA2B,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;AAChD,CAAC;AAED,MAAM,UAAU,2BAA2B,CAAC,KAAa,EAAE,MAAc;IACvE,2BAA2B,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;AACtD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc;IAClC,MAAM,kBAAkB,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC;AACvC,CAAC"}

package/dist/telemetry/request-stats.d.ts

@@ -0,0 +1,15 @@
+export type IndexSyncTelemetryMode = 'full' | 'incremental' | 'hydrate' | 'skip';
+export interface ContentfulRequestStats {
+    cma_requests: number;
+    cpa_requests: number;
+    index_sync_mode?: IndexSyncTelemetryMode;
+}
+/** Reuse an existing request store so nested CLI-in-MCP does not drop PAT counts. */
+export declare function runWithContentfulRequestStats<T>(fn: () => T): T;
+export declare function getContentfulRequestStats(): ContentfulRequestStats | undefined;
+export declare function incrementCmaRequests(): void;
+export declare function incrementCpaRequests(): void;
+export declare function setIndexSyncMode(mode: IndexSyncTelemetryMode): void;
+/** @internal */
+export declare function resetContentfulRequestStatsForTests(): void;
+//# sourceMappingURL=request-stats.d.ts.map

package/dist/telemetry/request-stats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-stats.d.ts","sourceRoot":"","sources":["../../src/telemetry/request-stats.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,sBAAsB,GAAG,MAAM,GAAG,aAAa,GAAG,SAAS,GAAG,MAAM,CAAC;AAEjF,MAAM,WAAW,sBAAsB;IACrC,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,sBAAsB,CAAC;CAC1C;AAQD,qFAAqF;AACrF,wBAAgB,6BAA6B,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAG/D;AAED,wBAAgB,yBAAyB,IAAI,sBAAsB,GAAG,SAAS,CAE9E;AAED,wBAAgB,oBAAoB,IAAI,IAAI,CAG3C;AAED,wBAAgB,oBAAoB,IAAI,IAAI,CAG3C;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,sBAAsB,GAAG,IAAI,CAGnE;AAED,gBAAgB;AAChB,wBAAgB,mCAAmC,IAAI,IAAI,CAE1D"}

package/dist/telemetry/request-stats.js

@@ -0,0 +1,34 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+const storage = new AsyncLocalStorage();
+function emptyStats() {
+    return { cma_requests: 0, cpa_requests: 0 };
+}
+/** Reuse an existing request store so nested CLI-in-MCP does not drop PAT counts. */
+export function runWithContentfulRequestStats(fn) {
+    if (storage.getStore())
+        return fn();
+    return storage.run(emptyStats(), fn);
+}
+export function getContentfulRequestStats() {
+    return storage.getStore();
+}
+export function incrementCmaRequests() {
+    const stats = storage.getStore();
+    if (stats)
+        stats.cma_requests += 1;
+}
+export function incrementCpaRequests() {
+    const stats = storage.getStore();
+    if (stats)
+        stats.cpa_requests += 1;
+}
+export function setIndexSyncMode(mode) {
+    const stats = storage.getStore();
+    if (stats)
+        stats.index_sync_mode = mode;
+}
+/** @internal */
+export function resetContentfulRequestStatsForTests() {
+    // ALS is request-scoped; tests call runWithContentfulRequestStats instead.
+}
+//# sourceMappingURL=request-stats.js.map

package/dist/telemetry/request-stats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-stats.js","sourceRoot":"","sources":["../../src/telemetry/request-stats.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAUrD,MAAM,OAAO,GAAG,IAAI,iBAAiB,EAA0B,CAAC;AAEhE,SAAS,UAAU;IACjB,OAAO,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,CAAC;AAC9C,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,6BAA6B,CAAI,EAAW;IAC1D,IAAI,OAAO,CAAC,QAAQ,EAAE;QAAE,OAAO,EAAE,EAAE,CAAC;IACpC,OAAO,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,EAAE,EAAE,CAAC,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,yBAAyB;IACvC,OAAO,OAAO,CAAC,QAAQ,EAAE,CAAC;AAC5B,CAAC;AAED,MAAM,UAAU,oBAAoB;IAClC,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IACjC,IAAI,KAAK;QAAE,KAAK,CAAC,YAAY,IAAI,CAAC,CAAC;AACrC,CAAC;AAED,MAAM,UAAU,oBAAoB;IAClC,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IACjC,IAAI,KAAK;QAAE,KAAK,CAAC,YAAY,IAAI,CAAC,CAAC;AACrC,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,IAA4B;IAC3D,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IACjC,IAAI,KAAK;QAAE,KAAK,CAAC,eAAe,GAAG,IAAI,CAAC;AAC1C,CAAC;AAED,gBAAgB;AAChB,MAAM,UAAU,mCAAmC;IACjD,2EAA2E;AAC7E,CAAC"}

package/dist/telemetry/types.d.ts

@@ -0,0 +1,47 @@
+/**
+ * A single telemetry event recording one CLI command invocation.
+ * No PII is stored: no slugs, entry IDs, field values, query text, or replacement strings.
+ */
+export interface TelemetryEvent {
+    /** Stable id for deduplication in downstream analytics. */
+    event_id: string;
+    /** ISO 8601 timestamp of when the command completed. */
+    timestamp: string;
+    /** Top-level command name (e.g. "rtf", "open", "save", "oauth"). */
+    command: string;
+    /** Subcommand name when applicable (e.g. "replace", "embed", "link-contentful"). */
+    subcommand?: string;
+    /** Whether the command succeeded, errored, or exited (process.exit called). */
+    outcome: 'success' | 'error' | 'exit';
+    /** Process exit code (populated for 'exit' outcome). */
+    exit_code?: number;
+    /** Error constructor name or stable reason code — NOT the message, to avoid logging PII. */
+    error_name?: string;
+    /** Wall-clock duration from command start to completion in milliseconds. */
+    duration_ms: number;
+    /** cms-edit package version. */
+    cms_edit_version: string;
+    /** Invocation context. */
+    mode: 'cli' | 'hosted-mcp';
+    /** Deployment aggregate key (CMS_EDIT_PROJECT_KEY); never user id or email. */
+    project_key?: string;
+    /** Node.js runtime version. */
+    node_version: string;
+    /** process.platform value. */
+    platform: string;
+    /** Content Management API origin requests during this command (when counted). */
+    cma_requests?: number;
+    /** Content Preview API origin requests during this command (when counted). */
+    cpa_requests?: number;
+    /** How the content index was satisfied for this command. */
+    index_sync_mode?: 'full' | 'incremental' | 'hydrate' | 'skip';
+}
+/**
+ * Abstraction for telemetry sinks. Swap out LocalFileTelemetryWriter for a remote
+ * implementation in the future without changing call sites.
+ */
+export interface TelemetryWriter {
+    record(event: TelemetryEvent): void;
+    flush?(): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/telemetry/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/telemetry/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;IACjB,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,oFAAoF;IACpF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+EAA+E;IAC/E,OAAO,EAAE,SAAS,GAAG,OAAO,GAAG,MAAM,CAAC;IACtC,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4FAA4F;IAC5F,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,WAAW,EAAE,MAAM,CAAC;IACpB,gCAAgC;IAChC,gBAAgB,EAAE,MAAM,CAAC;IACzB,0BAA0B;IAC1B,IAAI,EAAE,KAAK,GAAG,YAAY,CAAC;IAC3B,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+BAA+B;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,8EAA8E;IAC9E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,eAAe,CAAC,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,GAAG,MAAM,CAAC;CAC/D;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,CAAC;IACpC,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB"}

package/dist/telemetry/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/telemetry/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/telemetry/types.ts"],"names":[],"mappings":""}

package/dist/validation/allowed-types.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Content type IDs allowed when adding entries to page/article/template content arrays.
+ * Used by the add command to refuse unsupported types with a clear error.
+ */
+export declare const ALLOWED_CONTENT_TYPES_FOR_PAGE_ARTICLE: readonly ["collection", "component", "externalComponent", "externalVideo", "htmlComponent", "media", "person"];
+export declare function isAllowedContentTypeForAdd(contentTypeId: string): boolean;
+//# sourceMappingURL=allowed-types.d.ts.map

package/dist/validation/allowed-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"allowed-types.d.ts","sourceRoot":"","sources":["../../src/validation/allowed-types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,sCAAsC,gHAQzC,CAAC;AAEX,wBAAgB,0BAA0B,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAEzE"}

package/dist/validation/allowed-types.js

@@ -0,0 +1,17 @@
+/**
+ * Content type IDs allowed when adding entries to page/article/template content arrays.
+ * Used by the add command to refuse unsupported types with a clear error.
+ */
+export const ALLOWED_CONTENT_TYPES_FOR_PAGE_ARTICLE = [
+    'collection',
+    'component',
+    'externalComponent',
+    'externalVideo',
+    'htmlComponent',
+    'media',
+    'person',
+];
+export function isAllowedContentTypeForAdd(contentTypeId) {
+    return ALLOWED_CONTENT_TYPES_FOR_PAGE_ARTICLE.includes(contentTypeId);
+}
+//# sourceMappingURL=allowed-types.js.map

package/dist/validation/allowed-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"allowed-types.js","sourceRoot":"","sources":["../../src/validation/allowed-types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,CAAC,MAAM,sCAAsC,GAAG;IACpD,YAAY;IACZ,WAAW;IACX,mBAAmB;IACnB,eAAe;IACf,eAAe;IACf,OAAO;IACP,QAAQ;CACA,CAAC;AAEX,MAAM,UAAU,0BAA0B,CAAC,aAAqB;IAC9D,OAAQ,sCAA4D,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC;AAC/F,CAAC"}

package/dist/version.d.ts

@@ -0,0 +1,9 @@
+import { CMS_EDIT_PACKAGE_NAME, CMS_EDIT_VERSION } from './generated/version.js';
+export interface CmsEditVersionInfo {
+    name: 'cms-edit';
+    version: string;
+    package: string;
+}
+export { CMS_EDIT_PACKAGE_NAME, CMS_EDIT_VERSION };
+export declare function getVersionInfo(): CmsEditVersionInfo;
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAEjF,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,UAAU,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,CAAC;AAEnD,wBAAgB,cAAc,IAAI,kBAAkB,CAMnD"}

package/dist/version.js

@@ -0,0 +1,10 @@
+import { CMS_EDIT_PACKAGE_NAME, CMS_EDIT_VERSION } from './generated/version.js';
+export { CMS_EDIT_PACKAGE_NAME, CMS_EDIT_VERSION };
+export function getVersionInfo() {
+    return {
+        name: 'cms-edit',
+        version: CMS_EDIT_VERSION,
+        package: CMS_EDIT_PACKAGE_NAME,
+    };
+}
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAQjF,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,CAAC;AAEnD,MAAM,UAAU,cAAc;IAC5B,OAAO;QACL,IAAI,EAAE,UAAU;QAChB,OAAO,EAAE,gBAAgB;QACzB,OAAO,EAAE,qBAAqB;KAC/B,CAAC;AACJ,CAAC"}

package/docs/FEATURE_REQUESTS_ARCHIVE.md

@@ -0,0 +1,141 @@
+# cms-edit: Feature Requests Archive — `rtf replace` Improvements
+
+> **Archive notice (2026-03-26):** All items in this file have been implemented. FR-1 (`--protect-pattern`), FR-2 (`--find-plain`), FR-3 (`--ignore-marks`), and FR-4 (`--in-table-col`) are all available in `rtf replace`. Retained for historical context.
+
+These requests were identified during real-world compliance automation work where `cms-edit rtf replace` was used to surgically insert Quidget codes into credit card affiliate articles. Each issue caused a failed or unsafe replacement and required a discard-and-redo.
+
+---
+
+## FR-1 — `rtf replace`: `--mode all` must skip content inside existing quidget spans
+
+### Problem
+
+Once a quidget code has been inserted into a text node (e.g. `{*credit_card_id*:*2061159*,*field*:*annual_fees*,*api*:*cc*,*case*:*uf*,*placeholder*:*$95*}`), a subsequent `--find '$95' --mode all` matches the `$95` character sequence inside the placeholder value of the already-inserted code. This nests a new quidget code inside the old one, producing:
+
+```
+{*credit_card_id*:*2061159*,...,*placeholder*:*{*credit_card_id*:*2061159*,...,*placeholder*:*$95*}*}
+```
+
+The document is now corrupt and the quidget will not render correctly.
+
+### Reproducing scenario
+
+```bash
+# Step 1 — insert a quidget code for one occurrence of $95
+cms-edit rtf replace @c1 body \
+  --find 'justify the $95 annual fee' \
+  --replace-plain 'justify the {*credit_card_id*:*2061159*,*field*:*annual_fees*,*api*:*cc*,*case*:*uf*,*placeholder*:*$95*} annual fee' \
+  --mode exactlyOne
+
+# Step 2 — now try to replace remaining $95 occurrences
+cms-edit rtf replace @c1 body \
+  --find '$95' \
+  --replace-plain '{*credit_card_id*:*2061159*,*field*:*annual_fees*,*api*:*cc*,*case*:*uf*,*placeholder*:*$95*}' \
+  --mode all
+# ❌ Step 2 also matches $95 inside the placeholder written in Step 1
+```
+
+### Proposed solution
+
+When scanning text nodes for `--find` matches, treat any span matching `{*...*}` as opaque — skip over it entirely. The tool already understands quidget token syntax (it writes them via `--replace-plain`); it should also recognise them as protected spans during search, the same way a text editor's Find would not match inside a non-editable region.
+
+---
+
+## FR-2 — `rtf replace`: add `--find-plain` to search for literal asterisks
+
+### Problem
+
+`--replace-plain` exists so that quidget tokens containing `*` are written as literal characters rather than parsed as Markdown bold markers. There is no equivalent flag for `--find`. This makes it impossible to search for any string that contains `*`, including:
+
+- Existing quidget codes (e.g. to verify or fix a previously inserted code)
+- Any content that legitimately contains asterisks
+
+As a practical consequence, when FR-1's corruption does occur, there is no surgical way to fix the corrupted node — it can only be corrected by discarding the entire session and starting over.
+
+### Reproducing scenario
+
+```bash
+# Try to fix a corrupted quidget by searching for its text — fails silently
+cms-edit rtf replace @c1 body \
+  --find 'placeholder*:*{*credit_card_id' \
+  --replace-plain 'placeholder*:*$95*}' \
+  --mode all
+# ❌ Warning: No occurrence of --find in "body" on @c1; session unchanged for this field.
+# (asterisks are parsed as Markdown bold markers, not literal characters)
+```
+
+### Proposed solution
+
+Add a `--find-plain` flag (mirroring `--replace-plain`) that treats the `--find` argument as a literal string with no Markdown interpretation. Combined with FR-1, this would allow both safe searching and recovery from corruption.
+
+```bash
+# Desired behaviour with --find-plain
+cms-edit rtf replace @c1 body \
+  --find-plain 'placeholder*:*{*credit_card_id*:*2061159*,...' \
+  --replace-plain 'placeholder*:*$95*}' \
+  --mode exactlyOne
+```
+
+---
+
+## FR-3 — `rtf replace`: `--ignore-marks` to match across inline formatting boundaries
+
+### Problem
+
+The `--find` search operates per text node. A paragraph stored as `**Annual fee: **$95` is two adjacent text nodes — one bold (`Annual fee: `) and one normal (`$95`) — so `--find "Annual fee: $95"` finds nothing. This affects every bold-label + plain-value pattern in credit card articles:
+
+- `**Annual fee: **$95`
+- `**Foreign transaction fees: **None`
+- `**Current welcome bonus: **75,000 points…`
+
+These are extremely common in affiliate content. Because the label cannot be used as context, the search string must be the bare value (`$95`), which is then often not unique across the document.
+
+### Reproducing scenario
+
+```bash
+# Article body contains: **Annual fee: **$95
+cms-edit rtf replace @c1 body \
+  --find 'Annual fee: $95' \
+  --replace-plain 'Annual fee: {*credit_card_id*:*2061159*,*field*:*annual_fees*,...*}' \
+  --mode exactlyOne
+# ❌ Error: No occurrence of find string in document
+# (because "Annual fee: " and "$95" are in different text nodes)
+```
+
+### Proposed solution
+
+Add an `--ignore-marks` flag that, for the purpose of matching only, concatenates the text content of adjacent sibling nodes within the same block (paragraph, list item, table cell). The replacement then applies to the matching text while preserving the original inline marks in the output.
+
+**Alternative (lower effort):** If the full implementation is complex, at minimum document this limitation in the `rtf replace --help` output with a concrete example, so that LLMs using the tool do not waste retries on searches that can never succeed.
+
+---
+
+## FR-4 — `rtf replace`: table column targeting
+
+### Problem
+
+When a comparison table contains the same plain-text value in multiple columns — for example, both the primary card and a competitor showing `None` for foreign transaction fees — there is no way to target only the column belonging to the primary card. Any `--find "None"` replacement hits every matching cell in every column.
+
+In the specific case that prompted this request: a Chase Sapphire Preferred vs. Chase Sapphire Reserve comparison table has `None` in both the CSP and CSR foreign-transaction-fee cells. Replacing all occurrences would incorrectly tag the CSR cell with the CSP card's quidget code.
+
+### Proposed solution
+
+**Option A (preferred):** A `--in-table-col N` flag (1-indexed) that restricts matches to cells in the Nth column of any table encountered in the field.
+
+```bash
+cms-edit rtf replace @c1 body \
+  --find 'None' \
+  --replace-plain '{*credit_card_id*:*2061159*,*field*:*foreign_transaction_fee*,...*}' \
+  --in-table-col 2 \
+  --mode all
+```
+
+**Option B:** An `--after "text"` flag that requires the match to appear after a specific string in document order, scoped to the nearest enclosing table row.
+
+---
+
+## Minor: `diff` output for rich text fields
+
+The `diff` command currently shows a single-line before/after delta for an entire rich text body field, making it impossible to verify which text runs actually changed before saving.
+
+**Requested:** Show a count of changed text runs (e.g. `7 text run(s) changed`) and/or show abbreviated before/after excerpts for each changed span. This would let an LLM confirm that exactly the expected number of replacements took effect without requiring a full re-read of the field.