@formigio/fazemos-cli 0.6.1 → 0.8.0

package/dist/index.js

@@ -1,9 +1,12 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
 import chalk from 'chalk';
-import { config, getEnv, getToken, getActiveOrgId, setActiveOrgId, addEnvironment, hasEnvironments } from './config.js';
+import { config, getEnv, getToken, getActiveOrgId, setActiveOrgId, addEnvironment, hasEnvironments, 
+// F15 — project context helpers
+getActiveProjectId, setActiveProjectId, clearActiveProjectId, findProjectBySlug, findProjectById, findOrgById, } from './config.js';
 import { login, signup, confirmSignup, adminLogin } from './auth.js';
-import { api, ApiError } from './api.js';
+import { api, ApiError, refreshAuthMeCache, invalidateAuthMeCache } from './api.js';
+import { isProjectConnectionUnavailable, renderProjectConnectionUnavailableCopy, } from './connectionErrorCopy.js';
 import { execSync } from 'child_process';
 import { readFileSync, readdirSync, writeFileSync, mkdirSync, existsSync, statSync } from 'fs';
 import { fileURLToPath } from 'url';
@@ -249,13 +252,47 @@ auth
 // ── Whoami ──────────────────────────────────────────────────
 program
     .command('whoami')
-    .description('Show current user and org context')
+    .description('Show current user, org, and project context')
     .action(async () => {
     try {
-        const data = await api('GET', '/auth/me');
-        console.log(`  User:   ${chalk.cyan(data.user.email)}`);
-        console.log(`  Member: ${data.member.displayName} (${data.member.role})`);
-        console.log(`  Org:    ${data.member.orgId}`);
+        // Force-refresh the /auth/me cache on whoami so subsequent slug
+        // resolutions (e.g., `projects switch vahmos`) see the fresh state
+        // without a second round-trip.
+        const data = await refreshAuthMeCache();
+        if (!data) {
+            // Fall back to a direct call if refresh failed silently.
+            const direct = await api('GET', '/auth/me', undefined, { noProjectHeader: true });
+            console.log(`  User:   ${chalk.cyan(direct.user.email)}`);
+            console.log(`  Member: ${direct.member.displayName} (${direct.member.role})`);
+            console.log(`  Org:    ${direct.member.orgId}`);
+            return;
+        }
+        console.log(`  User:    ${chalk.cyan(data.user.email)}`);
+        console.log(`  Member:  ${data.member.displayName} (${data.member.role})`);
+        const activeOrgId = getActiveOrgId() ?? data.activeOrgId;
+        const activeOrg = data.orgs.find(o => o.id === activeOrgId);
+        if (activeOrg) {
+            console.log(`  Org:     ${chalk.cyan(activeOrg.name)} (${activeOrg.slug})`);
+        }
+        else {
+            console.log(`  Org:     ${activeOrgId}`);
+        }
+        const activeProjectId = getActiveProjectId();
+        if (activeProjectId && activeOrg) {
+            const activeProject = activeOrg.projects.find(p => p.id === activeProjectId);
+            if (activeProject) {
+                console.log(`  Project: ${chalk.cyan(activeProject.name)} (${activeProject.slug})`);
+            }
+            else {
+                console.log(`  Project: ${activeProjectId}`);
+            }
+        }
+        else if (activeOrg && activeOrg.projects.length === 0) {
+            console.log(`  Project: ${chalk.gray('(none — create one with: fazemos projects create <slug> --name <n>)')}`);
+        }
+        else {
+            console.log(`  Project: ${chalk.gray('(none set — fazemos projects switch <slug>)')}`);
+        }
     }
     catch (err) {
         console.error(chalk.red(err.message));
@@ -269,7 +306,7 @@ orgs
     .description('List your organizations')
     .action(async () => {
     try {
-        const data = await api('GET', '/api/organizations/mine');
+        const data = await api('GET', '/api/organizations/mine', undefined, { noProjectHeader: true });
         if (data.organizations.length === 0) {
             console.log(chalk.yellow('No organizations. Create one with: fazemos orgs create'));
             return;
@@ -313,11 +350,11 @@ orgs
 });
 orgs
     .command('switch')
-    .description('Switch active organization')
+    .description('Switch active organization. Restores the last active project for this org from config, or clears it if none has been used here before.')
     .argument('<slug>', 'Organization slug')
     .action(async (slug) => {
     try {
-        const data = await api('GET', '/api/organizations/mine');
+        const data = await api('GET', '/api/organizations/mine', undefined, { noProjectHeader: true });
         const org = data.organizations.find((o) => o.slug === slug);
         if (!org) {
             console.error(chalk.red(`No organization with slug "${slug}"`));
@@ -329,6 +366,36 @@ orgs
         }
         setActiveOrgId(org.id);
         console.log(chalk.green(`Switched to ${org.name} (${org.slug})`));
+        // F15 — refresh /auth/me so the next `fazemos projects list` (and any
+        // slug→id resolutions) see the project set for the new org. Without
+        // this the cached authMeCache is effectively stale and slug lookups
+        // force an extra network call each time.
+        invalidateAuthMeCache();
+        await refreshAuthMeCache();
+        // Report the restored active project, if any. Matches UX §1.8
+        // "Switching Org" — restore last-used project for this org or fall
+        // back to the first project alphabetically.
+        const activeProjectId = getActiveProjectId();
+        if (activeProjectId) {
+            const restored = findProjectById(org.id, activeProjectId);
+            if (restored) {
+                console.log(chalk.cyan(`Restored project: ${restored.name} (${restored.slug})`));
+            }
+            else {
+                // Stored project id is no longer in this org (archived?). Clear it.
+                clearActiveProjectId(org.id);
+                console.log(chalk.gray('Previously active project for this org is no longer available.'));
+            }
+        }
+        else {
+            const orgCache = findOrgById(org.id);
+            if (orgCache && orgCache.projects.length === 0) {
+                console.log(chalk.gray('No projects in this org yet. Create one with: fazemos projects create <slug> --name <n>'));
+            }
+            else if (orgCache && orgCache.projects.length > 0) {
+                console.log(chalk.gray(`No active project set. Run: fazemos projects switch <slug>`));
+            }
+        }
     }
     catch (err) {
         console.error(chalk.red(err.message));
@@ -733,6 +800,26 @@ function requireActiveOrgOrExit() {
     }
     return orgId;
 }
+/**
+ * F16 — Resolve the caller's role in the active Org from the cached
+ * /auth/me response. Used to branch the `PROJECT_CONNECTION_UNAVAILABLE`
+ * error copy (tech spec §5.14) — admin variant includes a settings URL,
+ * member variant does not.
+ *
+ * Falls back to 'member' if the cache is empty or the active Org isn't
+ * present in it. Conservative — better to render the no-CTA copy than
+ * mislead a non-admin into clicking a settings link they can't act on.
+ */
+function resolveActiveOrgRole() {
+    const orgId = getActiveOrgId();
+    if (!orgId)
+        return 'member';
+    const org = findOrgById(orgId);
+    const role = org?.role;
+    if (role === 'owner' || role === 'admin' || role === 'member')
+        return role;
+    return 'member';
+}
 notifications
     .command('get')
     .description('Show current notification config (events enabled, webhook source)')
@@ -848,15 +935,701 @@ notifications
         process.exit(1);
     }
 });
+// ── F15 — Scoped-command helpers ────────────────────────────
+// Shared helpers for commands whose API calls require a Project context.
+// Keeps the two new flags (--project <slug>, --all-projects) and the
+// uniform missing-project error rendering in one place so every scoped
+// command uses the exact same shape.
+/**
+ * Extract ApiOptions (projectSlug + allProjects) from a commander opts
+ * bag. Call this inside any `.action()` that forwards to `api()`.
+ */
+function projectOpts(opts) {
+    return {
+        projectSlug: opts.project,
+        allProjects: opts.allProjects,
+    };
+}
+/**
+ * Uniform error handler for scoped commands. When the API emits
+ * MISSING_PROJECT_CONTEXT (§7.3.1), the api helper has already re-shaped
+ * the message to "requirement missing: project". This helper prints that
+ * as the error AND appends the standard three-option hint block per KD9.
+ *
+ * All other errors pass through with their original message (preserving
+ * PROJECT_NOT_FOUND, PROJECT_MISMATCH, VALIDATION_ERROR wording) — the
+ * CLI's job is to be a thin validator, not to re-author API errors.
+ */
+function handleScopedError(err) {
+    if (err instanceof ApiError && err.code === 'MISSING_PROJECT_CONTEXT') {
+        console.error(chalk.red('Error: requirement missing: project'));
+        console.error('');
+        console.error(chalk.gray('Set one with:  fazemos projects switch <slug>'));
+        console.error(chalk.gray('Or pass:       --project <slug>'));
+        console.error(chalk.gray('Or view all:   --all-projects'));
+        process.exit(1);
+    }
+    if (err instanceof Error) {
+        console.error(chalk.red(err.message));
+    }
+    else {
+        console.error(chalk.red(String(err)));
+    }
+    process.exit(1);
+}
+// ── F15 — Projects ──────────────────────────────────────────
+const projects = program.command('projects').alias('proj').description('Project commands');
+projects
+    .command('list')
+    .description('List projects in the active organization')
+    .option('-s, --status <status>', 'Filter by status: active (default), archived, or all', 'active')
+    .action(async (opts) => {
+    try {
+        const orgId = requireActiveOrgOrExit();
+        const data = await api('GET', `/api/organizations/${orgId}/projects?status=${encodeURIComponent(opts.status)}`, undefined, { noProjectHeader: true });
+        if (!data.projects || data.projects.length === 0) {
+            if (opts.status === 'active') {
+                console.log(chalk.yellow('No active projects in this organization.'));
+                console.log(chalk.gray('Create one with: fazemos projects create <slug> --name <name>'));
+            }
+            else {
+                console.log(chalk.yellow(`No ${opts.status} projects.`));
+            }
+            return;
+        }
+        const activeProjectId = getActiveProjectId();
+        for (const p of data.projects) {
+            const active = p.id === activeProjectId ? chalk.green(' ✓') : '';
+            const status = p.status === 'archived' ? chalk.gray(' [archived]') : '';
+            const activity = p.lastActivityAt
+                ? chalk.gray(` — last active ${formatRelative(new Date(p.lastActivityAt))}`)
+                : '';
+            console.log(`  ${chalk.cyan(p.name)} (${p.slug})${active}${status}${activity}`);
+            if (p.stats) {
+                const stats = [];
+                if (p.stats.activePipelines)
+                    stats.push(`${p.stats.activePipelines} pipelines`);
+                if (p.stats.worksheets)
+                    stats.push(`${p.stats.worksheets} worksheets`);
+                if (p.stats.templates)
+                    stats.push(`${p.stats.templates} templates`);
+                if (stats.length)
+                    console.log(chalk.gray(`      ${stats.join(' · ')}`));
+            }
+        }
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+projects
+    .command('create')
+    .description('Create a new project in the active organization. Owner/admin only. Slug is immutable after creation — pick carefully.')
+    .argument('<slug>', 'URL slug (lowercase letters, numbers, hyphens; 1-32 chars). Used in URLs and CLI config — cannot be changed.')
+    .requiredOption('-n, --name <name>', 'Human-readable name (max 200 chars)')
+    .option('-d, --description <desc>', 'Optional description (max 2000 chars)')
+    .action(async (slug, opts) => {
+    try {
+        const orgId = requireActiveOrgOrExit();
+        const body = {
+            slug,
+            name: opts.name,
+        };
+        if (opts.description)
+            body.description = opts.description;
+        const data = await api('POST', `/api/organizations/${orgId}/projects`, body, { noProjectHeader: true });
+        const p = data.project;
+        console.log(chalk.green(`Created project: ${p.name} (${p.slug})`));
+        console.log(`  ID:    ${p.id}`);
+        console.log(`  Org:   ${orgId}`);
+        if (p.description)
+            console.log(`  Desc:  ${p.description}`);
+        // Invalidate cached /auth/me and set as active — a fresh project is
+        // usually created immediately before scoped work on it, so auto-
+        // switching saves an extra command. Matches the spec's post-create
+        // success path (UX §2.1 toast "You're in.").
+        invalidateAuthMeCache();
+        setActiveProjectId(orgId, p.id);
+        console.log(chalk.cyan(`Switched active project to ${p.slug}.`));
+    }
+    catch (err) {
+        if (err instanceof ApiError && err.code === 'SLUG_CONFLICT') {
+            console.error(chalk.red(`Error: "${slug}" is already taken in this organization.`));
+            console.log(chalk.gray('Pick a different slug or use: fazemos projects list'));
+            process.exit(1);
+        }
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+projects
+    .command('show')
+    .description('Show project details by slug. Resolves against the active organization.')
+    .argument('<slug>', 'Project slug')
+    .action(async (slug) => {
+    try {
+        const orgId = requireActiveOrgOrExit();
+        // Resolve slug -> id via cached /auth/me; refresh once on miss.
+        let project = findProjectBySlug(orgId, slug);
+        if (!project) {
+            await refreshAuthMeCache();
+            project = findProjectBySlug(orgId, slug);
+        }
+        if (!project) {
+            console.error(chalk.red(`Unknown project: ${slug}`));
+            console.log(chalk.gray('Run: fazemos projects list'));
+            process.exit(1);
+        }
+        const data = await api('GET', `/api/organizations/${orgId}/projects/${project.id}`, undefined, { noProjectHeader: true });
+        const p = data.project;
+        console.log(chalk.cyan(p.name));
+        console.log(`  Slug:         ${p.slug}`);
+        console.log(`  ID:           ${p.id}`);
+        console.log(`  Status:       ${p.status === 'archived' ? chalk.gray('archived') : chalk.green('active')}`);
+        if (p.description)
+            console.log(`  Description:  ${p.description}`);
+        console.log(`  Created:      ${p.createdAt ? new Date(p.createdAt).toLocaleString() : '(unknown)'}`);
+        if (p.archivedAt)
+            console.log(`  Archived at:  ${new Date(p.archivedAt).toLocaleString()}`);
+        if (p.stats) {
+            console.log('');
+            console.log(chalk.cyan('Activity:'));
+            console.log(`  Active pipelines: ${p.stats.activePipelines ?? 0}`);
+            console.log(`  Worksheets:       ${p.stats.worksheets ?? 0}`);
+            console.log(`  Templates:        ${p.stats.templates ?? 0}`);
+        }
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+projects
+    .command('switch')
+    .description('Switch active project. Persists in ~/.fazemos/config.json as the active project for the current org.')
+    .argument('<slug>', 'Project slug')
+    .action(async (slug) => {
+    try {
+        const orgId = requireActiveOrgOrExit();
+        let project = findProjectBySlug(orgId, slug);
+        if (!project) {
+            // Slug-miss cache refresh per §8.3.
+            await refreshAuthMeCache();
+            project = findProjectBySlug(orgId, slug);
+        }
+        if (!project) {
+            console.error(chalk.red(`Unknown project: ${slug}`));
+            console.log(chalk.gray('Run: fazemos projects list'));
+            process.exit(1);
+        }
+        setActiveProjectId(orgId, project.id);
+        const org = findOrgById(orgId);
+        const orgName = org?.name ?? orgId;
+        console.log(chalk.green(`Switched to project: ${project.name} (${project.slug}) in ${orgName}`));
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+projects
+    .command('archive')
+    .description('Archive a project. Puts it in read-only mode; existing work is preserved. Owner/admin only. Blocked if any pipeline is currently running — wait for it to finish or cancel it first.')
+    .argument('<slug>', 'Project slug')
+    .action(async (slug) => {
+    try {
+        const orgId = requireActiveOrgOrExit();
+        let project = findProjectBySlug(orgId, slug);
+        if (!project) {
+            await refreshAuthMeCache();
+            project = findProjectBySlug(orgId, slug);
+        }
+        if (!project) {
+            console.error(chalk.red(`Unknown project: ${slug}`));
+            process.exit(1);
+        }
+        const data = await api('POST', `/api/organizations/${orgId}/projects/${project.id}/archive`, {}, { noProjectHeader: true });
+        console.log(chalk.green(`Archived: ${data.project.name} (${data.project.slug})`));
+        invalidateAuthMeCache();
+        // If this was the active project, clear it — subsequent scoped
+        // commands will emit "requirement missing: project" per KD9.
+        if (getActiveProjectId() === project.id) {
+            clearActiveProjectId(orgId);
+            console.log(chalk.cyan('Active project cleared. Run: fazemos projects switch <slug>'));
+        }
+    }
+    catch (err) {
+        if (err instanceof ApiError && err.code === 'PROJECT_HAS_RUNNING_PIPELINES') {
+            console.error(chalk.red(`Can't archive ${slug} yet — pipelines are still running.`));
+            const body = err.body;
+            if (body?.runningPipelines?.length) {
+                console.log('');
+                console.log(chalk.yellow('Running pipelines:'));
+                for (const p of body.runningPipelines) {
+                    console.log(`  · ${p.name} (${p.id})`);
+                }
+            }
+            console.log('');
+            console.log(chalk.gray('Wait for them to finish or cancel them, then retry.'));
+            process.exit(1);
+        }
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+projects
+    .command('unarchive')
+    .description('Restore an archived project to active status. Owner/admin only.')
+    .argument('<slug>', 'Project slug (must be archived)')
+    .action(async (slug) => {
+    try {
+        const orgId = requireActiveOrgOrExit();
+        // Archived projects aren't in the default /auth/me response, so we
+        // can't always resolve via cache. Fall back to the full-status list
+        // endpoint to find the id.
+        let project = findProjectBySlug(orgId, slug);
+        if (!project) {
+            const listData = await api('GET', `/api/organizations/${orgId}/projects?status=all`, undefined, { noProjectHeader: true });
+            const match = (listData.projects ?? []).find((p) => p.slug === slug);
+            if (match) {
+                project = {
+                    id: match.id,
+                    slug: match.slug,
+                    name: match.name,
+                    colorIndex: match.colorIndex ?? 0,
+                    status: match.status,
+                };
+            }
+        }
+        if (!project) {
+            console.error(chalk.red(`Unknown project: ${slug}`));
+            process.exit(1);
+        }
+        const data = await api('POST', `/api/organizations/${orgId}/projects/${project.id}/unarchive`, {}, { noProjectHeader: true });
+        console.log(chalk.green(`Unarchived: ${data.project.name} (${data.project.slug})`));
+        invalidateAuthMeCache();
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+projects
+    .command('update')
+    .description('Update project name or description. Slug is immutable — to use a different slug, create a new project. Owner/admin only.')
+    .argument('<slug>', 'Project slug')
+    .option('-n, --name <name>', 'New name')
+    .option('-d, --description <desc>', 'New description (pass empty string to clear)')
+    .action(async (slug, opts) => {
+    try {
+        if (!opts.name && opts.description == null) {
+            console.error(chalk.red('Provide --name and/or --description'));
+            process.exit(1);
+        }
+        const orgId = requireActiveOrgOrExit();
+        let project = findProjectBySlug(orgId, slug);
+        if (!project) {
+            await refreshAuthMeCache();
+            project = findProjectBySlug(orgId, slug);
+        }
+        if (!project) {
+            console.error(chalk.red(`Unknown project: ${slug}`));
+            process.exit(1);
+        }
+        const body = {};
+        if (opts.name)
+            body.name = opts.name;
+        if (opts.description != null)
+            body.description = opts.description;
+        const data = await api('PATCH', `/api/organizations/${orgId}/projects/${project.id}`, body, { noProjectHeader: true });
+        console.log(chalk.green(`Updated: ${data.project.name} (${data.project.slug})`));
+        invalidateAuthMeCache();
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+// ── F16 — projects set-connection (binds a Connection to a project) ─
+projects
+    .command('set-connection')
+    .description('Bind a GitHub Connection to a project. Pass "none" to unbind. Owner/admin only.')
+    .argument('<slug>', 'Project slug')
+    .argument('<connection>', 'Connection ID, or "none" to unbind')
+    .action(async (slug, connection) => {
+    try {
+        const orgId = requireActiveOrgOrExit();
+        let project = findProjectBySlug(orgId, slug);
+        if (!project) {
+            await refreshAuthMeCache();
+            project = findProjectBySlug(orgId, slug);
+        }
+        if (!project) {
+            console.error(chalk.red(`Unknown project: ${slug}`));
+            console.log(chalk.gray('Run: fazemos projects list'));
+            process.exit(1);
+        }
+        const githubConnectionId = connection === 'none' ? null : connection;
+        const data = await api('PATCH', `/api/organizations/${orgId}/projects/${project.id}`, { githubConnectionId }, { noProjectHeader: true });
+        const p = data.project;
+        if (githubConnectionId === null) {
+            console.log(chalk.green(`✓ ${p.name} (${p.slug}) — GitHub connection cleared`));
+        }
+        else {
+            // The detail endpoint may not return the connection's display
+            // name; show the bound id and let the user run `fazemos
+            // connections show <id>` for full details.
+            console.log(chalk.green(`✓ ${p.name} (${p.slug}) is now using connection ${githubConnectionId}`));
+        }
+        invalidateAuthMeCache();
+    }
+    catch (err) {
+        if (err instanceof ApiError) {
+            if (err.code === 'CONNECTION_NOT_ACTIVE') {
+                const body = (err.body ?? {});
+                const reasonLabel = body.reason ?? 'not active';
+                console.error(chalk.red(`Connection is ${reasonLabel} and can't be bound to a project.`));
+                console.log(chalk.gray('Pick a different connection: fazemos connections list'));
+                process.exit(1);
+            }
+            if (err.code === 'CONNECTION_NOT_FOUND') {
+                console.error(chalk.red('Connection not found.'));
+                console.log(chalk.gray('List your connections: fazemos connections list'));
+                process.exit(1);
+            }
+            if (err.code === 'CONNECTION_CROSS_ORG') {
+                console.error(chalk.red("That connection belongs to a different organization."));
+                process.exit(1);
+            }
+        }
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+// ── F16 — Connections ───────────────────────────────────────
+const connections = program.command('connections').alias('conn').description('GitHub Connection commands');
+/**
+ * `fazemos connections list` — list active+pending Connections in the
+ * active Org. Output is tabular per Sage UX §8.3.
+ */
+connections
+    .command('list')
+    .description('List GitHub Connections 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 ?? [];
+        if (list.length === 0) {
+            const orgName = findOrgById(orgId)?.name ?? orgId;
+            console.log(chalk.yellow(`No GitHub 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('');
+        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)}`);
+            console.log(chalk.gray(`    ID: ${c.id}`));
+        }
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+/**
+ * `fazemos connections show <id>` — full detail including repos and
+ * bound projects.
+ */
+connections
+    .command('show')
+    .description('Show a GitHub 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));
+        console.log(`  ID:           ${c.id}`);
+        console.log(`  GitHub:       ${c.githubAccountLogin ?? chalk.gray('— (pending)')}`);
+        if (c.githubAccountType)
+            console.log(`  Account type: ${c.githubAccountType}`);
+        const statusColor = pickStatusColor(c.status);
+        console.log(`  Status:       ${statusColor(c.status)}`);
+        console.log(`  Installed:    ${c.installedAt ? new Date(c.installedAt).toLocaleString() : '(unknown)'}`);
+        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}` : ''}`);
+        }
+        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}`));
+            }
+        }
+        if (Array.isArray(c.boundProjects) && c.boundProjects.length > 0) {
+            console.log('');
+            console.log(chalk.cyan('Projects using this connection:'));
+            for (const p of c.boundProjects) {
+                console.log(`  · ${p.name} (${p.slug})`);
+            }
+        }
+    }
+    catch (err) {
+        if (err instanceof ApiError && err.code === 'CONNECTION_NOT_FOUND') {
+            console.error(chalk.red('Connection not found.'));
+            console.log(chalk.gray('List your connections: fazemos connections list'));
+            process.exit(1);
+        }
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+/**
+ * `fazemos connections install` — print-URL + confirmation-code flow per
+ * Sage UX §8.1. Two API calls: mint URL → exchange code.
+ */
+connections
+    .command('install')
+    .description('Add a GitHub Connection. Prints an install URL and waits for a confirmation code.')
+    .action(async () => {
+    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 });
+        console.log('');
+        console.log(`To add a GitHub connection to ${chalk.cyan(orgName)}:`);
+        console.log('');
+        console.log('  1. Open this URL in your browser (expires in 10 minutes):');
+        console.log(`     ${chalk.cyan(mintData.url)}`);
+        console.log('');
+        console.log('  2. Install the Fazemos App on your GitHub org or account.');
+        console.log('');
+        console.log('  3. After installing, you\'ll see a confirmation code on the page.');
+        console.log('     Paste it here:');
+        console.log('');
+        const code = await promptLine('  Code: ');
+        if (!code) {
+            console.error(chalk.red('No code provided. Aborted.'));
+            process.exit(1);
+        }
+        try {
+            const exchangeData = await api('POST', '/api/github/connections/exchange-code', { code: code.trim() }, { noProjectHeader: true });
+            const c = exchangeData.connection;
+            console.log('');
+            console.log(chalk.green(`  ✓ Connected: ${c.name}${c.githubAccountLogin ? ` (${c.githubAccountLogin})` : ''}`));
+            if (c.repositorySelection === 'all') {
+                console.log(chalk.gray(`    Repos: All repositories${c.githubAccountLogin ? ` in ${c.githubAccountLogin}` : ''}`));
+            }
+            console.log(chalk.gray(`    Connection ID: ${c.id}`));
+            console.log('');
+            console.log(chalk.gray('  To use this in a project:'));
+            console.log(chalk.gray(`    fazemos projects set-connection <project-slug> ${c.id}`));
+            invalidateAuthMeCache();
+        }
+        catch (err) {
+            if (err instanceof ApiError) {
+                if (err.code === 'CODE_EXPIRED') {
+                    console.error(chalk.red('  ✗ That code expired. Codes are valid for 10 minutes.'));
+                    console.log(chalk.gray('    Try again: fazemos connections install'));
+                    process.exit(1);
+                }
+                if (err.code === 'CODE_ALREADY_USED') {
+                    console.error(chalk.red('  ✗ That code was already used.'));
+                    console.log(chalk.gray('    Start over: fazemos connections install'));
+                    process.exit(1);
+                }
+                if (err.code === 'CODE_NOT_FOUND') {
+                    console.error(chalk.red('  ✗ That code didn\'t match.'));
+                    console.log(chalk.gray('    Double-check it or start over: fazemos connections install'));
+                    process.exit(1);
+                }
+                if (err.code === 'CODE_WRONG_USER') {
+                    console.error(chalk.red('  ✗ That code was generated by a different user.'));
+                    console.log(chalk.gray('    Start over: fazemos connections install'));
+                    process.exit(1);
+                }
+                if (err.code === 'CODE_INVALID') {
+                    console.error(chalk.red('  ✗ That code doesn\'t look right.'));
+                    console.log(chalk.gray('    Start over: fazemos connections install'));
+                    process.exit(1);
+                }
+                if (err.code === 'CODE_RATE_LIMITED') {
+                    const body = (err.body ?? {});
+                    const after = body.retryAfter ? `${body.retryAfter}s` : '60s';
+                    console.error(chalk.red(`  ✗ Too many code attempts. Try again in ${after}.`));
+                    process.exit(1);
+                }
+            }
+            throw err;
+        }
+    }
+    catch (err) {
+        if (err instanceof ApiError && err.code === 'MISSING_GITHUB_CONFIG') {
+            console.error(chalk.red('GitHub App is not configured on this server.'));
+            console.log(chalk.gray('Contact your Fazemos operator.'));
+            process.exit(1);
+        }
+        if (err instanceof ApiError && err.code === 'FORBIDDEN_ROLE') {
+            console.error(chalk.red('Only org owners and admins can add GitHub connections.'));
+            process.exit(1);
+        }
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+/**
+ * `fazemos connections revoke <id>` — disconnect with confirmation
+ * prompt. `--force` skips the prompt for scripted use.
+ */
+connections
+    .command('revoke')
+    .alias('disconnect')
+    .description('Disconnect a GitHub Connection (Fazemos-side; does not uninstall the App from GitHub).')
+    .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;
+        try {
+            const detail = await api('GET', `/api/organizations/${orgId}/github/connections/${id}`, undefined, { noProjectHeader: true });
+            connection = detail.connection;
+        }
+        catch (err) {
+            if (err instanceof ApiError && err.code === 'CONNECTION_NOT_FOUND') {
+                console.error(chalk.red('Connection not found.'));
+                process.exit(1);
+            }
+            throw err;
+        }
+        const boundProjects = connection.boundProjects ?? [];
+        if (!opts.force) {
+            console.log('');
+            console.log(`Disconnect ${chalk.cyan(connection.name)}?`);
+            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('  they are bound to a different connection.');
+                console.log('');
+            }
+            else {
+                console.log('  No projects are using this connection.');
+                console.log('');
+            }
+            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())) {
+                console.log(chalk.gray('Cancelled.'));
+                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.`));
+        }
+        invalidateAuthMeCache();
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+/**
+ * `fazemos connections health-check <id>` — manually verify with
+ * GitHub. Updates status and last_health_check_at.
+ */
+connections
+    .command('health-check')
+    .description('Verify a Connection is still healthy on GitHub')
+    .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;
+        const statusColor = pickStatusColor(c.status);
+        if (data.changed) {
+            console.log(chalk.yellow(`Status changed: ${c.name} → ${statusColor(c.status)}`));
+        }
+        else {
+            console.log(chalk.green(`✓ ${c.name} — ${statusColor(c.status)}`));
+        }
+    }
+    catch (err) {
+        if (err instanceof ApiError && err.code === 'CONNECTION_NOT_FOUND') {
+            console.error(chalk.red('Connection not found.'));
+            process.exit(1);
+        }
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+/**
+ * Helper — color a status string per the Sage §2.2 taxonomy.
+ */
+function pickStatusColor(status) {
+    switch (status) {
+        case 'active':
+            return chalk.green;
+        case 'pending':
+            return chalk.yellow;
+        case 'suspended':
+            return chalk.yellow;
+        case 'uninstalled':
+            return chalk.red;
+        case 'revoked':
+            return chalk.gray;
+        default:
+            return chalk.white;
+    }
+}
+/**
+ * Read a single line of input from stdin. No fancy framing — `readline`
+ * is sufficient for the install confirmation-code prompt and the
+ * revoke yes/no.
+ */
+async function promptLine(prompt) {
+    const readline = await import('readline');
+    return new Promise((resolve) => {
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        rl.question(prompt, (answer) => {
+            rl.close();
+            resolve(answer);
+        });
+    });
+}
 // ── Worksheets ──────────────────────────────────────────────
 const ws = program.command('worksheets').alias('ws').description('Worksheet commands');
 ws
     .command('list')
-    .description('List worksheets')
+    .description('List worksheets in the active project (or all projects with --all-projects)')
     .option('-s, --status <status>', 'Filter by status', 'active')
+    .option('--project <slug>', 'Override active project for this call')
+    .option('--all-projects', 'List worksheets across every project in the active org', false)
     .action(async (opts) => {
     try {
-        const data = await api('GET', `/api/worksheets?status=${opts.status}`);
+        const data = await api('GET', `/api/worksheets?status=${opts.status}`, undefined, projectOpts(opts));
         if (data.worksheets.length === 0) {
             console.log(chalk.yellow('No worksheets'));
             return;
@@ -866,16 +1639,16 @@ ws
         }
     }
     catch (err) {
-        console.error(chalk.red(err.message));
-        process.exit(1);
+        handleScopedError(err);
     }
 });
 ws
     .command('create')
-    .description('Create a worksheet')
+    .description('Create a worksheet in the active project')
     .requiredOption('-n, --name <name>', 'Worksheet name')
     .option('-p, --purpose <purpose>', 'Purpose (e.g., "From X to Y by When")')
     .option('--cadence <cadence>', 'Check-in cadence (weekly, biweekly, monthly)', 'weekly')
+    .option('--project <slug>', 'Override active project for this call')
     .action(async (opts) => {
     try {
         const body = { name: opts.name };
@@ -883,7 +1656,7 @@ ws
             body.purpose = opts.purpose;
         if (opts.cadence)
             body.checkInCadence = opts.cadence;
-        const data = await api('POST', '/api/worksheets', body);
+        const data = await api('POST', '/api/worksheets', body, projectOpts(opts));
         const w = data.worksheet;
         console.log(chalk.green(`Created: ${w.name}`));
         console.log(`  ID:      ${w.id}`);
@@ -891,8 +1664,7 @@ ws
         console.log(`  Cadence: ${w.check_in_cadence}`);
     }
     catch (err) {
-        console.error(chalk.red(err.message));
-        process.exit(1);
+        handleScopedError(err);
     }
 });
 ws
@@ -1960,12 +2732,14 @@ const templates = program.command('templates').alias('tpl').description('Pipelin
     '  Use "tpl show <id>" to see full structure with I/O declarations.');
 templates
     .command('list')
-    .description('List pipeline templates')
+    .description('List pipeline templates in the active project (or all projects with --all-projects)')
     .option('-s, --status <status>', 'Filter by status (draft, active, archived)')
+    .option('--project <slug>', 'Override active project for this call')
+    .option('--all-projects', 'List templates across every project in the active org', false)
     .action(async (opts) => {
     try {
         const qs = opts.status ? `?status=${opts.status}` : '';
-        const data = await api('GET', `/api/pipeline-templates${qs}`);
+        const data = await api('GET', `/api/pipeline-templates${qs}`, undefined, projectOpts(opts));
         if (!data.templates?.length) {
             console.log(chalk.yellow('No templates'));
             return;
@@ -1977,8 +2751,7 @@ templates
         }
     }
     catch (err) {
-        console.error(chalk.red(err.message));
-        process.exit(1);
+        handleScopedError(err);
     }
 });
 templates
@@ -3086,10 +3859,12 @@ templates
 const pipelines = program.command('pipelines').alias('pl').description('Pipeline instance commands');
 pipelines
     .command('list')
-    .description('List pipeline instances')
+    .description('List pipeline instances in the active project (or all projects with --all-projects)')
     .option('-s, --status <status>', 'Filter by status (active, completed, archived)', 'active')
     .option('--search <term>', 'Search by name or ID')
     .option('--expand', 'Include steps inline (avoids N+1)')
+    .option('--project <slug>', 'Override active project for this call')
+    .option('--all-projects', 'List pipelines across every project in the active org', false)
     .action(async (opts) => {
     try {
         const params = [];
@@ -3100,7 +3875,7 @@ pipelines
         if (opts.expand)
             params.push('expand=steps');
         const qs = params.length ? `?${params.join('&')}` : '';
-        const data = await api('GET', `/api/pipeline-instances${qs}`);
+        const data = await api('GET', `/api/pipeline-instances${qs}`, undefined, projectOpts(opts));
         if (!data.instances?.length) {
             console.log(chalk.yellow('No pipeline instances'));
             return;
@@ -3121,8 +3896,7 @@ pipelines
         }
     }
     catch (err) {
-        console.error(chalk.red(err.message));
-        process.exit(1);
+        handleScopedError(err);
     }
 });
 pipelines
@@ -3172,6 +3946,24 @@ pipelines
         console.log(`  ID: ${inst.id}`);
     }
     catch (err) {
+        // F16 — Role-aware Connection-unavailable error (tech spec §5.14).
+        // The pipeline-run path returns a structured payload when the
+        // Project's Connection is missing/revoked/suspended/uninstalled.
+        // Branch copy on the caller's role from the cached /auth/me; admin
+        // sees a settings URL, member sees "Ask your admin" without one.
+        if (err instanceof ApiError && isProjectConnectionUnavailable(err.body)) {
+            const role = resolveActiveOrgRole();
+            const lines = renderProjectConnectionUnavailableCopy(err.body, role);
+            console.error('');
+            console.error(chalk.red(lines.title));
+            if (lines.body)
+                console.error(chalk.gray(lines.body));
+            if (lines.ctaUrl) {
+                console.error('');
+                console.error(chalk.gray(`  ${lines.ctaUrl}`));
+            }
+            process.exit(1);
+        }
         console.error(chalk.red(err.message));
         process.exit(1);
     }
@@ -3613,10 +4405,12 @@ step
 const queue = program.command('queue').alias('q').description('Work queue commands');
 queue
     .command('summary')
-    .description('Show queue depth per agent')
-    .action(async () => {
+    .description('Show queue depth per agent, scoped to the active project (or all projects with --all-projects)')
+    .option('--project <slug>', 'Override active project for this call')
+    .option('--all-projects', 'Show queue across every project in the active org', false)
+    .action(async (opts) => {
     try {
-        const data = await api('GET', '/api/work-queue/summary');
+        const data = await api('GET', '/api/work-queue/summary', undefined, projectOpts(opts));
         const entries = Object.entries(data.depths ?? {});
         if (entries.length === 0) {
             console.log(chalk.yellow('No agents in queue'));
@@ -3631,15 +4425,16 @@ queue
         console.log(`  ${'Total'.padEnd(12)} ${total} steps`);
     }
     catch (err) {
-        console.error(chalk.red(err.message));
-        process.exit(1);
+        handleScopedError(err);
     }
 });
 queue
     .command('list')
-    .description('List queued and in-progress steps')
+    .description('List queued and in-progress steps in the active project (or all projects with --all-projects)')
     .option('-a, --agent <name>', 'Filter by agent name')
     .option('--message-id <id>', 'Filter by JOE messageId in step metadata')
+    .option('--project <slug>', 'Override active project for this call')
+    .option('--all-projects', 'List queue items across every project in the active org', false)
     .action(async (opts) => {
     try {
         const params = [];
@@ -3648,7 +4443,7 @@ queue
         if (opts.messageId)
             params.push(`messageId=${encodeURIComponent(opts.messageId)}`);
         const qs = params.length ? `?${params.join('&')}` : '';
-        const data = await api('GET', `/api/work-queue${qs}`);
+        const data = await api('GET', `/api/work-queue${qs}`, undefined, projectOpts(opts));
         if (!data.items?.length) {
             console.log(chalk.yellow('No queued steps'));
             return;
@@ -3660,8 +4455,7 @@ queue
         }
     }
     catch (err) {
-        console.error(chalk.red(err.message));
-        process.exit(1);
+        handleScopedError(err);
     }
 });
 // ── Executions ─────────────────────────────────────────────
@@ -3773,6 +4567,22 @@ program
         console.log(`  Status: ${exec.status}`);
     }
     catch (err) {
+        // F16 — Same role-aware Connection-unavailable handling as `pl
+        // create` (tech spec §5.14). The launcher rejects executions when
+        // the Project's Connection is missing/unhealthy.
+        if (err instanceof ApiError && isProjectConnectionUnavailable(err.body)) {
+            const role = resolveActiveOrgRole();
+            const lines = renderProjectConnectionUnavailableCopy(err.body, role);
+            console.error('');
+            console.error(chalk.red(lines.title));
+            if (lines.body)
+                console.error(chalk.gray(lines.body));
+            if (lines.ctaUrl) {
+                console.error('');
+                console.error(chalk.gray(`  ${lines.ctaUrl}`));
+            }
+            process.exit(1);
+        }
         console.error(chalk.red(err.message));
         process.exit(1);
     }
@@ -4155,10 +4965,12 @@ executions
 // ── My Work ─────────────────────────────────────────────────
 program
     .command('my-work')
-    .description('Show pending work across all worksheets')
-    .action(async () => {
+    .description('Show pending work in the active project (or all projects with --all-projects)')
+    .option('--project <slug>', 'Override active project for this call')
+    .option('--all-projects', 'Show pending work across every project in the active org', false)
+    .action(async (opts) => {
     try {
-        const data = await api('GET', '/api/my-work');
+        const data = await api('GET', '/api/my-work', undefined, projectOpts(opts));
         const c = data.commitments;
         const total = c.overdue.length + c.due_today.length + c.due_this_week.length + c.upcoming.length;
         console.log(chalk.cyan(`Commitments: ${total}`));
@@ -4175,8 +4987,7 @@ program
         console.log(chalk.cyan(`Pipeline steps: ${data.pipeline_steps.length}`));
     }
     catch (err) {
-        console.error(chalk.red(err.message));
-        process.exit(1);
+        handleScopedError(err);
     }
 });
 // ── Test ────────────────────────────────────────────────────