@meetless/mla 0.1.4

package/dist/commands/debug.js

@@ -0,0 +1,313 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseArgs = parseArgs;
+exports.runDebug = runDebug;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const readline = __importStar(require("readline"));
+const config_1 = require("../lib/config");
+const observability_1 = require("../lib/observability");
+const workspace_1 = require("../lib/workspace");
+const http_1 = require("../lib/http");
+const debug_bundle_1 = require("../lib/debug-bundle");
+const KNOWN_FLAGS = new Set([
+    "--trace-id",
+    "--out",
+    "--include-prompts",
+    "--include-diffs",
+    "--yes",
+    "-y",
+    "--no-backend",
+    "--command",
+    "--run-id",
+    "--session-id",
+    "--quiet",
+    "-q",
+]);
+const FLAGS_WITH_VALUES = new Set([
+    "--trace-id",
+    "--out",
+    "--command",
+    "--run-id",
+    "--session-id",
+]);
+// A value-bearing flag must be followed by a real value, never the next flag,
+// or an operator's "drop the value" typo silently changes intent.
+function takeValue(argv, i, flag) {
+    const v = argv[i + 1];
+    if (v === undefined) {
+        throw new Error(`Missing value for ${flag}`);
+    }
+    if (v.startsWith("-")) {
+        throw new Error(`Missing value for ${flag} (got the next flag ${v} instead)`);
+    }
+    return v;
+}
+function parseArgs(argv) {
+    const out = {
+        includePrompts: false,
+        includeDiffs: false,
+        yes: false,
+        noBackend: false,
+        quiet: false,
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        switch (a) {
+            case "--trace-id":
+                out.traceId = takeValue(argv, i, a);
+                i += 1;
+                break;
+            case "--out":
+                out.out = takeValue(argv, i, a);
+                i += 1;
+                break;
+            case "--command":
+                out.command = takeValue(argv, i, a);
+                i += 1;
+                break;
+            case "--run-id":
+                out.runId = takeValue(argv, i, a);
+                i += 1;
+                break;
+            case "--session-id":
+                out.sessionId = takeValue(argv, i, a);
+                i += 1;
+                break;
+            case "--include-prompts":
+                out.includePrompts = true;
+                break;
+            case "--include-diffs":
+                out.includeDiffs = true;
+                break;
+            case "--yes":
+            case "-y":
+                out.yes = true;
+                break;
+            case "--no-backend":
+                out.noBackend = true;
+                break;
+            case "--quiet":
+            case "-q":
+                out.quiet = true;
+                break;
+            default:
+                if (a.startsWith("-") && !KNOWN_FLAGS.has(a)) {
+                    throw new Error(`Unknown flag: ${a}. Supported: ${[...KNOWN_FLAGS].join(", ")}`);
+                }
+                throw new Error(`Unexpected argument: ${a}`);
+        }
+    }
+    if (!out.traceId) {
+        throw new Error("`mla debug bundle` requires --trace-id <id>");
+    }
+    return out;
+}
+// Default fetcher: ask control for an observability summary of the trace. There
+// is no such endpoint today, so this will normally fail; that is fine and
+// expected. The point of the seam is that it is fail-soft (any error becomes a
+// warning + a partial bundle) and that it lights up automatically the day
+// control grows the endpoint. A bundle never requires backend access (spec 6.7).
+const defaultBackendFetcher = async (traceId, opts, counts) => {
+    let cfg;
+    try {
+        cfg = (0, config_1.readConfig)();
+    }
+    catch (e) {
+        return {
+            summary: null,
+            langfuseProjectId: null,
+            warning: `backend summary skipped: no usable config (${errText(e)})`,
+        };
+    }
+    try {
+        const raw = await (0, http_1.get)(cfg, `/internal/v1/observability/trace/${traceId}`, 8000);
+        const summary = raw && typeof raw === "object" && "summary" in raw
+            ? (0, debug_bundle_1.redactValue)(raw.summary, opts, counts)
+            : (0, debug_bundle_1.redactValue)(raw, opts, counts);
+        const lf = raw && typeof raw === "object" && typeof raw.langfuseProjectId === "string"
+            ? raw.langfuseProjectId
+            : null;
+        return { summary, langfuseProjectId: lf, warning: null };
+    }
+    catch (e) {
+        return {
+            summary: null,
+            langfuseProjectId: null,
+            warning: `backend trace summary unavailable (${errText(e)}); bundle is partial ` +
+                `(local logs only). This is expected offline or against a backend ` +
+                `without the observability summary endpoint.`,
+        };
+    }
+};
+function errText(e) {
+    if (e instanceof Error)
+        return e.message;
+    return String(e);
+}
+// Interactive confirmation for the raw-payload opt-ins. Default reads from the
+// TTY. Non-interactive callers (no TTY) MUST pass --yes to include raw payloads;
+// otherwise we refuse rather than silently bundling sensitive content.
+async function confirmInteractive(prompt) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        const answer = await new Promise((resolve) => rl.question(prompt, resolve));
+        const norm = answer.trim().toLowerCase();
+        return norm === "y" || norm === "yes";
+    }
+    finally {
+        rl.close();
+    }
+}
+async function runDebug(argv, deps = {}) {
+    const [sub, ...rest] = argv;
+    if (sub !== "bundle") {
+        console.error(`Unknown debug subcommand: ${sub ?? "(none)"}. Usage: mla debug bundle --trace-id <id>`);
+        return 2;
+    }
+    let flags;
+    try {
+        flags = parseArgs(rest);
+    }
+    catch (e) {
+        console.error(errText(e));
+        return 2;
+    }
+    // OBS-1 shape guard up front: a malformed id never seeds a bundle path.
+    if (!(0, observability_1.isCanonicalTraceId)(flags.traceId)) {
+        console.error(`Invalid --trace-id "${flags.traceId}": expected 32 lowercase hex chars ` +
+            `(OBS-1). The id is the last path segment of the Langfuse deep-link mla ` +
+            `prints on a run.`);
+        return 2;
+    }
+    const home = deps.home ?? config_1.HOME;
+    const now = deps.now ?? (() => new Date().toISOString());
+    const isTTY = deps.isTTY ?? Boolean(process.stdin.isTTY);
+    const confirm = deps.confirm ?? confirmInteractive;
+    const backendFetcher = deps.backendFetcher ?? defaultBackendFetcher;
+    const opts = {
+        includePrompts: flags.includePrompts,
+        includeDiffs: flags.includeDiffs,
+    };
+    // Gate the raw-payload opt-ins. Interactive: ask once, naming exactly what
+    // would be included. Non-interactive without --yes: refuse (never silently
+    // bundle sensitive content for an automated caller).
+    if (opts.includePrompts || opts.includeDiffs) {
+        const categories = [
+            opts.includePrompts ? "prompts, document bodies, tool payloads, raw requests" : null,
+            opts.includeDiffs ? "source diffs" : null,
+        ]
+            .filter(Boolean)
+            .join("; ");
+        if (!flags.yes) {
+            if (!isTTY) {
+                console.error(`Refusing to include raw payloads (${categories}) non-interactively. ` +
+                    `Re-run with --yes to confirm in a non-interactive context.`);
+                return 2;
+            }
+            const ok = await confirm(`This bundle will include RAW payloads (${categories}). These can contain ` +
+                `sensitive content. Include them? [y/N] `);
+            if (!ok) {
+                console.error("Aborted: raw payloads not included. Re-run without the include flags for a redacted bundle.");
+                return 1;
+            }
+        }
+    }
+    const counts = { diffs: 0, prompts: 0, secrets: 0 };
+    const warnings = [];
+    // Local logs: always, offline-capable. Trace-scoped + redacted in the core.
+    const logsDir = path.join(home, "logs");
+    const localLogs = (0, debug_bundle_1.collectLocalLogs)(logsDir, flags.traceId, opts, counts);
+    // Best-effort backend summary (skippable with --no-backend).
+    let backendSummary = null;
+    let langfuseProjectId = null;
+    if (flags.noBackend) {
+        warnings.push("backend summary skipped (--no-backend); bundle is local-only.");
+    }
+    else {
+        const r = await backendFetcher(flags.traceId, opts, counts);
+        backendSummary = r.summary;
+        langfuseProjectId = r.langfuseProjectId;
+        if (r.warning)
+            warnings.push(r.warning);
+    }
+    const workspaceId = (() => {
+        try {
+            return (0, workspace_1.tryResolveWorkspaceId)(deps.cwd ?? process.cwd());
+        }
+        catch {
+            return null;
+        }
+    })();
+    const build = (0, observability_1.loadBuildInfo)();
+    const inputs = {
+        traceId: flags.traceId,
+        createdAt: now(),
+        mlaVersion: build.version,
+        releaseSha: build.sha,
+        workspaceId,
+        command: flags.command ?? "unknown",
+        runId: flags.runId ?? null,
+        sessionId: flags.sessionId ?? null,
+        telemetryEnabled: !(0, observability_1.telemetryDisabled)(),
+        langfuseProjectId,
+        sentryUrl: null,
+        opts,
+        localLogs,
+        backendSummary,
+        warnings,
+        redactionCounts: counts,
+    };
+    const built = (0, debug_bundle_1.buildBundle)(inputs);
+    const outPath = flags.out
+        ? path.resolve(flags.out)
+        : path.join(home, "debug", `${flags.traceId}.zip`);
+    fs.mkdirSync(path.dirname(outPath), { recursive: true });
+    fs.writeFileSync(outPath, built.zip, { mode: 0o600 });
+    if (!flags.quiet) {
+        console.log(`Wrote debug bundle: ${outPath}`);
+        console.log(`  trace_id:  ${flags.traceId}`);
+        console.log(`  files:     ${built.fileList.length + 1} (incl. manifest.json)`);
+        console.log(`  redacted:  ${counts.prompts} prompt-field(s), ${counts.diffs} diff-field(s), ` +
+            `${counts.secrets} secret(s)` +
+            (opts.includePrompts || opts.includeDiffs ? " (raw payloads INCLUDED per flags)" : ""));
+        if (warnings.length > 0) {
+            console.log(`  warnings:  ${warnings.length} (see manifest.json / redaction-report.json)`);
+        }
+        console.log("Review manifest.json + redaction-report.json before sharing. Nothing was uploaded.");
+    }
+    return 0;
+}