@ttctl/core 0.0.0 → 0.1.0-rc.1

package/dist/lib/redact.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Centralized redaction primitives for diagnostic logging and pattern-leak
+ * detection.
+ *
+ * This module is the **single source of truth** for "what is a secret" across
+ * the project — both the runtime debug-log path (issue #139) and the static
+ * `check-secret-leakage` script consume the constants defined here. Any
+ * future addition to either redaction (runtime) or detection (lint) MUST
+ * extend these exports rather than redefining them locally.
+ *
+ * Consumers:
+ *
+ * - `packages/core/src/lib/diagnostic-log.ts` calls {@link redactHeaders} /
+ *   {@link redactBody} before emitting any `--verbose` / `--debug` line
+ *   to stderr.
+ * - `scripts/check-secret-leakage.ts` consumes {@link BEARER_PATTERN_SOURCE}
+ *   to scan tracked source for accidentally committed Toptal session
+ *   bearers.
+ *
+ * Wire shape is stable; downstream tools and tests identify redaction sites
+ * by exact match against {@link REDACTED}. Patterns are append-only — never
+ * remove an entry, only add. Tests assert that no `authToken` value or
+ * cookie value can appear verbatim in the output of either consumer.
+ */
+/**
+ * Replacement marker for redacted scalar values. Stable wire-shape so
+ * downstream tools and tests can identify redaction sites by exact match.
+ */
+export declare const REDACTED: "***REDACTED***";
+/**
+ * Source pattern for Toptal Talent's session bearer token, exported as a
+ * STRING (not a `RegExp`) so non-TypeScript consumers (the
+ * `scripts/check-secret-leakage.ts` lint script before its own
+ * `new RegExp(..., "g")` construction) can adopt the canonical pattern
+ * without paying for any module-load-time `g`-flag state. The TS-side
+ * {@link BEARER_PATTERN} below wraps this source in a fresh `RegExp` per
+ * import so callers do not share the `lastIndex` cursor (`/g` flag is
+ * stateful per-instance).
+ *
+ * The bearer shape is `user_<24hex>_<20alnum>` — the canonical output of
+ * Toptal's `EmailPasswordSignIn` mutation (per
+ * `hq/engineering/adr/ADR-005-auth-model.md`). Anchored to character
+ * class boundaries: the `user_` literal prefix is TTCtl-specific (no false
+ * positives against unrelated `user_` strings in test data), the 24-hex +
+ * 20-alphanumeric pair is the empirically observed shape.
+ */
+export declare const BEARER_PATTERN_SOURCE: "user_[0-9a-f]{24}_[A-Za-z0-9]{20}";
+/**
+ * Compiled bearer-shape regex with the `g` (global) flag. A fresh `RegExp`
+ * instance constructed at module-load time so callers in this package can
+ * use `.test()` / `.exec()` against multiline strings without resetting
+ * `lastIndex` between unrelated callers.
+ *
+ * **Stateful flag warning**: the `g` flag makes `exec` / `test` advance an
+ * internal cursor. Callers iterating over multiple inputs must either
+ * reset `BEARER_PATTERN.lastIndex = 0` before each input, or construct a
+ * fresh instance via `new RegExp(BEARER_PATTERN_SOURCE, "g")`.
+ */
+export declare const BEARER_PATTERN: RegExp;
+/**
+ * Header names whose VALUES carry session-bearing or otherwise
+ * authentication-sensitive material. Lowercased for case-insensitive
+ * matching — runtime code paths normalise the header key to lowercase
+ * before lookup. Includes both standard auth headers (`authorization`,
+ * `cookie`, `proxy-authorization`) and a small set of vendor-specific
+ * variants that historically carry session tokens.
+ *
+ * `set-cookie` is included because GraphQL responses occasionally echo
+ * session-bearing cookies on the response side; redacting it on the
+ * response trace keeps the symmetric request/response wire shape clean.
+ */
+export declare const SECRET_HEADER_NAMES: ReadonlySet<string>;
+/**
+ * Field names (case-insensitive) whose VALUES carry secrets when they
+ * appear inside request or response bodies — GraphQL `variables`, JSON
+ * payloads, REST request bodies, error envelopes, etc. Runtime code
+ * paths normalise the field key to lowercase before lookup.
+ *
+ * Conservative on purpose: the cost of redacting a field that turns out
+ * to be benign is zero (one fewer scalar visible in debug output); the
+ * cost of NOT redacting an actual secret is a credential leak. Add new
+ * field names freely.
+ */
+export declare const SECRET_BODY_FIELD_NAMES: ReadonlySet<string>;
+/**
+ * Return a redacted copy of `headers`. Keys are preserved verbatim; values
+ * for keys whose lowercase form is in {@link SECRET_HEADER_NAMES} are
+ * replaced with {@link REDACTED}. Non-secret headers pass through unchanged.
+ *
+ * For the `cookie` and `set-cookie` headers, the entire header value is
+ * replaced. TTCtl is bearer-only (no cookie jar is configured in either
+ * transport — see ADR-005), but a server may still emit `Set-Cookie` on
+ * responses (Cloudflare bot-management cookies, Toptal session hints
+ * TTCtl ignores). Whole-value redaction is the safe default for that
+ * case; cookie names carry no operational signal here because TTCtl
+ * never sends them back.
+ *
+ * Pure — does not mutate the input.
+ */
+export declare function redactHeaders(headers: Record<string, string>): Record<string, string>;
+/**
+ * Deep-walk `body` and replace values of any field whose key (lowercased)
+ * is in {@link SECRET_BODY_FIELD_NAMES} with {@link REDACTED}. Returns a
+ * structurally cloned copy — does NOT mutate the input. Non-object inputs
+ * pass through unchanged (scalars, null, undefined).
+ *
+ * Walks both plain objects and arrays. Arrays inherit the parent's
+ * redaction rules — e.g., `{credentials: [{password: "..."}]}` redacts
+ * the `password` field inside the array element.
+ *
+ * Designed for GraphQL `variables` payloads (which are arbitrary JSON
+ * trees) and REST request bodies. Cycle detection is NOT implemented —
+ * GraphQL request/response payloads are tree-shaped by spec, so cycles
+ * cannot occur in valid inputs; defensive callers (e.g.,
+ * `diagnostic-log.ts`) parse JSON before invoking and pass the parsed
+ * tree.
+ *
+ * The implementation walks keys via `Object.entries` which preserves
+ * insertion order in V8 — useful for tests that snapshot the redacted
+ * output as JSON.
+ */
+export declare function redactBody(body: unknown): unknown;
+/**
+ * True when `text` contains a Toptal Talent session bearer match per
+ * {@link BEARER_PATTERN_SOURCE}. Convenience wrapper that constructs a
+ * fresh `RegExp` per call so `lastIndex` state on the shared
+ * {@link BEARER_PATTERN} cannot leak into the test.
+ *
+ * Used by `scripts/check-secret-leakage.ts` as the authoritative
+ * "contains-bearer" check, replacing the previous in-script regex.
+ */
+export declare function containsBearerToken(text: string): boolean;
+/**
+ * Replace every Toptal Talent session bearer match in `text` with the
+ * canonical {@link REDACTED} marker. Returns the input unchanged when no
+ * match is present.
+ *
+ * Free-text counterpart to the structural {@link redactBody} /
+ * {@link redactHeaders} pair — designed for diagnostic output whose
+ * shape is a single string (error messages, stack traces, crash logs)
+ * rather than a parsed object graph. The bearer regex is the only
+ * pattern this scrubs; password and other unstructured secrets cannot
+ * be detected without a runtime registry of known values (out of scope
+ * for this module — see SECURITY.md § Crash-output secret invariant).
+ *
+ * Constructs a fresh `RegExp` per call so the shared
+ * {@link BEARER_PATTERN}'s `lastIndex` cursor cannot be advanced by
+ * unrelated callers.
+ *
+ * Pure — does not mutate the input string.
+ */
+export declare function redactString(text: string): string;
+//# sourceMappingURL=redact.d.ts.map

package/dist/lib/redact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.d.ts","sourceRoot":"","sources":["../../src/lib/redact.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;;GAGG;AACH,eAAO,MAAM,QAAQ,EAAG,gBAAyB,CAAC;AAElD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,qBAAqB,EAAG,mCAA4C,CAAC;AAElF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,cAAc,EAAE,MAA+C,CAAC;AAE7E;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,MAAM,CASlD,CAAC;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,uBAAuB,EAAE,WAAW,CAAC,MAAM,CAetD,CAAC;AAEH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMrF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAcjD;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEjD"}

package/dist/lib/redact.js

@@ -0,0 +1,207 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+/**
+ * Centralized redaction primitives for diagnostic logging and pattern-leak
+ * detection.
+ *
+ * This module is the **single source of truth** for "what is a secret" across
+ * the project — both the runtime debug-log path (issue #139) and the static
+ * `check-secret-leakage` script consume the constants defined here. Any
+ * future addition to either redaction (runtime) or detection (lint) MUST
+ * extend these exports rather than redefining them locally.
+ *
+ * Consumers:
+ *
+ * - `packages/core/src/lib/diagnostic-log.ts` calls {@link redactHeaders} /
+ *   {@link redactBody} before emitting any `--verbose` / `--debug` line
+ *   to stderr.
+ * - `scripts/check-secret-leakage.ts` consumes {@link BEARER_PATTERN_SOURCE}
+ *   to scan tracked source for accidentally committed Toptal session
+ *   bearers.
+ *
+ * Wire shape is stable; downstream tools and tests identify redaction sites
+ * by exact match against {@link REDACTED}. Patterns are append-only — never
+ * remove an entry, only add. Tests assert that no `authToken` value or
+ * cookie value can appear verbatim in the output of either consumer.
+ */
+/**
+ * Replacement marker for redacted scalar values. Stable wire-shape so
+ * downstream tools and tests can identify redaction sites by exact match.
+ */
+export const REDACTED = "***REDACTED***";
+/**
+ * Source pattern for Toptal Talent's session bearer token, exported as a
+ * STRING (not a `RegExp`) so non-TypeScript consumers (the
+ * `scripts/check-secret-leakage.ts` lint script before its own
+ * `new RegExp(..., "g")` construction) can adopt the canonical pattern
+ * without paying for any module-load-time `g`-flag state. The TS-side
+ * {@link BEARER_PATTERN} below wraps this source in a fresh `RegExp` per
+ * import so callers do not share the `lastIndex` cursor (`/g` flag is
+ * stateful per-instance).
+ *
+ * The bearer shape is `user_<24hex>_<20alnum>` — the canonical output of
+ * Toptal's `EmailPasswordSignIn` mutation (per
+ * `hq/engineering/adr/ADR-005-auth-model.md`). Anchored to character
+ * class boundaries: the `user_` literal prefix is TTCtl-specific (no false
+ * positives against unrelated `user_` strings in test data), the 24-hex +
+ * 20-alphanumeric pair is the empirically observed shape.
+ */
+export const BEARER_PATTERN_SOURCE = "user_[0-9a-f]{24}_[A-Za-z0-9]{20}";
+/**
+ * Compiled bearer-shape regex with the `g` (global) flag. A fresh `RegExp`
+ * instance constructed at module-load time so callers in this package can
+ * use `.test()` / `.exec()` against multiline strings without resetting
+ * `lastIndex` between unrelated callers.
+ *
+ * **Stateful flag warning**: the `g` flag makes `exec` / `test` advance an
+ * internal cursor. Callers iterating over multiple inputs must either
+ * reset `BEARER_PATTERN.lastIndex = 0` before each input, or construct a
+ * fresh instance via `new RegExp(BEARER_PATTERN_SOURCE, "g")`.
+ */
+export const BEARER_PATTERN = new RegExp(BEARER_PATTERN_SOURCE, "g");
+/**
+ * Header names whose VALUES carry session-bearing or otherwise
+ * authentication-sensitive material. Lowercased for case-insensitive
+ * matching — runtime code paths normalise the header key to lowercase
+ * before lookup. Includes both standard auth headers (`authorization`,
+ * `cookie`, `proxy-authorization`) and a small set of vendor-specific
+ * variants that historically carry session tokens.
+ *
+ * `set-cookie` is included because GraphQL responses occasionally echo
+ * session-bearing cookies on the response side; redacting it on the
+ * response trace keeps the symmetric request/response wire shape clean.
+ */
+export const SECRET_HEADER_NAMES = new Set([
+    "authorization",
+    "cookie",
+    "set-cookie",
+    "proxy-authorization",
+    "x-auth-token",
+    "x-csrf-token",
+    "x-session-token",
+    "x-toptal-session",
+]);
+/**
+ * Field names (case-insensitive) whose VALUES carry secrets when they
+ * appear inside request or response bodies — GraphQL `variables`, JSON
+ * payloads, REST request bodies, error envelopes, etc. Runtime code
+ * paths normalise the field key to lowercase before lookup.
+ *
+ * Conservative on purpose: the cost of redacting a field that turns out
+ * to be benign is zero (one fewer scalar visible in debug output); the
+ * cost of NOT redacting an actual secret is a credential leak. Add new
+ * field names freely.
+ */
+export const SECRET_BODY_FIELD_NAMES = new Set([
+    "password",
+    "passwd",
+    "token",
+    "secret",
+    "apikey",
+    "api_key",
+    "authtoken",
+    "auth_token",
+    "accesstoken",
+    "access_token",
+    "refreshtoken",
+    "refresh_token",
+    "authorization",
+    "email",
+]);
+/**
+ * Return a redacted copy of `headers`. Keys are preserved verbatim; values
+ * for keys whose lowercase form is in {@link SECRET_HEADER_NAMES} are
+ * replaced with {@link REDACTED}. Non-secret headers pass through unchanged.
+ *
+ * For the `cookie` and `set-cookie` headers, the entire header value is
+ * replaced. TTCtl is bearer-only (no cookie jar is configured in either
+ * transport — see ADR-005), but a server may still emit `Set-Cookie` on
+ * responses (Cloudflare bot-management cookies, Toptal session hints
+ * TTCtl ignores). Whole-value redaction is the safe default for that
+ * case; cookie names carry no operational signal here because TTCtl
+ * never sends them back.
+ *
+ * Pure — does not mutate the input.
+ */
+export function redactHeaders(headers) {
+    const out = {};
+    for (const [key, value] of Object.entries(headers)) {
+        out[key] = SECRET_HEADER_NAMES.has(key.toLowerCase()) ? REDACTED : value;
+    }
+    return out;
+}
+/**
+ * Deep-walk `body` and replace values of any field whose key (lowercased)
+ * is in {@link SECRET_BODY_FIELD_NAMES} with {@link REDACTED}. Returns a
+ * structurally cloned copy — does NOT mutate the input. Non-object inputs
+ * pass through unchanged (scalars, null, undefined).
+ *
+ * Walks both plain objects and arrays. Arrays inherit the parent's
+ * redaction rules — e.g., `{credentials: [{password: "..."}]}` redacts
+ * the `password` field inside the array element.
+ *
+ * Designed for GraphQL `variables` payloads (which are arbitrary JSON
+ * trees) and REST request bodies. Cycle detection is NOT implemented —
+ * GraphQL request/response payloads are tree-shaped by spec, so cycles
+ * cannot occur in valid inputs; defensive callers (e.g.,
+ * `diagnostic-log.ts`) parse JSON before invoking and pass the parsed
+ * tree.
+ *
+ * The implementation walks keys via `Object.entries` which preserves
+ * insertion order in V8 — useful for tests that snapshot the redacted
+ * output as JSON.
+ */
+export function redactBody(body) {
+    if (body === null || body === undefined)
+        return body;
+    if (Array.isArray(body))
+        return body.map((item) => redactBody(item));
+    if (typeof body !== "object")
+        return body;
+    const input = body;
+    const out = {};
+    for (const [key, value] of Object.entries(input)) {
+        if (SECRET_BODY_FIELD_NAMES.has(key.toLowerCase())) {
+            out[key] = REDACTED;
+        }
+        else {
+            out[key] = redactBody(value);
+        }
+    }
+    return out;
+}
+/**
+ * True when `text` contains a Toptal Talent session bearer match per
+ * {@link BEARER_PATTERN_SOURCE}. Convenience wrapper that constructs a
+ * fresh `RegExp` per call so `lastIndex` state on the shared
+ * {@link BEARER_PATTERN} cannot leak into the test.
+ *
+ * Used by `scripts/check-secret-leakage.ts` as the authoritative
+ * "contains-bearer" check, replacing the previous in-script regex.
+ */
+export function containsBearerToken(text) {
+    return new RegExp(BEARER_PATTERN_SOURCE).test(text);
+}
+/**
+ * Replace every Toptal Talent session bearer match in `text` with the
+ * canonical {@link REDACTED} marker. Returns the input unchanged when no
+ * match is present.
+ *
+ * Free-text counterpart to the structural {@link redactBody} /
+ * {@link redactHeaders} pair — designed for diagnostic output whose
+ * shape is a single string (error messages, stack traces, crash logs)
+ * rather than a parsed object graph. The bearer regex is the only
+ * pattern this scrubs; password and other unstructured secrets cannot
+ * be detected without a runtime registry of known values (out of scope
+ * for this module — see SECURITY.md § Crash-output secret invariant).
+ *
+ * Constructs a fresh `RegExp` per call so the shared
+ * {@link BEARER_PATTERN}'s `lastIndex` cursor cannot be advanced by
+ * unrelated callers.
+ *
+ * Pure — does not mutate the input string.
+ */
+export function redactString(text) {
+    return text.replace(new RegExp(BEARER_PATTERN_SOURCE, "g"), REDACTED);
+}
+//# sourceMappingURL=redact.js.map

package/dist/lib/redact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.js","sourceRoot":"","sources":["../../src/lib/redact.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,oCAAoC;AAEpC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,gBAAyB,CAAC;AAElD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,mCAA4C,CAAC;AAElF;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,cAAc,GAAW,IAAI,MAAM,CAAC,qBAAqB,EAAE,GAAG,CAAC,CAAC;AAE7E;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAwB,IAAI,GAAG,CAAC;IAC9D,eAAe;IACf,QAAQ;IACR,YAAY;IACZ,qBAAqB;IACrB,cAAc;IACd,cAAc;IACd,iBAAiB;IACjB,kBAAkB;CACnB,CAAC,CAAC;AAEH;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAwB,IAAI,GAAG,CAAC;IAClE,UAAU;IACV,QAAQ;IACR,OAAO;IACP,QAAQ;IACR,QAAQ;IACR,SAAS;IACT,WAAW;IACX,YAAY;IACZ,aAAa;IACb,cAAc;IACd,cAAc;IACd,eAAe;IACf,eAAe;IACf,OAAO;CACR,CAAC,CAAC;AAEH;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,aAAa,CAAC,OAA+B;IAC3D,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACnD,GAAG,CAAC,GAAG,CAAC,GAAG,mBAAmB,CAAC,GAAG,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC;IAC3E,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,UAAU,CAAC,IAAa;IACtC,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACrD,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;IACrE,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC1C,MAAM,KAAK,GAAG,IAA+B,CAAC;IAC9C,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,IAAI,uBAAuB,CAAC,GAAG,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;YACnD,GAAG,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC;QACtB,CAAC;aAAM,CAAC;YACN,GAAG,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,OAAO,IAAI,MAAM,CAAC,qBAAqB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACtD,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,qBAAqB,EAAE,GAAG,CAAC,EAAE,QAAQ,CAAC,CAAC;AACxE,CAAC"}

package/dist/lib/text.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Split a multi-paragraph string on blank lines into an array of trimmed
+ * paragraphs (drops empties). Mirrors the wire shape used by sub-domains
+ * whose mutation inputs accept paragraph arrays (e.g. `experienceItems`
+ * on `UpdateEmploymentInput` per
+ * `research/captures/web/inputs/UpdateEmploymentInput.json`).
+ *
+ * Pure — no I/O — so it's directly unit-testable.
+ *
+ * @param text - source string with paragraphs separated by blank lines
+ * @returns array of trimmed paragraphs (empty paragraphs dropped)
+ */
+export declare function splitParagraphs(text: string): string[];
+//# sourceMappingURL=text.d.ts.map

package/dist/lib/text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../../src/lib/text.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAKtD"}

package/dist/lib/text.js

@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+/**
+ * Split a multi-paragraph string on blank lines into an array of trimmed
+ * paragraphs (drops empties). Mirrors the wire shape used by sub-domains
+ * whose mutation inputs accept paragraph arrays (e.g. `experienceItems`
+ * on `UpdateEmploymentInput` per
+ * `research/captures/web/inputs/UpdateEmploymentInput.json`).
+ *
+ * Pure — no I/O — so it's directly unit-testable.
+ *
+ * @param text - source string with paragraphs separated by blank lines
+ * @returns array of trimmed paragraphs (empty paragraphs dropped)
+ */
+export function splitParagraphs(text) {
+    return text
+        .split(/\r?\n\s*\r?\n/)
+        .map((p) => p.trim())
+        .filter((p) => p.length > 0);
+}
+//# sourceMappingURL=text.js.map

package/dist/lib/text.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.js","sourceRoot":"","sources":["../../src/lib/text.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,oCAAoC;AAEpC;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,IAAI;SACR,KAAK,CAAC,eAAe,CAAC;SACtB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACjC,CAAC"}

package/dist/lib/wire-shape.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Shared wire-shape validation helper for the hybrid runtime
+ * field-level validation model (ADR-006). Used by every per-service
+ * `callGateway` / `callTalentProfile` helper to convert a
+ * {@link z.ZodError} from a failed `schema.parse(body.data)` call into
+ * the structured payload required by the project's `WIRE_SHAPE_ERROR`
+ * UX (see `docs/wire-validation-error-format.md`, M2 / #281).
+ *
+ * Operationally a `WIRE_SHAPE_ERROR` means Toptal changed the wire
+ * shape (the schemas were synthesized from APK decompilation + live
+ * captures and lag behind server-side updates). The CLI / MCP surfaces
+ * render the diff so an operator can file an actionable bug.
+ *
+ * Z-3 (#286) wires this helper through the call path. No production op
+ * has `schema` wired yet — that's Z-4 (#288)'s beachhead.
+ *
+ * Zod v4 note: in v4 the public `error.issues[]` does NOT carry the
+ * raw input value (`input` is stripped from the user-facing
+ * {@link z.core.$ZodIssue} despite being present on the internal
+ * {@link z.core.$ZodRawIssue}). To recover the wire value for the
+ * `actual` and `value` slots of a {@link WireShapeDiffEntry}, the
+ * caller passes the original wire data (`body.data`) as the second
+ * argument to {@link buildWireShapeError} / {@link projectZodErrorToDiff};
+ * we walk the issue's `path` against that snapshot. When the wire
+ * value can't be resolved (e.g., the schema rejected the entire
+ * top-level shape), the entry falls back to a path-only render.
+ */
+import type { z } from "zod";
+/**
+ * One field-level diff entry in a {@link WireShapeErrorPayload}. Wire
+ * shape matches the JSON contract in `docs/wire-validation-error-format.md`:
+ *
+ *   - `op` — `"+"` schema-unknown wire field (strict mode unrecognized
+ *     keys) / `"-"` schema-required missing on wire / `"~"` type
+ *     mismatch.
+ *   - `path` — JSON path from operation root with zero-indexed bracket
+ *     notation for arrays (`billingCycle.records[0].duration`) so it
+ *     matches `jq` semantics.
+ *   - `expected` — schema type as a short string (`"number"`,
+ *     `"string"`, `"undefined"`, …).
+ *   - `actual` — wire value type as a short string.
+ *   - `value?` — raw wire value rendered to a string, truncated to
+ *     {@link MAX_VALUE_LENGTH} chars with `…` on overflow. Omitted for
+ *     `+` (key absent from schema, value undefined) and `-` (field
+ *     absent from wire, value undefined). `body.data` never contains
+ *     the bearer, so no redaction is needed.
+ */
+export interface WireShapeDiffEntry {
+    op: "+" | "-" | "~";
+    path: string;
+    expected: string;
+    actual: string;
+    value?: string;
+}
+/**
+ * Structured payload returned by {@link buildWireShapeError}. Each
+ * service-level `WIRE_SHAPE_ERROR` carries this payload through its
+ * own domain-error class via the `cause` field. The CLI / MCP layers
+ * lift `message`, `hint`, and `diff` into the user-visible envelope.
+ */
+export interface WireShapeErrorPayload {
+    message: string;
+    hint: string;
+    diff: WireShapeDiffEntry[];
+}
+/**
+ * Maximum rendered length of a {@link WireShapeDiffEntry.value} field
+ * (per `docs/wire-validation-error-format.md` § Diff entries).
+ * Truncation appends `…` (a single ellipsis character, not three
+ * dots) to mark overflow.
+ */
+export declare const MAX_VALUE_LENGTH = 32;
+/**
+ * Verbatim hint string emitted alongside every `WIRE_SHAPE_ERROR`.
+ * Lifted into the CLI envelope's `hint` slot and the MCP error-text
+ * `Hint:` block; identical across all surfaces so an operator pattern-
+ * matches the message regardless of where it's encountered. The text
+ * comes directly from `docs/wire-validation-error-format.md` § Code +
+ * base fields (M2 / #281).
+ */
+export declare const WIRE_SHAPE_HINT = "wire shape doesn't match expected \u2014 this typically means Toptal changed the API; please file an issue at https://github.com/alexey-pelykh/ttctl/issues with the operation name and timestamp.";
+/**
+ * Build the field-level diff from a {@link z.ZodError}. Issues are
+ * projected per {@link issueToDiffEntries} and sorted deterministically
+ * per {@link compareDiffEntries} so two runs against the same drifted
+ * wire response produce byte-identical output (load-bearing for
+ * snapshot tests and CI grep-fu).
+ *
+ * `wireData` is the original `body.data` snapshot that failed
+ * validation — walking it against each issue's `path` recovers the
+ * actual wire value (Zod v4 strips `input` from public issues; see
+ * file header). Pass `undefined` only in tests / migration paths
+ * where the snapshot is unavailable; entries will degrade to path-
+ * only render in that case.
+ *
+ * Exported for unit tests; callers should prefer
+ * {@link buildWireShapeError} which composes the full payload.
+ */
+export declare function projectZodErrorToDiff(error: z.ZodError, wireData?: unknown): WireShapeDiffEntry[];
+/**
+ * Compose the `message` line of a `WIRE_SHAPE_ERROR` per
+ * `docs/wire-validation-error-format.md` § Code + base fields. The
+ * pluralisation is wire-stable (`1 field issue` vs `2 field issues`)
+ * so snapshot tests don't need locale-aware matchers.
+ *
+ * Exported for unit tests; callers should prefer
+ * {@link buildWireShapeError} which composes the full payload.
+ */
+export declare function buildWireShapeMessage(operationName: string, diffEntryCount: number): string;
+/**
+ * Convert a {@link z.ZodError} from a failed `schema.parse(body.data)`
+ * call into the full {@link WireShapeErrorPayload}. The payload is
+ * stable across surfaces (CLI envelope, MCP error text) and round-
+ * trips through JSON without redaction (body.data never carries the
+ * bearer).
+ *
+ * Each service's `callGateway` / `callTalentProfile` helper wraps the
+ * payload's `message` into its own domain-error class with
+ * `code: "WIRE_SHAPE_ERROR"` and `cause: zodError`; the CLI / MCP
+ * layers reconstruct the diff from `cause` when rendering.
+ *
+ * Pass `wireData` (the original `body.data` snapshot) so the diff
+ * can recover actual wire values via path walk — Zod v4 strips the
+ * `input` field from public issues, so the snapshot is the only way
+ * to render `actual` / `value` for non-`unrecognized_keys` entries.
+ *
+ * Z-3 (#286) wires the mechanism; no production op has `schema`
+ * passed in yet (Z-4 / #288 ships the first beachhead).
+ */
+export declare function buildWireShapeError(operationName: string, error: z.ZodError, wireData?: unknown): WireShapeErrorPayload;
+//# sourceMappingURL=wire-shape.d.ts.map

package/dist/lib/wire-shape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire-shape.d.ts","sourceRoot":"","sources":["../../src/lib/wire-shape.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,kBAAkB,EAAE,CAAC;CAC5B;AAED;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAEnC;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,uMACqK,CAAC;AAqRlM;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,CAAC,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,kBAAkB,EAAE,CAOjG;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,aAAa,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM,CAG3F;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,mBAAmB,CACjC,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,CAAC,CAAC,QAAQ,EACjB,QAAQ,CAAC,EAAE,OAAO,GACjB,qBAAqB,CAOvB"}