@formigio/fazemos-cli 0.7.0 → 0.8.0

package/dist/connectionErrorCopy.d.ts

@@ -0,0 +1,46 @@
+/**
+ * F16 — Role-aware copy for the `PROJECT_CONNECTION_UNAVAILABLE`
+ * structured error (tech spec §5.14).
+ *
+ * Mirrors the web's `renderProjectConnectionUnavailableCopy` so admin
+ * and member experiences stay consistent across surfaces. CLI variant
+ * adds the settings URL as a trailing line for admins; members see
+ * "Ask your admin" without a URL.
+ *
+ * The `getEnv()` helper supplies the web origin so we can construct
+ * fully-qualified URLs the user can click in the terminal.
+ */
+/**
+ * Structured payload returned by pipeline-run endpoints when the
+ * Project's Connection is missing/revoked/suspended/uninstalled.
+ * Matches the contract in tech spec §5.14.
+ */
+export interface ProjectConnectionUnavailableErrorBody {
+    error: 'project_connection_unavailable';
+    code: 'PROJECT_CONNECTION_UNAVAILABLE';
+    reason: 'missing' | 'revoked' | 'suspended' | 'uninstalled';
+    orgId: string;
+    orgSlug: string;
+    projectId: string;
+    projectSlug: string;
+    connectionId: string | null;
+}
+export interface ConnectionErrorLines {
+    /** Lead headline. */
+    title: string;
+    /** Body explanation. */
+    body: string;
+    /** Optional fully-qualified URL line, only set for admin role. */
+    ctaUrl?: string;
+}
+/**
+ * Type guard — narrow `ApiError.body` (or any unknown payload) to the
+ * structured shape so callers can render copy.
+ */
+export declare function isProjectConnectionUnavailable(body: unknown): body is ProjectConnectionUnavailableErrorBody;
+/**
+ * Produce the role-aware lines for terminal rendering. Caller decides
+ * how to color / format. The shape is plain so a JSON test fixture
+ * stays readable.
+ */
+export declare function renderProjectConnectionUnavailableCopy(error: Pick<ProjectConnectionUnavailableErrorBody, 'reason' | 'orgSlug' | 'connectionId'>, role: 'owner' | 'admin' | 'member' | string): ConnectionErrorLines;

package/dist/connectionErrorCopy.js

@@ -0,0 +1,102 @@
+/**
+ * F16 — Role-aware copy for the `PROJECT_CONNECTION_UNAVAILABLE`
+ * structured error (tech spec §5.14).
+ *
+ * Mirrors the web's `renderProjectConnectionUnavailableCopy` so admin
+ * and member experiences stay consistent across surfaces. CLI variant
+ * adds the settings URL as a trailing line for admins; members see
+ * "Ask your admin" without a URL.
+ *
+ * The `getEnv()` helper supplies the web origin so we can construct
+ * fully-qualified URLs the user can click in the terminal.
+ */
+import { getEnv } from './config.js';
+/**
+ * Type guard — narrow `ApiError.body` (or any unknown payload) to the
+ * structured shape so callers can render copy.
+ */
+export function isProjectConnectionUnavailable(body) {
+    if (!body || typeof body !== 'object')
+        return false;
+    const b = body;
+    return (b.code === 'PROJECT_CONNECTION_UNAVAILABLE' &&
+        typeof b.reason === 'string' &&
+        ['missing', 'revoked', 'suspended', 'uninstalled'].includes(b.reason) &&
+        typeof b.orgSlug === 'string' &&
+        typeof b.projectSlug === 'string');
+}
+/**
+ * Resolve the web origin (where the settings URLs live). The CLI's
+ * `env` config holds an `apiUrl` like `https://api.fazemos.../api`.
+ * The web origin is conventionally the same host minus `api`. For
+ * local dev (`http://localhost:8080`) we point at the dev web URL.
+ *
+ * Conservative behavior: if we can't derive cleanly, render the path
+ * without an origin (the user can still see what to do).
+ */
+function deriveWebOrigin() {
+    try {
+        const env = getEnv();
+        // Prod: api.fazemos.journeyjuntos.com → fazemos.journeyjuntos.com
+        // Dev:  api.fazemos-dev.journeyjuntos.com → fazemos-dev.journeyjuntos.com
+        // Local: http://localhost:8080 → http://localhost:5173
+        const apiUrl = env.apiUrl;
+        if (!apiUrl)
+            return null;
+        // Local — vite dev port for the web app.
+        if (apiUrl.includes('localhost') || apiUrl.includes('127.0.0.1')) {
+            return 'http://localhost:5173';
+        }
+        // Strip a leading `api.` if present in the host.
+        const url = new URL(apiUrl);
+        const host = url.host.replace(/^api\./, '');
+        return `${url.protocol}//${host}`;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Produce the role-aware lines for terminal rendering. Caller decides
+ * how to color / format. The shape is plain so a JSON test fixture
+ * stays readable.
+ */
+export function renderProjectConnectionUnavailableCopy(error, role) {
+    const isAdmin = role === 'owner' || role === 'admin';
+    const origin = deriveWebOrigin();
+    const settingsPath = error.connectionId
+        ? `/org/${error.orgSlug}/settings/connections/${error.connectionId}`
+        : `/org/${error.orgSlug}/settings/connections`;
+    const ctaUrl = origin ? `${origin}${settingsPath}` : settingsPath;
+    if (error.reason === 'missing') {
+        return isAdmin
+            ? {
+                title: 'Connect GitHub to run this pipeline.',
+                body: 'This project needs a GitHub connection to clone its repos.',
+                ctaUrl,
+            }
+            : {
+                title: 'This project needs a GitHub connection.',
+                body: 'Ask your admin to add one in Project Settings.',
+            };
+    }
+    if (error.reason === 'revoked' ||
+        error.reason === 'uninstalled' ||
+        error.reason === 'suspended') {
+        return isAdmin
+            ? {
+                title: `GitHub connection ${error.reason}.`,
+                body: 'New pipeline steps that need GitHub will fail until the project is bound to a different connection.',
+                ctaUrl,
+            }
+            : {
+                title: 'This project needs a GitHub connection.',
+                body: 'Ask your admin — the existing connection is not usable.',
+            };
+    }
+    return {
+        title: 'GitHub connection is unavailable.',
+        body: '',
+    };
+}
+//# sourceMappingURL=connectionErrorCopy.js.map

package/dist/connectionErrorCopy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connectionErrorCopy.js","sourceRoot":"","sources":["../src/connectionErrorCopy.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -6,6 +6,7 @@ import { config, getEnv, getToken, getActiveOrgId, setActiveOrgId, addEnvironmen
 getActiveProjectId, setActiveProjectId, clearActiveProjectId, findProjectBySlug, findProjectById, findOrgById, } from './config.js';
 import { login, signup, confirmSignup, adminLogin } from './auth.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';
@@ -799,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)')
@@ -1230,6 +1251,374 @@ projects
         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
@@ -3557,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);
     }
@@ -4160,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);
     }