@gerbaudo/cli 0.1.0

package/dist/catalog/endpoint.d.ts

@@ -0,0 +1,10 @@
+export interface Endpoint {
+    id: string;
+    method: string;
+    path: string;
+    params?: string;
+    bodySchema?: string;
+    responseSchema?: string;
+    createdAt: string;
+    updatedAt: string;
+}

package/dist/catalog/endpoint.js

@@ -0,0 +1 @@
+export {};

package/dist/commands/daemon.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function createDaemonCommand(): Command;

package/dist/commands/daemon.js

@@ -0,0 +1,48 @@
+import path from 'node:path';
+import { Command } from 'commander';
+import { loadConfig, findConfigPath } from '../config/config.js';
+import { getDb, closeDb } from '../storage/db.js';
+import { CatalogStore } from '../storage/catalog.js';
+import { RecordStore } from '../storage/records.js';
+import { DaemonServer } from '../daemon/server.js';
+export function createDaemonCommand() {
+    const cmd = new Command('daemon')
+        .description('Start the Gerbaudo daemon server')
+        .option('-p, --port <number>', 'Port to listen on')
+        .option('--db <path>', 'Path to SQLite database file')
+        .action(async (opts) => {
+        const configPath = findConfigPath();
+        const config = loadConfig(configPath ?? undefined);
+        if (opts.port)
+            config.daemonPort = parseInt(opts.port, 10);
+        const dbPath = opts.db
+            ? path.resolve(opts.db)
+            : configPath
+                ? path.join(path.dirname(configPath), config.dbPath)
+                : config.dbPath;
+        const db = getDb(dbPath);
+        const catalogStore = new CatalogStore(db);
+        const recordStore = new RecordStore(db);
+        const server = new DaemonServer(config, catalogStore, recordStore);
+        try {
+            await server.start();
+            console.log(`Gerbaudo daemon listening on http://127.0.0.1:${server.getPort()}`);
+        }
+        catch (err) {
+            console.error('Failed to start daemon:', err);
+            closeDb();
+            process.exit(1);
+        }
+        process.on('SIGINT', async () => {
+            await server.stop();
+            closeDb();
+            process.exit(0);
+        });
+        process.on('SIGTERM', async () => {
+            await server.stop();
+            closeDb();
+            process.exit(0);
+        });
+    });
+    return cmd;
+}

package/dist/commands/endpoints.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function createEndpointsCommand(): Command;

package/dist/commands/endpoints.js

@@ -0,0 +1,42 @@
+import path from 'node:path';
+import { Command } from 'commander';
+import { loadConfig, findConfigPath } from '../config/config.js';
+import { getDb } from '../storage/db.js';
+import { CatalogStore } from '../storage/catalog.js';
+export function createEndpointsCommand() {
+    const cmd = new Command('endpoints')
+        .description('List discovered API endpoints')
+        .option('-m, --method <method>', 'Filter by HTTP method')
+        .option('-p, --path <path>', 'Filter by path (partial match)')
+        .option('--json', 'Output as JSON')
+        .action((opts) => {
+        const configPath = findConfigPath();
+        const config = loadConfig(configPath ?? undefined);
+        const dbPath = configPath
+            ? path.join(path.dirname(configPath), config.dbPath)
+            : config.dbPath;
+        const db = getDb(dbPath);
+        const catalogStore = new CatalogStore(db);
+        const filter = {
+            method: opts.method,
+            path: opts.path,
+        };
+        const endpoints = catalogStore.findAll(filter);
+        if (opts.json) {
+            console.log(JSON.stringify(endpoints, null, 2));
+            return;
+        }
+        if (endpoints.length === 0) {
+            console.log('No endpoints discovered yet.');
+            return;
+        }
+        const rows = endpoints.map((e) => ({
+            Method: e.method,
+            Path: e.path,
+            'Params': e.params ?? '-',
+            'Registered': e.createdAt,
+        }));
+        console.table(rows);
+    });
+    return cmd;
+}

package/dist/commands/install.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function createInstallCommand(): Command;

package/dist/commands/install.js

@@ -0,0 +1,112 @@
+import { Command } from 'commander';
+import { existsSync, mkdirSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { execSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { writeConfig } from '../config/config.js';
+function detectExpress(dir) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf-8'));
+        const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+        return 'express' in deps;
+    }
+    catch {
+        return false;
+    }
+}
+function getSdkPath() {
+    const __dirname = dirname(fileURLToPath(import.meta.url));
+    // Walk up looking for sdk/node/package.json marker
+    let dir = __dirname;
+    for (let i = 0; i < 10; i++) {
+        if (existsSync(join(dir, 'sdk', 'node', 'package.json'))) {
+            return join(dir, 'sdk', 'node');
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    // Fallback: assume repo-local dev layout (tsx from cli/)
+    return join(__dirname, '..', '..', '..', '..', 'sdk', 'node');
+}
+export function createInstallCommand() {
+    const cmd = new Command('install')
+        .alias('init')
+        .description('Install Gerbaudo into the current project')
+        .option('--port <number>', 'Daemon port', '9876')
+        .option('--sdk', 'Auto-install the Node SDK package')
+        .action((opts) => {
+        const targetDir = process.cwd();
+        const configPath = join(targetDir, 'gerbaudo.json');
+        if (existsSync(configPath)) {
+            console.log('gerbaudo.json already exists. Skipping config creation.');
+            return;
+        }
+        const config = {
+            daemonPort: parseInt(opts.port, 10),
+            dbPath: '.gerbaudo/data.db',
+        };
+        writeConfig(config, configPath);
+        const dbDir = join(targetDir, '.gerbaudo');
+        if (!existsSync(dbDir)) {
+            mkdirSync(dbDir, { recursive: true });
+        }
+        console.log('Gerbaudo installed successfully.');
+        console.log();
+        console.log('Configuration written to: gerbaudo.json');
+        const isExpress = detectExpress(targetDir);
+        if (opts.sdk && isExpress) {
+            const sdkPath = getSdkPath();
+            console.log('Installing @gerbaudo/sdk-node...');
+            try {
+                execSync(`npm install "${sdkPath}"`, { cwd: targetDir, stdio: 'inherit' });
+                console.log('SDK installed successfully.');
+                console.log();
+                console.log('Add to your Express app:');
+                console.log('  import { gerbaudo } from "@gerbaudo/sdk-node"');
+                console.log('  app.use(gerbaudo({ app }))');
+            }
+            catch {
+                console.error('Failed to install SDK. Install manually:');
+                console.log(`  npm install "${sdkPath}"`);
+            }
+        }
+        else if (opts.sdk && !isExpress) {
+            console.log('No Express project detected. Installing SDK anyway...');
+            const sdkPath = getSdkPath();
+            try {
+                execSync(`npm install "${sdkPath}"`, { cwd: targetDir, stdio: 'inherit' });
+                console.log('SDK installed successfully.');
+            }
+            catch {
+                console.error('Failed to install SDK.');
+            }
+        }
+        else {
+            console.log();
+            console.log('Next steps:');
+            console.log('  1. Start the daemon:');
+            console.log('     npx gerbaudo daemon');
+            console.log();
+            if (isExpress) {
+                console.log('  2. Install the SDK:');
+                console.log('     npx gerbaudo init --sdk');
+                console.log();
+                console.log('  3. Add to your Express app:');
+                console.log('     import { gerbaudo } from "@gerbaudo/sdk-node"');
+                console.log('     app.use(gerbaudo({ app }))');
+            }
+            else {
+                console.log('  2. Install the Node SDK:');
+                console.log('     npm install <path-to>/gerbaudo/sdk/node');
+                console.log();
+                console.log('  3. Add to your app:');
+                console.log('     import { gerbaudo } from "@gerbaudo/sdk-node"');
+                console.log('     app.use(gerbaudo({ app }))');
+            }
+        }
+    });
+    return cmd;
+}

package/dist/commands/log.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function createLogCommand(): Command;

package/dist/commands/log.js

@@ -0,0 +1,51 @@
+import path from 'node:path';
+import { Command } from 'commander';
+import { loadConfig, findConfigPath } from '../config/config.js';
+import { getDb } from '../storage/db.js';
+import { RecordStore } from '../storage/records.js';
+export function createLogCommand() {
+    const cmd = new Command('log')
+        .description('Query request history')
+        .argument('[endpoint]', 'Endpoint path to filter')
+        .option('-m, --method <method>', 'Filter by HTTP method')
+        .option('-s, --status <status>', 'Filter by HTTP status code')
+        .option('--since <date>', 'Start date (ISO format)')
+        .option('--until <date>', 'End date (ISO format)')
+        .option('-n, --limit <number>', 'Max records', '50')
+        .option('--json', 'Output as JSON')
+        .action((endpoint, opts) => {
+        const configPath = findConfigPath();
+        const config = loadConfig(configPath ?? undefined);
+        const dbPath = configPath
+            ? path.join(path.dirname(configPath), config.dbPath)
+            : config.dbPath;
+        const db = getDb(dbPath);
+        const recordStore = new RecordStore(db);
+        const records = recordStore.findAll({
+            path: endpoint,
+            method: opts.method,
+            status: opts.status ? parseInt(opts.status, 10) : undefined,
+            since: opts.since,
+            until: opts.until,
+            limit: parseInt(opts.limit, 10),
+        });
+        if (opts.json) {
+            console.log(JSON.stringify(records, null, 2));
+            return;
+        }
+        if (records.length === 0) {
+            console.log('No records found.');
+            return;
+        }
+        const rows = records.map((r) => ({
+            ID: r.id.slice(0, 8),
+            Method: r.method,
+            Path: r.path,
+            Status: r.status,
+            'Duration (ms)': r.durationMs ?? '-',
+            'Time': r.createdAt,
+        }));
+        console.table(rows);
+    });
+    return cmd;
+}

package/dist/commands/run.d.ts

@@ -0,0 +1,4 @@
+import { Command } from 'commander';
+export declare function matchRoute(pattern: string, actual: string): Record<string, string> | null;
+export declare function resolvePath(pattern: string, params: Record<string, string>): string;
+export declare function createRunCommand(): Command;

package/dist/commands/run.js

@@ -0,0 +1,181 @@
+import path from 'node:path';
+import { Command } from 'commander';
+import { loadConfig, findConfigPath } from '../config/config.js';
+import { getDb } from '../storage/db.js';
+import { CatalogStore } from '../storage/catalog.js';
+import { RecordStore } from '../storage/records.js';
+export function matchRoute(pattern, actual) {
+    const patternParts = pattern.split('/');
+    const actualParts = actual.split('/');
+    if (patternParts.length !== actualParts.length)
+        return null;
+    const params = {};
+    for (let i = 0; i < patternParts.length; i++) {
+        if (patternParts[i].startsWith(':')) {
+            params[patternParts[i].slice(1)] = decodeURIComponent(actualParts[i]);
+        }
+        else if (patternParts[i] !== actualParts[i]) {
+            return null;
+        }
+    }
+    return params;
+}
+export function resolvePath(pattern, params) {
+    return pattern.replace(/:(\w+)/g, (_, name) => {
+        if (params[name] !== undefined)
+            return params[name];
+        return `:${name}`;
+    });
+}
+export function createRunCommand() {
+    const cmd = new Command('run')
+        .description('Execute an API endpoint')
+        .argument('<endpoint>', 'Endpoint path (e.g., /api/users or /api/users/123)')
+        .option('-X, --method <method>', 'HTTP method', 'GET')
+        .option('-d, --data <body>', 'Request body (JSON string)')
+        .option('-H, --header <headers...>', 'Request headers (Key:Value)')
+        .option('-p, --param <params...>', 'Path/query params (Key=Value). Fills :param in route first, remainder become query string.')
+        .option('--json', 'Output raw JSON response')
+        .action(async (endpoint, opts) => {
+        const configPath = findConfigPath();
+        if (!configPath) {
+            console.error('No gerbaudo.json found. Run "gerbaudo init" first.');
+            process.exit(1);
+        }
+        const config = loadConfig(configPath);
+        const dbPath = path.join(path.dirname(configPath), config.dbPath);
+        const db = getDb(dbPath);
+        const catalogStore = new CatalogStore(db);
+        const recordStore = new RecordStore(db);
+        const allByMethod = catalogStore.findAll({ method: opts.method });
+        let match;
+        let pathParams = {};
+        // 1) exact match
+        match = allByMethod.find((e) => e.path === endpoint);
+        if (!match) {
+            // 2) pattern match with :params
+            for (const candidate of allByMethod) {
+                const params = matchRoute(candidate.path, endpoint);
+                if (params) {
+                    match = candidate;
+                    pathParams = params;
+                    break;
+                }
+            }
+        }
+        if (!match) {
+            // 3) endsWith fallback (for sub-path matching)
+            match = allByMethod.find((e) => e.path.endsWith(endpoint));
+        }
+        if (!match) {
+            console.error(`Endpoint not found: ${opts.method} ${endpoint}`);
+            console.error();
+            const total = catalogStore.findAll().length;
+            if (total === 0) {
+                console.error('No endpoints registered. Make sure:');
+                console.error('  1. The daemon is running: npx gerbaudo daemon');
+                console.error('  2. The SDK middleware is active in your backend app');
+                console.error('  3. Routes have been registered: check with "gerbaudo endpoints"');
+            }
+            else {
+                console.error(`Available endpoints: ${total}. Use "gerbaudo endpoints" to list them.`);
+                console.error('Check the method and path spelling.');
+            }
+            process.exit(1);
+        }
+        let body;
+        if (opts.data) {
+            body = opts.data;
+        }
+        const headers = {};
+        if (opts.header) {
+            for (const h of opts.header) {
+                const idx = h.indexOf(':');
+                if (idx > 0) {
+                    headers[h.slice(0, idx).trim()] = h.slice(idx + 1).trim();
+                }
+            }
+        }
+        const allParams = {};
+        if (opts.param) {
+            for (const p of opts.param) {
+                const idx = p.indexOf('=');
+                if (idx > 0) {
+                    allParams[p.slice(0, idx)] = p.slice(idx + 1);
+                }
+            }
+        }
+        // Extracted path params take precedence over --param
+        const mergedParams = { ...allParams, ...pathParams };
+        // Resolve :param tokens in the path
+        const resolvedPath = resolvePath(match.path, mergedParams);
+        // Remaining params become query string
+        const queryParams = { ...allParams };
+        for (const key of Object.keys(pathParams)) {
+            delete queryParams[key];
+        }
+        const baseUrl = `http://127.0.0.1:${config.daemonPort}`;
+        const url = new URL(resolvedPath, baseUrl);
+        for (const [k, v] of Object.entries(queryParams)) {
+            url.searchParams.set(k, v);
+        }
+        const start = performance.now();
+        try {
+            const response = await fetch(url.toString(), {
+                method: match.method,
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...headers,
+                },
+                body: body ?? undefined,
+            });
+            const durationMs = Math.round(performance.now() - start);
+            const responseBody = await response.text();
+            const record = recordStore.insert({
+                endpointId: match.id,
+                method: match.method,
+                path: match.path,
+                status: response.status,
+                requestHeaders: JSON.stringify(headers),
+                requestBody: body,
+                responseHeaders: JSON.stringify(Object.fromEntries(response.headers)),
+                responseBody,
+                durationMs,
+            });
+            if (opts.json) {
+                console.log(JSON.stringify({
+                    status: response.status,
+                    headers: Object.fromEntries(response.headers),
+                    body: responseBody,
+                    durationMs,
+                    recordId: record.id,
+                }));
+                return;
+            }
+            console.log(`\n${response.status} ${response.statusText} (${durationMs}ms)\n`);
+            try {
+                const parsed = JSON.parse(responseBody);
+                console.log(JSON.stringify(parsed, null, 2));
+            }
+            catch {
+                console.log(responseBody);
+            }
+        }
+        catch (err) {
+            const msg = String(err);
+            if (msg.includes('ECONNREFUSED')) {
+                console.error(`Cannot connect to backend at ${baseUrl}. Is the daemon running?`);
+                console.error('Start it with: npx gerbaudo daemon');
+            }
+            else if (msg.includes('fetch')) {
+                console.error(`Request to ${match.method} ${match.path} failed.`);
+                console.error(`Is the backend server running at ${baseUrl}?`);
+            }
+            else {
+                console.error(`Request failed: ${err}`);
+            }
+            process.exit(1);
+        }
+    });
+    return cmd;
+}

package/dist/commands/stats.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function createStatsCommand(): Command;

package/dist/commands/stats.js

@@ -0,0 +1,38 @@
+import path from 'node:path';
+import { Command } from 'commander';
+import { loadConfig, findConfigPath } from '../config/config.js';
+import { getDb } from '../storage/db.js';
+import { RecordStore } from '../storage/records.js';
+export function createStatsCommand() {
+    const cmd = new Command('stats')
+        .description('Show API usage statistics')
+        .option('--json', 'Output as JSON')
+        .action((opts) => {
+        const configPath = findConfigPath();
+        const config = loadConfig(configPath ?? undefined);
+        const dbPath = configPath
+            ? path.join(path.dirname(configPath), config.dbPath)
+            : config.dbPath;
+        const db = getDb(dbPath);
+        const recordStore = new RecordStore(db);
+        const stats = recordStore.getStats();
+        if (opts.json) {
+            console.log(JSON.stringify(stats, null, 2));
+            return;
+        }
+        console.log('=== Gerbaudo Stats ===');
+        console.log(`Total endpoints: ${stats.totalEndpoints}`);
+        console.log(`Total requests:  ${stats.totalRecords}`);
+        console.log(`Errors (4xx+):   ${stats.errorCount}`);
+        console.log();
+        if (stats.topEndpoints.length > 0) {
+            console.log('Top endpoints:');
+            console.table(stats.topEndpoints);
+        }
+        if (stats.slowestEndpoints.length > 0) {
+            console.log('Slowest endpoints (avg ms):');
+            console.table(stats.slowestEndpoints);
+        }
+    });
+    return cmd;
+}

package/dist/config/config.d.ts

@@ -0,0 +1,8 @@
+export interface GerbaudoConfig {
+    daemonPort: number;
+    dbPath: string;
+    sdkPath?: string;
+}
+export declare function findConfigPath(startDir?: string): string | null;
+export declare function loadConfig(path?: string): GerbaudoConfig;
+export declare function writeConfig(config: GerbaudoConfig, targetPath: string): void;

package/dist/config/config.js

@@ -0,0 +1,30 @@
+import { readFileSync, existsSync, writeFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+const DEFAULT_CONFIG = {
+    daemonPort: 9876,
+    dbPath: '.gerbaudo/data.db',
+};
+export function findConfigPath(startDir) {
+    let dir = startDir ?? process.cwd();
+    for (let i = 0; i < 10; i++) {
+        const candidate = join(dir, 'gerbaudo.json');
+        if (existsSync(candidate))
+            return candidate;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+export function loadConfig(path) {
+    const configPath = path ?? findConfigPath();
+    if (!configPath) {
+        return { ...DEFAULT_CONFIG };
+    }
+    const raw = readFileSync(configPath, 'utf-8');
+    return { ...DEFAULT_CONFIG, ...JSON.parse(raw) };
+}
+export function writeConfig(config, targetPath) {
+    writeFileSync(targetPath, JSON.stringify(config, null, 2));
+}

package/dist/daemon/router.d.ts

@@ -0,0 +1,4 @@
+import { Router } from 'express';
+import type { CatalogStore } from '../storage/catalog.js';
+import type { RecordStore } from '../storage/records.js';
+export declare function createRouter(catalogStore: CatalogStore, recordStore: RecordStore): Router;

package/dist/daemon/router.js

@@ -0,0 +1,111 @@
+import { Router } from 'express';
+export function createRouter(catalogStore, recordStore) {
+    const router = Router();
+    router.post('/catalog/register', (req, res) => {
+        const { method, path, params, bodySchema, responseSchema } = req.body;
+        if (!method || !path) {
+            res.status(400).json({ error: 'method and path are required' });
+            return;
+        }
+        const endpoint = catalogStore.upsert({
+            method,
+            path,
+            params,
+            bodySchema,
+            responseSchema,
+        });
+        res.json(endpoint);
+    });
+    router.get('/catalog', (req, res) => {
+        const filter = {
+            method: req.query.method,
+            path: req.query.path,
+        };
+        const endpoints = catalogStore.findAll(filter);
+        res.json(endpoints);
+    });
+    router.post('/intercept/record', (req, res) => {
+        const { endpointId, method, path, status, requestHeaders, requestBody, responseHeaders, responseBody, durationMs, } = req.body;
+        if (!method || !path || status === undefined) {
+            res.status(400).json({ error: 'method, path, and status are required' });
+            return;
+        }
+        const record = recordStore.insert({
+            endpointId,
+            method,
+            path,
+            status,
+            requestHeaders,
+            requestBody,
+            responseHeaders,
+            responseBody,
+            durationMs,
+        });
+        res.json(record);
+    });
+    router.get('/records', (req, res) => {
+        const filter = {
+            endpointId: req.query.endpointId,
+            method: req.query.method,
+            status: req.query.status ? Number(req.query.status) : undefined,
+            since: req.query.since,
+            until: req.query.until,
+            path: req.query.path,
+            limit: req.query.limit ? Number(req.query.limit) : undefined,
+            offset: req.query.offset ? Number(req.query.offset) : undefined,
+        };
+        const records = recordStore.findAll(filter);
+        res.json(records);
+    });
+    router.get('/records/:id', (req, res) => {
+        const record = recordStore.findById(req.params.id);
+        if (!record) {
+            res.status(404).json({ error: 'record not found' });
+            return;
+        }
+        res.json(record);
+    });
+    router.get('/stats', (_req, res) => {
+        const stats = recordStore.getStats();
+        res.json(stats);
+    });
+    router.get('/agent/endpoints', (req, res) => {
+        const filter = {
+            method: req.query.method,
+            path: req.query.path,
+        };
+        const endpoints = catalogStore.findAll(filter);
+        res.json({
+            version: '0.1.0',
+            endpoints: endpoints.map((e) => ({
+                id: e.id,
+                method: e.method,
+                path: e.path,
+                params: e.params,
+                bodySchema: e.bodySchema,
+                responseSchema: e.responseSchema,
+            })),
+        });
+    });
+    router.post('/agent/exec', (req, res) => {
+        const { endpointId, body, params, headers } = req.body;
+        if (!endpointId) {
+            res.status(400).json({ error: 'endpointId is required' });
+            return;
+        }
+        const endpoint = catalogStore.findById(endpointId);
+        if (!endpoint) {
+            res.status(404).json({ error: 'endpoint not found' });
+            return;
+        }
+        res.json({
+            instruction: 'forward',
+            method: endpoint.method,
+            path: endpoint.path,
+            params,
+            body,
+            headers,
+        });
+    });
+    return router;
+}

package/dist/daemon/server.d.ts

@@ -0,0 +1,12 @@
+import type { CatalogStore } from '../storage/catalog.js';
+import type { RecordStore } from '../storage/records.js';
+import type { GerbaudoConfig } from '../config/config.js';
+export declare class DaemonServer {
+    private app;
+    private server;
+    private port;
+    constructor(config: GerbaudoConfig, catalogStore: CatalogStore, recordStore: RecordStore);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    getPort(): number;
+}

package/dist/daemon/server.js

@@ -0,0 +1,42 @@
+import express from 'express';
+import { createRouter } from './router.js';
+export class DaemonServer {
+    app;
+    server = null;
+    port;
+    constructor(config, catalogStore, recordStore) {
+        this.port = config.daemonPort;
+        this.app = express();
+        this.app.use(express.json());
+        this.app.use('/api', createRouter(catalogStore, recordStore));
+    }
+    start() {
+        return new Promise((resolve, reject) => {
+            this.server = this.app.listen(this.port, '127.0.0.1', () => {
+                const addr = this.server.address();
+                if (addr && typeof addr === 'object') {
+                    this.port = addr.port;
+                }
+                resolve();
+            });
+            this.server.on('error', reject);
+        });
+    }
+    stop() {
+        return new Promise((resolve, reject) => {
+            if (!this.server) {
+                resolve();
+                return;
+            }
+            this.server.close((err) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve();
+            });
+        });
+    }
+    getPort() {
+        return this.port;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { createDaemonCommand } from './commands/daemon.js';
+import { createInstallCommand } from './commands/install.js';
+import { createEndpointsCommand } from './commands/endpoints.js';
+import { createLogCommand } from './commands/log.js';
+import { createStatsCommand } from './commands/stats.js';
+import { createRunCommand } from './commands/run.js';
+const program = new Command();
+program
+    .name('gerbaudo')
+    .description('Local CLI tool for backend API instrumentation')
+    .version('0.1.0');
+program.addCommand(createDaemonCommand());
+program.addCommand(createInstallCommand());
+program.addCommand(createEndpointsCommand());
+program.addCommand(createLogCommand());
+program.addCommand(createStatsCommand());
+program.addCommand(createRunCommand());
+program.parse(process.argv);

package/dist/intercept/record.d.ts

@@ -0,0 +1,13 @@
+export interface InterceptRecord {
+    id: string;
+    endpointId: string;
+    method: string;
+    path: string;
+    status: number;
+    requestHeaders?: string;
+    requestBody?: string;
+    responseHeaders?: string;
+    responseBody?: string;
+    durationMs: number;
+    createdAt: string;
+}

package/dist/intercept/record.js

@@ -0,0 +1 @@
+export {};

package/dist/storage/catalog.d.ts

@@ -0,0 +1,13 @@
+import type Database from 'better-sqlite3';
+import type { Endpoint } from '../catalog/endpoint.js';
+export declare class CatalogStore {
+    private db;
+    constructor(db: Database.Database);
+    upsert(endpoint: Omit<Endpoint, 'id' | 'createdAt' | 'updatedAt'>): Endpoint;
+    findAll(filter?: {
+        method?: string;
+        path?: string;
+    }): Endpoint[];
+    findById(id: string): Endpoint | undefined;
+    findByMethodAndPath(method: string, path: string): Endpoint | undefined;
+}

package/dist/storage/catalog.js

@@ -0,0 +1,59 @@
+import { v4 as uuid } from 'uuid';
+export class CatalogStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    upsert(endpoint) {
+        const existing = this.db
+            .prepare('SELECT * FROM endpoints WHERE method = ? AND path = ?')
+            .get(endpoint.method, endpoint.path);
+        if (existing) {
+            this.db
+                .prepare('UPDATE endpoints SET params = ?, body_schema = ?, response_schema = ?, updated_at = datetime(\'now\') WHERE id = ?')
+                .run(endpoint.params ?? null, endpoint.bodySchema ?? null, endpoint.responseSchema ?? null, existing.id);
+            return {
+                ...existing,
+                params: endpoint.params ?? existing.params,
+                bodySchema: endpoint.bodySchema ?? existing.bodySchema,
+                responseSchema: endpoint.responseSchema ?? existing.responseSchema,
+                updatedAt: new Date().toISOString(),
+            };
+        }
+        const id = uuid();
+        const now = new Date().toISOString();
+        this.db
+            .prepare(`INSERT INTO endpoints (id, method, path, params, body_schema, response_schema, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(id, endpoint.method, endpoint.path, endpoint.params ?? null, endpoint.bodySchema ?? null, endpoint.responseSchema ?? null, now, now);
+        return { id, ...endpoint, createdAt: now, updatedAt: now };
+    }
+    findAll(filter) {
+        let sql = 'SELECT * FROM endpoints';
+        const conditions = [];
+        const params = [];
+        if (filter?.method) {
+            conditions.push('method = ?');
+            params.push(filter.method);
+        }
+        if (filter?.path) {
+            conditions.push('path LIKE ?');
+            params.push(`%${filter.path}%`);
+        }
+        if (conditions.length > 0) {
+            sql += ' WHERE ' + conditions.join(' AND ');
+        }
+        sql += ' ORDER BY method, path';
+        return this.db.prepare(sql).all(...params);
+    }
+    findById(id) {
+        return this.db
+            .prepare('SELECT * FROM endpoints WHERE id = ?')
+            .get(id);
+    }
+    findByMethodAndPath(method, path) {
+        return this.db
+            .prepare('SELECT * FROM endpoints WHERE method = ? AND path = ?')
+            .get(method, path);
+    }
+}

package/dist/storage/db.d.ts

@@ -0,0 +1,3 @@
+import Database from 'better-sqlite3';
+export declare function getDb(dbPath: string): Database.Database;
+export declare function closeDb(): void;

package/dist/storage/db.js

@@ -0,0 +1,27 @@
+import Database from 'better-sqlite3';
+import { mkdirp } from './mkdirp.js';
+import { runMigrations } from './migrations.js';
+let db = null;
+export function getDb(dbPath) {
+    if (db) {
+        try {
+            db.prepare('SELECT 1').get();
+            return db;
+        }
+        catch {
+            db = null;
+        }
+    }
+    mkdirp(dbPath);
+    db = new Database(dbPath);
+    db.pragma('journal_mode = WAL');
+    db.pragma('foreign_keys = ON');
+    runMigrations(db);
+    return db;
+}
+export function closeDb() {
+    if (db) {
+        db.close();
+        db = null;
+    }
+}

package/dist/storage/migrations.d.ts

@@ -0,0 +1,2 @@
+import type Database from 'better-sqlite3';
+export declare function runMigrations(db: Database.Database): void;

package/dist/storage/migrations.js

@@ -0,0 +1,60 @@
+const migrations = [
+    // 0: tracking table
+    `
+  CREATE TABLE IF NOT EXISTS _migrations (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    applied_at TEXT DEFAULT (datetime('now'))
+  );
+  `,
+    // 1: endpoints
+    `
+  CREATE TABLE IF NOT EXISTS endpoints (
+    id TEXT PRIMARY KEY,
+    method TEXT NOT NULL,
+    path TEXT NOT NULL,
+    params TEXT,
+    body_schema TEXT,
+    response_schema TEXT,
+    created_at TEXT DEFAULT (datetime('now')),
+    updated_at TEXT DEFAULT (datetime('now')),
+    UNIQUE(method, path)
+  );
+  `,
+    // 2: records
+    `
+  CREATE TABLE IF NOT EXISTS records (
+    id TEXT PRIMARY KEY,
+    endpoint_id TEXT REFERENCES endpoints(id),
+    method TEXT NOT NULL,
+    path TEXT NOT NULL,
+    status INTEGER NOT NULL,
+    request_headers TEXT,
+    request_body TEXT,
+    response_headers TEXT,
+    response_body TEXT,
+    duration_ms INTEGER,
+    created_at TEXT DEFAULT (datetime('now'))
+  );
+  `,
+    // 3: indexes
+    `
+  CREATE INDEX IF NOT EXISTS idx_records_endpoint ON records(endpoint_id);
+  `,
+    `
+  CREATE INDEX IF NOT EXISTS idx_records_created ON records(created_at);
+  `,
+];
+export function runMigrations(db) {
+    // ensure _migrations table exists first
+    db.exec(migrations[0]);
+    const row = db
+        .prepare('SELECT COUNT(*) as cnt FROM _migrations')
+        .get();
+    const applied = row?.cnt ?? 0;
+    for (let i = applied; i < migrations.length; i++) {
+        db.exec(migrations[i]);
+        if (i > 0) {
+            db.prepare('INSERT INTO _migrations DEFAULT VALUES').run();
+        }
+    }
+}

package/dist/storage/mkdirp.d.ts

@@ -0,0 +1 @@
+export declare function mkdirp(filePath: string): void;

package/dist/storage/mkdirp.js

@@ -0,0 +1,8 @@
+import { existsSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+export function mkdirp(filePath) {
+    const dir = dirname(filePath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+}

package/dist/storage/records.d.ts

@@ -0,0 +1,34 @@
+import type Database from 'better-sqlite3';
+import type { InterceptRecord } from '../intercept/record.js';
+export interface RecordFilter {
+    endpointId?: string;
+    method?: string;
+    status?: number;
+    since?: string;
+    until?: string;
+    path?: string;
+    limit?: number;
+    offset?: number;
+}
+export declare class RecordStore {
+    private db;
+    constructor(db: Database.Database);
+    insert(record: Omit<InterceptRecord, 'id' | 'createdAt'>): InterceptRecord;
+    findAll(filter?: RecordFilter): InterceptRecord[];
+    findById(id: string): InterceptRecord | undefined;
+    getStats(): {
+        totalEndpoints: number;
+        totalRecords: number;
+        topEndpoints: {
+            path: string;
+            method: string;
+            count: number;
+        }[];
+        slowestEndpoints: {
+            path: string;
+            method: string;
+            avgDuration: number;
+        }[];
+        errorCount: number;
+    };
+}

package/dist/storage/records.js

@@ -0,0 +1,92 @@
+import { v4 as uuid } from 'uuid';
+export class RecordStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    insert(record) {
+        const id = uuid();
+        const now = new Date().toISOString();
+        this.db
+            .prepare(`INSERT INTO records (id, endpoint_id, method, path, status, request_headers, request_body, response_headers, response_body, duration_ms, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(id, record.endpointId, record.method, record.path, record.status, record.requestHeaders ?? null, record.requestBody ?? null, record.responseHeaders ?? null, record.responseBody ?? null, record.durationMs, now);
+        return { id, ...record, createdAt: now };
+    }
+    findAll(filter) {
+        let sql = 'SELECT * FROM records';
+        const conditions = [];
+        const params = [];
+        if (filter?.endpointId) {
+            conditions.push('endpoint_id = ?');
+            params.push(filter.endpointId);
+        }
+        if (filter?.method) {
+            conditions.push('method = ?');
+            params.push(filter.method);
+        }
+        if (filter?.status) {
+            conditions.push('status = ?');
+            params.push(filter.status);
+        }
+        if (filter?.since) {
+            conditions.push('created_at >= ?');
+            params.push(filter.since);
+        }
+        if (filter?.until) {
+            conditions.push('created_at <= ?');
+            params.push(filter.until);
+        }
+        if (filter?.path) {
+            conditions.push('path LIKE ?');
+            params.push(`%${filter.path}%`);
+        }
+        if (conditions.length > 0) {
+            sql += ' WHERE ' + conditions.join(' AND ');
+        }
+        sql += ' ORDER BY created_at DESC';
+        if (filter?.limit) {
+            sql += ' LIMIT ?';
+            params.push(filter.limit);
+        }
+        if (filter?.offset) {
+            sql += ' OFFSET ?';
+            params.push(filter.offset);
+        }
+        return this.db.prepare(sql).all(...params);
+    }
+    findById(id) {
+        return this.db
+            .prepare('SELECT * FROM records WHERE id = ?')
+            .get(id);
+    }
+    getStats() {
+        const totalEndpoints = this.db.prepare('SELECT COUNT(*) as cnt FROM endpoints').get().cnt;
+        const totalRecords = this.db.prepare('SELECT COUNT(*) as cnt FROM records').get().cnt;
+        const topEndpoints = this.db
+            .prepare(`SELECT path, method, COUNT(*) as count
+         FROM records
+         GROUP BY method, path
+         ORDER BY count DESC
+         LIMIT 10`)
+            .all();
+        const slowestEndpoints = this.db
+            .prepare(`SELECT path, method, AVG(duration_ms) as avgDuration
+         FROM records
+         WHERE duration_ms IS NOT NULL
+         GROUP BY method, path
+         ORDER BY avgDuration DESC
+         LIMIT 10`)
+            .all();
+        const errorCount = this.db
+            .prepare('SELECT COUNT(*) as cnt FROM records WHERE status >= 400')
+            .get().cnt;
+        return {
+            totalEndpoints,
+            totalRecords,
+            topEndpoints,
+            slowestEndpoints,
+            errorCount,
+        };
+    }
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@gerbaudo/cli",
+  "version": "0.1.0",
+  "description": "Local CLI tool for backend API instrumentation",
+  "type": "module",
+  "bin": {
+    "gerbaudo": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "package.json",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "prepare": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "better-sqlite3": "^11.0.0",
+    "commander": "^12.0.0",
+    "express": "^4.21.0",
+    "uuid": "^10.0.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.0",
+    "@types/express": "^4.17.0",
+    "@types/node": "^22.0.0",
+    "@types/uuid": "^10.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^4.1.9"
+  },
+  "license": "MIT"
+}