@uxmaltech/collab-cli 0.1.0

package/dist/lib/ai-client.js

@@ -0,0 +1,317 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAiClient = createAiClient;
+exports.createFirstAvailableClient = createFirstAvailableClient;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_https_1 = __importDefault(require("node:https"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_url_1 = require("node:url");
+const credentials_1 = require("./credentials");
+const providers_1 = require("./providers");
+/**
+ * Makes an HTTPS POST request and returns the response body as a string.
+ */
+function httpsPost(url, headers, body, timeoutMs = 120_000) {
+    return new Promise((resolve, reject) => {
+        const parsed = new node_url_1.URL(url);
+        const req = node_https_1.default.request({
+            hostname: parsed.hostname,
+            port: parsed.port || 443,
+            path: parsed.pathname + parsed.search,
+            method: 'POST',
+            headers: {
+                ...headers,
+                'Content-Type': 'application/json',
+                'Content-Length': Buffer.byteLength(body).toString(),
+            },
+        }, (res) => {
+            let data = '';
+            res.on('data', (chunk) => {
+                data += chunk.toString();
+            });
+            res.on('end', () => {
+                resolve({ statusCode: res.statusCode ?? 0, body: data });
+            });
+        });
+        req.setTimeout(timeoutMs, () => {
+            req.destroy(new Error('AI API request timed out'));
+        });
+        req.on('error', reject);
+        req.write(body);
+        req.end();
+    });
+}
+/**
+ * Resolves the API key for a provider.
+ *
+ * Resolution order:
+ *   1. Environment variable (e.g. OPENAI_API_KEY)
+ *   2. Stored credential from .collab/credentials.json
+ */
+function resolveApiKey(provider, config) {
+    const defaults = providers_1.PROVIDER_DEFAULTS[provider];
+    // 1. Check environment variable
+    const envKey = process.env[defaults.envVar];
+    if (envKey) {
+        return envKey;
+    }
+    // 2. Check stored credentials
+    const storedKey = (0, credentials_1.loadApiKey)(config, provider);
+    if (storedKey) {
+        return storedKey;
+    }
+    return null;
+}
+// ---------- OpenAI ----------
+function createOpenAiClient(apiKey) {
+    return {
+        provider: 'codex',
+        async complete(messages, options = {}) {
+            const model = options.model ?? providers_1.PROVIDER_DEFAULTS.codex.models[0];
+            const body = JSON.stringify({
+                model,
+                messages: messages.map((m) => ({ role: m.role, content: m.content })),
+                max_completion_tokens: options.maxTokens ?? 4096,
+                temperature: options.temperature ?? 0.2,
+            });
+            const res = await httpsPost('https://api.openai.com/v1/chat/completions', {
+                Authorization: `Bearer ${apiKey}`,
+                Accept: 'application/json',
+            }, body);
+            if (res.statusCode < 200 || res.statusCode >= 300) {
+                throw new Error(`OpenAI API error (${res.statusCode}): ${res.body}`);
+            }
+            const parsed = JSON.parse(res.body);
+            return parsed.choices?.[0]?.message?.content ?? '';
+        },
+    };
+}
+// ---------- Anthropic ----------
+function createAnthropicClient(apiKey) {
+    return {
+        provider: 'claude',
+        async complete(messages, options = {}) {
+            const model = options.model ?? providers_1.PROVIDER_DEFAULTS.claude.models[0];
+            // Anthropic API uses a system parameter, not a system message
+            const systemMessage = messages.find((m) => m.role === 'system');
+            const userMessages = messages.filter((m) => m.role !== 'system');
+            const body = JSON.stringify({
+                model,
+                max_tokens: options.maxTokens ?? 4096,
+                ...(systemMessage ? { system: systemMessage.content } : {}),
+                messages: userMessages.map((m) => ({ role: m.role, content: m.content })),
+            });
+            const res = await httpsPost('https://api.anthropic.com/v1/messages', {
+                'x-api-key': apiKey,
+                'anthropic-version': '2023-06-01',
+                Accept: 'application/json',
+            }, body);
+            if (res.statusCode < 200 || res.statusCode >= 300) {
+                throw new Error(`Anthropic API error (${res.statusCode}): ${res.body}`);
+            }
+            const parsed = JSON.parse(res.body);
+            const textBlock = parsed.content?.find((b) => b.type === 'text');
+            return textBlock?.text ?? '';
+        },
+    };
+}
+// ---------- Gemini ----------
+function createGeminiClient(apiKey) {
+    return {
+        provider: 'gemini',
+        async complete(messages, options = {}) {
+            const model = options.model ?? providers_1.PROVIDER_DEFAULTS.gemini.models[0];
+            // Gemini uses a different message format
+            const systemInstruction = messages.find((m) => m.role === 'system');
+            const contents = messages
+                .filter((m) => m.role !== 'system')
+                .map((m) => ({
+                role: m.role === 'assistant' ? 'model' : 'user',
+                parts: [{ text: m.content }],
+            }));
+            const body = JSON.stringify({
+                ...(systemInstruction
+                    ? { system_instruction: { parts: [{ text: systemInstruction.content }] } }
+                    : {}),
+                contents,
+                generationConfig: {
+                    maxOutputTokens: options.maxTokens ?? 4096,
+                    temperature: options.temperature ?? 0.2,
+                },
+            });
+            const url = `https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent?key=${apiKey}`;
+            const res = await httpsPost(url, { Accept: 'application/json' }, body);
+            if (res.statusCode < 200 || res.statusCode >= 300) {
+                throw new Error(`Gemini API error (${res.statusCode}): ${res.body}`);
+            }
+            const parsed = JSON.parse(res.body);
+            return parsed.candidates?.[0]?.content?.parts?.[0]?.text ?? '';
+        },
+    };
+}
+// ---------- CLI-based clients ----------
+/**
+ * Combines system and user messages into a single prompt string
+ * for CLI tools that don't support separate message roles.
+ */
+function buildCombinedPrompt(messages) {
+    const parts = [];
+    for (const msg of messages) {
+        if (msg.role === 'system') {
+            parts.push(msg.content);
+        }
+        else if (msg.role === 'user') {
+            parts.push('---\n\n' + msg.content);
+        }
+        else if (msg.role === 'assistant') {
+            parts.push('Assistant: ' + msg.content);
+        }
+    }
+    return parts.join('\n\n');
+}
+/**
+ * Executes codex CLI for completion using `codex exec`.
+ */
+function execCodexCli(prompt, model) {
+    const tmpFile = node_path_1.default.join(node_os_1.default.tmpdir(), `collab-analysis-${Date.now()}.txt`);
+    try {
+        const args = [
+            'exec',
+            '--ephemeral',
+            '--sandbox', 'read-only',
+            '--skip-git-repo-check',
+            '-o', tmpFile,
+        ];
+        if (model) {
+            args.push('-m', model);
+        }
+        args.push(prompt);
+        (0, node_child_process_1.execFileSync)('codex', args, {
+            encoding: 'utf8',
+            timeout: 300_000,
+            stdio: ['ignore', 'inherit', 'inherit'],
+        });
+        if (node_fs_1.default.existsSync(tmpFile)) {
+            return node_fs_1.default.readFileSync(tmpFile, 'utf8').trim();
+        }
+        return '';
+    }
+    finally {
+        try {
+            if (node_fs_1.default.existsSync(tmpFile)) {
+                node_fs_1.default.unlinkSync(tmpFile);
+            }
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+    }
+}
+/**
+ * Executes claude CLI for completion using `claude -p`.
+ */
+function execClaudeCli(prompt, model) {
+    const args = ['-p'];
+    if (model) {
+        args.push('--model', model);
+    }
+    args.push(prompt);
+    const output = (0, node_child_process_1.execFileSync)('claude', args, {
+        encoding: 'utf8',
+        timeout: 300_000,
+        stdio: ['ignore', 'pipe', 'inherit'],
+    });
+    return output.trim();
+}
+/**
+ * Executes gemini CLI for completion.
+ */
+function execGeminiCli(prompt, model) {
+    const args = [];
+    if (model) {
+        args.push('--model', model);
+    }
+    args.push(prompt);
+    const output = (0, node_child_process_1.execFileSync)('gemini', args, {
+        encoding: 'utf8',
+        timeout: 300_000,
+        stdio: ['ignore', 'pipe', 'inherit'],
+    });
+    return output.trim();
+}
+const CLI_EXECUTORS = {
+    codex: execCodexCli,
+    claude: execClaudeCli,
+    gemini: execGeminiCli,
+};
+/**
+ * Creates an AI client that uses the provider's official CLI for completion.
+ * This allows repo analysis to work without API keys.
+ */
+function createCliClient(provider, model) {
+    return {
+        provider,
+        complete(messages, options = {}) {
+            const effectiveModel = options.model ?? model;
+            const prompt = buildCombinedPrompt(messages);
+            const executor = CLI_EXECUTORS[provider];
+            if (!executor) {
+                throw new Error(`No CLI executor available for provider '${provider}'.`);
+            }
+            return Promise.resolve(executor(prompt, effectiveModel));
+        },
+    };
+}
+// ---------- Factory ----------
+const CLIENT_FACTORIES = {
+    codex: createOpenAiClient,
+    claude: createAnthropicClient,
+    gemini: createGeminiClient,
+};
+/**
+ * Creates an AI client for the given provider, resolving auth automatically.
+ *
+ * Resolution order:
+ *   1. API key (env var or stored credentials) → use HTTP API
+ *   2. CLI auth configured with CLI available → use CLI executable
+ *   3. null if neither available
+ */
+function createAiClient(provider, config, logger) {
+    // Copilot doesn't support AI completion — it works via GitHub issues
+    if (provider === 'copilot') {
+        return null;
+    }
+    // 1. Try API key first
+    const factory = CLIENT_FACTORIES[provider];
+    const apiKey = resolveApiKey(provider, config);
+    if (apiKey && factory) {
+        return factory(apiKey);
+    }
+    // 2. Try CLI auth if configured
+    const providerConfig = config.assistants?.providers?.[provider];
+    if (providerConfig?.auth?.method === 'cli' && providerConfig?.cli?.available) {
+        const model = providerConfig.model ?? providerConfig.cli.configuredModel;
+        logger.debug(`Using ${providerConfig.cli.command} CLI for ${providers_1.PROVIDER_DEFAULTS[provider].label} completion.`);
+        return createCliClient(provider, model);
+    }
+    return null;
+}
+/**
+ * Creates an AI client for the first available provider.
+ * Tries providers in order: codex, claude, gemini.
+ */
+function createFirstAvailableClient(providers, config, logger) {
+    for (const provider of providers) {
+        const client = createAiClient(provider, config, logger);
+        if (client) {
+            logger.info(`Using ${providers_1.PROVIDER_DEFAULTS[provider].label} for repository analysis.`);
+            return client;
+        }
+    }
+    return null;
+}

package/dist/lib/ansi.js

@@ -0,0 +1,58 @@
+"use strict";
+/**
+ * ANSI escape code utilities for terminal output.
+ * Zero external dependencies — uses raw escape sequences.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLEAR_SCREEN = exports.BULLET = exports.CROSS = exports.CHECK = void 0;
+exports.bold = bold;
+exports.dim = dim;
+exports.green = green;
+exports.red = red;
+exports.yellow = yellow;
+exports.cyan = cyan;
+exports.gray = gray;
+const ESC = '\x1b[';
+const RESET = `${ESC}0m`;
+function supportsColor() {
+    if (process.env['NO_COLOR'] !== undefined) {
+        return false;
+    }
+    if (process.env['FORCE_COLOR'] !== undefined) {
+        return true;
+    }
+    return Boolean(process.stdout.isTTY);
+}
+const colorEnabled = supportsColor();
+function wrap(code, text) {
+    if (!colorEnabled) {
+        return text;
+    }
+    return `${ESC}${code}m${text}${RESET}`;
+}
+function bold(text) {
+    return wrap('1', text);
+}
+function dim(text) {
+    return wrap('2', text);
+}
+function green(text) {
+    return wrap('32', text);
+}
+function red(text) {
+    return wrap('31', text);
+}
+function yellow(text) {
+    return wrap('33', text);
+}
+function cyan(text) {
+    return wrap('36', text);
+}
+function gray(text) {
+    return wrap('90', text);
+}
+exports.CHECK = '\u2713';
+exports.CROSS = '\u2717';
+exports.BULLET = '\u2022';
+/** ANSI: clear entire screen and move cursor to top-left. */
+exports.CLEAR_SCREEN = '\x1b[2J\x1b[H';

package/dist/lib/canon-index-generator.js

@@ -0,0 +1,64 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scanCanonEntries = scanCanonEntries;
+exports.generateIndexReadme = generateIndexReadme;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Scans .md files in a directory and extracts canon entry metadata.
+ * Parses the heading (# ID Title) and plain-text Status/Confidence fields.
+ * Skips README.md files.
+ */
+function scanCanonEntries(dir) {
+    if (!node_fs_1.default.existsSync(dir))
+        return [];
+    const entries = [];
+    const files = node_fs_1.default.readdirSync(dir).filter((f) => f.endsWith('.md') && f.toLowerCase() !== 'readme.md');
+    for (const file of files) {
+        const content = node_fs_1.default.readFileSync(node_path_1.default.join(dir, file), 'utf8');
+        // Parse heading: "# AX-001 Authoritative Canon" or "# ADR-006 Collab: ..."
+        const heading = content.match(/^#\s+(.+)/m);
+        if (!heading)
+            continue;
+        const headingText = heading[1].trim();
+        // Match "ID Title" where ID is like AX-001, ADR-006, CN-002, AP-003, UIC-001, etc.
+        const parts = headingText.match(/^([A-Z]+-\d+)\s+(.+)$/);
+        const id = parts?.[1] ?? file.replace(/\.md$/, '');
+        const title = parts?.[2] ?? headingText;
+        // Parse plain-text fields (not bold)
+        const confidence = content.match(/^Confidence:\s*(\w+)/mi)?.[1] ?? 'unknown';
+        const status = content.match(/^Status:\s*(\w+)/mi)?.[1] ?? 'active';
+        entries.push({ id, title, confidence, status, fileName: file });
+    }
+    return entries.sort((a, b) => a.id.localeCompare(b.id));
+}
+/**
+ * Generates a README.md index table from scanned canon entries.
+ */
+function generateIndexReadme(sectionTitle, description, entries) {
+    const lines = [
+        `# ${sectionTitle}`,
+        '',
+        `> ${description}`,
+        '',
+    ];
+    if (entries.length === 0) {
+        lines.push('_No entries yet._');
+        lines.push('');
+        lines.push('<!-- GENERATED: INDEX -->');
+        return lines.join('\n');
+    }
+    lines.push('| ID | Title | Confidence | Status |');
+    lines.push('|----|-------|------------|--------|');
+    for (const e of entries) {
+        lines.push(`| ${e.id} | [${e.title}](./${e.fileName}) | ${e.confidence} | ${e.status} |`);
+    }
+    lines.push('');
+    lines.push(`_${entries.length} entries indexed._`);
+    lines.push('');
+    lines.push('<!-- GENERATED: INDEX -->');
+    return lines.join('\n');
+}

package/dist/lib/canon-index-targets.js

@@ -0,0 +1,68 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCanonIndexTargets = getCanonIndexTargets;
+exports.getSnapshotIndexPaths = getSnapshotIndexPaths;
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Returns the canonical index targets for a given architecture directory.
+ * This is the single source of truth for which index files are
+ * generated/snapshotted/validated across canon rebuild stages.
+ */
+function getCanonIndexTargets(archDir) {
+    return [
+        {
+            scanDir: node_path_1.default.join(archDir, 'knowledge', 'axioms'),
+            outputFile: node_path_1.default.join(archDir, 'knowledge', 'axioms', 'README.md'),
+            sectionTitle: 'Axioms',
+            description: 'Fundamental architectural invariants that MUST always hold.',
+        },
+        {
+            scanDir: node_path_1.default.join(archDir, 'knowledge', 'decisions'),
+            outputFile: node_path_1.default.join(archDir, 'knowledge', 'decisions', 'README.md'),
+            sectionTitle: 'Architectural Decisions',
+            description: 'ADRs documenting key architectural choices and their rationale.',
+        },
+        {
+            scanDir: node_path_1.default.join(archDir, 'knowledge', 'conventions'),
+            outputFile: node_path_1.default.join(archDir, 'knowledge', 'conventions', 'README.md'),
+            sectionTitle: 'Conventions',
+            description: 'Coding and design conventions followed across this codebase.',
+        },
+        {
+            scanDir: node_path_1.default.join(archDir, 'knowledge', 'anti-patterns'),
+            outputFile: node_path_1.default.join(archDir, 'knowledge', 'anti-patterns', 'README.md'),
+            sectionTitle: 'Anti-Patterns',
+            description: 'Known pitfalls and patterns that MUST be avoided.',
+        },
+        {
+            scanDir: node_path_1.default.join(archDir, 'domains'),
+            outputFile: node_path_1.default.join(archDir, 'domains', 'README.md'),
+            sectionTitle: 'Domains',
+            description: 'Bounded contexts and domain boundaries identified in the architecture.',
+        },
+        {
+            scanDir: node_path_1.default.join(archDir, 'contracts'),
+            outputFile: node_path_1.default.join(archDir, 'contracts', 'README.md'),
+            sectionTitle: 'Contracts',
+            description: 'Interface contracts between domains (UI-backend shapes, command outcomes).',
+        },
+    ];
+}
+/**
+ * Returns relative paths of all README files to snapshot during rebuild.
+ * Includes top-level and parent READMEs that are not auto-generated
+ * but should be preserved for rollback.
+ */
+function getSnapshotIndexPaths(archDir) {
+    // Top-level hand-crafted READMEs (not regenerable, but worth snapshotting)
+    const topLevel = [
+        'README.md',
+        'knowledge/README.md',
+    ];
+    // Auto-generated sub-category READMEs (from getCanonIndexTargets)
+    const generated = getCanonIndexTargets(archDir).map((t) => node_path_1.default.relative(archDir, t.outputFile));
+    return [...topLevel, ...generated];
+}