@formigio/fazemos-cli 0.10.14 → 0.10.16

package/dist/index.js

@@ -10,6 +10,7 @@ import { isProjectConnectionUnavailable, renderProjectConnectionUnavailableCopy,
 import { loadYaml, summarize } from './yaml/load.js';
 import { printFindings, printJson } from './yaml/format.js';
 import { validateManifest } from './manifest/checks.js';
+import { findLocalRegistry, resolveRole, buildInboxFile, writeInboxFile, buildNotificationPayload, gitCommitInboxFile, } from './dispatch.js';
 import { execSync } from 'child_process';
 import { readFileSync, readdirSync, writeFileSync, mkdirSync, existsSync, statSync } from 'fs';
 import { fileURLToPath } from 'url';
@@ -1390,27 +1391,34 @@ const connections = program.command('connections').alias('conn').description('Gi
  */
 connections
     .command('list')
-    .description('List GitHub Connections in the active organization')
+    .description('List VCS Connections (GitHub + BitBucket) in the active organization')
     .option('-s, --status <status>', 'Filter: active (default), all, pending, suspended, revoked, uninstalled', 'active')
     .action(async (opts) => {
     try {
         const orgId = requireActiveOrgOrExit();
-        const data = await api('GET', `/api/organizations/${orgId}/github/connections?status=${encodeURIComponent(opts.status)}`, undefined, { noProjectHeader: true });
-        const list = data.connections ?? [];
+        // F22 — call the provider-agnostic /vcs/connections endpoint.
+        // The legacy /github/connections alias still works during the
+        // dual-write phase, but `vcs/` returns BOTH providers' rows so
+        // the user sees their full Org Connection list.
+        const data = await api('GET', `/api/organizations/${orgId}/vcs/connections?status=${encodeURIComponent(opts.status)}`, undefined, { noProjectHeader: true });
+        const list = (data.connections ?? []).map(normalizeConnection);
         if (list.length === 0) {
             const orgName = findOrgById(orgId)?.name ?? orgId;
-            console.log(chalk.yellow(`No GitHub connections in ${orgName}.`));
+            console.log(chalk.yellow(`No code platform connections in ${orgName}.`));
             console.log(chalk.gray('Add one with: fazemos connections install'));
             return;
         }
         const orgName = findOrgById(orgId)?.name ?? orgId;
-        console.log(chalk.cyan(`GitHub connections in ${orgName}:`));
+        console.log(chalk.cyan(`Code platform connections in ${orgName}:`));
         console.log('');
         for (const c of list) {
             const statusColor = pickStatusColor(c.status);
             const projects = c.projectCount == null ? '—' : `${c.projectCount} ${c.projectCount === 1 ? 'project' : 'projects'}`;
-            const login = c.githubAccountLogin ?? chalk.gray('—');
-            console.log(`  ${chalk.cyan(c.name)}  ${chalk.gray(login)}  ${statusColor(c.status)}  ${chalk.gray(projects)}`);
+            const login = c.accountLogin ?? chalk.gray('—');
+            const providerLabel = formatProviderLabel(c.provider);
+            // F22 §8.3 item 1: provider column. Renders as a prefix tag so
+            // mixed-provider lists are scannable at a glance.
+            console.log(`  ${chalk.magenta(providerLabel)}  ${chalk.cyan(c.name)}  ${chalk.gray(login)}  ${statusColor(c.status)}  ${chalk.gray(projects)}`);
             console.log(chalk.gray(`    ID: ${c.id}`));
         }
     }
@@ -1425,40 +1433,56 @@ connections
  */
 connections
     .command('show')
-    .description('Show a GitHub Connection in detail')
+    .description('Show a VCS Connection in detail')
     .argument('<id>', 'Connection ID')
     .action(async (id) => {
     try {
         const orgId = requireActiveOrgOrExit();
-        const data = await api('GET', `/api/organizations/${orgId}/github/connections/${id}`, undefined, { noProjectHeader: true });
-        const c = data.connection;
-        console.log(chalk.cyan(c.name));
+        // F22 — provider-agnostic detail endpoint. The serialized shape
+        // includes `provider`, `account_login`, `supports_contents_api`
+        // and (for GitHub) `installation_id` / (BitBucket) `workspace_uuid`.
+        const data = await api('GET', `/api/organizations/${orgId}/vcs/connections/${id}`, undefined, { noProjectHeader: true });
+        const raw = data.connection ?? data;
+        const c = normalizeConnection(raw);
+        console.log(chalk.cyan(c.name ?? '(unnamed connection)'));
         console.log(`  ID:           ${c.id}`);
-        console.log(`  GitHub:       ${c.githubAccountLogin ?? chalk.gray('— (pending)')}`);
-        if (c.githubAccountType)
-            console.log(`  Account type: ${c.githubAccountType}`);
+        // F22 §8.3 item 2 — provider line above account info.
+        console.log(`  Provider:     ${formatProviderLabel(c.provider)}`);
+        console.log(`  Account:      ${c.accountLogin ?? chalk.gray('— (pending)')}`);
+        if (c.accountType)
+            console.log(`  Account type: ${c.accountType}`);
         const statusColor = pickStatusColor(c.status);
         console.log(`  Status:       ${statusColor(c.status)}`);
-        console.log(`  Installed:    ${c.installedAt ? new Date(c.installedAt).toLocaleString() : '(unknown)'}`);
+        if (c.installedAt) {
+            console.log(`  Installed:    ${new Date(c.installedAt).toLocaleString()}`);
+        }
         if (c.lastHealthCheckAt) {
             console.log(`  Last checked: ${new Date(c.lastHealthCheckAt).toLocaleString()}`);
         }
         if (c.lastUsedAt) {
             console.log(`  Last used:    ${new Date(c.lastUsedAt).toLocaleString()}`);
         }
-        if (c.repositorySelection === 'all') {
-            console.log(`  Repos:        All repositories${c.githubAccountLogin ? ` in ${c.githubAccountLogin}` : ''}`);
+        // F22 §6.4 — supports_contents_api is the canonical signal for
+        // "can this Connection back F18 docs surfaces?" Surface it so
+        // users understand why docs may be unavailable on BitBucket.
+        if (typeof c.supportsContentsApi === 'boolean') {
+            const docs = c.supportsContentsApi ? 'yes' : chalk.yellow('no');
+            console.log(`  Docs API:     ${docs}`);
+        }
+        if (raw.repositorySelection === 'all') {
+            console.log(`  Repos:        All repositories${c.accountLogin ? ` in ${c.accountLogin}` : ''}`);
         }
-        else if (Array.isArray(c.repositories)) {
-            console.log(`  Repos:        ${c.repositories.length}${c.repositoriesTruncated ? ' (showing 100)' : ''}`);
-            for (const r of c.repositories) {
-                console.log(chalk.gray(`    · ${r.fullName}`));
+        else if (Array.isArray(raw.repositories)) {
+            console.log(`  Repos:        ${raw.repositories.length}${raw.repositoriesTruncated ? ' (showing 100)' : ''}`);
+            for (const r of raw.repositories) {
+                console.log(chalk.gray(`    · ${r.fullName ?? r.full_name ?? r.name}`));
             }
         }
-        if (Array.isArray(c.boundProjects) && c.boundProjects.length > 0) {
+        const boundProjects = raw.boundProjects ?? raw.bound_projects ?? [];
+        if (Array.isArray(boundProjects) && boundProjects.length > 0) {
             console.log('');
             console.log(chalk.cyan('Projects using this connection:'));
-            for (const p of c.boundProjects) {
+            for (const p of boundProjects) {
                 console.log(`  · ${p.name} (${p.slug})`);
             }
         }
@@ -1479,12 +1503,55 @@ connections
  */
 connections
     .command('install')
-    .description('Add a GitHub Connection. Prints an install URL and waits for a confirmation code.')
-    .action(async () => {
+    .description('Add a VCS Connection (GitHub or BitBucket). Prints an install URL and (for GitHub) waits for a confirmation code.')
+    .option('--provider <provider>', 'VCS provider: github | bitbucket')
+    .action(async (opts) => {
     try {
         const orgId = requireActiveOrgOrExit();
         const orgName = findOrgById(orgId)?.name ?? orgId;
-        const mintData = await api('POST', `/api/organizations/${orgId}/github/connections/install-url`, { source: 'cli', returnTo: null }, { noProjectHeader: true });
+        // F22 §8.3 item 3 — provider selection matrix.
+        // 1) `--provider github|bitbucket` supplied: use directly.
+        // 2) No flag: prompt the user interactively (provider-picker).
+        //    The CLI cannot probe server-side provider configuration, so the
+        //    "exactly one provider configured" auto-select branch of the spec
+        //    is implemented as "user always confirms" — narrower than the
+        //    spec wording but strictly safer (no silent provider choice).
+        let provider = opts.provider?.toLowerCase();
+        if (!provider) {
+            provider = await promptProviderChoice();
+        }
+        if (provider !== 'github' && provider !== 'bitbucket') {
+            console.error(chalk.red(`Invalid --provider: ${provider}. Use 'github' or 'bitbucket'.`));
+            process.exit(1);
+        }
+        // F22 prefers the new provider-agnostic /vcs/connections route, which
+        // expects `provider` in the body. The github-only endpoint is kept
+        // alive but not used here so all new connections flow through one path.
+        const mintData = await api('POST', `/api/organizations/${orgId}/vcs/connections/install-url`, { provider, source: 'cli', returnTo: null }, { noProjectHeader: true });
+        // F22 §8.3 item 8 — BitBucket install is browser-only in v1 (no CLI
+        // confirmation-code exchange counterpart). Print the literal copy
+        // block specified in the spec verbatim, then exit successfully.
+        // The user completes consent in the browser and the /api/bitbucket/
+        // oauth/callback handler finishes the Connection server-side.
+        //
+        // Dex nit N4 — output literal MUST match the spec block exactly so
+        // the acceptance test can assert it.
+        if (provider === 'bitbucket') {
+            console.log('');
+            console.log('BitBucket Connection install — browser required');
+            console.log('');
+            console.log('Open this URL in your browser to authorize Fazemos:');
+            console.log('');
+            console.log(`    ${mintData.url}`);
+            console.log('');
+            console.log('After you authorize, BitBucket will redirect to Fazemos and complete the Connection.');
+            console.log('You can then list your connections with:');
+            console.log('');
+            console.log('    fazemos connections list');
+            console.log('');
+            console.log('This URL expires in 10 minutes.');
+            return;
+        }
         console.log('');
         console.log(`To add a GitHub connection to ${chalk.cyan(orgName)}:`);
         console.log('');
@@ -1573,18 +1640,20 @@ connections
 connections
     .command('revoke')
     .alias('disconnect')
-    .description('Disconnect a GitHub Connection (Fazemos-side; does not uninstall the App from GitHub).')
+    .description('Disconnect a VCS Connection (Fazemos-side; does not uninstall the App from GitHub / revoke the OAuth grant on BitBucket).')
     .argument('<id>', 'Connection ID')
     .option('-f, --force', 'Skip the confirmation prompt', false)
     .action(async (id, opts) => {
     try {
         const orgId = requireActiveOrgOrExit();
         // Fetch the Connection so we can show what we're about to revoke
-        // and how many projects it affects (Sage §8.3 confirmation copy).
-        let connection;
+        // and how many projects it affects (UX §8.3 confirmation copy).
+        // F22 — use the provider-agnostic /vcs/ endpoint so both provider
+        // rows are reachable.
+        let raw;
         try {
-            const detail = await api('GET', `/api/organizations/${orgId}/github/connections/${id}`, undefined, { noProjectHeader: true });
-            connection = detail.connection;
+            const detail = await api('GET', `/api/organizations/${orgId}/vcs/connections/${id}`, undefined, { noProjectHeader: true });
+            raw = detail.connection ?? detail;
         }
         catch (err) {
             if (err instanceof ApiError && err.code === 'CONNECTION_NOT_FOUND') {
@@ -1593,15 +1662,17 @@ connections
             }
             throw err;
         }
-        const boundProjects = connection.boundProjects ?? [];
+        const connection = normalizeConnection(raw);
+        const boundProjects = raw.boundProjects ?? raw.bound_projects ?? [];
+        const providerLabelStr = formatProviderLabel(connection.provider);
         if (!opts.force) {
             console.log('');
-            console.log(`Disconnect ${chalk.cyan(connection.name)}?`);
+            console.log(`Disconnect ${chalk.magenta(providerLabelStr)} ${chalk.cyan(connection.name ?? id)}?`);
             console.log('');
             if (boundProjects.length > 0) {
                 const projectList = boundProjects.map(p => p.name).join(', ');
                 console.log(`  This connection is used by ${boundProjects.length} ${boundProjects.length === 1 ? 'project' : 'projects'}: ${projectList}.`);
-                console.log('  Pipelines in those projects will fail on GitHub steps until');
+                console.log(`  Pipelines in those projects will fail on ${providerLabelStr} steps until`);
                 console.log('  they are bound to a different connection.');
                 console.log('');
             }
@@ -1609,7 +1680,13 @@ connections
                 console.log('  No projects are using this connection.');
                 console.log('');
             }
-            console.log(chalk.gray('  This does not uninstall the Fazemos App from GitHub.'));
+            // Provider-aware caveat: GitHub App vs BitBucket OAuth grant.
+            if (connection.provider === 'bitbucket') {
+                console.log(chalk.gray('  This does not revoke the OAuth grant on BitBucket.'));
+            }
+            else {
+                console.log(chalk.gray('  This does not uninstall the Fazemos App from GitHub.'));
+            }
             console.log('');
             const answer = await promptLine('Disconnect? [y/N]: ');
             if (!answer || !/^y/i.test(answer.trim())) {
@@ -1617,11 +1694,14 @@ connections
                 return;
             }
         }
-        const data = await api('DELETE', `/api/organizations/${orgId}/github/connections/${id}`, undefined, { noProjectHeader: true });
-        console.log(chalk.green(`Disconnected: ${connection.name}`));
-        const affected = data.affectedProjects ?? [];
-        if (affected.length > 0) {
-            console.log(chalk.gray(`  ${affected.length} project${affected.length === 1 ? '' : 's'} unbound.`));
+        const data = await api('DELETE', `/api/organizations/${orgId}/vcs/connections/${id}`, undefined, { noProjectHeader: true });
+        console.log(chalk.green(`Disconnected: ${providerLabelStr} ${connection.name ?? id}`));
+        // F22 response shape: { revoked, secrets_deleted, projects_unbound }.
+        // F16 legacy shape: { affectedProjects: [...] }. Handle both during
+        // the dual-write rollout.
+        const unbound = data.projects_unbound ?? (data.affectedProjects ?? []).length ?? 0;
+        if (unbound > 0) {
+            console.log(chalk.gray(`  ${unbound} project${unbound === 1 ? '' : 's'} unbound.`));
         }
         invalidateAuthMeCache();
     }
@@ -1636,19 +1716,23 @@ connections
  */
 connections
     .command('health-check')
-    .description('Verify a Connection is still healthy on GitHub')
+    .description('Verify a Connection is still healthy on its code platform (GitHub or BitBucket)')
     .argument('<id>', 'Connection ID')
     .action(async (id) => {
     try {
         const orgId = requireActiveOrgOrExit();
-        const data = await api('POST', `/api/organizations/${orgId}/github/connections/${id}/health-check`, {}, { noProjectHeader: true });
-        const c = data.connection;
+        // F22 — provider-aware health-check route on the /vcs/ alias.
+        // The handler dispatches to the right provider (GitHub installation
+        // probe / BitBucket OAuth-refresh + workspace probe).
+        const data = await api('POST', `/api/organizations/${orgId}/vcs/connections/${id}/health-check`, {}, { noProjectHeader: true });
+        const c = normalizeConnection(data.connection ?? data);
         const statusColor = pickStatusColor(c.status);
+        const label = `${formatProviderLabel(c.provider)} ${c.name ?? id}`;
         if (data.changed) {
-            console.log(chalk.yellow(`Status changed: ${c.name} → ${statusColor(c.status)}`));
+            console.log(chalk.yellow(`Status changed: ${label} → ${statusColor(c.status)}`));
         }
         else {
-            console.log(chalk.green(`✓ ${c.name} — ${statusColor(c.status)}`));
+            console.log(chalk.green(`✓ ${label} — ${statusColor(c.status)}`));
         }
     }
     catch (err) {
@@ -1660,6 +1744,53 @@ connections
         process.exit(1);
     }
 });
+export function normalizeConnection(raw) {
+    if (!raw || typeof raw !== 'object') {
+        return {
+            id: '',
+            provider: null,
+            name: null,
+            accountLogin: null,
+            accountType: null,
+            status: 'unknown',
+            installedAt: null,
+            lastHealthCheckAt: null,
+            lastUsedAt: null,
+            supportsContentsApi: null,
+            projectCount: null,
+        };
+    }
+    // Provider — F22 new field. Older /github/ rows always meant github;
+    // default there for back-compat.
+    const provider = raw.provider ?? (raw.githubAccountLogin !== undefined ? 'github' : null);
+    return {
+        id: String(raw.id ?? ''),
+        provider,
+        name: raw.name ?? null,
+        accountLogin: raw.accountLogin ?? raw.account_login ?? raw.githubAccountLogin ?? null,
+        accountType: raw.accountType ?? raw.account_type ?? raw.githubAccountType ?? null,
+        status: raw.status ?? 'unknown',
+        installedAt: raw.installedAt ?? raw.installed_at ?? raw.created_at ?? null,
+        lastHealthCheckAt: raw.lastHealthCheckAt ?? raw.last_health_check_at ?? null,
+        lastUsedAt: raw.lastUsedAt ?? raw.last_used_at ?? null,
+        supportsContentsApi: typeof raw.supportsContentsApi === 'boolean'
+            ? raw.supportsContentsApi
+            : typeof raw.supports_contents_api === 'boolean'
+                ? raw.supports_contents_api
+                : null,
+        projectCount: raw.projectCount ?? raw.project_count ?? null,
+    };
+}
+/**
+ * F22 — Human-friendly provider label used in CLI columns and lines.
+ */
+export function formatProviderLabel(provider) {
+    if (provider === 'github')
+        return 'GitHub';
+    if (provider === 'bitbucket')
+        return 'BitBucket';
+    return '—';
+}
 /**
  * Helper — color a status string per the Sage §2.2 taxonomy.
  */
@@ -1679,6 +1810,30 @@ function pickStatusColor(status) {
             return chalk.white;
     }
 }
+/**
+ * F22 §8.3 item 3 — interactive provider picker. Used by
+ * `fazemos connections install` when no `--provider` flag is supplied
+ * so the user explicitly chooses GitHub or BitBucket before the URL
+ * mint hits the API. Mirrors the web `ProviderPickerModal` choice
+ * without the modal chrome.
+ *
+ * Returns 'github' or 'bitbucket'. Repeats on invalid input.
+ */
+export async function promptProviderChoice() {
+    console.log('');
+    console.log('Which code platform do you want to connect?');
+    console.log('  1. GitHub');
+    console.log('  2. BitBucket');
+    console.log('');
+    while (true) {
+        const ans = (await promptLine('  Choose [1=GitHub / 2=BitBucket]: ')).trim().toLowerCase();
+        if (ans === '1' || ans === 'github' || ans === 'gh')
+            return 'github';
+        if (ans === '2' || ans === 'bitbucket' || ans === 'bb')
+            return 'bitbucket';
+        console.log(chalk.yellow('  Please answer 1 (GitHub) or 2 (BitBucket).'));
+    }
+}
 /**
  * Read a single line of input from stdin. No fancy framing — `readline`
  * is sufficient for the install confirmation-code prompt and the
@@ -7898,6 +8053,151 @@ Examples:
     if (summary.errors > 0)
         process.exit(1);
 });
+// ── `fazemos dispatch` — role-to-role dispatch ─────────────────────
+//
+// Writes an inbox markdown file in the recipient role's operating dir and
+// calls POST /api/notifications/dispatch so the API can fire any
+// configured human-filler notifications (Slack today).
+//
+// Recipients are resolved via `.fazemos/roles.json` walked up from cwd.
+// Cross-workspace roles are followed via the local registry's
+// `cross_workspace_roles` block.
+//
+// Example:
+//   fazemos dispatch founder question --from business-strategist \
+//     --body "Should we ship F19 before F7?" --priority high --commit
+program
+    .command('dispatch <to> <type>')
+    .description(`Write an inbox markdown file in <to>'s operating dir and (optionally) fire
+notifications via the API.
+
+Recipients are resolved via the nearest .fazemos/roles.json registry, walking
+up from the current directory. Cross-workspace recipients are followed via
+the local registry's cross_workspace_roles block.
+
+Types: question | task | signal | response | flag | decision | direction`)
+    .requiredOption('--from <role>', 'sender role-slug (required)')
+    .option('--body <text>', 'markdown body of the dispatch (or use --body-file)')
+    .option('--body-file <path>', 'read body from a file')
+    .option('--priority <level>', 'low | normal | high', 'normal')
+    .option('--re <ref>', 'optional reference (worksheet id, file path, etc.)')
+    .option('--thread <id>', 'optional prior item id this responds to')
+    .option('--expires-at <iso>', 'optional deadline (ISO 8601)')
+    .option('--commit', 'git add + commit the inbox file after writing')
+    .option('--no-notify', 'skip the API notification call (file-only)')
+    .action(async (to, type, opts) => {
+    try {
+        // Validate type
+        const allowedTypes = ['question', 'task', 'signal', 'response', 'flag', 'decision', 'direction'];
+        if (!allowedTypes.includes(type)) {
+            throw new Error(`Invalid type "${type}". Allowed: ${allowedTypes.join(', ')}`);
+        }
+        // Resolve body
+        let body = opts.body;
+        if (!body && opts.bodyFile) {
+            body = readFileSync(opts.bodyFile, 'utf-8').trim();
+        }
+        if (!body) {
+            throw new Error('--body or --body-file is required');
+        }
+        // Find local registry
+        const localRegistry = findLocalRegistry(process.cwd());
+        if (!localRegistry) {
+            throw new Error(`No .fazemos/roles.json found in cwd or any parent. ` +
+                `Run from inside a Fazemos-aware workspace.`);
+        }
+        // Resolve recipient
+        const resolved = resolveRole(to, localRegistry);
+        if (!resolved) {
+            throw new Error(`Role "${to}" not found in local registry or any cross-workspace ref. ` +
+                `Check .fazemos/roles.json.`);
+        }
+        const { role, registry } = resolved;
+        const input = {
+            to,
+            from: opts.from,
+            type: type,
+            priority: (opts.priority ?? 'normal'),
+            body,
+            re: opts.re,
+            thread: opts.thread,
+            expiresAt: opts.expiresAt,
+        };
+        // Build + write file
+        const { filename, content, summary } = buildInboxFile(input);
+        const fullPath = writeInboxFile(registry._workspaceRoot, role, filename, content);
+        const relPath = fullPath.startsWith(registry._workspaceRoot)
+            ? fullPath.slice(registry._workspaceRoot.length + 1)
+            : fullPath;
+        console.log(chalk.green(`✓ Wrote inbox file:`));
+        console.log(`  ${chalk.cyan(fullPath)}`);
+        console.log(`  Workspace: ${registry.workspace}  Filler: ${role.filler.identity} (${role.filler.type})`);
+        // Notify (unless --no-notify)
+        if (opts.notify !== false) {
+            try {
+                const payload = buildNotificationPayload(input, role, relPath, summary);
+                const resp = await api('POST', '/api/notifications/dispatch', payload);
+                if (resp.notified) {
+                    console.log(chalk.green(`✓ Notification fired: ${resp.channel}`));
+                }
+                else {
+                    console.log(chalk.gray(`  (no notification fired — ${resp.reason ?? 'unknown'})`));
+                }
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                console.log(chalk.yellow(`  warning: notification call failed — ${msg}`));
+                console.log(chalk.yellow(`  (inbox file was still written successfully)`));
+            }
+        }
+        else {
+            console.log(chalk.gray('  (--no-notify; API not called)'));
+        }
+        // Commit if requested
+        if (opts.commit) {
+            try {
+                gitCommitInboxFile(registry._workspaceRoot, relPath, `dispatch(${opts.from} → ${to}): ${type}`);
+                console.log(chalk.green('✓ Committed.'));
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                console.log(chalk.yellow(`  warning: commit failed — ${msg}`));
+            }
+        }
+    }
+    catch (err) {
+        console.error(chalk.red(err instanceof Error ? err.message : String(err)));
+        process.exit(1);
+    }
+});
+program
+    .command('dispatch-list-roles')
+    .description('List roles available in the nearest .fazemos/roles.json registry')
+    .action(() => {
+    const reg = findLocalRegistry(process.cwd());
+    if (!reg) {
+        console.error(chalk.red('No .fazemos/roles.json found in cwd or any parent.'));
+        process.exit(1);
+    }
+    console.log(chalk.cyan(`Registry: ${reg._registryPath}`));
+    console.log(chalk.cyan(`Workspace: ${reg.workspace}  Org: ${reg.org}${reg.project ? '  Project: ' + reg.project : ''}`));
+    console.log();
+    console.log(chalk.bold('Local roles:'));
+    for (const [slug, role] of Object.entries(reg.roles)) {
+        const fillerTag = role.filler.type === 'human'
+            ? chalk.yellow(`${role.filler.identity} (human)`)
+            : chalk.gray(`${role.filler.identity} (agent)`);
+        const notifyTag = role.notification ? chalk.green(' [notify]') : '';
+        console.log(`  ${chalk.cyan(slug.padEnd(32))} ${fillerTag}${notifyTag}`);
+    }
+    if (reg.cross_workspace_roles) {
+        console.log();
+        console.log(chalk.bold('Cross-workspace roles:'));
+        for (const [slug, xref] of Object.entries(reg.cross_workspace_roles)) {
+            console.log(`  ${chalk.cyan(slug.padEnd(32))} → ${xref.workspace_path}`);
+        }
+    }
+});
 // Skip auto-parse only when running under Vitest (which sets process.env.VITEST).
 // Tests import `program` and drive it via `program.parseAsync(...)` after mocking
 // `./api.js`. In every other context — direct invocation, npx tsx, OR the bin