vibesane 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vibesane Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,115 @@
-# Temporary Holding Version
+# vibesane
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Preflight sanity check for vibe-coded web apps, typically under 3 seconds. Zero config, zero runtime dependencies, instant copy-paste AI fix prompts.
+
+## Quickstart
+
+Start your local dev server (`npm run dev`), then run in another terminal:
+
+```bash
+npx vibesane
+```
+
+Check a specific port:
+
+```bash
+npx vibesane --port 8080
+```
+
+**Requirement:** Node.js `>= 22.13.0`.
+
+## Pipe Directly to Clipboard (`pbcopy` / `clip`)
+
+All scan output goes to `stdout` (`stderr` receives only CLI usage errors, exit code `2`, and unexpected internal errors), so you can pipe the report and AI fix prompt directly to your clipboard:
+
+macOS:
+
+```bash
+npx vibesane | pbcopy
+```
+
+Windows (`cmd.exe` or PowerShell):
+
+```powershell
+npx vibesane | clip
+```
+
+> **Windows UTF-8 Note:** `vibesane` emits pure ASCII headers, separators, and code frames so `| clip` works cleanly even under the default Windows codepage (`CP850`). If your own application code contains accented characters (e.g., Portuguese or Spanish) that you want to preserve when copying on Windows:
+> - **PowerShell:** `[Console]::OutputEncoding = [Text.Encoding]::UTF8; npx vibesane | Set-Clipboard`
+> - **`cmd.exe`:** `chcp 65001 >nul && npx vibesane | clip`
+
+## Real Output Example
+
+```text
+vibesane: sanity check failed on http://localhost:5173 (2 error(s))
+error [http_error]: HTTP 500 on script /src/components/Pay.tsx:2:98 - [PARSE_ERROR] Expected `,` or `}` but found `Identifier`
+     +-[ src/components/Pay.tsx:2:98 ]
+     |
+   2 |   const broken = { stripeKey: "sk_live_****abcd", msg: "Olá, senha inválida" b: 2 };
+     |                  +                                                                               +
+     |                  +---------------------------------------------------------------------------------- Opened here
+     |                                                                                                  |
+     |                                                                                                  +-- `,` or `}` expected
+  ---+
+error [secret_leak]: Secret leak on /src/components/Pay.tsx: Stripe secret key (sk_live_****abcd)
+
+AI FIX PROMPT (copy & paste into Cursor / Claude Code / Gemini CLI):
+Target: http://localhost:5173
+1. [http_error] HTTP 500 on script /src/components/Pay.tsx:2:98 - [PARSE_ERROR] Expected `,` or `}` but found `Identifier`
+      +-[ src/components/Pay.tsx:2:98 ]
+      |
+    2 |   const broken = { stripeKey: "sk_live_****abcd", msg: "Olá, senha inválida" b: 2 };
+      |                  +                                                                               +
+      |                  +---------------------------------------------------------------------------------- Opened here
+      |                                                                                                  |
+      |                                                                                                  +-- `,` or `}` expected
+   ---+
+2. [secret_leak] Secret leak on /src/components/Pay.tsx: Stripe secret key (sk_live_****abcd)
+Instruction (secrets): Move this key to a server-only environment variable (never NEXT_PUBLIC_ / VITE_) and rotate it if it was ever committed or deployed.
+Instruction (code): Fix only the error pointed out above; do not refactor unrelated code.
+```
+
+## What It Checks
+
+- **Dual-Stack Port Auto-Detection:** Probes `127.0.0.1` and `::1` across `3000, 3001, 5173, 5174, 8080, 8000, 4321` and confirms an active HTTP server.
+- **HTTP Status & Route Crawling:** Checks `/` plus up to 10 internal routes (`<a href>`) and up to 5 application scripts/modules (`<script src>` and first-level `/src/` ESM imports) for `4xx`/`5xx` responses.
+- **Masked Error Overlays on `200 OK`:** Detects Next.js and Vite runtime/compile error overlays hidden inside `200 OK` HTML responses, including Next 16 RSC/Flight error payloads and Vite/Oxc code frames.
+- **Client-Side Secret Leaks:** Scans HTML and JS bundles for exposed secrets (`sk_live_*`, `sk_test_*`, `rk_live_*`, `rk_test_*`, `AIzaSy*`, `ghp_*`, `sk-proj-*`, `sk-ant-*`, `*_SECRET`, `*_PRIVATE_KEY`, `DATABASE_URL` with credentials, and hardcoded `password`/`senha` assignments), resolving the original source file inside Turbopack and Webpack chunks while ignoring public keys (`pk_live_*`, `pk_test_*`, `NEXT_PUBLIC_*`, `VITE_*`).
+- **Slow Routes:** Flags routes taking `> 1500ms` to return headers as `warning [slow_route]`.
+
+## Next.js Cold Start (On-Demand Compilation)
+
+Right after starting `next dev`, Next.js compiles routes on demand on the very first request:
+
+- If the root route `/` takes **more than 2 seconds** to compile, the port detector exits with an HTTP timeout (exit code `1`: `port 3000 accepted the connection but took >2s to respond (still compiling?)`).
+- If sub-routes take too long to compile on first hit, they are reported as `warning [slow_route]` or `info: N route(s) not checked (time budget reached)`.
+- **Fix:** Simply **run `npx vibesane` again** — once the dev server has compiled and cached the route, the scan finishes in milliseconds.
+
+## Limitations (What It Does Not Do)
+
+- **No Headless Browser (Not Playwright/Cypress):** Runs fast HTTP/HTML/JS inspection via `fetch`. It does not execute client-side JavaScript, click buttons, submit forms, or detect crashes that only trigger after DOM user interaction.
+- **HTML-Based Route Discovery:** Discovers sub-routes from `<a href="...">` links rendered in the HTML of `/`. In pure client-side SPAs where `<div id="root"></div>` is empty and routes exist only inside a client-side router, `vibesane` inspects `/` and up to 5 application JS modules (`/src/*`), but does not navigate client-only routes absent from initial HTML.
+- **No Authentication / Session State:** Protected routes redirecting to external login providers are skipped; same-origin redirects are followed up to 3 hops.
+- **Deterministic Caps:** Enforces a `2.5s` global crawl budget, up to `10` routes, `5` scripts, and `1 MB` per response body.
+
+## CLI Options & Exit Codes
+
+### Options
+
+| Flag | Description |
+| :--- | :--- |
+| `-p, --port <number>` | Check a specific TCP port (`1-65535`) instead of auto-detecting |
+| `-h, --help` | Show CLI usage information |
+| `-v, --version` | Print the package version |
+
+### Exit Codes
+
+| Code | Meaning |
+| :--- | :--- |
+| `0` | All sanity checks passed (including non-fatal warnings) |
+| `1` | Sanity check failed (`http_error`, `masked_error`, `secret_leak`) or no local HTTP server found |
+| `2` | CLI usage error (invalid flag or invalid `--port` value) |
+
+## License
+
+MIT

package/bin/vibesane.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from '../dist/cli.js';
+process.exitCode = await main(process.argv.slice(2));

package/dist/cli.d.ts

@@ -0,0 +1,5 @@
+export interface CliIO {
+    stdout: (msg: string) => void;
+    stderr: (msg: string) => void;
+}
+export declare function main(argv?: string[], io?: Partial<CliIO>): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,79 @@
+import { parseArgs } from 'node:util';
+import { readFileSync } from 'node:fs';
+import { runVibesane, EXIT_CODES } from './index.js';
+import { formatTerminalReport, shouldEnableColor } from './reporter/terminal-ui.js';
+const HELP_TEXT = [
+    'Usage: vibesane [options]',
+    '',
+    'Options:',
+    '  -p, --port <number>  Target local port (1-65535)',
+    '  -h, --help           Show help',
+    '  -v, --version        Show version',
+].join('\n');
+function getVersion() {
+    const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+    return pkg.version;
+}
+export async function main(argv = process.argv.slice(2), io = {}) {
+    const stdout = io.stdout ?? ((msg) => process.stdout.write(`${msg}\n`));
+    const stderr = io.stderr ?? ((msg) => process.stderr.write(`${msg}\n`));
+    const stopIdx = argv.indexOf('--');
+    const activeArgs = stopIdx === -1 ? argv : argv.slice(0, stopIdx);
+    if (activeArgs.includes('--help') || activeArgs.includes('-h')) {
+        stdout(HELP_TEXT);
+        return EXIT_CODES.OK;
+    }
+    if (activeArgs.includes('--version') || activeArgs.includes('-v')) {
+        stdout(getVersion());
+        return EXIT_CODES.OK;
+    }
+    let values;
+    try {
+        const parsed = parseArgs({
+            args: argv,
+            strict: true,
+            allowPositionals: false,
+            options: {
+                port: { type: 'string', short: 'p', multiple: true },
+                help: { type: 'boolean', short: 'h' },
+                version: { type: 'boolean', short: 'v' },
+            },
+        });
+        values = parsed.values;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        stderr(`vibesane: error: ${message}`);
+        return EXIT_CODES.USAGE_ERROR;
+    }
+    if (values.help) {
+        stdout(HELP_TEXT);
+        return EXIT_CODES.OK;
+    }
+    if (values.version) {
+        stdout(getVersion());
+        return EXIT_CODES.OK;
+    }
+    let portNum;
+    if (values.port !== undefined) {
+        if (values.port.length > 1) {
+            stderr('vibesane: error: option --port cannot be specified multiple times');
+            return EXIT_CODES.USAGE_ERROR;
+        }
+        const rawPort = values.port[0];
+        if (rawPort === undefined || !/^[1-9]\d*$/.test(rawPort)) {
+            stderr(`vibesane: error: invalid port "${rawPort ?? ''}" (expected integer 1-65535)`);
+            return EXIT_CODES.USAGE_ERROR;
+        }
+        portNum = Number(rawPort);
+        if (portNum < 1 || portNum > 65535) {
+            stderr(`vibesane: error: invalid port "${rawPort}" (expected integer 1-65535)`);
+            return EXIT_CODES.USAGE_ERROR;
+        }
+    }
+    const result = await runVibesane(portNum !== undefined ? { port: portNum } : {});
+    const useColor = io.stdout === undefined && shouldEnableColor();
+    const output = formatTerminalReport(result, { color: useColor });
+    stdout(output);
+    return result.ok ? EXIT_CODES.OK : EXIT_CODES.SANITY_FAILURE;
+}

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+import { DEFAULT_PORTS, DEFAULT_TCP_TIMEOUT_MS, DEFAULT_HTTP_TIMEOUT_MS, DEFAULT_BODY_READ_TIMEOUT_MS, MAX_BODY_BYTES, assertValidPort, assertValidTimeout, readBoundedTextBody, probeTcpPort, detectServer, type LoopbackHost, type DetectionFailureReason, type PortDetectorOptions, type TcpProbeResult, type RootHttpSnapshot, type PortDetectionResult } from './scanner/port-detector.js';
+import { redactSecret, redactPassword, redactConnectionUri, stripViteTimestampQuery, resolveBundledSourceFile, sanitizeSecretsInText, sanitizeErrorSnippet, extractViteErrorInfo, extractNextErrorInfo, detectMaskedError, scanSecrets, type SanitySeverity, type SanityIssueKind, type SanityIssue } from './scanner/security-scan.js';
+import { DEFAULT_SCAN_BUDGET_MS, DEFAULT_ROUTE_TIMEOUT_MS, DEFAULT_SLOW_ROUTE_MS, DEFAULT_MAX_ROUTES, DEFAULT_MAX_SCRIPTS, DEFAULT_MAX_CONCURRENCY, MAX_REDIRECTS, isExcludedFrameworkScript, getScriptPriority, extractInternalLinks, extractCandidateScripts, selectScriptsToFetch, extractModuleImports, runSanityScan, type RouteScanItem, type SanityScanOptions, type SanityScanSummary } from './scanner/route-crawler.js';
+import { AI_PROMPT_HEADER, SECRET_LEAK_INSTRUCTION, CODE_ERROR_INSTRUCTION, MAX_PROMPT_ERRORS, stripAnsiCodes, generateAiFixPrompt, type AiPromptIssue, type AiPromptInput } from './reporter/ai-prompt-gen.js';
+import { shouldEnableColor, formatTerminalReport, type VibesaneReportInput, type TerminalReportOptions } from './reporter/terminal-ui.js';
+export type AiPromptIssueInput = AiPromptIssue;
+export { DEFAULT_PORTS, DEFAULT_TCP_TIMEOUT_MS, DEFAULT_HTTP_TIMEOUT_MS, DEFAULT_BODY_READ_TIMEOUT_MS, MAX_BODY_BYTES, assertValidPort, assertValidTimeout, readBoundedTextBody, probeTcpPort, detectServer, type LoopbackHost, type DetectionFailureReason, type PortDetectorOptions, type TcpProbeResult, type RootHttpSnapshot, type PortDetectionResult, redactSecret, redactPassword, redactConnectionUri, stripViteTimestampQuery, resolveBundledSourceFile, sanitizeSecretsInText, sanitizeErrorSnippet, extractViteErrorInfo, extractNextErrorInfo, detectMaskedError, scanSecrets, type SanitySeverity, type SanityIssueKind, type SanityIssue, DEFAULT_SCAN_BUDGET_MS, DEFAULT_ROUTE_TIMEOUT_MS, DEFAULT_SLOW_ROUTE_MS, DEFAULT_MAX_ROUTES, DEFAULT_MAX_SCRIPTS, DEFAULT_MAX_CONCURRENCY, MAX_REDIRECTS, isExcludedFrameworkScript, getScriptPriority, extractInternalLinks, extractCandidateScripts, selectScriptsToFetch, extractModuleImports, runSanityScan, type RouteScanItem, type SanityScanOptions, type SanityScanSummary, AI_PROMPT_HEADER, SECRET_LEAK_INSTRUCTION, CODE_ERROR_INSTRUCTION, MAX_PROMPT_ERRORS, stripAnsiCodes, generateAiFixPrompt, type AiPromptIssue, type AiPromptInput, shouldEnableColor, formatTerminalReport, type VibesaneReportInput, type TerminalReportOptions, };
+export declare const EXIT_CODES: {
+    readonly OK: 0;
+    readonly SANITY_FAILURE: 1;
+    readonly USAGE_ERROR: 2;
+};
+export type ExitCode = (typeof EXIT_CODES)[keyof typeof EXIT_CODES];
+export interface VibesaneOptions extends PortDetectorOptions, SanityScanOptions {
+}
+export interface VibesaneResult extends PortDetectionResult {
+    routes: RouteScanItem[];
+    scannedScripts: string[];
+    skippedRoutes: string[];
+    issues: SanityIssue[];
+    aiPrompt: string | null;
+    message: string;
+}
+export declare function runVibesane(options?: VibesaneOptions): Promise<VibesaneResult>;

package/dist/index.js

@@ -0,0 +1,121 @@
+import { DEFAULT_PORTS, DEFAULT_TCP_TIMEOUT_MS, DEFAULT_HTTP_TIMEOUT_MS, DEFAULT_BODY_READ_TIMEOUT_MS, MAX_BODY_BYTES, assertValidPort, assertValidTimeout, readBoundedTextBody, probeTcpPort, detectServer, } from './scanner/port-detector.js';
+import { redactSecret, redactPassword, redactConnectionUri, stripViteTimestampQuery, resolveBundledSourceFile, sanitizeSecretsInText, sanitizeErrorSnippet, extractViteErrorInfo, extractNextErrorInfo, detectMaskedError, scanSecrets, } from './scanner/security-scan.js';
+import { DEFAULT_SCAN_BUDGET_MS, DEFAULT_ROUTE_TIMEOUT_MS, DEFAULT_SLOW_ROUTE_MS, DEFAULT_MAX_ROUTES, DEFAULT_MAX_SCRIPTS, DEFAULT_MAX_CONCURRENCY, MAX_REDIRECTS, isExcludedFrameworkScript, getScriptPriority, extractInternalLinks, extractCandidateScripts, selectScriptsToFetch, extractModuleImports, runSanityScan, } from './scanner/route-crawler.js';
+import { AI_PROMPT_HEADER, SECRET_LEAK_INSTRUCTION, CODE_ERROR_INSTRUCTION, MAX_PROMPT_ERRORS, stripAnsiCodes, generateAiFixPrompt, } from './reporter/ai-prompt-gen.js';
+import { shouldEnableColor, formatTerminalReport, } from './reporter/terminal-ui.js';
+export { DEFAULT_PORTS, DEFAULT_TCP_TIMEOUT_MS, DEFAULT_HTTP_TIMEOUT_MS, DEFAULT_BODY_READ_TIMEOUT_MS, MAX_BODY_BYTES, assertValidPort, assertValidTimeout, readBoundedTextBody, probeTcpPort, detectServer, redactSecret, redactPassword, redactConnectionUri, stripViteTimestampQuery, resolveBundledSourceFile, sanitizeSecretsInText, sanitizeErrorSnippet, extractViteErrorInfo, extractNextErrorInfo, detectMaskedError, scanSecrets, DEFAULT_SCAN_BUDGET_MS, DEFAULT_ROUTE_TIMEOUT_MS, DEFAULT_SLOW_ROUTE_MS, DEFAULT_MAX_ROUTES, DEFAULT_MAX_SCRIPTS, DEFAULT_MAX_CONCURRENCY, MAX_REDIRECTS, isExcludedFrameworkScript, getScriptPriority, extractInternalLinks, extractCandidateScripts, selectScriptsToFetch, extractModuleImports, runSanityScan, AI_PROMPT_HEADER, SECRET_LEAK_INSTRUCTION, CODE_ERROR_INSTRUCTION, MAX_PROMPT_ERRORS, stripAnsiCodes, generateAiFixPrompt, shouldEnableColor, formatTerminalReport, };
+export const EXIT_CODES = {
+    OK: 0,
+    SANITY_FAILURE: 1,
+    USAGE_ERROR: 2,
+};
+function validateSanityScanOptions(options) {
+    if (options.scanBudgetMs !== undefined) {
+        assertValidTimeout(options.scanBudgetMs, 'scanBudgetMs');
+    }
+    if (options.routeTimeoutMs !== undefined) {
+        assertValidTimeout(options.routeTimeoutMs, 'routeTimeoutMs');
+    }
+    if (options.slowRouteMs !== undefined) {
+        assertValidTimeout(options.slowRouteMs, 'slowRouteMs');
+    }
+    if (options.maxRoutes !== undefined &&
+        (!Number.isInteger(options.maxRoutes) || options.maxRoutes < 1)) {
+        throw new RangeError(`Invalid maxRoutes "${options.maxRoutes}": expected integer >= 1`);
+    }
+    if (options.maxScripts !== undefined &&
+        (!Number.isInteger(options.maxScripts) || options.maxScripts < 0)) {
+        throw new RangeError(`Invalid maxScripts "${options.maxScripts}": expected integer >= 0`);
+    }
+    if (options.maxConcurrency !== undefined &&
+        (!Number.isInteger(options.maxConcurrency) || options.maxConcurrency < 1)) {
+        throw new RangeError(`Invalid maxConcurrency "${options.maxConcurrency}": expected integer >= 1`);
+    }
+}
+function formatScanMessage(detection, ok, errors, warnings, skippedRoutes) {
+    const alsoSuffix = detection.alsoActivePorts.length > 0
+        ? ` (also active: ${detection.alsoActivePorts.join(', ')})`
+        : '';
+    const baseLine = `vibesane: connected to ${detection.url} (${detection.elapsedMs}ms)${alsoSuffix}`;
+    if (ok) {
+        const lines = [baseLine];
+        for (const w of warnings) {
+            lines.push(`warning [${w.kind}]: ${stripViteTimestampQuery(w.detail)}`);
+        }
+        if (skippedRoutes.length > 0) {
+            lines.push(`info: ${skippedRoutes.length} route(s) not checked (time budget reached): ${skippedRoutes.join(', ')}`);
+        }
+        return lines.join('\n');
+    }
+    const lines = [
+        `vibesane: sanity check failed on ${detection.url} (${errors.length} error(s))`,
+    ];
+    for (const e of errors) {
+        const cleanDetail = stripViteTimestampQuery(e.detail);
+        lines.push(`error [${e.kind}]: ${cleanDetail}`);
+    }
+    for (const w of warnings) {
+        lines.push(`warning [${w.kind}]: ${stripViteTimestampQuery(w.detail)}`);
+    }
+    if (skippedRoutes.length > 0) {
+        lines.push(`info: ${skippedRoutes.length} route(s) not checked (time budget reached): ${skippedRoutes.join(', ')}`);
+    }
+    return lines.join('\n');
+}
+export async function runVibesane(options = {}) {
+    validateSanityScanOptions(options);
+    const detection = await detectServer(options);
+    if (!detection.ok || detection.port === null || !detection.host || !detection.rootResponse) {
+        let message;
+        if (detection.reason === 'http_timeout') {
+            const httpTimeoutMs = options.httpTimeoutMs ?? DEFAULT_HTTP_TIMEOUT_MS;
+            const label = httpTimeoutMs % 1000 === 0 ? `${httpTimeoutMs / 1000}s` : `${httpTimeoutMs}ms`;
+            message = `vibesane: port ${detection.port} accepted the connection but took >${label} to respond (still compiling?)`;
+        }
+        else if (detection.reason === 'non_http') {
+            message = `vibesane: port ${detection.port} is open but did not respond to HTTP`;
+        }
+        else {
+            if (detection.checkedPorts.length === 1) {
+                message = `vibesane: no active server found on port ${detection.checkedPorts[0]}`;
+            }
+            else {
+                message = `vibesane: no active server found on ports ${detection.checkedPorts.join(', ')}`;
+            }
+        }
+        return {
+            ...detection,
+            routes: [],
+            scannedScripts: [],
+            skippedRoutes: [],
+            issues: [],
+            aiPrompt: null,
+            message,
+        };
+    }
+    const scan = await runSanityScan(detection.host, detection.port, detection.rootResponse, options);
+    const normalizedIssues = scan.issues.map((issue) => ({
+        ...issue,
+        route: stripViteTimestampQuery(issue.route),
+    }));
+    const errors = normalizedIssues.filter((i) => i.severity === 'error');
+    const warnings = normalizedIssues.filter((i) => i.severity === 'warning');
+    const ok = errors.length === 0;
+    const message = formatScanMessage(detection, ok, errors, warnings, scan.skippedRoutes);
+    const aiPrompt = generateAiFixPrompt({
+        ok,
+        port: detection.port,
+        url: detection.url,
+        issues: normalizedIssues,
+    });
+    return {
+        ...detection,
+        ok,
+        routes: scan.routes,
+        scannedScripts: scan.scannedScripts,
+        skippedRoutes: scan.skippedRoutes,
+        issues: normalizedIssues,
+        aiPrompt,
+        message,
+    };
+}

package/dist/reporter/ai-prompt-gen.d.ts

@@ -0,0 +1,18 @@
+import { stripViteTimestampQuery, type SanityIssue } from '../scanner/security-scan.js';
+export { stripViteTimestampQuery };
+export declare const AI_PROMPT_HEADER = "AI FIX PROMPT (copy & paste into Cursor / Claude Code / Gemini CLI):";
+export declare const SECRET_LEAK_INSTRUCTION = "Move this key to a server-only environment variable (never NEXT_PUBLIC_ / VITE_) and rotate it if it was ever committed or deployed.";
+export declare const CODE_ERROR_INSTRUCTION = "Fix only the error pointed out above; do not refactor unrelated code.";
+export declare const MAX_PROMPT_ERRORS = 10;
+export type AiPromptIssue = SanityIssue & {
+    codeFrame?: string;
+};
+export interface AiPromptInput {
+    ok: boolean;
+    port: number | null;
+    url?: string;
+    issues: readonly AiPromptIssue[];
+}
+export declare function stripAnsiCodes(value: string): string;
+export declare function detailContainsRoute(detail: string, route: string): boolean;
+export declare function generateAiFixPrompt(input: AiPromptInput): string | null;

package/dist/reporter/ai-prompt-gen.js

@@ -0,0 +1,101 @@
+import { stripViteTimestampQuery, } from '../scanner/security-scan.js';
+import { toAsciiSafe } from '../text/ascii.js';
+export { stripViteTimestampQuery };
+export const AI_PROMPT_HEADER = 'AI FIX PROMPT (copy & paste into Cursor / Claude Code / Gemini CLI):';
+export const SECRET_LEAK_INSTRUCTION = 'Move this key to a server-only environment variable (never NEXT_PUBLIC_ / VITE_) and rotate it if it was ever committed or deployed.';
+export const CODE_ERROR_INSTRUCTION = 'Fix only the error pointed out above; do not refactor unrelated code.';
+export const MAX_PROMPT_ERRORS = 10;
+const ANSI_ESCAPE_RE = /\x1b\[[0-9;]*m/g;
+export function stripAnsiCodes(value) {
+    if (!value) {
+        return '';
+    }
+    return value.replace(ANSI_ESCAPE_RE, '');
+}
+export function detailContainsRoute(detail, route) {
+    if (!detail || !route) {
+        return false;
+    }
+    const escaped = route.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(`(?:^|\\s)${escaped}(?=$|\\s|:|\\)|,)`).test(detail);
+}
+function formatIndentedCodeFrame(rawFrame, maxLines = 10) {
+    const clean = toAsciiSafe(stripAnsiCodes(rawFrame)).replace(/\r\n/g, '\n').trimEnd();
+    if (!clean) {
+        return '';
+    }
+    const lines = clean
+        .split('\n')
+        .map((line) => line.trimEnd())
+        .filter((line, idx, arr) => !(line === '' && (idx === 0 || idx === arr.length - 1)))
+        .slice(0, maxLines);
+    if (lines.length === 0) {
+        return '';
+    }
+    return lines.map((line) => `   ${line}`).join('\n');
+}
+export function generateAiFixPrompt(input) {
+    if (input.port === null || !Array.isArray(input.issues) || input.issues.length === 0) {
+        return null;
+    }
+    const errorIssues = input.issues.filter((issue) => issue.severity === 'error');
+    if (errorIssues.length === 0) {
+        return null;
+    }
+    const uniqueErrors = [];
+    const seenKeys = new Set();
+    for (const issue of errorIssues) {
+        const cleanRoute = toAsciiSafe(stripViteTimestampQuery(stripAnsiCodes(issue.route).trim())) || '/';
+        const cleanDetail = toAsciiSafe(stripViteTimestampQuery(stripAnsiCodes(issue.detail).trim()));
+        const dedupeKey = `${issue.kind}::${cleanRoute}::${cleanDetail}`;
+        if (seenKeys.has(dedupeKey)) {
+            continue;
+        }
+        seenKeys.add(dedupeKey);
+        const formattedFrame = issue.codeFrame
+            ? formatIndentedCodeFrame(issue.codeFrame, 10)
+            : '';
+        uniqueErrors.push({
+            kind: issue.kind,
+            route: cleanRoute,
+            detail: cleanDetail,
+            ...(formattedFrame ? { codeFrame: formattedFrame } : {}),
+        });
+    }
+    if (uniqueErrors.length === 0) {
+        return null;
+    }
+    const shownErrors = uniqueErrors.slice(0, MAX_PROMPT_ERRORS);
+    const remaining = uniqueErrors.length - shownErrors.length;
+    const lines = [AI_PROMPT_HEADER];
+    if (typeof input.url === 'string' && input.url.trim().length > 0) {
+        lines.push(`Target: ${toAsciiSafe(stripAnsiCodes(input.url.trim()))}`);
+    }
+    shownErrors.forEach((err, index) => {
+        if (detailContainsRoute(err.detail, err.route)) {
+            lines.push(`${index + 1}. [${err.kind}] ${err.detail}`);
+        }
+        else {
+            lines.push(`${index + 1}. [${err.kind}] ${err.route} - ${err.detail}`);
+        }
+        if (err.codeFrame) {
+            lines.push(err.codeFrame);
+        }
+    });
+    if (remaining > 0) {
+        lines.push(`...and ${remaining} more`);
+    }
+    const hasSecretLeak = uniqueErrors.some((err) => err.kind === 'secret_leak');
+    const hasCodeError = uniqueErrors.some((err) => err.kind === 'http_error' || err.kind === 'masked_error');
+    if (hasSecretLeak && hasCodeError) {
+        lines.push(`Instruction (secrets): ${SECRET_LEAK_INSTRUCTION}`);
+        lines.push(`Instruction (code): ${CODE_ERROR_INSTRUCTION}`);
+    }
+    else if (hasSecretLeak) {
+        lines.push(`Instruction: ${SECRET_LEAK_INSTRUCTION}`);
+    }
+    else if (hasCodeError) {
+        lines.push(`Instruction: ${CODE_ERROR_INSTRUCTION}`);
+    }
+    return toAsciiSafe(stripAnsiCodes(lines.join('\n')));
+}

package/dist/reporter/terminal-ui.d.ts

@@ -0,0 +1,14 @@
+import { type AiPromptInput } from './ai-prompt-gen.js';
+export interface VibesaneReportInput extends AiPromptInput {
+    message: string;
+    reason?: string;
+    skippedRoutes?: readonly string[];
+    aiPrompt?: string | null;
+}
+export interface TerminalReportOptions {
+    color?: boolean;
+    isTTY?: boolean;
+    env?: NodeJS.ProcessEnv;
+}
+export declare function shouldEnableColor(customOpt?: boolean, isTTY?: boolean, env?: NodeJS.ProcessEnv): boolean;
+export declare function formatTerminalReport(result: VibesaneReportInput, options?: TerminalReportOptions): string;

package/dist/reporter/terminal-ui.js

@@ -0,0 +1,103 @@
+import { styleText } from 'node:util';
+import { toAsciiSafe } from '../text/ascii.js';
+import { AI_PROMPT_HEADER, generateAiFixPrompt, stripAnsiCodes, } from './ai-prompt-gen.js';
+export function shouldEnableColor(customOpt, isTTY = Boolean(process.stdout?.isTTY), env = process.env) {
+    if (env?.NO_COLOR !== undefined && env.NO_COLOR !== '') {
+        return false;
+    }
+    if (typeof customOpt === 'boolean') {
+        return customOpt;
+    }
+    return Boolean(isTTY);
+}
+function formatSummaryCodeFrame(rawFrame, maxLines = 10) {
+    const clean = toAsciiSafe(stripAnsiCodes(rawFrame)).replace(/\r\n/g, '\n').trimEnd();
+    if (!clean) {
+        return [];
+    }
+    return clean
+        .split('\n')
+        .map((line) => line.trimEnd())
+        .filter((line, idx, arr) => !(line === '' && (idx === 0 || idx === arr.length - 1)))
+        .slice(0, maxLines)
+        .map((line) => `  ${line}`);
+}
+function injectMissingCodeFrames(summaryText, issues) {
+    const issuesWithFrames = issues.filter((i) => i.severity === 'error' && typeof i.codeFrame === 'string' && i.codeFrame.trim().length > 0);
+    if (issuesWithFrames.length === 0) {
+        return summaryText;
+    }
+    const lines = summaryText.split('\n');
+    const out = [];
+    const usedIssueIndices = new Set();
+    for (const line of lines) {
+        out.push(line);
+        if (!line.startsWith('error [')) {
+            continue;
+        }
+        const matchIdx = issuesWithFrames.findIndex((issue, idx) => {
+            if (usedIssueIndices.has(idx)) {
+                return false;
+            }
+            return line.includes(`[${issue.kind}]`) && line.includes(issue.route);
+        });
+        if (matchIdx !== -1) {
+            usedIssueIndices.add(matchIdx);
+            const frameLines = formatSummaryCodeFrame(issuesWithFrames[matchIdx].codeFrame);
+            const firstFrameLine = frameLines[0]?.trim();
+            if (firstFrameLine && !summaryText.includes(firstFrameLine)) {
+                out.push(...frameLines);
+            }
+        }
+    }
+    return out.join('\n');
+}
+function styleSummaryLines(summaryText, ok) {
+    return summaryText
+        .split('\n')
+        .map((line) => {
+        if (ok && line.startsWith('vibesane: connected to ')) {
+            return styleText('green', line);
+        }
+        if (!ok && (line.startsWith('vibesane: sanity check failed') || line.startsWith('error '))) {
+            return styleText('red', line);
+        }
+        if (line.startsWith('warning ')) {
+            return styleText('yellow', line);
+        }
+        return line;
+    })
+        .join('\n');
+}
+export function formatTerminalReport(result, options = {}) {
+    const useColor = shouldEnableColor(options.color, options.isTTY, options.env);
+    const hasErrors = Array.isArray(result.issues) &&
+        result.issues.some((issue) => issue.severity === 'error');
+    const safeMessage = toAsciiSafe(result.message);
+    if (result.port === null || (!result.ok && !hasErrors)) {
+        return useColor ? styleText('red', safeMessage) : safeMessage;
+    }
+    if (result.ok) {
+        if (!useColor) {
+            return safeMessage;
+        }
+        return styleSummaryLines(safeMessage, true);
+    }
+    let summarySection = safeMessage;
+    let existingPromptSection = null;
+    const headerIndex = safeMessage.indexOf(AI_PROMPT_HEADER);
+    if (headerIndex !== -1) {
+        summarySection = safeMessage.slice(0, headerIndex).trimEnd();
+        existingPromptSection = safeMessage.slice(headerIndex);
+    }
+    summarySection = injectMissingCodeFrames(toAsciiSafe(summarySection), result.issues);
+    const renderedSummary = useColor
+        ? styleSummaryLines(summarySection, false)
+        : summarySection;
+    const promptBlock = existingPromptSection ??
+        (result.aiPrompt !== undefined ? result.aiPrompt : generateAiFixPrompt(result));
+    if (!promptBlock) {
+        return renderedSummary;
+    }
+    return `${renderedSummary}\n\n${toAsciiSafe(stripAnsiCodes(promptBlock))}`;
+}