opensip-cli 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * OpenSIP CLI — composition root (sequencer, not a god file).
+ *
+ * The canonical ordered description of the full tool + host lifecycle lives in
+ * `bootstrap/tool-lifecycle.ts` (the 10 named steps, two phases: STARTUP in
+ * bootstrapCli + mountToolCommands, PER-RUN in the preAction hook + builders).
+ * This file wires the major seams (fresh registries per invocation, bootstrap,
+ * pre-action hook install, ToolCliContext construction, command mounting,
+ * host command registration, telemetry, top-level error paths) and then
+ * dispatches. Individual steps are factored into `./bootstrap/*` (admission,
+ * scope building, capability wiring, delivery) and `./commands/*`.
+ *
+ * Adding a new tool requires zero changes here — tools declare `commandSpecs`
+ * (and optional hooks) and are discovered/admitted/mounted uniformly.
+ *
+ * See also: bootstrap/tool-lifecycle.ts (TOOL_LIFECYCLE_STEPS + JSDoc),
+ * pre-action-hook.ts, build-per-run-scope.ts, register-tools.ts.
+ */
+export * from './api.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAGA;;;;;;;;;;;;;;;;;GAiBG;AA4BH,cAAc,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+// @fitness-ignore-file detached-promises -- composition root invokes synchronous bootstrap helpers (mountAllToolCommands, registerCliCommands, printWelcome) that the heuristic mistakes for promise-returning calls
+/**
+ * OpenSIP CLI — composition root (sequencer, not a god file).
+ *
+ * The canonical ordered description of the full tool + host lifecycle lives in
+ * `bootstrap/tool-lifecycle.ts` (the 10 named steps, two phases: STARTUP in
+ * bootstrapCli + mountToolCommands, PER-RUN in the preAction hook + builders).
+ * This file wires the major seams (fresh registries per invocation, bootstrap,
+ * pre-action hook install, ToolCliContext construction, command mounting,
+ * host command registration, telemetry, top-level error paths) and then
+ * dispatches. Individual steps are factored into `./bootstrap/*` (admission,
+ * scope building, capability wiring, delivery) and `./commands/*`.
+ *
+ * Adding a new tool requires zero changes here — tools declare `commandSpecs`
+ * (and optional hooks) and are discovered/admitted/mounted uniformly.
+ *
+ * See also: bootstrap/tool-lifecycle.ts (TOOL_LIFECYCLE_STEPS + JSDoc),
+ * pre-action-hook.ts, build-per-run-scope.ts, register-tools.ts.
+ */
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { LanguageRegistry, ToolRegistry, logger, readPackageVersion, getMeter, } from '@opensip-cli/core';
+import { Command } from 'commander';
+import { bootstrapCli, installPreActionHook, maybeOpenReport, mountToolCommands, renderResult, buildCommandRegistrationInput, } from './bootstrap/index.js';
+import { buildToolCliContext, createLiveViewRegistry, getOrOpenDatastore } from './cli-context.js';
+import { registerCliCommands } from './commands/index.js';
+import { handleFatalBootstrapError, handleParseError } from './error-handler.js';
+import { runWithTelemetryContext, shutdownTelemetry } from './telemetry/sdk-init.js';
+import { printWelcome } from './welcome.js';
+export * from './api.js';
+const cliVersion = readPackageVersion(import.meta.url);
+const program = new Command('opensip')
+    .description('Codebase analysis toolkit — pluggable tools for fitness, simulation, and more')
+    // ADR-0008: per-run opt-out of OpenSIP Cloud signal sync. `--no-cloud` sets
+    // `cloud` to false; the pre-action hook reads it via optsWithGlobals().
+    .option('--no-cloud', 'Disable OpenSIP Cloud signal sync for this run')
+    .version(cliVersion)
+    // Route Commander's own parse failures through `parseAsync().catch` →
+    // `handleParseError` instead of letting Commander call `process.exit(N)`
+    // directly. This restores the project's typed-error → exit-code contract for
+    // declarative `choices`/argument validation: a bad `--resolution`/option
+    // value is a usage error that must exit `CONFIGURATION_ERROR` (2) — the same
+    // code the pre-command-plane in-handler `ValidationError` produced — not
+    // Commander's default `1`. `handleParseError` preserves Commander's own
+    // exit code for every OTHER Commander condition (unknown command/option →
+    // 1, --help/--version → 0), so only the invalid-argument case is re-mapped.
+    // Commander still writes its own error line to stderr before throwing, so the
+    // handler renders nothing extra for a CommanderError (no duplicate output).
+    .exitOverride();
+async function main() {
+    // Fresh registries per CLI invocation. Tools read these via
+    // `cli.scope.languages` / `cli.scope.tools`; bootstrap populates them here.
+    const langRegistry = new LanguageRegistry();
+    const toolRegistry = new ToolRegistry();
+    // Persistence: datastore is opened LAZILY in cli-context.ts on
+    // first access via getOrOpenDatastore. bootstrapCli just registers
+    // tools and adapters; no SQLite file is created here.
+    const { provenance, manifests } = await bootstrapCli({
+        langRegistry,
+        toolRegistry,
+        projectDir: dirname(dirname(fileURLToPath(import.meta.url))),
+        cwd: process.cwd(),
+        cliEntryUrl: import.meta.url,
+    });
+    // Install the pre-action hook AFTER bootstrap so the populated registries +
+    // admitted-tool manifests/provenance are captured directly in the hook
+    // closure — no module-global handoff bag. The hook builds + enters the
+    // per-run RunScope (stamping manifests/provenance onto it); from there every
+    // per-run read goes through `currentScope()`.
+    installPreActionHook(program, cliVersion, {
+        languages: langRegistry,
+        tools: toolRegistry,
+        manifests,
+        provenance,
+    });
+    const { ctx } = buildToolCliContext({
+        render: renderResult,
+        liveViews: createLiveViewRegistry(logger),
+        maybeOpenReport,
+        logger,
+    });
+    // Step 8 of the tool lifecycle (§5.4): mount each registered tool's commands
+    // through the named sequencer seam. The host owns `program` and passes it in
+    // (launch — the tool context no longer carries a raw-Commander handle, §8); the
+    // one command surface is each tool's declarative commandSpecs.
+    mountToolCommands(toolRegistry, program, ctx);
+    // Extracted into a thin dedicated builder (roadmap item 2) to keep the
+    // top-level composition root focused on sequencing. The builder returns the
+    // exact shape consumed by `registerCliCommands`.
+    const registrationInput = buildCommandRegistrationInput(toolRegistry);
+    registerCliCommands(program, {
+        setExitCode: ctx.setExitCode,
+        render: renderResult,
+        emitJson: ctx.emitJson,
+        emitRaw: ctx.emitRaw,
+        emitError: ctx.emitError,
+        datastore: () => getOrOpenDatastore(logger),
+        ...registrationInput,
+    });
+    // Bare `opensip` → welcome screen. The update check is owned by the
+    // pre-action hook (which only runs for actual subcommands), so it naturally
+    // skips zero-arg runs without a guard here.
+    // Return (not process.exit) so the top-level `finally` still runs the
+    // telemetry shutdown flush — consistent with this file's exitCode-over-
+    // exit() principle below. Exit code defaults to 0.
+    if (process.argv.length <= 2) {
+        printWelcome({ version: program.version() ?? 'dev' });
+        return;
+    }
+    // Dispatch inside the telemetry parent context so spans emitted during the
+    // run (e.g. graph's per-stage spans) nest under the consumer's TRACEPARENT
+    // when one was supplied. A plain pass-through when telemetry is disabled or
+    // no parent context was extracted, so standalone runs pay nothing.
+    // `--json` is read from argv here because bootstrap/parse errors fire OUTSIDE a
+    // handler (no parsed opts). It selects the structured `CommandOutcome` error
+    // path (§5.5) over human Ink rendering.
+    const jsonRequested = process.argv.includes('--json');
+    const commandStart = Date.now();
+    await runWithTelemetryContext(() => program.parseAsync().catch((error) => handleParseError(error, {
+        setExitCode: ctx.setExitCode,
+        render: renderResult,
+        jsonRequested,
+    })));
+    // Phase 2: command duration histogram (low cardinality labels)
+    const durationMs = Date.now() - commandStart;
+    getMeter('opensip-cli')
+        .createHistogram('opensip_cli.command.duration_ms')
+        .record(durationMs, {
+        command: process.argv[2] || 'welcome', // rough; real commands go through pre-action
+    });
+}
+// Top-level fatal handler. Errors that escape `main` predate Commander's
+// parse loop (bootstrap, registry registration, fs I/O during preflight)
+// and so don't reach the per-command catch in `parseAsync().catch(...)`.
+// Route them through the same error-handler seam so the exit code flows
+// through `process.exitCode` (not `process.exit(N)` — the latter skips
+// the pending stderr flush) and a `cli.bootstrap.failed` log line is
+// emitted for observability. Audit 2026-05-23 G1.
+try {
+    await main();
+}
+catch (error) {
+    handleFatalBootstrapError(error, logger);
+}
+finally {
+    // Flush batched spans before the short-lived process exits — on normal
+    // completion and on handled error exits alike. No-op when telemetry was
+    // never started (standalone), so standalone runs pay nothing. The early
+    // welcome-screen `process.exit(0)` above runs no commands and emits no
+    // spans, so skipping the flush there is harmless.
+    await shutdownTelemetry();
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/open-report.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @fileoverview Helper for the `--open` flag on report-producing commands.
+ *
+ * After a run completes, generate the HTML report and launch it in
+ * the default browser. Hard-skip conditions are strict: we NEVER open
+ * a browser in environments where it would be wrong (CI, non-TTY,
+ * --json output, SSH without a display).
+ *
+ * The underlying cross-platform launcher is the `open` npm package
+ * (wraps macOS `open`, Linux `xdg-open`, Windows `start`).
+ */
+export interface OpenReportDecision {
+    readonly shouldOpen: boolean;
+    readonly reason: string;
+}
+export interface OpenReportContext {
+    readonly openRequested: boolean;
+    readonly jsonOutput: boolean;
+    readonly stdoutIsTTY: boolean;
+    readonly env: NodeJS.ProcessEnv;
+}
+/**
+ * Decide whether to honor a --open request. Kept pure so tests can
+ * exercise every branch without process manipulation.
+ *
+ * Skip conditions (all strict — no override):
+ *   - --json set (caller wants machine output)
+ *   - stdout is not a TTY (pipeline / log redirect)
+ *   - CI env var set (GitHub Actions, GitLab CI, CircleCI, etc.)
+ *   - SSH_CONNECTION set AND no DISPLAY/WAYLAND_DISPLAY (remote shell
+ *     without a graphical session — don't try)
+ */
+export declare function decideReportOpen(ctx: OpenReportContext): OpenReportDecision;
+/**
+ * Launch the given URL or file path in the default browser. Returns
+ * true on success, false if `open` refused or threw. Never propagates
+ * — a failure to open a browser should NOT fail the fitness run.
+ */
+export declare function launchReport(target: string): Promise<boolean>;
+//# sourceMappingURL=open-report.d.ts.map

package/dist/open-report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"open-report.d.ts","sourceRoot":"","sources":["../src/open-report.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;CACjC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,iBAAiB,GAAG,kBAAkB,CAS3E;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAQnE"}

package/dist/open-report.js

@@ -0,0 +1,54 @@
+/**
+ * @fileoverview Helper for the `--open` flag on report-producing commands.
+ *
+ * After a run completes, generate the HTML report and launch it in
+ * the default browser. Hard-skip conditions are strict: we NEVER open
+ * a browser in environments where it would be wrong (CI, non-TTY,
+ * --json output, SSH without a display).
+ *
+ * The underlying cross-platform launcher is the `open` npm package
+ * (wraps macOS `open`, Linux `xdg-open`, Windows `start`).
+ */
+import open from 'open';
+/**
+ * Decide whether to honor a --open request. Kept pure so tests can
+ * exercise every branch without process manipulation.
+ *
+ * Skip conditions (all strict — no override):
+ *   - --json set (caller wants machine output)
+ *   - stdout is not a TTY (pipeline / log redirect)
+ *   - CI env var set (GitHub Actions, GitLab CI, CircleCI, etc.)
+ *   - SSH_CONNECTION set AND no DISPLAY/WAYLAND_DISPLAY (remote shell
+ *     without a graphical session — don't try)
+ */
+export function decideReportOpen(ctx) {
+    if (!ctx.openRequested)
+        return { shouldOpen: false, reason: 'not-requested' };
+    if (ctx.jsonOutput)
+        return { shouldOpen: false, reason: 'json-mode' };
+    if (!ctx.stdoutIsTTY)
+        return { shouldOpen: false, reason: 'non-tty' };
+    if (ctx.env.CI)
+        return { shouldOpen: false, reason: 'ci-env' };
+    const ssh = ctx.env.SSH_CONNECTION ?? ctx.env.SSH_CLIENT;
+    const display = ctx.env.DISPLAY ?? ctx.env.WAYLAND_DISPLAY;
+    if (ssh && !display)
+        return { shouldOpen: false, reason: 'ssh-no-display' };
+    return { shouldOpen: true, reason: 'ok' };
+}
+/**
+ * Launch the given URL or file path in the default browser. Returns
+ * true on success, false if `open` refused or threw. Never propagates
+ * — a failure to open a browser should NOT fail the fitness run.
+ */
+export async function launchReport(target) {
+    try {
+        await open(target);
+        return true;
+    }
+    catch {
+        // @fitness-ignore-next-line error-handling-quality -- documented contract (see JSDoc above): failure to open a browser must NOT fail the fitness run; caller dispatches on the boolean return.
+        return false;
+    }
+}
+//# sourceMappingURL=open-report.js.map

package/dist/open-report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"open-report.js","sourceRoot":"","sources":["../src/open-report.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,IAAI,MAAM,MAAM,CAAC;AAcxB;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAsB;IACrD,IAAI,CAAC,GAAG,CAAC,aAAa;QAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;IAC9E,IAAI,GAAG,CAAC,UAAU;QAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;IACtE,IAAI,CAAC,GAAG,CAAC,WAAW;QAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IACtE,IAAI,GAAG,CAAC,GAAG,CAAC,EAAE;QAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;IAC/D,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,cAAc,IAAI,GAAG,CAAC,GAAG,CAAC,UAAU,CAAC;IACzD,MAAM,OAAO,GAAG,GAAG,CAAC,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC,GAAG,CAAC,eAAe,CAAC;IAC3D,IAAI,GAAG,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC5E,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AAC5C,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,MAAc;IAC/C,IAAI,CAAC;QACH,MAAM,IAAI,CAAC,MAAM,CAAC,CAAC;QACnB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,+LAA+L;QAC/L,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/report-compose.d.ts

@@ -0,0 +1,35 @@
+/**
+ * report-compose — the cross-tool report composition root.
+ *
+ * Audit 2026-05-29 (L2): the CLI, not any single tool, composes the HTML
+ * report. It walks every registered tool's `collectReportData(scope)`
+ * contribution and merges the results into one HTML report input, then
+ * renders the self-contained HTML via `@opensip-cli/dashboard` and
+ * writes it to the project's reports directory.
+ *
+ * This is what decouples fitness from graph: fitness contributes only
+ * its own catalogs (`checkCatalog` / `recipeCatalog` / `editorProtocol`)
+ * and graph contributes only `graphCatalog`. Neither reaches into the
+ * other; the CLI owns the merge because composition needs the tool
+ * REGISTRY (`RunScope.tools`), which the tool-facing `ToolScope`
+ * deliberately excludes.
+ *
+ * Why read `currentScope()` here and nowhere in the tool packages: the
+ * `Tool` contract must not depend on `RunScope` (that would reintroduce
+ * a kernel⟷tool cycle). The CLI is the only layer allowed to read the
+ * concrete `RunScope` (which has `.tools`) — tools receive the narrower
+ * `ToolScope` view as the `collectReportData` parameter.
+ */
+import type { ReportResult } from '@opensip-cli/contracts';
+/**
+ * Compose the cross-tool report, write it to
+ * `<reportsDir>/latest.html`, and (optionally) open it in the browser.
+ *
+ * Returns a `ReportResult` describing the written path and whether a
+ * browser was launched. Browser-launch failures never propagate — they
+ * fall through to `opened: false` so the user can open the file manually.
+ */
+export declare function composeAndWriteReport(opts: {
+    open: boolean;
+}): Promise<ReportResult>;
+//# sourceMappingURL=report-compose.d.ts.map

package/dist/report-compose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report-compose.d.ts","sourceRoot":"","sources":["../src/report-compose.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAoBH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAkE3D;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,YAAY,CAAC,CAY1F"}

package/dist/report-compose.js

@@ -0,0 +1,103 @@
+/**
+ * report-compose — the cross-tool report composition root.
+ *
+ * Audit 2026-05-29 (L2): the CLI, not any single tool, composes the HTML
+ * report. It walks every registered tool's `collectReportData(scope)`
+ * contribution and merges the results into one HTML report input, then
+ * renders the self-contained HTML via `@opensip-cli/dashboard` and
+ * writes it to the project's reports directory.
+ *
+ * This is what decouples fitness from graph: fitness contributes only
+ * its own catalogs (`checkCatalog` / `recipeCatalog` / `editorProtocol`)
+ * and graph contributes only `graphCatalog`. Neither reaches into the
+ * other; the CLI owns the merge because composition needs the tool
+ * REGISTRY (`RunScope.tools`), which the tool-facing `ToolScope`
+ * deliberately excludes.
+ *
+ * Why read `currentScope()` here and nowhere in the tool packages: the
+ * `Tool` contract must not depend on `RunScope` (that would reintroduce
+ * a kernel⟷tool cycle). The CLI is the only layer allowed to read the
+ * concrete `RunScope` (which has `.tools`) — tools receive the narrower
+ * `ToolScope` view as the `collectReportData` parameter.
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { currentScope, resolveProjectPaths, SystemError, logger as defaultLogger, } from '@opensip-cli/core';
+import { generateDashboardHtml, } from '@opensip-cli/dashboard';
+import { SessionRepo } from '@opensip-cli/session-store';
+import { getCurrentProjectRoot } from './cli-context.js';
+import { launchReport } from './open-report.js';
+/**
+ * Host-reserved top-level dashboard-input key a tool's `collectReportData` must
+ * never set: `sessions` is the durable cross-tool run history the host owns. A
+ * tool that returns it is ignored (best-effort) with a warning.
+ */
+const RESERVED_DASHBOARD_KEYS = new Set(['sessions']);
+/**
+ * Build the merged HTML report input from every registered tool's
+ * report-data contribution, on top of the shared session history.
+ *
+ * Sessions come from the CLI (cross-tool history); each tool's
+ * `collectReportData` returns its own keyed inputs which are merged
+ * onto the base via `Object.assign`. Contributions are best-effort: a
+ * tool that omits `collectReportData`, or returns an empty object,
+ * simply contributes nothing.
+ *
+ * @throws {Error} When called outside an entered `RunScope` (i.e. not inside
+ *   a CLI action body), since session history and tool contributions both
+ *   require the scope.
+ */
+async function composeReportInput() {
+    const scope = currentScope();
+    if (!scope) {
+        // Use a typed error with code so the top-level handler + --json paths
+        // produce a clean, consistent failure instead of a raw Error.
+        throw new SystemError('report composition requires an entered RunScope (run inside a CLI action body).', { code: 'SYSTEM.SCOPE.NOT_ENTERED' });
+    }
+    const log = scope.logger ?? defaultLogger;
+    const datastore = scope.datastore();
+    const repo = datastore ? new SessionRepo(datastore) : undefined;
+    const sessions = repo ? [...repo.list({ limit: 20 })] : [];
+    const input = { sessions };
+    for (const tool of scope.tools.list()) {
+        const contribution = await tool.collectReportData?.(scope);
+        if (contribution) {
+            // Guardrail (spec §8): tools must never clobber the host-owned `sessions`
+            // run history. Ignore with a warning (best-effort, like other contribution
+            // faults) — the host owns the cross-tool history.
+            const reserved = Object.keys(contribution).filter((k) => RESERVED_DASHBOARD_KEYS.has(k));
+            if (reserved.length > 0) {
+                void log.warn({
+                    evt: 'cli.report.compose.reserved_key_ignored',
+                    module: 'cli:report',
+                    tool: tool.metadata.id,
+                    keys: reserved,
+                    msg: 'Tool collectReportData returned a reserved host key; it was ignored.',
+                });
+                for (const k of reserved)
+                    delete contribution[k];
+            }
+            Object.assign(input, contribution);
+        }
+    }
+    return input;
+}
+/**
+ * Compose the cross-tool report, write it to
+ * `<reportsDir>/latest.html`, and (optionally) open it in the browser.
+ *
+ * Returns a `ReportResult` describing the written path and whether a
+ * browser was launched. Browser-launch failures never propagate — they
+ * fall through to `opened: false` so the user can open the file manually.
+ */
+export async function composeAndWriteReport(opts) {
+    const input = await composeReportInput();
+    const html = generateDashboardHtml(input);
+    const paths = resolveProjectPaths(getCurrentProjectRoot());
+    mkdirSync(paths.reportsDir, { recursive: true });
+    const reportPath = join(paths.reportsDir, 'latest.html');
+    writeFileSync(reportPath, html, 'utf8');
+    const opened = opts.open ? await launchReport(reportPath) : false;
+    return { type: 'report', path: reportPath, opened };
+}
+//# sourceMappingURL=report-compose.js.map

package/dist/report-compose.js.map

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

package/dist/session-replay-registry.d.ts

@@ -0,0 +1,20 @@
+import type { CommandResult, ToolSessionReplay } from '@opensip-cli/contracts';
+import type { ToolRegistry, ToolSessionRecord, ToolShortId } from '@opensip-cli/core';
+export interface CliSessionReplayContribution {
+    readonly tool: ToolShortId;
+    readonly replaySession: (stored: ToolSessionRecord) => ToolSessionReplay<CommandResult>;
+}
+export declare class SessionReplayRegistry {
+    private readonly byTool;
+    private constructor();
+    static empty(): SessionReplayRegistry;
+    /**
+     * Build the registry from the tools' `sessionReplay` contributions.
+     *
+     * @throws {Error} when two registered tools claim the same `tool` short id
+     *   (a duplicate session-replay contribution).
+     */
+    static fromTools(registry: ToolRegistry): SessionReplayRegistry;
+    get(tool: ToolShortId): CliSessionReplayContribution | undefined;
+}
+//# sourceMappingURL=session-replay-registry.d.ts.map

package/dist/session-replay-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-replay-registry.d.ts","sourceRoot":"","sources":["../src/session-replay-registry.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC/E,OAAO,KAAK,EACV,YAAY,EACZ,iBAAiB,EAEjB,WAAW,EACZ,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,iBAAiB,CAAC,aAAa,CAAC,CAAC;CACzF;AAED,qBAAa,qBAAqB;IAE9B,OAAO,CAAC,QAAQ,CAAC,MAAM;IADzB,OAAO;IAIP,MAAM,CAAC,KAAK,IAAI,qBAAqB;IAIrC;;;;;OAKG;IACH,MAAM,CAAC,SAAS,CAAC,QAAQ,EAAE,YAAY,GAAG,qBAAqB;IAa/D,GAAG,CAAC,IAAI,EAAE,WAAW,GAAG,4BAA4B,GAAG,SAAS;CAGjE"}

package/dist/session-replay-registry.js

@@ -0,0 +1,38 @@
+export class SessionReplayRegistry {
+    byTool;
+    constructor(byTool) {
+        this.byTool = byTool;
+    }
+    static empty() {
+        return new SessionReplayRegistry(new Map());
+    }
+    /**
+     * Build the registry from the tools' `sessionReplay` contributions.
+     *
+     * @throws {Error} when two registered tools claim the same `tool` short id
+     *   (a duplicate session-replay contribution).
+     */
+    static fromTools(registry) {
+        const byTool = new Map();
+        for (const tool of registry.list()) {
+            const contribution = tool.sessionReplay;
+            if (contribution === undefined)
+                continue;
+            if (byTool.has(contribution.tool)) {
+                throw new Error(`Duplicate session replay contribution for tool '${contribution.tool}'`);
+            }
+            byTool.set(contribution.tool, normalizeContribution(contribution));
+        }
+        return new SessionReplayRegistry(byTool);
+    }
+    get(tool) {
+        return this.byTool.get(tool);
+    }
+}
+function normalizeContribution(contribution) {
+    return {
+        tool: contribution.tool,
+        replaySession: (stored) => contribution.replaySession(stored),
+    };
+}
+//# sourceMappingURL=session-replay-registry.js.map

package/dist/session-replay-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-replay-registry.js","sourceRoot":"","sources":["../src/session-replay-registry.ts"],"names":[],"mappings":"AAcA,MAAM,OAAO,qBAAqB;IAEb;IADnB,YACmB,MAA8D;QAA9D,WAAM,GAAN,MAAM,CAAwD;IAC9E,CAAC;IAEJ,MAAM,CAAC,KAAK;QACV,OAAO,IAAI,qBAAqB,CAAC,IAAI,GAAG,EAAE,CAAC,CAAC;IAC9C,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,SAAS,CAAC,QAAsB;QACrC,MAAM,MAAM,GAAG,IAAI,GAAG,EAA6C,CAAC;QACpE,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC;YACnC,MAAM,YAAY,GAAG,IAAI,CAAC,aAAa,CAAC;YACxC,IAAI,YAAY,KAAK,SAAS;gBAAE,SAAS;YACzC,IAAI,MAAM,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC;gBAClC,MAAM,IAAI,KAAK,CAAC,mDAAmD,YAAY,CAAC,IAAI,GAAG,CAAC,CAAC;YAC3F,CAAC;YACD,MAAM,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,EAAE,qBAAqB,CAAC,YAAY,CAAC,CAAC,CAAC;QACrE,CAAC;QACD,OAAO,IAAI,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAC3C,CAAC;IAED,GAAG,CAAC,IAAiB;QACnB,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;CACF;AAED,SAAS,qBAAqB,CAC5B,YAA2C;IAE3C,OAAO;QACL,IAAI,EAAE,YAAY,CAAC,IAAI;QACvB,aAAa,EAAE,CAAC,MAAM,EAAE,EAAE,CACxB,YAAY,CAAC,aAAa,CAAC,MAAM,CAAqC;KACzE,CAAC;AACJ,CAAC"}

package/dist/telemetry/profiling.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Profiling support — optional and severable (see observability-hardening plan).
+ *
+ * Gate (per ADR-0049 and plan):
+ * - Recommended: OPENSIP_PROFILING=1 AND OTEL_EXPORTER_OTLP_ENDPOINT set.
+ * - Supported alternative (kept for flexibility): profiling can be tied to
+ *   OTEL_EXPORTER_OTLP_ENDPOINT alone (documented with cost warnings).
+ *
+ * Implementation uses Node's built-in `inspector` module for real CPU profiles
+ * (no extra published dependency for the optional profiling path). This gives
+ * actionable .cpuprofile files for short-lived CLI runs, with runId/command
+ * labels embedded in the filename and a sidecar JSON.
+ *
+ * When a full OTel profiles signal / Pyroscope client is desired, the start/stop
+ * hooks here are the single place to swap in that implementation while reusing
+ * the same resource attributes, runId, and shutdown discipline.
+ *
+ * The seam is intentionally thin in core; all heavy lifting and any future
+ * SDK bits stay in the CLI root.
+ */
+import { type RunScope } from '@opensip-cli/core';
+export interface ProfilingLabels {
+    readonly runId?: string;
+    readonly command?: string;
+    readonly [key: string]: unknown;
+}
+/** Returns true if the recommended or OTEL-only profiling gate is satisfied. */
+export declare function isProfilingEnabled(): boolean;
+/**
+ * Start CPU profiling for this invocation (if gate is open).
+ * Must be called after RunScope is entered (so runId is available).
+ * Safe to call multiple times (idempotent).
+ */
+export declare function startProfiling(scope?: RunScope, command?: string): void;
+/**
+ * Stop profiling and flush the .cpuprofile + labels sidecar.
+ * Safe and idempotent.
+ */
+export declare function stopProfiling(): void;
+/** Exposed for tests / shutdown. */
+export declare function resetProfilingForTests(): void;
+//# sourceMappingURL=profiling.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"profiling.d.ts","sourceRoot":"","sources":["../../src/telemetry/profiling.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAMH,OAAO,EAAU,KAAK,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAY1D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AAED,gFAAgF;AAChF,wBAAgB,kBAAkB,IAAI,OAAO,CAW5C;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAuDvE;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAuCpC;AAgBD,oCAAoC;AACpC,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C"}