@uxmaltech/collab-cli 0.1.0

package/dist/lib/executor.js

@@ -0,0 +1,85 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Executor = void 0;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const errors_1 = require("./errors");
+const shell_1 = require("./shell");
+/**
+ * Central side-effect executor.
+ * All file writes and subprocess calls go through this class so that
+ * `--dry-run` can suppress them while still logging what *would* happen.
+ */
+class Executor {
+    dryRun;
+    cwd;
+    logger;
+    constructor(logger, options) {
+        this.logger = logger;
+        this.dryRun = options.dryRun;
+        this.cwd = options.cwd;
+    }
+    run(commandName, args, options = {}) {
+        const commandLine = (0, shell_1.toShellCommand)([commandName, ...args]);
+        this.logger.command([commandName, ...args], { verboseOnly: options.verboseOnly });
+        if (this.dryRun) {
+            return {
+                status: 0,
+                stdout: '',
+                stderr: '',
+                command: commandLine,
+                simulated: true,
+            };
+        }
+        const result = (0, node_child_process_1.spawnSync)(commandName, args, {
+            cwd: options.cwd ?? this.cwd,
+            encoding: 'utf8',
+        });
+        if (result.error) {
+            const errorCode = result.error.code;
+            if (errorCode === 'ENOENT') {
+                throw new errors_1.CliError(`Command not found: ${commandName}`);
+            }
+            throw new errors_1.CliError(result.error.message);
+        }
+        const outcome = {
+            status: result.status ?? 1,
+            stdout: result.stdout ?? '',
+            stderr: result.stderr ?? '',
+            command: commandLine,
+            simulated: false,
+        };
+        if (options.check ?? true) {
+            if (outcome.status !== 0) {
+                throw new errors_1.CommandExecutionError(`Command failed: ${commandLine}`, {
+                    command: commandLine,
+                    exitCode: outcome.status,
+                    stderr: outcome.stderr,
+                    stdout: outcome.stdout,
+                });
+            }
+        }
+        return outcome;
+    }
+    ensureDirectory(directoryPath) {
+        if (this.dryRun) {
+            this.logger.info(`[dry-run] mkdir -p ${directoryPath}`);
+            return;
+        }
+        node_fs_1.default.mkdirSync(directoryPath, { recursive: true });
+    }
+    writeFile(filePath, content, options = {}) {
+        const description = options.description ?? 'write file';
+        if (this.dryRun) {
+            this.logger.info(`[dry-run] ${description}: ${filePath}`);
+            return;
+        }
+        node_fs_1.default.mkdirSync(node_path_1.default.dirname(filePath), { recursive: true });
+        node_fs_1.default.writeFileSync(filePath, content, 'utf8');
+    }
+}
+exports.Executor = Executor;

package/dist/lib/github-auth.js

@@ -0,0 +1,204 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadGitHubAuth = loadGitHubAuth;
+exports.isGitHubAuthValid = isGitHubAuthValid;
+exports.ensureAuthGitIgnore = ensureAuthGitIgnore;
+exports.runGitHubDeviceFlow = runGitHubDeviceFlow;
+exports.storeGitHubToken = storeGitHubToken;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * GitHub OAuth Device Flow for workspace-scoped authentication.
+ *
+ * Token is stored in `.collab/github-auth.json` and MUST be in `.gitignore`.
+ * It is NEVER logged, stored in config.json, or exposed to stage pipelines.
+ */
+const AUTH_FILENAME = 'github-auth.json';
+/**
+ * Client ID for the collab-cli GitHub OAuth App.
+ * Override with COLLAB_GITHUB_CLIENT_ID env var until the app is registered.
+ */
+const DEFAULT_CLIENT_ID = process.env.COLLAB_GITHUB_CLIENT_ID ?? '';
+const DEVICE_CODE_URL = 'https://github.com/login/device/code';
+const ACCESS_TOKEN_URL = 'https://github.com/login/oauth/access_token';
+const SCOPES = 'repo read:org read:project';
+// ────────────────────────────────────────────────────────────────
+// Token persistence
+// ────────────────────────────────────────────────────────────────
+function authFilePath(collabDir) {
+    return node_path_1.default.join(collabDir, AUTH_FILENAME);
+}
+/**
+ * Loads the GitHub auth token from `.collab/github-auth.json`.
+ * Returns null if the file does not exist or cannot be parsed.
+ */
+function loadGitHubAuth(collabDir) {
+    const filePath = authFilePath(collabDir);
+    if (!node_fs_1.default.existsSync(filePath)) {
+        return null;
+    }
+    try {
+        const raw = node_fs_1.default.readFileSync(filePath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!parsed.token || parsed.provider !== 'github') {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function saveGitHubAuth(collabDir, auth) {
+    node_fs_1.default.mkdirSync(collabDir, { recursive: true });
+    node_fs_1.default.writeFileSync(authFilePath(collabDir), JSON.stringify(auth, null, 2) + '\n', 'utf8');
+}
+// ────────────────────────────────────────────────────────────────
+// Token validation
+// ────────────────────────────────────────────────────────────────
+/**
+ * Validates the GitHub token by calling `GET /user`.
+ * Returns true if the token is valid and has the expected scopes.
+ */
+async function isGitHubAuthValid(auth) {
+    try {
+        const response = await fetch('https://api.github.com/user', {
+            headers: {
+                Authorization: `Bearer ${auth.token}`,
+                Accept: 'application/vnd.github+json',
+                'X-GitHub-Api-Version': '2022-11-28',
+            },
+        });
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+}
+// ────────────────────────────────────────────────────────────────
+// .gitignore management
+// ────────────────────────────────────────────────────────────────
+/**
+ * Ensures `.collab/.gitignore` contains `github-auth.json`.
+ */
+function ensureAuthGitIgnore(collabDir) {
+    const gitignorePath = node_path_1.default.join(collabDir, '.gitignore');
+    let content = '';
+    if (node_fs_1.default.existsSync(gitignorePath)) {
+        content = node_fs_1.default.readFileSync(gitignorePath, 'utf8');
+    }
+    if (content.includes(AUTH_FILENAME)) {
+        return;
+    }
+    const newLine = content.length > 0 && !content.endsWith('\n') ? '\n' : '';
+    node_fs_1.default.writeFileSync(gitignorePath, `${content}${newLine}${AUTH_FILENAME}\n`, 'utf8');
+}
+// ────────────────────────────────────────────────────────────────
+// OAuth Device Flow
+// ────────────────────────────────────────────────────────────────
+async function requestDeviceCode(clientId) {
+    const response = await fetch(DEVICE_CODE_URL, {
+        method: 'POST',
+        headers: {
+            Accept: 'application/json',
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+            client_id: clientId,
+            scope: SCOPES,
+        }),
+    });
+    if (!response.ok) {
+        const text = await response.text();
+        throw new Error(`GitHub device code request failed (${response.status}): ${text}`);
+    }
+    return (await response.json());
+}
+async function pollForAccessToken(clientId, deviceCode, interval, expiresIn) {
+    const deadline = Date.now() + expiresIn * 1000;
+    let pollInterval = interval * 1000;
+    while (Date.now() < deadline) {
+        await new Promise((resolve) => setTimeout(resolve, pollInterval));
+        const response = await fetch(ACCESS_TOKEN_URL, {
+            method: 'POST',
+            headers: {
+                Accept: 'application/json',
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                client_id: clientId,
+                device_code: deviceCode,
+                grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+            }),
+        });
+        const body = (await response.json());
+        if (body.access_token) {
+            return body.access_token;
+        }
+        if (body.error === 'authorization_pending') {
+            continue;
+        }
+        if (body.error === 'slow_down') {
+            pollInterval += 5000;
+            continue;
+        }
+        if (body.error === 'expired_token') {
+            throw new Error('GitHub device code expired. Please try again.');
+        }
+        if (body.error === 'access_denied') {
+            throw new Error('GitHub authorization was denied by the user.');
+        }
+        throw new Error(`GitHub OAuth error: ${body.error ?? 'unknown'}`);
+    }
+    throw new Error('GitHub device code expired. Please try again.');
+}
+/**
+ * Runs the GitHub OAuth Device Flow interactively.
+ *
+ * 1. Requests a device code from GitHub
+ * 2. Displays the user code and opens the browser
+ * 3. Polls until the user authorizes or the code expires
+ * 4. Stores the token in `.collab/github-auth.json`
+ */
+async function runGitHubDeviceFlow(collabDir, log) {
+    const print = log ?? console.log;
+    const clientId = process.env.COLLAB_GITHUB_CLIENT_ID ?? DEFAULT_CLIENT_ID;
+    if (!clientId) {
+        throw new Error('GitHub OAuth client ID not configured. Set COLLAB_GITHUB_CLIENT_ID environment variable.');
+    }
+    print('Authorizing collab-cli with GitHub...');
+    const deviceCode = await requestDeviceCode(clientId);
+    print('');
+    print(`  Open: ${deviceCode.verification_uri}`);
+    print(`  Code: ${deviceCode.user_code}`);
+    print('');
+    print('Waiting for authorization...');
+    const token = await pollForAccessToken(clientId, deviceCode.device_code, deviceCode.interval, deviceCode.expires_in);
+    const auth = {
+        provider: 'github',
+        token,
+        scopes: SCOPES.split(' '),
+        created_at: new Date().toISOString(),
+    };
+    saveGitHubAuth(collabDir, auth);
+    ensureAuthGitIgnore(collabDir);
+    print('GitHub authorization complete.');
+    return auth;
+}
+/**
+ * Stores a pre-existing token (e.g. from `--github-token` flag).
+ */
+function storeGitHubToken(collabDir, token) {
+    const auth = {
+        provider: 'github',
+        token,
+        scopes: SCOPES.split(' '),
+        created_at: new Date().toISOString(),
+    };
+    saveGitHubAuth(collabDir, auth);
+    ensureAuthGitIgnore(collabDir);
+    return auth;
+}

package/dist/lib/hash.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sha256 = sha256;
+const node_crypto_1 = require("node:crypto");
+function sha256(content) {
+    return (0, node_crypto_1.createHash)('sha256').update(content, 'utf8').digest('hex');
+}

package/dist/lib/health-checker.js

@@ -0,0 +1,140 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkHttpHealth = checkHttpHealth;
+exports.checkTcpHealth = checkTcpHealth;
+const node_net_1 = __importDefault(require("node:net"));
+const DEFAULT_TIMEOUT_MS = 5_000;
+const DEFAULT_RETRIES = 15;
+const DEFAULT_RETRY_DELAY_MS = 2_000;
+function normalizeOptions(options) {
+    return {
+        timeoutMs: options?.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        retries: options?.retries ?? DEFAULT_RETRIES,
+        retryDelayMs: options?.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS,
+        dryRun: options?.dryRun ?? false,
+    };
+}
+function wait(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function retryCheck(name, options, check) {
+    const normalized = normalizeOptions(options);
+    if (normalized.dryRun) {
+        return {
+            name,
+            ok: true,
+            attempts: 0,
+            detail: 'skipped in dry-run mode',
+            skipped: true,
+        };
+    }
+    let lastFailure = null;
+    for (let attempt = 1; attempt <= normalized.retries; attempt += 1) {
+        const result = await check(normalized.timeoutMs);
+        if (result.ok) {
+            return {
+                ...result,
+                attempts: attempt,
+            };
+        }
+        lastFailure = {
+            ...result,
+            attempts: attempt,
+        };
+        if (attempt < normalized.retries) {
+            await wait(normalized.retryDelayMs);
+        }
+    }
+    return (lastFailure ?? {
+        name,
+        ok: false,
+        attempts: normalized.retries,
+        detail: 'health check failed without details',
+    });
+}
+async function checkHttpHealth(name, url, options) {
+    return retryCheck(name, options ?? {}, async (timeoutMs) => {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const response = await fetch(url, {
+                method: 'GET',
+                signal: controller.signal,
+            });
+            if (response.ok) {
+                return {
+                    name,
+                    ok: true,
+                    detail: `HTTP ${response.status} from ${url}`,
+                    statusCode: response.status,
+                    attempts: 1,
+                };
+            }
+            return {
+                name,
+                ok: false,
+                detail: `HTTP ${response.status} from ${url}`,
+                statusCode: response.status,
+                attempts: 1,
+            };
+        }
+        catch (error) {
+            return {
+                name,
+                ok: false,
+                detail: `failed to reach ${url}`,
+                error: error instanceof Error ? error.message : String(error),
+                attempts: 1,
+            };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    });
+}
+async function checkTcpHealth(name, host, port, options) {
+    return retryCheck(name, options ?? {}, async (timeoutMs) => {
+        const connection = await new Promise((resolve) => {
+            let resolved = false;
+            const socket = node_net_1.default.createConnection({ host, port });
+            const settle = (result) => {
+                if (resolved) {
+                    return;
+                }
+                resolved = true;
+                clearTimeout(timeout);
+                resolve(result);
+            };
+            const timeout = setTimeout(() => {
+                socket.destroy();
+                settle({ ok: false, error: `timeout after ${timeoutMs}ms` });
+            }, timeoutMs);
+            socket.once('connect', () => {
+                socket.end();
+                settle({ ok: true });
+            });
+            socket.once('error', (error) => {
+                socket.destroy();
+                settle({ ok: false, error: error.message });
+            });
+        });
+        if (connection.ok) {
+            return {
+                name,
+                ok: true,
+                detail: `TCP ${host}:${port} reachable`,
+                attempts: 1,
+            };
+        }
+        return {
+            name,
+            ok: false,
+            detail: `TCP ${host}:${port} unreachable`,
+            error: connection.error,
+            attempts: 1,
+        };
+    });
+}

package/dist/lib/logger.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLogger = createLogger;
+const ansi_1 = require("./ansi");
+const shell_1 = require("./shell");
+class ConsoleLogger {
+    verbosity;
+    constructor(verbosity) {
+        this.verbosity = verbosity;
+    }
+    info(message) {
+        if (this.verbosity === 'quiet') {
+            return;
+        }
+        process.stdout.write(`        ${message}\n`);
+    }
+    debug(message) {
+        if (this.verbosity !== 'verbose') {
+            return;
+        }
+        process.stdout.write(`        ${(0, ansi_1.dim)(message)}\n`);
+    }
+    warn(message) {
+        process.stderr.write(`        ${(0, ansi_1.yellow)('Warning:')} ${message}\n`);
+    }
+    error(message) {
+        process.stderr.write(`        ${(0, ansi_1.red)('Error:')} ${message}\n`);
+    }
+    result(message) {
+        process.stdout.write(`${message}\n`);
+    }
+    command(parts, options) {
+        if (this.verbosity === 'quiet') {
+            return;
+        }
+        if (options?.verboseOnly && this.verbosity !== 'verbose') {
+            return;
+        }
+        process.stdout.write(`        ${(0, ansi_1.dim)('$')} ${(0, ansi_1.dim)((0, shell_1.toShellCommand)(parts))}\n`);
+    }
+    stageHeader(index, total, title) {
+        if (this.verbosity === 'quiet') {
+            return;
+        }
+        const tag = (0, ansi_1.bold)((0, ansi_1.cyan)(`[${index}/${total}]`));
+        process.stdout.write(`\n  ${tag} ${(0, ansi_1.bold)(title)}\n`);
+    }
+    step(ok, message) {
+        if (this.verbosity === 'quiet') {
+            return;
+        }
+        const marker = ok ? (0, ansi_1.green)(ansi_1.CHECK) : (0, ansi_1.red)(ansi_1.CROSS);
+        process.stdout.write(`        ${marker} ${message}\n`);
+    }
+    workflowHeader(workflow, mode) {
+        process.stdout.write(`\n  ${(0, ansi_1.bold)(workflow)} ${(0, ansi_1.dim)(`\u2014 ${mode}`)}\n`);
+    }
+    repoHeader(repoName, index, total) {
+        if (this.verbosity === 'quiet')
+            return;
+        const tag = (0, ansi_1.bold)((0, ansi_1.cyan)(`[repo ${index}/${total}]`));
+        process.stdout.write(`\n  ${tag} ${(0, ansi_1.bold)(repoName)}\n`);
+    }
+    phaseHeader(title, subtitle) {
+        if (this.verbosity === 'quiet')
+            return;
+        // Only clear when stdout is a real terminal (skip in pipes/tests)
+        if (process.stdout.isTTY) {
+            process.stdout.write(ansi_1.CLEAR_SCREEN);
+        }
+        const line = (0, ansi_1.dim)('\u2500'.repeat(48));
+        const sub = subtitle ? `  ${(0, ansi_1.dim)(subtitle)}` : '';
+        process.stdout.write(`\n  ${line}\n  ${(0, ansi_1.bold)((0, ansi_1.cyan)(title))}${sub}\n  ${line}\n\n`);
+    }
+    summaryFooter(entries) {
+        process.stdout.write(`\n  ${(0, ansi_1.dim)('\u2500'.repeat(40))}\n`);
+        process.stdout.write(`  ${(0, ansi_1.bold)((0, ansi_1.green)(ansi_1.CHECK))} ${(0, ansi_1.bold)('Init complete')}\n\n`);
+        for (const entry of entries) {
+            process.stdout.write(`  ${(0, ansi_1.dim)(entry.label + ':')} ${entry.value}\n`);
+        }
+        process.stdout.write('\n');
+    }
+}
+function createLogger(options) {
+    const verbosity = options.quiet ? 'quiet' : options.verbose ? 'verbose' : 'normal';
+    return new ConsoleLogger(verbosity);
+}

package/dist/lib/mcp-client.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveMcpHttpTimeoutMs = resolveMcpHttpTimeoutMs;
+exports.resolveMcpApiKey = resolveMcpApiKey;
+exports.getMcpBaseUrl = getMcpBaseUrl;
+exports.ingestDocuments = ingestDocuments;
+exports.triggerGraphSeed = triggerGraphSeed;
+const service_health_1 = require("./service-health");
+const DEFAULT_MCP_HTTP_TIMEOUT_MS = 30_000;
+function parseTimeoutMs(value, fallback) {
+    if (!value) {
+        return fallback;
+    }
+    const parsed = Number.parseInt(value, 10);
+    if (Number.isNaN(parsed) || parsed <= 0) {
+        return fallback;
+    }
+    return parsed;
+}
+async function fetchWithTimeout(url, init, timeoutMs, operation) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetch(url, { ...init, signal: controller.signal });
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === 'AbortError') {
+            throw new Error(`${operation} timed out after ${timeoutMs}ms`);
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
+function resolveMcpHttpTimeoutMs(env) {
+    return parseTimeoutMs(env.MCP_HTTP_TIMEOUT_MS, DEFAULT_MCP_HTTP_TIMEOUT_MS);
+}
+function resolveMcpApiKey(env) {
+    const explicit = env.MCP_API_KEY?.trim();
+    if (explicit) {
+        return explicit;
+    }
+    const firstFromList = env.MCP_API_KEYS
+        ?.split(/[,\s]+/)
+        .map((key) => key.trim())
+        .find((key) => key.length > 0);
+    return firstFromList || undefined;
+}
+function getMcpBaseUrl(config) {
+    const env = (0, service_health_1.loadRuntimeEnv)(config);
+    const host = env.MCP_HOST || '127.0.0.1';
+    const port = env.MCP_PORT || '7337';
+    return `http://${host}:${port}`;
+}
+async function ingestDocuments(baseUrl, payload, apiKey, timeoutMs = DEFAULT_MCP_HTTP_TIMEOUT_MS) {
+    const headers = {
+        'Content-Type': 'application/json',
+    };
+    if (apiKey) {
+        headers.Authorization = `Bearer ${apiKey}`;
+    }
+    const response = await fetchWithTimeout(`${baseUrl}/api/v1/ingest`, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(payload),
+    }, timeoutMs, 'MCP ingest request');
+    if (!response.ok) {
+        const body = await response.text();
+        throw new Error(`MCP ingest failed (${response.status}): ${body}`);
+    }
+    return (await response.json());
+}
+async function triggerGraphSeed(baseUrl, apiKey, timeoutMs = DEFAULT_MCP_HTTP_TIMEOUT_MS) {
+    const headers = {};
+    if (apiKey) {
+        headers.Authorization = `Bearer ${apiKey}`;
+    }
+    const response = await fetchWithTimeout(`${baseUrl}/api/v1/seed/graph`, {
+        method: 'POST',
+        headers,
+    }, timeoutMs, 'MCP graph seed request');
+    if (!response.ok) {
+        const body = await response.text();
+        throw new Error(`MCP graph seed failed (${response.status}): ${body}`);
+    }
+    return (await response.json());
+}

package/dist/lib/mode.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MODE = exports.COLLAB_MODES = void 0;
+exports.isCollabMode = isCollabMode;
+exports.parseMode = parseMode;
+exports.describeMode = describeMode;
+const errors_1 = require("./errors");
+/** Supported execution modes for the collab workspace. */
+exports.COLLAB_MODES = ['file-only', 'indexed'];
+const MODE_SET = new Set(exports.COLLAB_MODES);
+/** Default mode used when none is explicitly configured. */
+exports.DEFAULT_MODE = 'file-only';
+/** Type guard that checks whether a string is a valid {@link CollabMode}. */
+function isCollabMode(value) {
+    return MODE_SET.has(value);
+}
+/**
+ * Parses a mode string from CLI flags or config, returning the fallback
+ * when undefined. Throws on invalid values.
+ */
+function parseMode(value, fallback = exports.DEFAULT_MODE) {
+    if (value === undefined) {
+        return fallback;
+    }
+    if (isCollabMode(value)) {
+        return value;
+    }
+    throw new errors_1.CliError(`Invalid mode '${value}'. Valid values: ${exports.COLLAB_MODES.join(', ')}`);
+}
+/** Returns a human-readable description of a mode. */
+function describeMode(mode) {
+    if (mode === 'indexed') {
+        return 'indexed (starts infra + MCP and enables retrieval services)';
+    }
+    return 'file-only (no infra/MCP startup, local file workflow only)';
+}