@indigoai-us/hq-cli 5.108.5 → 5.108.7

package/dist/utils/feedback-logs.d.ts

@@ -0,0 +1,329 @@
+/**
+ * Debug-log and state capture for `hq feedback` submissions.
+ *
+ * A bug report is far cheaper to triage when the submitter's recent log output
+ * travels with it. This module collects two bounded, redacted classes of
+ * evidence from the user's `~/.hq` directory and hands them to the feedback
+ * command, which attaches them to the `diagnostics` blob on the submission:
+ *
+ *   - LOG TAILS (`files`) — the end of each rolling log. One file covers more
+ *     than its name suggests: `logs/hq-sync.log` is the shared diagnostic log
+ *     for BOTH the hq-cloud sync engine and the desktop sync app, which write
+ *     to it through the same path, and its ROTATED generations
+ *     (`hq-sync.log.1`, `.2`, `.3`) are eligible too — just after a rotation
+ *     the active file is nearly empty and the history lives in `.1`.
+ *     `logs/mcp-registry.log` is the CLI's own append-only MCP audit trail.
+ *     Any future `*.log`/`*.jsonl` dropped into `~/.hq/logs/` is picked up
+ *     automatically.
+ *
+ *   - STATE SNAPSHOTS (`state`) — small JSON files that describe where sync
+ *     and client health currently stand: the in-flight sync phase and conflict
+ *     count, the client-health failure streak, the per-company sync journal
+ *     locators. These are tiny and answer the questions a log tail usually
+ *     cannot ("was it mid-pull?", "how many conflicts?", "how long since the
+ *     last successful sync?"), so they are collected FIRST and the log budget
+ *     takes what remains.
+ *
+ * Contrast with `local-files-overview.ts`, which deliberately sends only
+ * metadata (existence, size, age, error-line counts) and NEVER a line of log
+ * text. That module feeds the BACKGROUND client-health heartbeat, where the
+ * user has not asked for anything and content would be surveillance. This
+ * module runs only on an EXPLICIT, user-initiated `hq feedback` invocation,
+ * where the user is asking us to look at their problem, so content is both
+ * expected and useful. The two must not be merged.
+ *
+ * Three hard safety properties, each with a regression test:
+ *
+ *   1. ALLOWLIST, NOT A SCAN. `~/.hq` also holds `cognito-tokens.json`,
+ *      `deploy-passwords.json`, and `secrets-cache/`. Only `*.log` files
+ *      directly inside `~/.hq/logs/` plus the two known root-level boot logs
+ *      are ever eligible. A recursive walk over `~/.hq` is a credential leak
+ *      and must never be introduced here.
+ *
+ *   2. NO SYMLINKS. Eligibility is decided with `lstat`, and a candidate must
+ *      be a REGULAR file. Without this, a symlink named `anything.log` inside
+ *      `~/.hq/logs/` pointing at `~/.hq/cognito-tokens.json` would satisfy the
+ *      allowlist and exfiltrate the user's tokens. `stat` would follow the link
+ *      and report a regular file — `lstat` is the whole guard.
+ *
+ *   3. REDACTION IS APPLIED BEFORE BUDGETING. Every tail passes through
+ *      `redactLogText` before it is measured or returned, so no code path can
+ *      emit an unredacted span. Redaction is defence in depth, not the primary
+ *      control — properties 1 and 2 are what keep secrets out.
+ *
+ * Every filesystem operation is independently best-effort: a missing file, a
+ * permission error, or a file that disappears mid-read degrades that one entry
+ * and never throws. Collecting diagnostics must never break a bug report.
+ */
+/**
+ * Ceiling on the total redacted log text attached to one submission.
+ *
+ * The server caps the WHOLE feedback request body at 64 KiB, so this is only
+ * an upper bound — the caller passes a smaller `budgetBytes` computed from the
+ * headroom actually left after the title, body, and the rest of diagnostics.
+ * See `submitFeedback` in `../commands/feedback.ts`.
+ */
+export declare const FEEDBACK_LOGS_MAX_TOTAL_BYTES: number;
+/** Per-file ceiling, so one noisy log cannot consume the entire budget. */
+export declare const FEEDBACK_LOGS_MAX_FILE_TAIL_BYTES: number;
+/**
+ * Below this much remaining budget a tail is too short to be worth reading,
+ * so the file is recorded as skipped rather than truncated into noise.
+ */
+export declare const FEEDBACK_LOGS_MIN_USEFUL_BYTES = 1024;
+/**
+ * Ceiling on how many skipped entries are recorded.
+ *
+ * `skipped` is metadata, not payload, so it was originally left outside the
+ * byte budget — which made it unbounded. An installation with hundreds of log
+ * files produced hundreds of `{name, reason}` objects and a blob several times
+ * the requested budget; `attachDebugLogs` then dropped the whole thing to stay
+ * under the request cap, so the user with the MOST log history got the LEAST
+ * evidence. The overflow count preserves the signal without the bytes.
+ */
+export declare const FEEDBACK_MAX_SKIPPED_ENTRIES = 25;
+/** Subdirectory of `~/.hq` whose log files are eligible. Not recursive. */
+export declare const FEEDBACK_LOGS_DIRNAME = "logs";
+/**
+ * Eligible extensions inside `~/.hq/logs/`. `.jsonl` is included because the
+ * CLI's MCP registry audit trail is JSON-lines, not plain text.
+ */
+export declare const FEEDBACK_LOG_EXTENSIONS: readonly string[];
+/**
+ * True for a log filename, including a ROTATED generation.
+ *
+ * The desktop/sync logger keeps 32 MiB x 3 generations named `hq-sync.log.1`,
+ * `.2`, `.3` (see hq-desktop-core `logfile.rs`). A plain "ends with .log"
+ * test misses every one of them — and they matter most in the worst case: just
+ * after a rotation the active log is nearly empty and all the history a
+ * triager needs sits in `.1`.
+ */
+export declare function isEligibleLogName(name: string): boolean;
+/** Per-state-file ceiling. These are status documents, not streams. */
+export declare const FEEDBACK_STATE_MAX_FILE_BYTES: number;
+/**
+ * Ceiling on all state snapshots combined. Deliberately a small slice of the
+ * overall budget: state is dense but finite, and the rest belongs to logs.
+ */
+export declare const FEEDBACK_STATE_MAX_TOTAL_BYTES: number;
+/**
+ * State files at the `~/.hq` ROOT that are eligible, by EXACT name.
+ *
+ * The root is where `cognito-tokens.json`, `deploy-passwords.json`, and
+ * `secrets-cache/` live, so it is never globbed. Adding a name here is a
+ * deliberate act: confirm the file carries no credential before listing it.
+ */
+export declare const FEEDBACK_STATE_FILENAMES: readonly string[];
+/**
+ * Per-company sync journal LOCATORS (`sync-journal.<slug>.json`) are also
+ * eligible. Matched by an exact prefix AND a `.json` suffix, which is what
+ * excludes the multi-hundred-megabyte `…json.last-good` snapshots sitting
+ * beside them. No credential file at the root carries this prefix.
+ */
+export declare const FEEDBACK_STATE_JOURNAL_PREFIX = "sync-journal.";
+/**
+ * `~/.hq/locks/` — held operation locks and background-work claims.
+ *
+ * The highest-signal thing in the whole collection, and the one place where the
+ * FILENAME is the diagnosis: a `…stale-claim…` entry names the operation, the
+ * process that abandoned it, and the fact that the claim went stale. That is
+ * the answer to "sync/reindex is stuck", which is otherwise invisible in a log
+ * tail because a hung process writes nothing. Contents are tiny (tens to a
+ * couple hundred bytes) and included too.
+ */
+export declare const FEEDBACK_LOCKS_DIRNAME = "locks";
+/**
+ * `~/.hq/jobs/` — scheduled-job status, reconcile results, and probe attempts.
+ * Nested one or two levels (`jobs/probes/<job>/last-attempt.json`), so this is
+ * the only source needing a directory walk. See {@link walkJsonFiles} for the
+ * bounds that walk carries.
+ */
+export declare const FEEDBACK_JOBS_DIRNAME = "jobs";
+/** Per-entry ceiling for a lock file. Their value is the name plus a little context. */
+export declare const FEEDBACK_LOCK_MAX_FILE_BYTES = 512;
+/**
+ * Bounds on the `jobs/` walk. Depth 3 reaches
+ * `jobs/probes/<job>/last-attempt.json`; the file cap stops a pathological
+ * tree from crowding out logs.
+ */
+export declare const FEEDBACK_JOBS_MAX_DEPTH = 3;
+export declare const FEEDBACK_JOBS_MAX_FILES = 20;
+/** Ceiling on how many lock entries are collected. */
+export declare const FEEDBACK_LOCKS_MAX_FILES = 20;
+/**
+ * Log files that live at the root of `~/.hq` rather than under `logs/`.
+ * Listed explicitly — the root directory holds credentials and must never be
+ * enumerated by pattern.
+ */
+export declare const FEEDBACK_ROOT_LOG_FILENAMES: readonly string[];
+/** Why a discovered log file contributed nothing to the submission. */
+export type SkipReason = "budget" | "empty" | "unreadable";
+export interface LogTail {
+    /** Path relative to `~/.hq`, e.g. `logs/hq-sync.log`. Never absolute. */
+    name: string;
+    /** Full on-disk size, even when only a tail was included. */
+    sizeBytes: number;
+    /** Last-modified time, or null when it could not be read. */
+    modifiedIso: string | null;
+    /** Byte length of `tail` after redaction. */
+    includedBytes: number;
+    /** True when `tail` is a suffix of a larger file. */
+    truncated: boolean;
+    /** How many spans redaction replaced. Non-zero is expected and fine. */
+    redactions: number;
+    /** The redacted tail itself. */
+    tail: string;
+}
+/** A small JSON status document included whole (or head-truncated). */
+export interface StateSnapshot {
+    /** Path relative to `~/.hq`, e.g. `sync-progress.json`. Never absolute. */
+    name: string;
+    sizeBytes: number;
+    modifiedIso: string | null;
+    includedBytes: number;
+    /** True when the file exceeded the per-file ceiling and was cut. */
+    truncated: boolean;
+    redactions: number;
+    /** The redacted document text. */
+    content: string;
+}
+export interface FeedbackLogsBlob {
+    /** The budget this collection was given, for interpreting truncation. */
+    budgetBytes: number;
+    /** Included tails, newest-modified first. */
+    files: LogTail[];
+    /** Sync and client-health status documents. Collected before the tails. */
+    state: StateSnapshot[];
+    /**
+     * Discovered files that contributed nothing, and why. Capped at
+     * {@link FEEDBACK_MAX_SKIPPED_ENTRIES}; see `skippedOverflow`.
+     */
+    skipped: Array<{
+        name: string;
+        reason: SkipReason;
+    }>;
+    /**
+     * How many further files were skipped but not listed individually. Absent
+     * when nothing overflowed.
+     */
+    skippedOverflow?: number;
+}
+export interface LogCandidate {
+    name: string;
+    absPath: string;
+    sizeBytes: number;
+    modifiedMs: number;
+}
+/**
+ * Replace every secret-shaped span in `text`. Returns the redacted text and a
+ * count of replacements, so triage can tell "no secrets present" from
+ * "redaction never ran".
+ */
+export declare function redactLogText(text: string): {
+    text: string;
+    redactions: number;
+};
+/**
+ * `true` unless the user disabled log capture via `HQ_FEEDBACK_LOGS`.
+ *
+ * Uses `?.trim() ||` rather than `??` on purpose: an env var that is SET BUT
+ * EMPTY must fall back to the default, and `??` would pass `""` through as a
+ * deliberate choice.
+ */
+export declare function feedbackLogsEnabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Enumerate eligible log files under `hqDir`.
+ *
+ * Eligibility is the allowlist described in the module header: `*.log` files
+ * directly inside `hqDir/logs/`, plus {@link FEEDBACK_ROOT_LOG_FILENAMES} at
+ * the root. Every candidate must be a REGULAR file by `lstat` — directories
+ * and, critically, symlinks are rejected. Returned newest-modified first so
+ * the most relevant log is offered the budget before older ones.
+ */
+export declare function discoverLogFiles(hqDir: string): LogCandidate[];
+/**
+ * Read the last `maxBytes` of a file.
+ *
+ * When the file is larger than the window, the first (partial) line is dropped
+ * so the tail always starts at a line boundary. Returns null if the file
+ * cannot be read.
+ */
+export declare function readLogTail(absPath: string, maxBytes: number): {
+    text: string;
+    truncated: boolean;
+} | null;
+/**
+ * Enumerate eligible state files at the `~/.hq` root.
+ *
+ * Two ways in, both narrow: an exact name in {@link FEEDBACK_STATE_FILENAMES},
+ * or the `sync-journal.<slug>.json` shape. As with logs, every candidate must
+ * be a REGULAR file by `lstat`, so a symlink cannot be used to reach a
+ * credential file through an eligible-looking name.
+ */
+export declare function discoverStateFiles(hqDir: string): LogCandidate[];
+/**
+ * Enumerate flat, non-recursive entries of a `~/.hq` subdirectory.
+ *
+ * Used for `locks/`, where every entry is eligible regardless of extension —
+ * the filename itself carries the diagnosis. As everywhere else in this module,
+ * `lstat` decides eligibility, so a symlink dropped into the directory is
+ * skipped rather than followed.
+ *
+ * Results are sorted NEWEST-FIRST and only then truncated to `maxFiles`, which
+ * is load-bearing rather than cosmetic. Sorting by name and cutting at the cap
+ * silently drops the most diagnostic entry: ordinary `operation-*.lock` files
+ * sort ahead of a `qmd-reindex-bg.claim…stale-claim…`, so an installation with
+ * more than `maxFiles` locks would have excluded exactly the entry this source
+ * exists to capture. Recency is the right proxy for relevance here, and it
+ * matches how log files are prioritised.
+ */
+export declare function discoverFlatDirFiles(hqDir: string, dirName: string, maxFiles: number): LogCandidate[];
+/**
+ * Walk a `~/.hq` subdirectory for `.json` files, bounded in BOTH depth and
+ * count.
+ *
+ * This is the module's only recursive traversal, so it is deliberately the
+ * most constrained. Three bounds, each load-bearing:
+ *
+ *   - `lstat` per entry, and recursion only into a REAL directory. A symlinked
+ *     directory is never followed, so a link at `jobs/x -> /home/user` cannot
+ *     turn a two-level walk into a scan of the home directory — where, as it
+ *     happens, `~/.codex/auth.json` and `~/.hq-agent/machine-creds.json` live.
+ *     This is the same guard the flat enumerations use, applied to directories
+ *     rather than files, and it is what keeps "walk a subtree" from being a
+ *     categorically riskier operation than the allowlists around it.
+ *   - `maxDepth`, so a deep tree cannot cost unbounded stat calls.
+ *   - `maxFiles`, so a wide tree cannot crowd the log budget.
+ *
+ * Entries are returned sorted by name for a stable, reviewable order.
+ */
+export declare function walkJsonFiles(hqDir: string, dirName: string, maxDepth: number, maxFiles: number): LogCandidate[];
+/**
+ * Read up to `maxBytes` from the START of a file. State documents are JSON,
+ * whose meaningful keys sit at the top, so a head is more useful than a tail.
+ * Returns null if the file cannot be read.
+ */
+export declare function readFileHead(absPath: string, maxBytes: number): {
+    text: string;
+    truncated: boolean;
+} | null;
+export interface CollectFeedbackLogsOptions {
+    /** Total redacted bytes this collection may emit. Clamped to the max. */
+    budgetBytes?: number;
+    /** Override `~/.hq` (tests). */
+    hqDir?: string;
+    /** Override the home directory used to derive `~/.hq` (tests). */
+    homeDir?: string;
+}
+/**
+ * Collect redacted `~/.hq` evidence within `budgetBytes`.
+ *
+ * State snapshots are taken first, capped by
+ * {@link FEEDBACK_STATE_MAX_TOTAL_BYTES}, because they are small and answer
+ * questions a log tail cannot. Log tails then take whatever budget remains.
+ *
+ * Returns `undefined` when nothing eligible exists at all, so the caller can
+ * omit the field entirely rather than attach an empty object. Never throws.
+ */
+export declare function collectFeedbackLogs(opts?: CollectFeedbackLogsOptions): FeedbackLogsBlob | undefined;
+//# sourceMappingURL=feedback-logs.d.ts.map