@uxmaltech/collab-cli 0.1.6 → 0.1.8

package/dist/commands/init.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerInitCommand = registerInitCommand;
 const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
 const command_context_1 = require("../lib/command-context");
 const compose_validator_1 = require("../lib/compose-validator");
@@ -12,7 +13,9 @@ const config_1 = require("../lib/config");
 const ecosystem_1 = require("../lib/ecosystem");
 const compose_renderer_1 = require("../lib/compose-renderer");
 const errors_1 = require("../lib/errors");
+const github_search_1 = require("../lib/github-search");
 const infra_type_1 = require("../lib/infra-type");
+const mcp_contract_1 = require("../lib/mcp-contract");
 const mode_1 = require("../lib/mode");
 const parsers_1 = require("../lib/parsers");
 const orchestrator_1 = require("../lib/orchestrator");
@@ -53,7 +56,7 @@ function inferComposeMode(config) {
     }
     return 'consolidated';
 }
-async function resolveWizardSelection(options, config, logger) {
+async function resolveWizardSelection(options, config, logger, dryRun) {
     const defaults = {
         mode: (0, mode_1.parseMode)(options.mode, config.mode),
         composeMode: parseComposeMode(options.composeMode, inferComposeMode(config)),
@@ -73,6 +76,7 @@ async function resolveWizardSelection(options, config, logger) {
                 throw new errors_1.CliError('--mcp-url is required with --infra-type remote in non-interactive mode.');
             }
             mcpUrl = (0, infra_type_1.validateMcpUrl)(options.mcpUrl);
+            await validateMcpServerContract(mcpUrl, logger, dryRun);
         }
         return {
             mode,
@@ -102,6 +106,7 @@ async function resolveWizardSelection(options, config, logger) {
             const rawUrl = options.mcpUrl
                 ?? await (0, prompt_1.promptText)('MCP server base URL:', 'http://127.0.0.1:7337');
             mcpUrl = (0, infra_type_1.validateMcpUrl)(rawUrl);
+            await validateMcpServerContract(mcpUrl, logger, dryRun);
         }
     }
     // Skip compose-mode prompt when mode is file-only or infra is remote —
@@ -187,9 +192,10 @@ function buildGitHubAuthStage(effectiveConfig, logger, options) {
             'Run collab init --resume after fixing GitHub access.',
         ],
         run: async () => {
-            // Skip if no business canon is configured — GitHub auth is only needed for private repos
-            if (!effectiveConfig.canons?.business) {
-                logger.info('No business canon configured; skipping GitHub authorization.');
+            // Skip if no business canon or local source — GitHub auth only needed for remote repos
+            const canon = effectiveConfig.canons?.business;
+            if (!canon || canon.source === 'local') {
+                logger.info('No GitHub canon configured; skipping GitHub authorization.');
                 return;
             }
             // Check for pre-existing valid token
@@ -217,48 +223,185 @@ function buildGitHubAuthStage(effectiveConfig, logger, options) {
         },
     };
 }
+// ────────────────────────────────────────────────────────────────
+// MCP contract validation (single-shot probe at URL-entry time)
+// ────────────────────────────────────────────────────────────────
+async function validateMcpServerContract(mcpUrl, logger, dryRun) {
+    const result = await (0, mcp_contract_1.probeMcpContract)(mcpUrl, {
+        contractRange: (0, ecosystem_1.getMcpContractRange)(),
+        dryRun,
+    });
+    if (result.skipped) {
+        logger.info('[dry-run] Skipped MCP contract validation.');
+        return;
+    }
+    if (!result.ok) {
+        throw new errors_1.CliError(result.error ?? `MCP contract validation failed for ${mcpUrl}`);
+    }
+    const health = result.health;
+    logger.step(true, `MCP server reachable at ${mcpUrl}`);
+    logger.info(`Server version: ${health.version}`);
+    logger.info(`Contract version: ${health.contractVersion}`);
+    const deps = Object.entries(health.dependencies)
+        .map(([name, status]) => `${name} (${status})`)
+        .join(', ');
+    if (deps) {
+        logger.info(`Dependencies: ${deps}`);
+    }
+    if (result.contractCompatible === false) {
+        logger.warn(`MCP contract version ${health.contractVersion} may be incompatible ` +
+            `(CLI expects ${(0, ecosystem_1.getMcpContractRange)()}). Some features may not work correctly.`);
+    }
+    const degraded = Object.entries(health.dependencies)
+        .filter(([, status]) => status !== 'up');
+    if (degraded.length > 0) {
+        const names = degraded.map(([name, status]) => `${name} (${status})`).join(', ');
+        logger.warn(`Some MCP dependencies are not fully ready: ${names}`);
+    }
+}
+// ────────────────────────────────────────────────────────────────
+// Business canon helpers
+// ────────────────────────────────────────────────────────────────
+const LOCAL_PATH_RE = /^[/~.]/;
+/**
+ * Expands `~`, resolves to absolute, and validates the path is an existing directory.
+ * Throws CliError on failure.
+ */
+function resolveLocalCanonPath(rawPath) {
+    const resolved = node_path_1.default.resolve(rawPath.replace(/^~/, node_os_1.default.homedir()));
+    if (!node_fs_1.default.existsSync(resolved) || !node_fs_1.default.statSync(resolved).isDirectory()) {
+        throw new errors_1.CliError(`Not a valid directory: ${resolved}`);
+    }
+    return resolved;
+}
 function parseBusinessCanonOption(value) {
     if (!value || value === 'none' || value === 'skip') {
         return undefined;
     }
+    // Detect local path: starts with /, ./, ../, or ~
+    if (LOCAL_PATH_RE.test(value)) {
+        const resolved = resolveLocalCanonPath(value);
+        return {
+            business: {
+                repo: `local/${node_path_1.default.basename(resolved)}`,
+                branch: 'local',
+                localDir: 'business',
+                source: 'local',
+                localPath: resolved,
+            },
+        };
+    }
+    // GitHub repo: must contain /
     if (!value.includes('/')) {
-        throw new errors_1.CliError(`Invalid business canon format "${value}". Use "owner/repo" or "none" to skip.`);
+        throw new errors_1.CliError(`Invalid business canon format "${value}". Use "owner/repo", a local path, or "none" to skip.`);
     }
     return {
         business: {
             repo: value,
             branch: 'main',
             localDir: 'business',
+            source: 'github',
         },
     };
 }
-async function resolveBusinessCanon(options, logger) {
+async function resolveBusinessCanon(options, config, logger) {
     // CLI flag takes priority
     if (options.businessCanon) {
         return parseBusinessCanonOption(options.businessCanon);
     }
     // --yes without --business-canon: mandatory error
     if (options.yes) {
-        throw new errors_1.CliError('--business-canon is required with --yes. Use --business-canon owner/repo or --business-canon none.');
+        throw new errors_1.CliError('--business-canon is required with --yes. Use --business-canon owner/repo, --business-canon /local/path, or --business-canon none.');
     }
-    // Interactive prompt
-    const repo = await (0, prompt_1.promptText)('Business architecture canon repo (owner/repo, empty to skip):');
-    if (!repo) {
+    // Interactive: choose source
+    const source = await (0, prompt_1.promptChoice)('Business canon source:', [
+        { value: 'github', label: 'GitHub repository (search and select)' },
+        { value: 'local', label: 'Local directory' },
+        { value: 'skip', label: 'Skip (no business canon)' },
+    ], 'skip');
+    if (source === 'skip') {
         logger.info('No business canon configured.');
         return undefined;
     }
-    if (!repo.includes('/')) {
-        throw new errors_1.CliError(`Invalid format "${repo}". Use "owner/repo".`);
+    if (source === 'local') {
+        return resolveLocalBusinessCanon(logger);
+    }
+    return resolveGitHubBusinessCanon(config, logger);
+}
+async function resolveLocalBusinessCanon(logger) {
+    const rawPath = await (0, prompt_1.promptText)('Local canon directory path:');
+    if (!rawPath) {
+        throw new errors_1.CliError('Path is required for local canon.');
+    }
+    const resolved = resolveLocalCanonPath(rawPath);
+    const dirName = node_path_1.default.basename(resolved);
+    logger.info(`Using local canon at ${resolved}`);
+    return {
+        business: {
+            repo: `local/${dirName}`,
+            branch: 'local',
+            localDir: 'business',
+            source: 'local',
+            localPath: resolved,
+        },
+    };
+}
+async function resolveGitHubBusinessCanon(config, logger) {
+    // Ensure GitHub auth
+    const token = await ensureGitHubAuth(config.collabDir, logger);
+    // Search loop
+    let repo;
+    let defaultBranch = 'main';
+    while (!repo) {
+        const query = await (0, prompt_1.promptText)('Search GitHub repositories:');
+        if (!query) {
+            throw new errors_1.CliError('Search query is required.');
+        }
+        const results = await (0, github_search_1.searchGitHubRepos)(query, token, 8);
+        if (results.items.length === 0) {
+            logger.info(`No repositories found for "${query}". Try a different search.`);
+            continue;
+        }
+        logger.info(`Found ${results.items.length} results (of ${results.totalCount} total):`);
+        const choices = results.items.map((r) => ({
+            value: r.fullName,
+            label: `${r.fullName}${r.private ? ' \u{1F512}' : ''}${r.description ? ` — ${r.description}` : ''}`,
+        }));
+        choices.push({ value: '__search_again__', label: '\u21BB Search again' });
+        const selected = await (0, prompt_1.promptChoice)('Select repository:', choices, choices[0].value);
+        if (selected === '__search_again__') {
+            continue;
+        }
+        repo = selected;
+        defaultBranch =
+            results.items.find((r) => r.fullName === selected)?.defaultBranch ?? 'main';
     }
-    const branch = await (0, prompt_1.promptText)('Business canon branch:', 'main');
+    const branch = await (0, prompt_1.promptText)('Branch:', defaultBranch);
     return {
         business: {
             repo,
-            branch: branch || 'main',
+            branch: branch || defaultBranch,
             localDir: 'business',
+            source: 'github',
         },
     };
 }
+async function ensureGitHubAuth(collabDir, logger) {
+    const existing = (0, github_auth_1.loadGitHubAuth)(collabDir);
+    if (existing) {
+        const valid = await (0, github_auth_1.isGitHubAuthValid)(existing);
+        if (valid) {
+            return existing.token;
+        }
+        logger.info('Existing GitHub token expired. Re-authorizing...');
+    }
+    await (0, github_auth_1.runGitHubDeviceFlow)(collabDir, (msg) => logger.info(msg));
+    const auth = (0, github_auth_1.loadGitHubAuth)(collabDir);
+    if (!auth) {
+        throw new errors_1.CliError('GitHub authorization failed.');
+    }
+    return auth.token;
+}
 // ────────────────────────────────────────────────────────────────
 // Shared inline stages used by both pipelines
 // ────────────────────────────────────────────────────────────────
@@ -584,6 +727,9 @@ async function runInfraOnly(context, options) {
         mcpUrl = options.mcpUrl ? (0, infra_type_1.validateMcpUrl)(options.mcpUrl) : effectiveConfig.mcpUrl;
         effectiveConfig.infraType = infraType;
         effectiveConfig.mcpUrl = mcpUrl;
+        if (mcpUrl) {
+            await validateMcpServerContract(mcpUrl, context.logger, context.executor.dryRun);
+        }
     }
     const composeMode = parseComposeMode(options.composeMode, inferComposeMode(effectiveConfig));
     const infraLabel = infraType === 'remote' ? 'Remote MCP services' : 'Docker + MCP services';
@@ -756,7 +902,7 @@ function registerInitCommand(program) {
         .option('--skip-analysis', 'Skip AI-powered repository analysis stage')
         .option('--skip-ci', 'Skip CI workflow generation')
         .option('--providers <list>', 'Comma-separated AI provider list (codex,claude,gemini,copilot)')
-        .option('--business-canon <owner/repo>', 'Business canon repo (owner/repo or "none" to skip)')
+        .option('--business-canon <value>', 'Business canon: owner/repo, /local/path, or "none" to skip')
         .option('--github-token <token>', 'GitHub token for non-interactive mode')
         .option('--timeout-ms <ms>', 'Per-check timeout in milliseconds', '5000')
         .option('--retries <count>', 'Health check retries', '15')
@@ -808,7 +954,7 @@ Examples:
         }
         // ── Step 1: Configuration wizard ────────────────────────
         context.logger.phaseHeader('collab init', 'Configuration');
-        const selections = await resolveWizardSelection(options, context.config, context.logger);
+        const selections = await resolveWizardSelection(options, context.config, context.logger, context.executor.dryRun);
         const preserveExisting = configExistedBefore && !options.force;
         const effectiveConfig = {
             ...(0, config_1.defaultCollabConfig)(context.config.workspaceDir),
@@ -818,7 +964,8 @@ Examples:
             mcpUrl: preserveExisting ? context.config.mcpUrl : selections.mcpUrl,
         };
         // ── Step 2: Business canon configuration ──────────────────
-        const canons = await resolveBusinessCanon(options, context.logger);
+        context.logger.phaseHeader('collab init', 'Business Canon');
+        const canons = await resolveBusinessCanon(options, effectiveConfig, context.logger);
         if (canons) {
             effectiveConfig.canons = canons;
         }

package/dist/commands/update-canons.js

@@ -29,19 +29,23 @@ function registerUpdateCanonsCommand(program) {
         }
         // ── Business canon ───────────────────────────────────────
         if ((0, canon_resolver_1.isBusinessCanonConfigured)(context.config)) {
+            const canon = context.config.canons?.business;
             const auth = (0, github_auth_1.loadGitHubAuth)(context.config.collabDir);
             const token = auth?.token;
             const bizOk = (0, canon_resolver_1.syncBusinessCanon)(context.config, (msg) => context.logger.info(msg), token);
             if (!bizOk) {
                 throw new errors_1.CliError('Failed to sync business canon.');
             }
-            const bizDir = (0, canon_resolver_1.getBusinessCanonDir)(context.config);
-            try {
-                const bizCommitInfo = (0, node_child_process_1.execFileSync)('git', ['-C', bizDir, 'log', '-1', `--format=${COMMIT_FORMAT}`], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
-                context.logger.info(`Business canon up to date: ${bizCommitInfo}`);
-            }
-            catch {
-                context.logger.info('Business canon updated successfully.');
+            // Show git log only for GitHub-sourced canons (local dirs may not be git repos)
+            if (canon?.source !== 'local') {
+                const bizDir = (0, canon_resolver_1.getBusinessCanonDir)(context.config);
+                try {
+                    const bizCommitInfo = (0, node_child_process_1.execFileSync)('git', ['-C', bizDir, 'log', '-1', `--format=${COMMIT_FORMAT}`], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+                    context.logger.info(`Business canon up to date: ${bizCommitInfo}`);
+                }
+                catch {
+                    context.logger.info('Business canon updated successfully.');
+                }
             }
         }
     });

package/dist/lib/canon-resolver.js

@@ -167,13 +167,20 @@ function isBusinessCanonConfigured(config) {
     return !!config.canons?.business?.repo;
 }
 /**
- * Returns the local directory where the business canon is cloned.
+ * Returns the local directory where the business canon lives.
+ * For local canons this is the user-provided path; for GitHub canons
+ * it's the cached clone under `~/.collab/canons/<repo>`.
  */
 function getBusinessCanonDir(config) {
     const canon = config.canons?.business;
     if (!canon) {
         throw new Error('No business canon configured.');
     }
+    // Local source: the user's directory as-is
+    if (canon.source === 'local' && canon.localPath) {
+        return canon.localPath;
+    }
+    // GitHub source: cached clone
     const repoName = canon.repo.split('/').pop() ?? canon.repo;
     const collabHome = process.env.COLLAB_HOME ?? node_path_1.default.join(node_os_1.default.homedir(), '.collab');
     return node_path_1.default.join(collabHome, CANONS_SUBDIR, repoName);
@@ -187,9 +194,18 @@ function syncBusinessCanon(config, log, token) {
     if (!canon) {
         return false;
     }
+    const print = log ?? console.log;
+    // Local canons don't need syncing — just validate the path exists
+    if (canon.source === 'local') {
+        if (!canon.localPath || !node_fs_1.default.existsSync(canon.localPath)) {
+            print(`Local canon path not found: ${canon.localPath ?? '(not set)'}`);
+            return false;
+        }
+        print(`Using local business canon at ${canon.localPath}`);
+        return true;
+    }
     const canonsDir = getBusinessCanonDir(config);
     const parentDir = node_path_1.default.dirname(canonsDir);
-    const print = log ?? console.log;
     const branch = canon.branch || 'main';
     // Build repo URL — inject token for private repo access if available
     let repoUrl;

package/dist/lib/ecosystem.js

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.getMcpContractRange = getMcpContractRange;
 exports.checkEcosystemCompatibility = checkEcosystemCompatibility;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
@@ -31,6 +32,10 @@ function readManifest() {
     }
     return manifest;
 }
+/** Returns the required MCP contract version range from the ecosystem manifest. */
+function getMcpContractRange() {
+    return readManifest().collabArchitectureMcpContractRange;
+}
 function readCliVersion() {
     const packagePath = node_path_1.default.resolve(__dirname, '../../package.json');
     const pkg = readJsonFile(packagePath);

package/dist/lib/github-auth.js

@@ -19,9 +19,9 @@ const node_path_1 = __importDefault(require("node:path"));
 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.
+ * Override with COLLAB_GITHUB_CLIENT_ID env var for custom OAuth apps.
  */
-const DEFAULT_CLIENT_ID = process.env.COLLAB_GITHUB_CLIENT_ID ?? '';
+const DEFAULT_CLIENT_ID = process.env.COLLAB_GITHUB_CLIENT_ID ?? 'Ov23liocAEoUmWO39r5B';
 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';

package/dist/lib/github-search.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.searchGitHubRepos = searchGitHubRepos;
+const errors_1 = require("./errors");
+const GITHUB_API_VERSION = '2022-11-28';
+const SEARCH_TIMEOUT_MS = 15_000;
+/**
+ * Searches GitHub repositories using the REST search API.
+ * Requires a valid GitHub token with `repo` scope for private repos.
+ *
+ * @param query  - Search query (same syntax as GitHub web search)
+ * @param token  - GitHub personal access token or OAuth token
+ * @param limit  - Max results to return (default 8, max 100)
+ */
+async function searchGitHubRepos(query, token, limit = 8) {
+    const encoded = encodeURIComponent(query);
+    const url = `https://api.github.com/search/repositories?q=${encoded}&per_page=${limit}&sort=updated`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), SEARCH_TIMEOUT_MS);
+    try {
+        const response = await fetch(url, {
+            headers: {
+                Authorization: `Bearer ${token}`,
+                Accept: 'application/vnd.github+json',
+                'X-GitHub-Api-Version': GITHUB_API_VERSION,
+            },
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            const body = await response.text().catch(() => '');
+            throw new errors_1.CliError(`GitHub search failed (HTTP ${response.status}): ${body || response.statusText}`);
+        }
+        const data = (await response.json());
+        return {
+            totalCount: data.total_count,
+            items: data.items.map((item) => ({
+                fullName: item.full_name,
+                description: item.description ?? '',
+                private: item.private,
+                defaultBranch: item.default_branch,
+            })),
+        };
+    }
+    catch (error) {
+        if (error instanceof errors_1.CliError) {
+            throw error;
+        }
+        // AbortController fires when the timeout elapses — surface a clear message
+        if (error instanceof Error && error.name === 'AbortError') {
+            throw new errors_1.CliError(`GitHub search request timed out after ${SEARCH_TIMEOUT_MS / 1000}s.`);
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        throw new errors_1.CliError(`GitHub search request failed: ${message}`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/lib/mcp-contract.js

@@ -0,0 +1,100 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.probeMcpContract = probeMcpContract;
+const semver_1 = __importDefault(require("semver"));
+const DEFAULT_PROBE_TIMEOUT_MS = 5_000;
+/**
+ * Probes the MCP server's /health endpoint once and validates
+ * the response contract structure and version compatibility.
+ *
+ * This is a quick, single-attempt probe — not a retry loop.
+ * Use it immediately after URL entry to give fast feedback.
+ */
+async function probeMcpContract(baseUrl, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS;
+    const contractRange = options.contractRange;
+    const dryRun = options.dryRun ?? false;
+    if (dryRun) {
+        return { ok: true, skipped: true };
+    }
+    const healthUrl = `${baseUrl}/health`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let response;
+    try {
+        response = await fetch(healthUrl, {
+            method: 'GET',
+            signal: controller.signal,
+        });
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === 'AbortError') {
+            return {
+                ok: false,
+                skipped: false,
+                error: `MCP server at ${baseUrl} did not respond within ${timeoutMs / 1000}s.`,
+            };
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            ok: false,
+            skipped: false,
+            error: `MCP server unreachable at ${baseUrl}: ${message}`,
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!response.ok) {
+        return {
+            ok: false,
+            skipped: false,
+            error: `MCP server returned HTTP ${response.status} at ${healthUrl}`,
+        };
+    }
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch {
+        return {
+            ok: false,
+            skipped: false,
+            error: `MCP server returned invalid JSON from ${healthUrl}`,
+        };
+    }
+    if (!isValidHealthResponse(body)) {
+        return {
+            ok: false,
+            skipped: false,
+            error: 'MCP /health response has unexpected structure. Expected: { status, version, contractVersion, dependencies }',
+        };
+    }
+    const health = body;
+    let contractCompatible;
+    if (contractRange) {
+        contractCompatible = semver_1.default.satisfies(health.contractVersion, contractRange, {
+            includePrerelease: true,
+        });
+    }
+    return {
+        ok: true,
+        skipped: false,
+        health,
+        contractCompatible,
+    };
+}
+/** Type guard for the expected /health response shape. */
+function isValidHealthResponse(body) {
+    if (typeof body !== 'object' || body === null)
+        return false;
+    const obj = body;
+    return (typeof obj.status === 'string' &&
+        typeof obj.version === 'string' &&
+        typeof obj.contractVersion === 'string' &&
+        typeof obj.dependencies === 'object' &&
+        obj.dependencies !== null);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uxmaltech/collab-cli",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "CLI for collaborative architecture and delivery workflows.",
   "private": false,
   "license": "UNLICENSED",