opensip-cli 0.1.0

package/dist/telemetry/profiling.js

@@ -0,0 +1,160 @@
+/**
+ * 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 { mkdirSync, writeFileSync } from 'node:fs';
+import { Session } from 'node:inspector';
+import { join } from 'node:path';
+import { logger } from '@opensip-cli/core';
+import { hostEnv } from '../env/host-env-specs.js';
+let session = null;
+let isProfiling = false;
+let profilePath = null;
+let labelsPath = null;
+/** Module tag for structured logging (also dedupes the sonarjs/no-duplicate-string occurrences). */
+const MODULE = 'cli:telemetry';
+/** Returns true if the recommended or OTEL-only profiling gate is satisfied. */
+export function isProfilingEnabled() {
+    const endpoint = hostEnv.get('OTEL_EXPORTER_OTLP_ENDPOINT');
+    if (!endpoint)
+        return false;
+    const explicit = hostEnv.get('OPENSIP_PROFILING');
+    if (explicit === '1' || explicit === 'true')
+        return true;
+    // Supported "just the OTEL endpoint" alternative (with warnings in docs/ADR-0049).
+    // Many teams prefer one knob; we honor it but log at warn so cost is visible.
+    // Operators who do not want this can set OPENSIP_PROFILING=0 explicitly.
+    return true; // OTEL endpoint present ⇒ profiling on in this fallback mode
+}
+/**
+ * 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 function startProfiling(scope, command) {
+    if (isProfiling)
+        return;
+    try {
+        if (!isProfilingEnabled())
+            return;
+        session = new Session();
+        session.connect();
+        session.post('Profiler.enable', (_err, _res) => {
+            if (!session)
+                return;
+            session.post('Profiler.start', (_err2, _res2) => {
+                isProfiling = true;
+                const runId = scope?.runId ?? 'unknown';
+                const safeCommand = (command ?? 'cli').replace(/[^a-z0-9_-]/gi, '_');
+                const ts = new Date().toISOString().replace(/[:.]/g, '-');
+                // Place profiles under project logs dir if available, else cwd/.runtime/profiles
+                const baseDir = scope?.projectContext?.scope === 'project'
+                    ? join(scope.projectContext.projectRoot, 'opensip-cli/.runtime/profiles')
+                    : join(process.cwd(), 'opensip-cli/.runtime/profiles');
+                mkdirSync(baseDir, { recursive: true });
+                profilePath = join(baseDir, `${ts}-${safeCommand}-${runId}.cpuprofile`);
+                labelsPath = join(baseDir, `${ts}-${safeCommand}-${runId}.labels.json`);
+                const labels = {
+                    runId,
+                    command: command ?? 'unknown',
+                    service: 'opensip-cli',
+                    // Add any OTEL_RESOURCE_ATTRIBUTES derived labels here if needed in future
+                };
+                writeFileSync(labelsPath, JSON.stringify(labels, null, 2));
+                logger.info({
+                    evt: 'cli.profiling.started',
+                    module: MODULE,
+                    runId,
+                    command,
+                    profilePath,
+                });
+            });
+        });
+    }
+    catch (error) {
+        logger.warn({
+            evt: 'cli.profiling.start_failed',
+            module: MODULE,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        // Best effort — profiling failure must never break the run
+        cleanup();
+    }
+}
+/**
+ * Stop profiling and flush the .cpuprofile + labels sidecar.
+ * Safe and idempotent.
+ */
+export function stopProfiling() {
+    if (!isProfiling || !session) {
+        cleanup();
+        return;
+    }
+    try {
+        // node:inspector post callbacks for Profiler.* use structural types not fully declared
+        // in the ambient types we consume; the result object (incl. profile) arrives as any.
+        // We narrow locally for the write path; the disable is scoped to the wire call.
+        session.post('Profiler.stop', (err, result = {}) => {
+            if (err) {
+                logger.warn({
+                    evt: 'cli.profiling.stop_failed',
+                    module: MODULE,
+                    error: err.message || String(err),
+                });
+            }
+            else if (result.profile && profilePath) {
+                writeFileSync(profilePath, JSON.stringify(result.profile));
+                logger.info({
+                    evt: 'cli.profiling.stopped',
+                    module: MODULE,
+                    profilePath,
+                    labelsPath,
+                });
+            }
+            cleanup();
+        });
+    }
+    catch (error) {
+        logger.warn({
+            evt: 'cli.profiling.stop_failed',
+            module: MODULE,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        cleanup();
+    }
+}
+function cleanup() {
+    if (session) {
+        try {
+            session.disconnect();
+        }
+        catch {
+            // @swallow-ok best-effort inspector session disconnect during profiling teardown
+        }
+    }
+    session = null;
+    isProfiling = false;
+    profilePath = null;
+    labelsPath = null;
+}
+/** Exposed for tests / shutdown. */
+export function resetProfilingForTests() {
+    cleanup();
+}
+//# sourceMappingURL=profiling.js.map

package/dist/telemetry/profiling.js.map

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

package/dist/telemetry/sdk-init.d.ts

@@ -0,0 +1,87 @@
+/**
+ * OpenTelemetry SDK init — the application half of the OTel library/application
+ * split, wired ONLY at the CLI composition root.
+ *
+ * ## Opt-in gate (the load-bearing contract)
+ *
+ * The entire SDK (traces + metrics + optional profiling) is gated on
+ * `OTEL_EXPORTER_OTLP_ENDPOINT` (see ADR-0049 and observability plan for details).
+ *
+ *   - **Set** ⇒ register NodeTracerProvider + (Phase 2) MeterProvider.
+ *     `core`'s `getTracer`/`withSpan`/`getMeter` resolve to real implementations.
+ *   - Profiling uses the same endpoint (recommended with dedicated
+ *     `OPENSIP_PROFILING=1` flag for cost control; "OTEL endpoint alone" mode
+ *     is supported with warnings).
+ *   - **Unset** ⇒ hard no-op for everything. Standalone CLI pays nothing.
+ *
+ * ## Layering
+ *
+ * The heavy SDK packages (`@opentelemetry/sdk-trace-node`, the OTLP exporter,
+ * `context-async-hooks`, `core`'s propagator, `resources`) are imported HERE
+ * and nowhere else. `core` and the tool packages depend on `@opentelemetry/api`
+ * only — dependency-cruiser enforces that an `@opentelemetry/sdk-*` import never
+ * leaks into the kernel or a tool.
+ *
+ * ## Parent-trace nesting
+ *
+ * An embedding consumer spawns the binary with a `TRACEPARENT` env var. We
+ * extract it via the W3C propagator and expose it as a parent context
+ * ({@link parentTelemetryContext} / {@link runWithTelemetryContext}) so the
+ * command dispatch — and therefore graph's stage spans — nests under the
+ * consumer's trace. When `TRACEPARENT` is unset the spans form their own trace,
+ * which is still valid.
+ *
+ * ## Fail-safe shutdown
+ *
+ * Telemetry must never crash OR hang the primary CLI run: a dead/slow collector
+ * has to degrade to "spans dropped," not a multi-second stall on exit (amplified
+ * on the sharded path, where every shard-worker subprocess also flushes). Two
+ * bounds enforce this: each export attempt is capped at {@link SHUTDOWN_TIMEOUT_MS}
+ * (`OTLPTraceExporter({ timeoutMillis })`), and {@link shutdownTelemetry} races the
+ * final flush against the same deadline and swallows any failure.
+ */
+import { type Context } from '@opentelemetry/api';
+/**
+ * Initialize OpenTelemetry tracing, gated on `OTEL_EXPORTER_OTLP_ENDPOINT`.
+ *
+ * No-op when the endpoint env var is falsy, or when already started (idempotent
+ * and safe to call from multiple entry points). Sets the GLOBAL tracer provider
+ * so `core`'s `getTracer` resolves to real tracers process-wide.
+ *
+ * @param cliEntryUrl `import.meta.url` of the CLI entry, used to read the CLI
+ *   package version for the `service.version` resource attribute.
+ */
+export declare function initTelemetry(cliEntryUrl: string): void;
+/**
+ * The parent context extracted from `TRACEPARENT`, or undefined. Exposed for
+ * tests; production code should prefer {@link runWithTelemetryContext}.
+ */
+export declare function parentTelemetryContext(): Context | undefined;
+/**
+ * Run `fn` with the extracted parent context active (when present), so spans
+ * created inside nest under the consumer's trace. A plain pass-through when no
+ * parent context was extracted (or telemetry is disabled), so standalone runs
+ * pay nothing.
+ */
+export declare function runWithTelemetryContext<T>(fn: () => T): T;
+/**
+ * Flush and shut down the tracer + meter providers (and stop profiling if active)
+ * so batched data export before the short-lived process exits.
+ * No-op when telemetry was never started. Swallows shutdown errors — a dead
+ * collector must not crash the CLI on the way out.
+ */
+export declare function shutdownTelemetry(): Promise<void>;
+/**
+ * Resolve when `work` settles, or reject with {@link TimeoutError} after `ms` —
+ * whichever comes first. The deadline timer is `unref`'d so it never keeps the
+ * (short-lived CLI) event loop alive when the work wins, and cleared on the
+ * happy path. Exported for tests.
+ */
+export declare function raceWithTimeout(work: Promise<void>, ms: number): Promise<void>;
+/**
+ * Test-only reset of module state. Production never calls this — the CLI is a
+ * one-shot process. Tests use it to exercise the gate across env permutations
+ * without a fresh module each time.
+ */
+export declare function resetTelemetryForTests(): void;
+//# sourceMappingURL=sdk-init.d.ts.map

package/dist/telemetry/sdk-init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk-init.d.ts","sourceRoot":"","sources":["../../src/telemetry/sdk-init.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAGH,OAAO,EAML,KAAK,OAAO,EACb,MAAM,oBAAoB,CAAC;AA8C5B;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAgEvD;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,GAAG,SAAS,CAE5D;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAEzD;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAyCvD;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBpF;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAG7C"}

package/dist/telemetry/sdk-init.js

@@ -0,0 +1,235 @@
+/**
+ * OpenTelemetry SDK init — the application half of the OTel library/application
+ * split, wired ONLY at the CLI composition root.
+ *
+ * ## Opt-in gate (the load-bearing contract)
+ *
+ * The entire SDK (traces + metrics + optional profiling) is gated on
+ * `OTEL_EXPORTER_OTLP_ENDPOINT` (see ADR-0049 and observability plan for details).
+ *
+ *   - **Set** ⇒ register NodeTracerProvider + (Phase 2) MeterProvider.
+ *     `core`'s `getTracer`/`withSpan`/`getMeter` resolve to real implementations.
+ *   - Profiling uses the same endpoint (recommended with dedicated
+ *     `OPENSIP_PROFILING=1` flag for cost control; "OTEL endpoint alone" mode
+ *     is supported with warnings).
+ *   - **Unset** ⇒ hard no-op for everything. Standalone CLI pays nothing.
+ *
+ * ## Layering
+ *
+ * The heavy SDK packages (`@opentelemetry/sdk-trace-node`, the OTLP exporter,
+ * `context-async-hooks`, `core`'s propagator, `resources`) are imported HERE
+ * and nowhere else. `core` and the tool packages depend on `@opentelemetry/api`
+ * only — dependency-cruiser enforces that an `@opentelemetry/sdk-*` import never
+ * leaks into the kernel or a tool.
+ *
+ * ## Parent-trace nesting
+ *
+ * An embedding consumer spawns the binary with a `TRACEPARENT` env var. We
+ * extract it via the W3C propagator and expose it as a parent context
+ * ({@link parentTelemetryContext} / {@link runWithTelemetryContext}) so the
+ * command dispatch — and therefore graph's stage spans — nests under the
+ * consumer's trace. When `TRACEPARENT` is unset the spans form their own trace,
+ * which is still valid.
+ *
+ * ## Fail-safe shutdown
+ *
+ * Telemetry must never crash OR hang the primary CLI run: a dead/slow collector
+ * has to degrade to "spans dropped," not a multi-second stall on exit (amplified
+ * on the sharded path, where every shard-worker subprocess also flushes). Two
+ * bounds enforce this: each export attempt is capped at {@link SHUTDOWN_TIMEOUT_MS}
+ * (`OTLPTraceExporter({ timeoutMillis })`), and {@link shutdownTelemetry} races the
+ * final flush against the same deadline and swallows any failure.
+ */
+import { logger, readPackageVersion, TimeoutError } from '@opensip-cli/core';
+import { ROOT_CONTEXT, context as otelContext, defaultTextMapGetter, metrics, trace, } from '@opentelemetry/api';
+import { AsyncLocalStorageContextManager } from '@opentelemetry/context-async-hooks';
+import { W3CTraceContextPropagator } from '@opentelemetry/core';
+import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { resourceFromAttributes, detectResources, envDetector } from '@opentelemetry/resources';
+import { MeterProvider, PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics';
+import { BatchSpanProcessor, NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from '@opentelemetry/semantic-conventions';
+import { hostEnv } from '../env/host-env-specs.js';
+import { stopProfiling, resetProfilingForTests } from './profiling.js';
+/**
+ * Hard ceiling (ms) on the final span flush AND on each individual export
+ * attempt. A dead/slow collector degrades to "spans dropped," never a hang on
+ * CLI or shard-worker exit. Kept short — a few seconds of lost batched spans is
+ * a fair trade for never stalling the primary run.
+ */
+const SHUTDOWN_TIMEOUT_MS = 2000;
+/** Idempotency guard — provider registration is process-wide and one-shot. */
+let started = false;
+/** Internal shared reset of the process-wide telemetry state. */
+function resetTelemetryState() {
+    started = false;
+    provider = undefined;
+    meterProvider = undefined;
+    parentContext = undefined;
+}
+/** The active tracer provider, retained so {@link shutdownTelemetry} can flush it. */
+let provider;
+/** The active meter provider (Phase 2). */
+let meterProvider;
+/**
+ * Parent context extracted from `TRACEPARENT`, or undefined when the var is
+ * absent (or telemetry is disabled). {@link runWithTelemetryContext} activates
+ * it so spans created during the run nest under the consumer's trace.
+ */
+let parentContext;
+/**
+ * Initialize OpenTelemetry tracing, gated on `OTEL_EXPORTER_OTLP_ENDPOINT`.
+ *
+ * No-op when the endpoint env var is falsy, or when already started (idempotent
+ * and safe to call from multiple entry points). Sets the GLOBAL tracer provider
+ * so `core`'s `getTracer` resolves to real tracers process-wide.
+ *
+ * @param cliEntryUrl `import.meta.url` of the CLI entry, used to read the CLI
+ *   package version for the `service.version` resource attribute.
+ */
+export function initTelemetry(cliEntryUrl) {
+    if (started)
+        return;
+    const endpoint = hostEnv.get('OTEL_EXPORTER_OTLP_ENDPOINT');
+    if (!endpoint)
+        return;
+    // Resource: explicit service identity merged with consumer-supplied
+    // attributes from OTEL_RESOURCE_ATTRIBUTES (via the env detector), e.g.
+    // `tenant_id=...,run_id=...`.
+    const resource = detectResources({ detectors: [envDetector] }).merge(resourceFromAttributes({
+        [ATTR_SERVICE_NAME]: 'opensip-cli',
+        [ATTR_SERVICE_VERSION]: readPackageVersion(cliEntryUrl),
+    }));
+    provider = new NodeTracerProvider({
+        resource,
+        // Bound each export attempt so a slow/dead collector fails fast instead of
+        // letting the batch processor block the final flush — see SHUTDOWN_TIMEOUT_MS.
+        spanProcessors: [
+            new BatchSpanProcessor(new OTLPTraceExporter({ timeoutMillis: SHUTDOWN_TIMEOUT_MS })),
+        ],
+    });
+    // register() installs the GLOBAL provider + propagator + context manager,
+    // so core's getTracer (Phase 0) resolves to real tracers everywhere.
+    provider.register({
+        contextManager: new AsyncLocalStorageContextManager().enable(),
+        propagator: new W3CTraceContextPropagator(),
+    });
+    // Phase 2: MeterProvider for metrics (same resource + gate).
+    // Uses PeriodicExportingMetricReader; for short-lived CLI the interesting
+    // export happens on shutdownTelemetry. No-op when gate closed.
+    meterProvider = new MeterProvider({
+        resource,
+        readers: [
+            new PeriodicExportingMetricReader({
+                exporter: new OTLPMetricExporter({ timeoutMillis: SHUTDOWN_TIMEOUT_MS }),
+                exportIntervalMillis: 5000, // short for CLI; shutdown forces final export
+            }),
+        ],
+    });
+    // Register globally so that core's getMeter() (and any tool code using
+    // @opentelemetry/api metrics.getMeter) resolves to this provider's meters.
+    // Without this, all CLI + tool metrics are silently no-op even when the
+    // OTLP endpoint is configured (the reader/exporter wiring is useless if
+    // nothing ever creates instruments against the provider).
+    metrics.setGlobalMeterProvider(meterProvider);
+    // Parent-trace nesting: extract the W3C traceparent the consumer passed via
+    // env so the run's spans attach under the parent trace. Unset ⇒ own trace.
+    const traceparent = hostEnv.get('TRACEPARENT');
+    if (traceparent) {
+        parentContext = new W3CTraceContextPropagator().extract(ROOT_CONTEXT, { traceparent }, defaultTextMapGetter);
+        // Only keep it if it actually yielded a valid span context.
+        if (!trace.getSpanContext(parentContext))
+            parentContext = undefined;
+    }
+    started = true;
+}
+/**
+ * The parent context extracted from `TRACEPARENT`, or undefined. Exposed for
+ * tests; production code should prefer {@link runWithTelemetryContext}.
+ */
+export function parentTelemetryContext() {
+    return parentContext;
+}
+/**
+ * Run `fn` with the extracted parent context active (when present), so spans
+ * created inside nest under the consumer's trace. A plain pass-through when no
+ * parent context was extracted (or telemetry is disabled), so standalone runs
+ * pay nothing.
+ */
+export function runWithTelemetryContext(fn) {
+    return parentContext ? otelContext.with(parentContext, fn) : fn();
+}
+/**
+ * Flush and shut down the tracer + meter providers (and stop profiling if active)
+ * so batched data export before the short-lived process exits.
+ * No-op when telemetry was never started. Swallows shutdown errors — a dead
+ * collector must not crash the CLI on the way out.
+ */
+export async function shutdownTelemetry() {
+    if (!started)
+        return;
+    // Stop profiling first (it may write files and is cheap).
+    try {
+        void stopProfiling();
+    }
+    catch {
+        // @swallow-ok best-effort profiling stop during SDK shutdown
+    }
+    const shutdowns = [];
+    if (provider) {
+        shutdowns.push(raceWithTimeout(provider.shutdown(), SHUTDOWN_TIMEOUT_MS).catch((error) => {
+            logger.warn('telemetry.shutdown.failed', {
+                evt: 'telemetry.shutdown.failed',
+                module: 'cli:telemetry',
+                kind: 'tracer',
+                err: error instanceof Error ? error.message : String(error),
+            });
+        }));
+    }
+    if (meterProvider) {
+        shutdowns.push(raceWithTimeout(meterProvider.shutdown(), SHUTDOWN_TIMEOUT_MS).catch((error) => {
+            logger.warn('telemetry.shutdown.failed', {
+                evt: 'telemetry.shutdown.failed',
+                module: 'cli:telemetry',
+                kind: 'meter',
+                err: error instanceof Error ? error.message : String(error),
+            });
+        }));
+    }
+    if (shutdowns.length > 0) {
+        await Promise.all(shutdowns);
+    }
+}
+/**
+ * Resolve when `work` settles, or reject with {@link TimeoutError} after `ms` —
+ * whichever comes first. The deadline timer is `unref`'d so it never keeps the
+ * (short-lived CLI) event loop alive when the work wins, and cleared on the
+ * happy path. Exported for tests.
+ */
+export async function raceWithTimeout(work, ms) {
+    let timer;
+    try {
+        await Promise.race([
+            work,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new TimeoutError(`telemetry shutdown exceeded ${String(ms)}ms`)), ms);
+                timer.unref();
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+/**
+ * Test-only reset of module state. Production never calls this — the CLI is a
+ * one-shot process. Tests use it to exercise the gate across env permutations
+ * without a fresh module each time.
+ */
+export function resetTelemetryForTests() {
+    resetTelemetryState();
+    resetProfilingForTests();
+}
+//# sourceMappingURL=sdk-init.js.map

package/dist/telemetry/sdk-init.js.map

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

package/dist/ui/App.d.ts

@@ -0,0 +1,32 @@
+/**
+ * App — top-level Ink shell. Renders the banner + project line, then the
+ * result body via the shared view-model (`resultToView` → `renderToInk`).
+ *
+ * There is no per-result-type rendering here anymore: every CommandResult
+ * is expressed once as a ViewNode by `resultToView`, and the same node is
+ * rendered to plain text on the non-TTY path (bootstrap/render.ts). This
+ * shell owns only the chrome the plain-text path intentionally omits — the
+ * banner and the `ℹ Project:` line.
+ */
+import React from 'react';
+import type { CommandResult } from '@opensip-cli/contracts';
+import type { UiContext } from '@opensip-cli/core';
+/** Project location for the shell's `ℹ Project:` line. */
+export interface ProjectHeaderProps {
+    readonly root: string;
+    readonly walkedUp: number;
+}
+export interface AppProps {
+    readonly result: CommandResult;
+    /** Omitted for project-agnostic commands (init/configure/completion) and scopeless error paths. */
+    readonly projectHeader?: ProjectHeaderProps;
+    /** Presentation settings (banner size + version). Omitted on scopeless paths. */
+    readonly ui?: UiContext;
+}
+/**
+ * App shell — the single source of truth for banner visibility. Renders
+ * the banner once for every human-facing command, then the result body
+ * through the shared view-model.
+ */
+export declare function App({ result, projectHeader, ui }: AppProps): React.ReactElement;
+//# sourceMappingURL=App.d.ts.map

package/dist/ui/App.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"App.d.ts","sourceRoot":"","sources":["../../src/ui/App.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAUH,OAAO,KAAK,MAAM,OAAO,CAAC;AAI1B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEnD,0DAA0D;AAC1D,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,mGAAmG;IACnG,QAAQ,CAAC,aAAa,CAAC,EAAE,kBAAkB,CAAC;IAC5C,iFAAiF;IACjF,QAAQ,CAAC,EAAE,CAAC,EAAE,SAAS,CAAC;CACzB;AAUD;;;;GAIG;AACH,wBAAgB,GAAG,CAAC,EAAE,MAAM,EAAE,aAAa,EAAE,EAAE,EAAE,EAAE,QAAQ,GAAG,KAAK,CAAC,YAAY,CAwB/E"}

package/dist/ui/App.js

@@ -0,0 +1,35 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * App — top-level Ink shell. Renders the banner + project line, then the
+ * result body via the shared view-model (`resultToView` → `renderToInk`).
+ *
+ * There is no per-result-type rendering here anymore: every CommandResult
+ * is expressed once as a ViewNode by `resultToView`, and the same node is
+ * rendered to plain text on the non-TTY path (bootstrap/render.ts). This
+ * shell owns only the chrome the plain-text path intentionally omits — the
+ * banner and the `ℹ Project:` line.
+ */
+import { Banner, UpdateHint, normalizeBannerSize, ProjectHeader, renderToInk, } from '@opensip-cli/cli-ui';
+import { Box } from 'ink';
+import { resultToView } from './result-to-view.js';
+/**
+ * Result types that render WITHOUT the banner. `error` stays terse — a
+ * bare `✗` line reads better in CI logs and above a stack of error text.
+ * `--json` and `completion` never reach this component (they bypass the
+ * Ink render seam entirely), so they need no entry here.
+ */
+const BANNERLESS_RESULT_TYPES = new Set(['error']);
+/**
+ * App shell — the single source of truth for banner visibility. Renders
+ * the banner once for every human-facing command, then the result body
+ * through the shared view-model.
+ */
+export function App({ result, projectHeader, ui }) {
+    const showBanner = !BANNERLESS_RESULT_TYPES.has(result.type);
+    const bannerSize = normalizeBannerSize(ui?.bannerSize);
+    // `mini` carries the project path inside its boxed card, so the separate
+    // `ℹ Project:` line would duplicate it — suppress ProjectHeader for mini.
+    const showProjectHeader = bannerSize !== 'mini' && projectHeader !== undefined;
+    return (_jsxs(Box, { flexDirection: "column", children: [showBanner && (_jsx(Banner, { size: bannerSize, version: ui?.version, projectPath: projectHeader?.root, walkedUp: projectHeader?.walkedUp, update: ui?.update })), showBanner && bannerSize === 'mini' && ui?.update !== undefined && _jsx(UpdateHint, {}), showBanner && showProjectHeader && (_jsx(ProjectHeader, { root: projectHeader.root, walkedUp: projectHeader.walkedUp })), renderToInk(resultToView(result))] }));
+}
+//# sourceMappingURL=App.js.map

package/dist/ui/App.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"App.js","sourceRoot":"","sources":["../../src/ui/App.tsx"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,MAAM,EACN,UAAU,EACV,mBAAmB,EACnB,aAAa,EACb,WAAW,GACZ,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC;AAG1B,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAmBnD;;;;;GAKG;AACH,MAAM,uBAAuB,GAAuC,IAAI,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;AAEvF;;;;GAIG;AACH,MAAM,UAAU,GAAG,CAAC,EAAE,MAAM,EAAE,aAAa,EAAE,EAAE,EAAY;IACzD,MAAM,UAAU,GAAG,CAAC,uBAAuB,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC7D,MAAM,UAAU,GAAG,mBAAmB,CAAC,EAAE,EAAE,UAAU,CAAC,CAAC;IACvD,yEAAyE;IACzE,0EAA0E;IAC1E,MAAM,iBAAiB,GAAG,UAAU,KAAK,MAAM,IAAI,aAAa,KAAK,SAAS,CAAC;IAC/E,OAAO,CACL,MAAC,GAAG,IAAC,aAAa,EAAC,QAAQ,aACxB,UAAU,IAAI,CACb,KAAC,MAAM,IACL,IAAI,EAAE,UAAU,EAChB,OAAO,EAAE,EAAE,EAAE,OAAO,EACpB,WAAW,EAAE,aAAa,EAAE,IAAI,EAChC,QAAQ,EAAE,aAAa,EAAE,QAAQ,EACjC,MAAM,EAAE,EAAE,EAAE,MAAM,GAClB,CACH,EACA,UAAU,IAAI,UAAU,KAAK,MAAM,IAAI,EAAE,EAAE,MAAM,KAAK,SAAS,IAAI,KAAC,UAAU,KAAG,EACjF,UAAU,IAAI,iBAAiB,IAAI,CAClC,KAAC,aAAa,IAAC,IAAI,EAAE,aAAa,CAAC,IAAI,EAAE,QAAQ,EAAE,aAAa,CAAC,QAAQ,GAAI,CAC9E,EACA,WAAW,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,IAC9B,CACP,CAAC;AACJ,CAAC"}

package/dist/ui/render.d.ts

@@ -0,0 +1,15 @@
+/**
+ * render — entry point for the CLI's static Ink rendering.
+ *
+ * Single responsibility: render a completed `CommandResult` through the
+ * tool-agnostic `App` component. Tools that drive a stateful live view
+ * (fitness, graph) own their own renderers in their packages and
+ * register them via `cli.registerLiveView`; this file no longer mounts
+ * any tool-specific component. Layer 5 Phase 3 (audit 2026-05-23 F3).
+ */
+import { type ProjectHeaderProps } from './App.js';
+import type { CommandResult } from '@opensip-cli/contracts';
+import type { UiContext } from '@opensip-cli/core';
+/** Render a static command result. */
+export declare function renderApp(result: CommandResult, projectHeader?: ProjectHeaderProps, ui?: UiContext): Promise<void>;
+//# sourceMappingURL=render.d.ts.map

package/dist/ui/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/ui/render.tsx"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,EAAO,KAAK,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAExD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEnD,sCAAsC;AACtC,wBAAsB,SAAS,CAC7B,MAAM,EAAE,aAAa,EACrB,aAAa,CAAC,EAAE,kBAAkB,EAClC,EAAE,CAAC,EAAE,SAAS,GACb,OAAO,CAAC,IAAI,CAAC,CAYf"}

package/dist/ui/render.js

@@ -0,0 +1,21 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * render — entry point for the CLI's static Ink rendering.
+ *
+ * Single responsibility: render a completed `CommandResult` through the
+ * tool-agnostic `App` component. Tools that drive a stateful live view
+ * (fitness, graph) own their own renderers in their packages and
+ * register them via `cli.registerLiveView`; this file no longer mounts
+ * any tool-specific component. Layer 5 Phase 3 (audit 2026-05-23 F3).
+ */
+import { ThemeProvider } from '@opensip-cli/cli-ui';
+import { App } from './App.js';
+/** Render a static command result. */
+export async function renderApp(result, projectHeader, ui) {
+    const { render } = await import('ink');
+    const app = render(_jsx(ThemeProvider, { children: _jsx(App, { result: result, projectHeader: projectHeader, ui: ui }) }));
+    app.unmount();
+    // Trailing newline so shell prompt starts on a new line
+    process.stdout.write('\n');
+}
+//# sourceMappingURL=render.js.map

package/dist/ui/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../../src/ui/render.tsx"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGpD,OAAO,EAAE,GAAG,EAA2B,MAAM,UAAU,CAAC;AAKxD,sCAAsC;AACtC,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,MAAqB,EACrB,aAAkC,EAClC,EAAc;IAEd,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,CAAC;IAEvC,MAAM,GAAG,GAAG,MAAM,CAChB,KAAC,aAAa,cACZ,KAAC,GAAG,IAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,aAAa,EAAE,EAAE,EAAE,EAAE,GAAI,GAC/C,CACjB,CAAC;IAEF,GAAG,CAAC,OAAO,EAAE,CAAC;IACd,wDAAwD;IACxD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC"}