@ttctl/core 0.0.0 → 0.1.0-rc.1

package/dist/lib/date.js

@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+/**
+ * Typed error thrown by {@link parseDateInput} for malformed user input.
+ * Callers render the standard `<command> failed (<code>): <message>` shape
+ * and exit non-zero before any network call is made.
+ */
+export class DateInputError extends Error {
+    code;
+    name = "DateInputError";
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+const ISO_DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
+const YEAR_ONLY_RE = /^(\d{4})$/;
+/**
+ * Parse a free-form date flag value into a {@link ParsedDate}.
+ *
+ * Accepts:
+ * - **ISO-8601 date** (`YYYY-MM-DD`, e.g. `2023-01-15`) — preserves all three
+ *   fields. Validates the date is a real calendar date (rejects 2023-02-30,
+ *   2023-13-01, etc.).
+ * - **Year-only** (`YYYY`, e.g. `2023`) — defaults `month` and `day` to `1`
+ *   per issue #74's "internally treated as January 1st" rule.
+ *
+ * Throws {@link DateInputError} with code `INVALID_DATE` on:
+ * - Empty / non-string input
+ * - Format that matches neither shape
+ * - Out-of-range year (rejects years before 1900 or after the current year + 30
+ *   to catch obvious typos like `203` or `20230` being written as a YYYY)
+ * - Out-of-range month or day for a real calendar date
+ *
+ * The helper is pure — no I/O — so it can be unit-tested directly.
+ *
+ * @param raw - the raw flag value as supplied by the user
+ * @param flagName - the user-facing flag name (e.g. `"from"`, `"issued"`),
+ *   surfaced in error messages so the user knows which flag is wrong
+ */
+export function parseDateInput(raw, flagName) {
+    if (typeof raw !== "string" || raw.length === 0) {
+        throw new DateInputError("INVALID_DATE", `--${flagName}: expected ISO-8601 date (YYYY-MM-DD) or year (YYYY); got empty input`);
+    }
+    const trimmed = raw.trim();
+    const isoMatch = ISO_DATE_RE.exec(trimmed);
+    if (isoMatch !== null) {
+        const year = Number(isoMatch[1]);
+        const month = Number(isoMatch[2]);
+        const day = Number(isoMatch[3]);
+        validateYear(year, flagName, trimmed);
+        validateMonth(month, flagName, trimmed);
+        validateDay(year, month, day, flagName, trimmed);
+        return { year, month, day };
+    }
+    const yearMatch = YEAR_ONLY_RE.exec(trimmed);
+    if (yearMatch !== null) {
+        const year = Number(yearMatch[1]);
+        validateYear(year, flagName, trimmed);
+        return { year, month: 1, day: 1 };
+    }
+    throw new DateInputError("INVALID_DATE", `--${flagName}: expected ISO-8601 date (YYYY-MM-DD) or year (YYYY); got "${trimmed}"`);
+}
+/**
+ * Year sanity check. The issue spec says "ISO-8601 (`2023-01-15`) or
+ * year-only (`2023`)" — anything dramatically before or after the
+ * professional-history range is almost certainly a typo. We use a loose
+ * 1900..(currentYear+30) window so the helper isn't a maintenance burden
+ * but still catches `203` (a typo for `2023`) and `20230` (a typo too).
+ */
+function validateYear(year, flagName, raw) {
+    const currentYear = new Date().getUTCFullYear();
+    if (year < 1900 || year > currentYear + 30) {
+        throw new DateInputError("INVALID_DATE", `--${flagName}: year ${year.toString()} is out of plausible range (1900..${(currentYear + 30).toString()}); got "${raw}"`);
+    }
+}
+function validateMonth(month, flagName, raw) {
+    if (month < 1 || month > 12) {
+        throw new DateInputError("INVALID_DATE", `--${flagName}: month ${month.toString()} is out of range (1..12); got "${raw}"`);
+    }
+}
+/**
+ * Validate `day` falls within the given `month` of the given `year`. Uses
+ * `Date` round-tripping rather than a hand-rolled days-per-month table so
+ * leap-year edge cases (Feb 29 of a leap year, NOT of a non-leap year) are
+ * handled correctly.
+ *
+ * `Date.UTC(year, monthZeroIndexed, day)` returns NaN for impossible dates
+ * but more importantly silently rolls over (e.g. `Date.UTC(2023, 1, 30)` =
+ * March 2). The reconstruction check catches the rollover.
+ */
+function validateDay(year, month, day, flagName, raw) {
+    if (day < 1 || day > 31) {
+        throw new DateInputError("INVALID_DATE", `--${flagName}: day ${day.toString()} is out of range (1..31); got "${raw}"`);
+    }
+    const utc = Date.UTC(year, month - 1, day);
+    const reconstructed = new Date(utc);
+    if (reconstructed.getUTCFullYear() !== year ||
+        reconstructed.getUTCMonth() !== month - 1 ||
+        reconstructed.getUTCDate() !== day) {
+        throw new DateInputError("INVALID_DATE", `--${flagName}: ${raw} is not a real calendar date`);
+    }
+}
+//# sourceMappingURL=date.js.map

package/dist/lib/date.js.map

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

package/dist/lib/diagnostic-log.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Diagnostic log level controlling transport-side observability emitted
+ * to stderr (issue #139). Three states:
+ *
+ * - `"none"` — default; all log functions are no-ops. The disabled path
+ *   is constant-folded against the module-scoped `currentLevel` so
+ *   the cost is a single integer comparison per transport call.
+ * - `"verbose"` — emit one line per transport request and one line per
+ *   response, of shape: `POST <url> operation=<op>` and
+ *   `<status> <reasonPhrase> (elapsedMs=<n>)`. Suitable for "what is
+ *   the CLI doing" diagnostics without exposing wire content.
+ * - `"debug"` — emit a single JSON-encoded record per request and per
+ *   response, including redacted headers and redacted body. Suitable
+ *   for paste-into-issue debugging. The bearer token (in the
+ *   `authorization` header) and any cookie values are redacted before
+ *   serialization per the `redact` module.
+ *
+ * Output channel is `process.stderr` exclusively (AC #5 of issue #139).
+ * The data channel (`process.stdout`, the json/yaml/pretty envelopes
+ * locked under #126 / #128) is never touched by this module.
+ */
+export type DiagnosticLevel = "none" | "verbose" | "debug";
+/**
+ * Set the diagnostic level. Called by the CLI's `preAction` hook once
+ * per invocation when `--verbose` or `--debug` is present. Setting
+ * `"none"` (or omitting the call) keeps the disabled path active.
+ *
+ * Precedence (for the CLI hook, not enforced here): `--debug` wins over
+ * `--verbose` if both are passed. The decision lives in `program.ts`;
+ * this function takes whatever level the caller computed.
+ */
+export declare function setDiagnosticLogger(level: DiagnosticLevel): void;
+/**
+ * Read the captured diagnostic level. Returns `"none"` when no level
+ * has been set (the default).
+ */
+export declare function getDiagnosticLogger(): DiagnosticLevel;
+/**
+ * Reset to `"none"`. Tests call this in `beforeEach` to keep the
+ * module-scoped state isolated. Production code never needs to call
+ * this — the CLI's `preAction` hook sets the level once per invocation.
+ */
+export declare function resetDiagnosticLogger(): void;
+/**
+ * Information about a transport request, captured by the transport
+ * layer before the network call. Shape mirrors `TransportRequest` /
+ * `MultipartTransportRequest` but is decoupled from those types so
+ * future transport additions can log without circular dependencies.
+ *
+ * `body` is the parsed request envelope (operation name, variables) —
+ * NOT the JSON-stringified wire bytes. Redaction is applied by this
+ * module on emission.
+ */
+export interface RequestLogInfo {
+    surface: string;
+    endpoint: string;
+    transport: "stock" | "impersonated" | "impersonated-multipart";
+    method: string;
+    operationName: string;
+    headers: Record<string, string>;
+    body: unknown;
+    /**
+     * Multipart upload metadata for `impersonated-multipart` requests:
+     * the file slot labels and the variable paths they bind to. The
+     * binary contents of the files are NOT included (intentionally —
+     * binary content is not useful in a diagnostic trace).
+     */
+    multipart?: {
+        files: string[];
+        map: Record<string, string[]>;
+    };
+}
+/**
+ * Information about a transport response, captured AFTER the network
+ * call completes. `body` is the parsed response envelope (when JSON)
+ * or the raw text (when the response was not JSON). `elapsedMs` is
+ * `performance.now()`-derived monotonic elapsed milliseconds from
+ * request start, so it stays accurate across wall-clock adjustments
+ * during the call.
+ */
+export interface ResponseLogInfo {
+    surface: string;
+    endpoint: string;
+    operationName: string;
+    status: number;
+    headers: Record<string, string>;
+    body: unknown;
+    elapsedMs: number;
+}
+/**
+ * Emit a `--verbose` / `--debug` line for a transport REQUEST.
+ *
+ * - `"none"`: no-op (single comparison, no allocation).
+ * - `"verbose"`: emits one line `POST <endpoint> operation=<op>`.
+ * - `"debug"`: emits one JSON-encoded line containing the redacted
+ *   request envelope: surface, transport, endpoint, method, operation
+ *   name, redacted headers, redacted body, optional multipart map.
+ *   Bearer token (`authorization` header) and cookie values are
+ *   replaced with `***REDACTED***` per the `redact` module BEFORE
+ *   JSON.stringify, so the serialized line cannot leak any secret.
+ *
+ * Writes to `process.stderr` only; never touches `process.stdout`.
+ */
+export declare function logTransportRequest(info: RequestLogInfo): void;
+/**
+ * Emit a `--verbose` / `--debug` line for a transport RESPONSE.
+ *
+ * - `"none"`: no-op.
+ * - `"verbose"`: emits one line `<status> <reasonPhrase> (elapsedMs=<n>)`.
+ *   `<reasonPhrase>` is derived from {@link HTTP_REASON_PHRASES}; for
+ *   uncatalogued status codes (rare; non-standard 7xx etc.), the
+ *   phrase is `"-"`.
+ * - `"debug"`: emits one JSON-encoded line containing the redacted
+ *   response envelope: surface, endpoint, operation name, status,
+ *   redacted headers, redacted body, elapsed milliseconds. The
+ *   response body is redacted because Toptal occasionally echoes
+ *   session-bearing fields back to the caller (per issue #139 spec).
+ *
+ * Writes to `process.stderr` only.
+ */
+export declare function logTransportResponse(info: ResponseLogInfo): void;
+/**
+ * Information about a transport retry event, captured when the resilience
+ * loop decides to back off and re-issue the request. `reason` discriminates
+ * the trigger (429 rate-limit, 5xx transient server error, or a per-attempt
+ * timeout). `delayMs` is the wait the loop is about to sleep for; `attempt`
+ * is the 1-indexed retry counter (1 = first retry after the initial attempt).
+ *
+ * `retryAfterMs` is set only when the server's `Retry-After` header was
+ * parsed and honored — operators reading the trace can distinguish
+ * server-driven backoff from client-side exponential backoff.
+ */
+export interface RetryLogInfo {
+    surface: string;
+    endpoint: string;
+    operationName: string;
+    attempt: number;
+    reason: "rate-limit" | "server-error" | "timeout";
+    status?: number;
+    delayMs: number;
+    retryAfterMs?: number;
+}
+/**
+ * Emit a `--verbose` / `--debug` line for a transport RETRY event,
+ * fired by the resilience layer (issue #229) when it decides to back off
+ * and re-issue a request after a 429, retryable 5xx, or per-attempt
+ * timeout.
+ *
+ * - `"none"`: no-op.
+ * - `"verbose"`: emits one line summarising the retry decision.
+ * - `"debug"`: emits one JSON-encoded record with full retry context
+ *   (surface, endpoint, operation, attempt, reason, status, delays).
+ *
+ * Bearer-absence: this event shape carries NO authorization header and NO
+ * body payload — only retry metadata — so there is no redaction path
+ * needed.
+ */
+export declare function logTransportRetry(info: RetryLogInfo): void;
+//# sourceMappingURL=diagnostic-log.d.ts.map

package/dist/lib/diagnostic-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostic-log.d.ts","sourceRoot":"","sources":["../../src/lib/diagnostic-log.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;AAe3D;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAEhE;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,eAAe,CAErD;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,OAAO,GAAG,cAAc,GAAG,wBAAwB,CAAC;IAC/D,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,OAAO,CAAC;IACd;;;;;OAKG;IACH,SAAS,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;KAAE,CAAC;CAChE;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,OAAO,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI,CAmB9D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,eAAe,GAAG,IAAI,CAqBhE;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,YAAY,GAAG,cAAc,GAAG,SAAS,CAAC;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAuB1D"}

package/dist/lib/diagnostic-log.js

@@ -0,0 +1,186 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+import { redactBody, redactHeaders } from "./redact.js";
+/**
+ * Module-scoped diagnostic level. Mirrors the `dry-run.ts` /
+ * `config-context.ts` pattern: one global holder, set once by the CLI's
+ * `preAction` hook, read by transport entry points. Module isolation
+ * keeps each call site's signature focused on its domain (no logger
+ * parameter threading) while exposing a single place to test the
+ * captured value.
+ *
+ * Tests MUST call {@link resetDiagnosticLogger} in `beforeEach` to
+ * avoid state bleeding across cases.
+ */
+let currentLevel = "none";
+/**
+ * Set the diagnostic level. Called by the CLI's `preAction` hook once
+ * per invocation when `--verbose` or `--debug` is present. Setting
+ * `"none"` (or omitting the call) keeps the disabled path active.
+ *
+ * Precedence (for the CLI hook, not enforced here): `--debug` wins over
+ * `--verbose` if both are passed. The decision lives in `program.ts`;
+ * this function takes whatever level the caller computed.
+ */
+export function setDiagnosticLogger(level) {
+    currentLevel = level;
+}
+/**
+ * Read the captured diagnostic level. Returns `"none"` when no level
+ * has been set (the default).
+ */
+export function getDiagnosticLogger() {
+    return currentLevel;
+}
+/**
+ * Reset to `"none"`. Tests call this in `beforeEach` to keep the
+ * module-scoped state isolated. Production code never needs to call
+ * this — the CLI's `preAction` hook sets the level once per invocation.
+ */
+export function resetDiagnosticLogger() {
+    currentLevel = "none";
+}
+/**
+ * Emit a `--verbose` / `--debug` line for a transport REQUEST.
+ *
+ * - `"none"`: no-op (single comparison, no allocation).
+ * - `"verbose"`: emits one line `POST <endpoint> operation=<op>`.
+ * - `"debug"`: emits one JSON-encoded line containing the redacted
+ *   request envelope: surface, transport, endpoint, method, operation
+ *   name, redacted headers, redacted body, optional multipart map.
+ *   Bearer token (`authorization` header) and cookie values are
+ *   replaced with `***REDACTED***` per the `redact` module BEFORE
+ *   JSON.stringify, so the serialized line cannot leak any secret.
+ *
+ * Writes to `process.stderr` only; never touches `process.stdout`.
+ */
+export function logTransportRequest(info) {
+    if (currentLevel === "none")
+        return;
+    if (currentLevel === "verbose") {
+        process.stderr.write(`${info.method} ${info.endpoint} operation=${info.operationName}\n`);
+        return;
+    }
+    // debug path: full request envelope with redaction
+    const record = {
+        kind: "request",
+        surface: info.surface,
+        transport: info.transport,
+        endpoint: info.endpoint,
+        method: info.method,
+        operationName: info.operationName,
+        headers: redactHeaders(info.headers),
+        body: redactBody(info.body),
+        ...(info.multipart !== undefined ? { multipart: info.multipart } : {}),
+    };
+    process.stderr.write(`${JSON.stringify(record)}\n`);
+}
+/**
+ * Emit a `--verbose` / `--debug` line for a transport RESPONSE.
+ *
+ * - `"none"`: no-op.
+ * - `"verbose"`: emits one line `<status> <reasonPhrase> (elapsedMs=<n>)`.
+ *   `<reasonPhrase>` is derived from {@link HTTP_REASON_PHRASES}; for
+ *   uncatalogued status codes (rare; non-standard 7xx etc.), the
+ *   phrase is `"-"`.
+ * - `"debug"`: emits one JSON-encoded line containing the redacted
+ *   response envelope: surface, endpoint, operation name, status,
+ *   redacted headers, redacted body, elapsed milliseconds. The
+ *   response body is redacted because Toptal occasionally echoes
+ *   session-bearing fields back to the caller (per issue #139 spec).
+ *
+ * Writes to `process.stderr` only.
+ */
+export function logTransportResponse(info) {
+    if (currentLevel === "none")
+        return;
+    if (currentLevel === "verbose") {
+        const phrase = HTTP_REASON_PHRASES[info.status] ?? "-";
+        process.stderr.write(`${info.status.toString()} ${phrase} (elapsedMs=${info.elapsedMs.toFixed(0)}, operation=${info.operationName})\n`);
+        return;
+    }
+    // debug path
+    const record = {
+        kind: "response",
+        surface: info.surface,
+        endpoint: info.endpoint,
+        operationName: info.operationName,
+        status: info.status,
+        headers: redactHeaders(info.headers),
+        body: redactBody(info.body),
+        elapsedMs: Math.round(info.elapsedMs),
+    };
+    process.stderr.write(`${JSON.stringify(record)}\n`);
+}
+/**
+ * Emit a `--verbose` / `--debug` line for a transport RETRY event,
+ * fired by the resilience layer (issue #229) when it decides to back off
+ * and re-issue a request after a 429, retryable 5xx, or per-attempt
+ * timeout.
+ *
+ * - `"none"`: no-op.
+ * - `"verbose"`: emits one line summarising the retry decision.
+ * - `"debug"`: emits one JSON-encoded record with full retry context
+ *   (surface, endpoint, operation, attempt, reason, status, delays).
+ *
+ * Bearer-absence: this event shape carries NO authorization header and NO
+ * body payload — only retry metadata — so there is no redaction path
+ * needed.
+ */
+export function logTransportRetry(info) {
+    if (currentLevel === "none")
+        return;
+    if (currentLevel === "verbose") {
+        const statusPart = info.status !== undefined ? ` status=${info.status.toString()}` : "";
+        const retryAfterPart = info.retryAfterMs !== undefined ? ` retryAfterMs=${info.retryAfterMs.toString()}` : "";
+        process.stderr.write(`retry attempt=${info.attempt.toString()} reason=${info.reason}${statusPart} ` +
+            `delayMs=${info.delayMs.toString()}${retryAfterPart} operation=${info.operationName}\n`);
+        return;
+    }
+    const record = {
+        kind: "retry",
+        surface: info.surface,
+        endpoint: info.endpoint,
+        operationName: info.operationName,
+        attempt: info.attempt,
+        reason: info.reason,
+        delayMs: info.delayMs,
+    };
+    if (info.status !== undefined)
+        record["status"] = info.status;
+    if (info.retryAfterMs !== undefined)
+        record["retryAfterMs"] = info.retryAfterMs;
+    process.stderr.write(`${JSON.stringify(record)}\n`);
+}
+/**
+ * Minimal table of HTTP reason phrases used by the `"verbose"` log
+ * line. Not exhaustive — covers the status codes TTCtl's transport
+ * paths plausibly observe in production (mobile gateway, Cloudflare
+ * surfaces, multipart upload). Uncatalogued codes render as `"-"`,
+ * which is sufficient signal for verbose-mode triage.
+ */
+const HTTP_REASON_PHRASES = {
+    200: "OK",
+    201: "Created",
+    204: "No Content",
+    301: "Moved Permanently",
+    302: "Found",
+    304: "Not Modified",
+    400: "Bad Request",
+    401: "Unauthorized",
+    403: "Forbidden",
+    404: "Not Found",
+    405: "Method Not Allowed",
+    408: "Request Timeout",
+    409: "Conflict",
+    410: "Gone",
+    413: "Payload Too Large",
+    415: "Unsupported Media Type",
+    422: "Unprocessable Entity",
+    429: "Too Many Requests",
+    500: "Internal Server Error",
+    502: "Bad Gateway",
+    503: "Service Unavailable",
+    504: "Gateway Timeout",
+};
+//# sourceMappingURL=diagnostic-log.js.map

package/dist/lib/diagnostic-log.js.map

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

package/dist/lib/package-version.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Resolve the running package's version by reading the sibling
+ * `package.json` of the calling module. Pass `import.meta.url` from the
+ * caller; the helper walks from `<dir>/../package.json` (the canonical
+ * `dist/<file>.js` → `package.json` layout used by every workspace
+ * package in this repo).
+ *
+ * Falls back to `0.0.0` if the file cannot be read or parsed —
+ * defensive against partial installs / chmod weirdness, never throws.
+ * `0.0.0` matches the unstamped placeholder used in source today
+ * (e.g., `packages/cli/src/program.ts:107`, `packages/mcp/src/server.ts`),
+ * so the fallback never surfaces a discontinuity to consumers.
+ *
+ * Used by the kill-switch wire-up sites (#312) to supply the running
+ * version to `checkKillSwitch`, and is available for any future
+ * version-aware feature.
+ */
+export declare function readPackageVersion(metaUrl: string): string;
+//# sourceMappingURL=package-version.d.ts.map

package/dist/lib/package-version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-version.d.ts","sourceRoot":"","sources":["../../src/lib/package-version.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAa1D"}

package/dist/lib/package-version.js

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Resolve the running package's version by reading the sibling
+ * `package.json` of the calling module. Pass `import.meta.url` from the
+ * caller; the helper walks from `<dir>/../package.json` (the canonical
+ * `dist/<file>.js` → `package.json` layout used by every workspace
+ * package in this repo).
+ *
+ * Falls back to `0.0.0` if the file cannot be read or parsed —
+ * defensive against partial installs / chmod weirdness, never throws.
+ * `0.0.0` matches the unstamped placeholder used in source today
+ * (e.g., `packages/cli/src/program.ts:107`, `packages/mcp/src/server.ts`),
+ * so the fallback never surfaces a discontinuity to consumers.
+ *
+ * Used by the kill-switch wire-up sites (#312) to supply the running
+ * version to `checkKillSwitch`, and is available for any future
+ * version-aware feature.
+ */
+export function readPackageVersion(metaUrl) {
+    try {
+        const dir = dirname(fileURLToPath(metaUrl));
+        const candidate = join(dir, "..", "package.json");
+        const raw = readFileSync(candidate, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.version === "string" && parsed.version.length > 0) {
+            return parsed.version;
+        }
+    }
+    catch {
+        // Fall through to the placeholder default.
+    }
+    return "0.0.0";
+}
+//# sourceMappingURL=package-version.js.map

package/dist/lib/package-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-version.js","sourceRoot":"","sources":["../../src/lib/package-version.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,oCAAoC;AAEpC,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAe;IAChD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,OAAO,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC;QAC5C,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC;QAClD,MAAM,GAAG,GAAG,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QAC7C,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAA0B,CAAC;QACxD,IAAI,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpE,OAAO,MAAM,CAAC,OAAO,CAAC;QACxB,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,2CAA2C;IAC7C,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}