@formigio/fazemos-cli 0.10.66 → 0.10.74

package/dist/commands/preflight.js

@@ -0,0 +1,706 @@
+/**
+ * F53 — `fazemos agents preflight <target>`
+ *
+ * 6-row PASS/FAIL/SKIP/TOOLING-ERROR/XWS_DEFERRED verifier for agent provisioning.
+ * Non-zero exit on FAIL (1), TOOLING-ERROR (2), or XWS_DEFERRED (3).
+ *
+ * Target forms:
+ *   <org>/<project>/<role>  — single project row-set
+ *   <org>/<project>         — fan-out all declared roles for a project
+ *   <org>/<role>            — fan-out all declared projects for a role
+ *
+ * Spec: projects/fazemos/specs/tech/platform/F53-agent-provision-tooling-tech-spec.md
+ */
+import chalk from 'chalk';
+import { api, resolveOrgIdMaybeSlug } from '../api.js';
+import { findLocalRegistry } from '../dispatch.js';
+import { getEnv } from '../config.js';
+import { checkGhAvailable, getWorkspaceGitHubRepo, listDirectoryFilenamesOnGitHub, } from '../preflight/repoRead.js';
+import { loadRoster, classifyRoleForProject, getProjectsForRole, getRolesForProject, RosterLoadError, } from '../preflight/roster.js';
+import { checkRow1Member } from '../preflight/row1_member.js';
+import { checkRow2RoleRegistration } from '../preflight/row2_roleRegistration.js';
+import { checkRow3aPersona } from '../preflight/row3_persona.js';
+import { checkRow3bPlaybook } from '../preflight/row3_playbook.js';
+import { checkRow3cRolesJson } from '../preflight/row3_rolesJson.js';
+import { checkRow4Ssm } from '../preflight/row4_ssm.js';
+import { checkRow5WorkerLambdaWakeConfig } from '../preflight/row5_workerLambdaWakeConfig.js';
+import { checkRow6Ingest } from '../preflight/row6_ingest.js';
+import { summarizeRows, computeExitCode, mergeExitCodes, } from '../preflight/schema.js';
+// ── Target parsing ─────────────────────────────────────────────────────────────
+/**
+ * Parse <target> into its components.
+ * Disambiguation of 2-segment form uses the roster:
+ *   - If segment[1] matches a role_slug in the roster → fan-out-role
+ *   - Otherwise → fan-out-project
+ */
+export function parseTarget(target, roster) {
+    const parts = target.split('/');
+    if (parts.length === 3) {
+        return {
+            form: 'single',
+            orgSlug: parts[0],
+            projectSlug: parts[1],
+            roleSlug: parts[2],
+        };
+    }
+    if (parts.length === 2) {
+        const orgSlug = parts[0];
+        const second = parts[1];
+        // Disambiguate: is the second segment a role slug or a project slug?
+        if (roster) {
+            const allRoles = new Set([
+                ...roster.declared_here.map((e) => e.role_slug),
+                ...roster.declared_cross_workspace.map((e) => e.role_slug),
+            ]);
+            if (allRoles.has(second)) {
+                return { form: 'fan-out-role', orgSlug, roleSlug: second };
+            }
+        }
+        // Default: treat as <org>/<project>
+        return { form: 'fan-out-project', orgSlug, projectSlug: second };
+    }
+    return null;
+}
+// ── Playbook pre-fetch (shared data for rows 3b and 4c) ───────────────────────
+/**
+ * Pre-fetch the playbook-*.md filenames for a role from the workspace GitHub repo.
+ *
+ * Row 4c needs this to classify SKIP vs FAIL when the role is absent from the
+ * triggers allowlist — symmetric with row 3b receiving `triggersAllowlist` from row 4c.
+ * Both rows read both inputs; neither verdict depends on the other's verdict.
+ *
+ * Returns:
+ *   string[]       — playbook-*.md files found (may be empty if none / dir missing)
+ *   'unavailable'  — gh CLI not installed, not authenticated, or workspace not on GitHub
+ */
+function fetchPlaybookFilesForRole(workspaceRoot, roleSlug, roleEntry) {
+    try {
+        checkGhAvailable();
+        const repoRef = getWorkspaceGitHubRepo(workspaceRoot);
+        if (!repoRef)
+            return 'unavailable';
+        // Derive role directory path (mirrors deriveRoleDir in row3_playbook.ts).
+        let roleDir;
+        if (roleEntry?.inbox) {
+            const trimmed = roleEntry.inbox.replace(/\/+$/, '');
+            const parts = trimmed.split('/');
+            roleDir = parts[parts.length - 1] === 'inbox'
+                ? parts.slice(0, -1).join('/')
+                : trimmed;
+        }
+        else {
+            roleDir = `roles/${roleSlug}`;
+        }
+        const files = listDirectoryFilenamesOnGitHub(repoRef, roleDir);
+        if (files === null)
+            return []; // directory absent → no playbooks
+        return files.filter((f) => /^playbook-.+\.md$/.test(f));
+    }
+    catch {
+        return 'unavailable';
+    }
+}
+async function runRowSet(opts) {
+    const { orgId, orgSlug, projectId, projectSlug, roleSlug, agentName, workspace, workspaceRoot, registry, env, region, } = opts;
+    const roleEntry = registry?.roles[roleSlug];
+    // r3.3: Pre-fetch playbook files (sync via gh CLI) so row 4c can classify SKIP vs FAIL
+    // for dispatch-driven roles — symmetric with row 3b receiving triggersAllowlist from row 4c.
+    // Both rows receive both data inputs; neither verdict depends on the other row's verdict.
+    const playbookFiles = fetchPlaybookFilesForRole(workspaceRoot, roleSlug, roleEntry);
+    // r3.2: Run row 4 first so row 3b can reuse the SSM triggers allowlist
+    // without a second SSM call (rul_f53_row3b_classifies_by_cadence_signal).
+    const { rows: rows4, triggersAllowlist } = await checkRow4Ssm({
+        env, agentName, roleSlug, region,
+        playbookFiles, // r3.3: row 4c uses this to classify SKIP vs FAIL
+    });
+    // Run remaining rows in parallel, passing SSM context to row 3b.
+    const [row1, row2, row3a, row3b, row3c, row5, rows6] = await Promise.all([
+        checkRow1Member(orgId, agentName, roleSlug),
+        checkRow2RoleRegistration({
+            workspace,
+            roleSlug,
+            orgId,
+            projectId,
+            orgSlug,
+            projectSlug,
+            env,
+        }),
+        checkRow3aPersona({ agentName, orgId, projectId }),
+        checkRow3bPlaybook({
+            workspaceRoot,
+            roleSlug,
+            roleEntry,
+            ssmContext: { triggers_allowlist: triggersAllowlist },
+        }),
+        Promise.resolve(checkRow3cRolesJson({ roleSlug, registry })),
+        checkRow5WorkerLambdaWakeConfig({ env, region }),
+        checkRow6Ingest({ orgId, projectId, projectSlug }),
+    ]);
+    return [row1, row2, row3a, row3b, row3c, ...rows4, row5, ...rows6];
+}
+// ── Human rendering ────────────────────────────────────────────────────────────
+function statusIcon(status) {
+    switch (status) {
+        case 'pass': return chalk.green('✓ PASS');
+        case 'fail': return chalk.red('✗ FAIL');
+        case 'skip': return chalk.gray('⊘ SKIP');
+        case 'tooling_error': return chalk.yellow('? TOOLING-ERROR');
+        case 'xws_deferred': return chalk.cyan('⌛ XWS_DEFERRED');
+        case 'indeterminate': return chalk.magenta('⚠ INDETERMINATE');
+        default: return String(status).toUpperCase();
+    }
+}
+function renderRows(rows) {
+    for (const row of rows) {
+        const icon = statusIcon(row.status);
+        console.log(`  ${icon}  [${row.id}] ${row.name}`);
+        console.log(`         ${chalk.gray(row.detail)}`);
+        if (row.fix_command) {
+            console.log(`         ${chalk.yellow('fix:')} ${row.fix_command}`);
+        }
+        else if (row.fix_instruction) {
+            console.log(`         ${chalk.yellow('fix:')} ${row.fix_instruction}`);
+        }
+        // Row 5 enumeration note
+        if (row.enumerated) {
+            console.log(chalk.gray(`         (${row.enumerated.count} worker(s), last audited ${row.enumerated.last_audited})`));
+        }
+    }
+}
+function renderSummary(summary) {
+    const parts = [`${summary.pass} PASS`, `${summary.fail} FAIL`, `${summary.skip} SKIP`];
+    if (summary.tooling_error > 0)
+        parts.push(`${summary.tooling_error} TOOLING-ERROR`);
+    if (summary.xws_deferred > 0)
+        parts.push(`${summary.xws_deferred} XWS_DEFERRED`);
+    if (summary.indeterminate > 0)
+        parts.push(`${summary.indeterminate} INDETERMINATE`);
+    return parts.join(', ');
+}
+function renderXwsDeferred(xws) {
+    console.log(chalk.cyan(`⌛ XWS_DEFERRED  ${xws.role_slug}: declared cross-workspace; verify from the owning workspace.`));
+    console.log(`  ${chalk.yellow('fix:')} ${xws.fix_instruction}`);
+}
+// ── Org/project resolution helpers ────────────────────────────────────────────
+async function resolveOrgAndProjects(orgSlug) {
+    const orgId = await resolveOrgIdMaybeSlug(orgSlug);
+    const data = (await api('GET', `/api/organizations/${orgId}/projects?status=active`, undefined, { noProjectHeader: true }));
+    return { orgId, projects: data.projects ?? [] };
+}
+async function resolveProject(orgId, orgSlug, projectSlug) {
+    const data = (await api('GET', `/api/organizations/${orgId}/projects?status=active`, undefined, { noProjectHeader: true }));
+    const project = (data.projects ?? []).find((p) => p.slug === projectSlug);
+    if (!project) {
+        throw new Error(`Project '${projectSlug}' not found in org '${orgSlug}'.`);
+    }
+    return project;
+}
+// ── Main preflight runner ──────────────────────────────────────────────────────
+export async function runPreflight(target, opts) {
+    const envConfig = getEnv();
+    const envName = opts.env ?? envConfig.name;
+    // ── Find workspace root + load roster ────────────────────────────────────
+    const startDir = opts.workspace ?? process.cwd();
+    const registry = findLocalRegistry(startDir);
+    if (!registry) {
+        const msg = 'No .fazemos/roles.json found in cwd or any parent. ' +
+            'Run from inside a workspace repo or specify --workspace <path>.';
+        if (opts.json) {
+            process.stdout.write(JSON.stringify({
+                schema_version: '1.2',
+                target,
+                env: envName,
+                exit_code: 2,
+                error: msg,
+            }) + '\n');
+        }
+        else {
+            console.error(chalk.red(`⚠ TOOLING-ERROR: ${msg}`));
+        }
+        return 2;
+    }
+    let roster;
+    try {
+        roster = loadRoster(registry._workspaceRoot, registry);
+    }
+    catch (err) {
+        const msg = err instanceof RosterLoadError ? err.message : String(err);
+        if (opts.json) {
+            process.stdout.write(JSON.stringify({ schema_version: '1.2', target, env: envName, exit_code: 2, error: msg }) + '\n');
+        }
+        else {
+            console.error(chalk.red(`⚠ TOOLING-ERROR: ${msg}`));
+        }
+        return 2;
+    }
+    // ── Parse target ─────────────────────────────────────────────────────────
+    const parsed = parseTarget(target, roster);
+    if (!parsed) {
+        const msg = `Invalid target '${target}'. Use <org>/<project>/<role>, <org>/<project>, or <org>/<role>.`;
+        if (opts.json) {
+            process.stdout.write(JSON.stringify({ schema_version: '1.2', target, env: envName, exit_code: 2, error: msg }) + '\n');
+        }
+        else {
+            console.error(chalk.red(msg));
+        }
+        return 2;
+    }
+    // ── Dispatch to the right form ────────────────────────────────────────────
+    if (parsed.form === 'single') {
+        return runSingleProject(parsed, registry, roster, opts, envName);
+    }
+    if (parsed.form === 'fan-out-role') {
+        return runFanOutRole(parsed, registry, roster, opts, envName);
+    }
+    return runFanOutProject(parsed, registry, roster, opts, envName);
+}
+// ── Single-project form ────────────────────────────────────────────────────────
+async function runSingleProject(parsed, registry, roster, opts, envName) {
+    const { orgSlug, projectSlug, roleSlug } = parsed;
+    // Check roster classification
+    const classification = classifyRoleForProject(roster, projectSlug, roleSlug);
+    // ── XWS_DEFERRED: role is cross-workspace ─────────────────────────────────
+    if (classification === 'declared_cross_workspace') {
+        const xwsEntry = roster.declared_cross_workspace.find((e) => e.role_slug === roleSlug);
+        const xwsResult = {
+            verdict: 'xws_deferred',
+            role_slug: roleSlug,
+            cross_workspace_source: {
+                workspace_path: xwsEntry.workspace_path,
+                registry_path: xwsEntry.registry_path,
+            },
+            fix_instruction: `cd ${xwsEntry.workspace_path} && fazemos agents preflight ${orgSlug}/${projectSlug}/${roleSlug}`,
+        };
+        if (opts.json) {
+            const out = {
+                schema_version: '1.2',
+                target: `${orgSlug}/${projectSlug}/${roleSlug}`,
+                env: envName,
+                exit_code: 3,
+                org: { slug: orgSlug, id: '' },
+                project: { slug: projectSlug, id: '' },
+                role: roleSlug,
+                xws_deferred: xwsResult,
+                summary: { pass: 0, fail: 0, skip: 0, tooling_error: 0, xws_deferred: 1, indeterminate: 0, ok: false },
+            };
+            process.stdout.write(JSON.stringify(out) + '\n');
+        }
+        else {
+            console.log(chalk.cyan(`\nRoster classification: role '${roleSlug}' is declared cross-workspace in this workspace.`));
+            console.log(`  Source: ${xwsEntry.workspace_path}/${xwsEntry.registry_path} (cross_workspace_roles block)\n`);
+            renderXwsDeferred(xwsResult);
+            console.log(`\nResult: 0 PASS, 0 FAIL, 0 SKIP, 1 XWS_DEFERRED.`);
+            console.log(`Exit 3.`);
+        }
+        return 3;
+    }
+    // Resolve org + project IDs
+    let orgId;
+    let projectId;
+    try {
+        orgId = await resolveOrgIdMaybeSlug(orgSlug);
+        const project = await resolveProject(orgId, orgSlug, projectSlug);
+        projectId = project.id;
+    }
+    catch (err) {
+        const msg = err?.message ?? String(err);
+        if (opts.json) {
+            process.stdout.write(JSON.stringify({ schema_version: '1.2', target: `${orgSlug}/${projectSlug}/${roleSlug}`, env: envName, exit_code: 2, error: msg }) + '\n');
+        }
+        else {
+            console.error(chalk.red(`⚠ TOOLING-ERROR: ${msg}`));
+        }
+        return 2;
+    }
+    // Determine agent name from roster or registry
+    const rosterEntry = roster.declared_here.find((e) => e.project_slug === projectSlug && e.role_slug === roleSlug);
+    const agentName = rosterEntry?.filler?.identity ??
+        registry.roles[roleSlug]?.filler?.identity ??
+        roleSlug;
+    if (!opts.json) {
+        console.log(`\nPreflight: ${orgSlug} / ${projectSlug} / ${roleSlug} (agent: ${agentName})\n`);
+        console.log(`  Workspace: ${registry.workspace} @ ${registry._registryPath}`);
+        console.log(`  Checking project '${projectSlug}' — this output is scoped to this project only.\n`);
+    }
+    const rows = await runRowSet({
+        orgId,
+        orgSlug,
+        projectId,
+        projectSlug,
+        roleSlug,
+        agentName,
+        workspace: registry.workspace,
+        workspaceRoot: registry._workspaceRoot,
+        registry,
+        env: envName,
+        region: opts.region,
+    });
+    const summary = summarizeRows(rows);
+    const exitCode = computeExitCode(rows, false);
+    if (opts.json) {
+        const out = {
+            schema_version: '1.2',
+            target: `${orgSlug}/${projectSlug}/${roleSlug}`,
+            env: envName,
+            exit_code: exitCode,
+            org: { slug: orgSlug, id: orgId },
+            project: { slug: projectSlug, id: projectId },
+            role: roleSlug,
+            agent: agentName,
+            workspace_repo: registry.workspace,
+            workspace_ref: 'main',
+            rows,
+            summary,
+        };
+        process.stdout.write(JSON.stringify(out) + '\n');
+    }
+    else {
+        renderRows(rows);
+        console.log(`\n  Result: ${renderSummary(summary)}. Exit ${exitCode}.`);
+    }
+    return exitCode;
+}
+// ── Fan-out: <org>/<role> — all declared projects for a role ──────────────────
+async function runFanOutRole(parsed, registry, roster, opts, envName) {
+    const { orgSlug, roleSlug } = parsed;
+    const { declared_here: declaredProjects, declared_cross_workspace: xwsEntry } = getProjectsForRole(roster, roleSlug);
+    // Empty roster for this role — TOOLING-ERROR (exit 2)
+    if (declaredProjects.length === 0 && !xwsEntry) {
+        const msg = `Roster: 0 declared projects for role '${roleSlug}'. ` +
+            `Add a filler for '${roleSlug}' in .fazemos/roles.json (or projects/<slug>/.fazemos/roles.json), then re-run.`;
+        if (opts.json) {
+            process.stdout.write(JSON.stringify({
+                schema_version: '1.2',
+                target: `${orgSlug}/${roleSlug}`,
+                env: envName,
+                exit_code: 2,
+                error: msg,
+            }) + '\n');
+        }
+        else {
+            console.error(chalk.red(`⚠ TOOLING-ERROR: ${msg}`));
+        }
+        return 2;
+    }
+    // If only cross-workspace — XWS_DEFERRED immediately
+    if (declaredProjects.length === 0 && xwsEntry) {
+        const fixInstruction = `cd ${xwsEntry.workspace_path} && fazemos agents preflight ${orgSlug}/${roleSlug}`;
+        if (opts.json) {
+            const out = {
+                schema_version: '1.2',
+                target: `${orgSlug}/${roleSlug}`,
+                env: envName,
+                exit_code: 3,
+                org: { slug: orgSlug, id: '' },
+                role: roleSlug,
+                roster: {
+                    source_files: roster.source_files,
+                    declared_projects: [],
+                    cross_workspace_roles: [{
+                            role_slug: roleSlug,
+                            workspace_path: xwsEntry.workspace_path,
+                            registry_path: xwsEntry.registry_path,
+                            fix_instruction: fixInstruction,
+                        }],
+                },
+                org_summary: { declared_projects: 0, xws_deferred_count: xwsEntry ? 1 : 0 },
+            };
+            process.stdout.write(JSON.stringify(out) + '\n');
+        }
+        else {
+            console.log(chalk.cyan(`\nRoster classification: role '${roleSlug}' is declared cross-workspace in this workspace.`));
+            console.log(`  Source: ${xwsEntry.workspace_path}/${xwsEntry.registry_path}\n`);
+            renderXwsDeferred({
+                verdict: 'xws_deferred',
+                role_slug: roleSlug,
+                cross_workspace_source: { workspace_path: xwsEntry.workspace_path, registry_path: xwsEntry.registry_path },
+                fix_instruction: fixInstruction,
+            });
+            const xwsCount = xwsEntry ? 1 : 0;
+            console.log(`\nOrg summary: 0 of 0 declared-here projects processed. ${xwsCount} cross-workspace role(s) declared (unverified).`);
+            console.log('Exit 3.');
+        }
+        return 3;
+    }
+    if (!opts.json) {
+        console.log(`\nRoster: ${declaredProjects.length} declared project(s) for role '${roleSlug}' (from ${roster.source_files.join(', ')}).`);
+        if (xwsEntry) {
+            console.log(chalk.cyan(`  + 1 cross-workspace declaration in ${xwsEntry.workspace_path} (XWS_DEFERRED — not fanned out).`));
+        }
+        console.log('');
+    }
+    // Resolve org + active projects
+    let orgId;
+    let allProjects;
+    try {
+        const resolved = await resolveOrgAndProjects(orgSlug);
+        orgId = resolved.orgId;
+        allProjects = resolved.projects;
+    }
+    catch (err) {
+        const msg = err?.message ?? String(err);
+        if (opts.json) {
+            process.stdout.write(JSON.stringify({ schema_version: '1.2', target: `${orgSlug}/${roleSlug}`, env: envName, exit_code: 2, error: msg }) + '\n');
+        }
+        else {
+            console.error(chalk.red(`⚠ TOOLING-ERROR: ${msg}`));
+        }
+        return 2;
+    }
+    const declaredSlugs = new Set(declaredProjects.map((e) => e.project_slug));
+    const projectResults = [];
+    const exitCodes = [];
+    // Declared projects (full row-set each)
+    for (let i = 0; i < declaredProjects.length; i++) {
+        const dp = declaredProjects[i];
+        const proj = allProjects.find((p) => p.slug === dp.project_slug);
+        if (!proj) {
+            if (!opts.json) {
+                console.log(chalk.yellow(`WARNING: roles.json declares '${roleSlug}' for project '${dp.project_slug}' but no active project by that slug exists in org '${orgSlug}'. Skipping.`));
+            }
+            continue;
+        }
+        if (!opts.json) {
+            console.log(`Preflight (project ${i + 1}/${declaredProjects.length} declared): ${orgSlug} / ${dp.project_slug} / ${roleSlug} (agent: ${dp.filler.identity})`);
+        }
+        const rows = await runRowSet({
+            orgId,
+            orgSlug,
+            projectId: proj.id,
+            projectSlug: dp.project_slug,
+            roleSlug: roleSlug,
+            agentName: dp.filler.identity,
+            workspace: registry.workspace,
+            workspaceRoot: registry._workspaceRoot,
+            registry,
+            env: envName,
+            region: opts.region,
+        });
+        const summary = summarizeRows(rows);
+        const code = computeExitCode(rows, false);
+        exitCodes.push(code);
+        if (!opts.json) {
+            renderRows(rows);
+            console.log(`  Result: ${renderSummary(summary)}. Exit contribution: ${code}.\n`);
+        }
+        projectResults.push({
+            project: { slug: dp.project_slug, id: proj.id },
+            declared: true,
+            role: roleSlug,
+            agent: dp.filler.identity,
+            rows,
+            summary,
+        });
+    }
+    // XWS_DEFERRED for cross-workspace role
+    let hasXwsDeferred = false;
+    if (xwsEntry) {
+        hasXwsDeferred = true;
+        exitCodes.push(3);
+        const fixInstruction = `cd ${xwsEntry.workspace_path} && fazemos agents preflight ${orgSlug}/${roleSlug}`;
+        if (!opts.json) {
+            console.log(chalk.cyan(`⌛ XWS_DEFERRED  ${roleSlug}: declared cross-workspace in ${xwsEntry.workspace_path}`));
+            console.log(`  ${chalk.yellow('fix:')} ${fixInstruction}`);
+        }
+        projectResults.push({
+            project: { slug: '(cross-workspace)', id: '' },
+            declared: true,
+            declared_cross_workspace: true,
+            fix_instruction: fixInstruction,
+        });
+    }
+    // Undeclared projects (SKIP — not FAIL)
+    const undeclaredProjects = allProjects.filter((p) => !declaredSlugs.has(p.slug));
+    if (!opts.json && undeclaredProjects.length > 0) {
+        console.log('Undeclared projects (SKIP — not FAIL):');
+        for (const p of undeclaredProjects) {
+            console.log(chalk.gray(`  ⊘ SKIP  ${p.slug}: role '${roleSlug}' not declared for this project.`));
+        }
+        console.log('');
+    }
+    for (const p of undeclaredProjects) {
+        projectResults.push({
+            project: { slug: p.slug, id: p.id },
+            declared: false,
+            reason: `role '${roleSlug}' not declared for this project`,
+        });
+    }
+    const finalCode = mergeExitCodes(exitCodes.length > 0 ? exitCodes : [0]);
+    const failingProjects = projectResults
+        .filter((p) => p.declared && !p.declared_cross_workspace && p.summary && !p.summary.ok)
+        .map((p) => p.project.slug);
+    if (!opts.json) {
+        const allDeclaredPass = failingProjects.length === 0;
+        console.log(`Org summary: ${declaredProjects.length - (allProjects.filter(p => !declaredSlugs.has(p.slug)).length)} of ${declaredProjects.length} declared projects PASS.` +
+            (undeclaredProjects.length > 0 ? ` ${undeclaredProjects.length} undeclared project(s) SKIPPED.` : '') +
+            (failingProjects.length > 0 ? ` FAIL projects: [${failingProjects.join(', ')}].` : '') +
+            (xwsEntry ? ` ${xwsEntry ? 1 : 0} cross-workspace role(s) XWS_DEFERRED.` : ''));
+        console.log(`Exit ${finalCode}.`);
+    }
+    else {
+        const out = {
+            schema_version: '1.2',
+            target: `${orgSlug}/${roleSlug}`,
+            env: envName,
+            exit_code: finalCode,
+            org: { slug: orgSlug, id: orgId },
+            role: roleSlug,
+            roster: {
+                source_files: roster.source_files,
+                declared_projects: declaredProjects.map((e) => e.project_slug),
+                undeclared_projects: undeclaredProjects.map((p) => p.slug),
+                ...(xwsEntry ? {
+                    cross_workspace_roles: [{
+                            role_slug: roleSlug,
+                            workspace_path: xwsEntry.workspace_path,
+                            registry_path: xwsEntry.registry_path,
+                            fix_instruction: `cd ${xwsEntry.workspace_path} && fazemos agents preflight ${orgSlug}/${roleSlug}`,
+                        }],
+                } : {}),
+            },
+            projects: projectResults,
+            org_summary: {
+                total_projects: allProjects.length,
+                declared_projects: declaredProjects.length,
+                undeclared_projects: undeclaredProjects.length,
+                all_declared_pass: failingProjects.length === 0 && !hasXwsDeferred,
+                failing_projects: failingProjects,
+                xws_deferred_count: xwsEntry ? 1 : 0,
+            },
+        };
+        process.stdout.write(JSON.stringify(out) + '\n');
+    }
+    return finalCode;
+}
+// ── Fan-out: <org>/<project> — all declared roles for a project ───────────────
+async function runFanOutProject(parsed, registry, roster, opts, envName) {
+    const { orgSlug, projectSlug } = parsed;
+    const { declared_here: declaredRoles, declared_cross_workspace: xwsEntries } = getRolesForProject(roster, projectSlug);
+    if (declaredRoles.length === 0 && xwsEntries.length === 0) {
+        const msg = `Roster: 0 declared roles for project '${projectSlug}' in this workspace.`;
+        if (opts.json) {
+            process.stdout.write(JSON.stringify({ schema_version: '1.2', target: `${orgSlug}/${projectSlug}`, env: envName, exit_code: 2, error: msg }) + '\n');
+        }
+        else {
+            console.error(chalk.red(`⚠ TOOLING-ERROR: ${msg}`));
+        }
+        return 2;
+    }
+    // Resolve org + project IDs
+    let orgId;
+    let projectId;
+    try {
+        orgId = await resolveOrgIdMaybeSlug(orgSlug);
+        const project = await resolveProject(orgId, orgSlug, projectSlug);
+        projectId = project.id;
+    }
+    catch (err) {
+        const msg = err?.message ?? String(err);
+        if (opts.json) {
+            process.stdout.write(JSON.stringify({ schema_version: '1.2', target: `${orgSlug}/${projectSlug}`, env: envName, exit_code: 2, error: msg }) + '\n');
+        }
+        else {
+            console.error(chalk.red(`⚠ TOOLING-ERROR: ${msg}`));
+        }
+        return 2;
+    }
+    if (!opts.json) {
+        console.log(`\nRoster for project '${projectSlug}': ${declaredRoles.length} locally-declared role(s)` +
+            (xwsEntries.length > 0 ? ` + ${xwsEntries.length} cross-workspace role(s) (${xwsEntries.map((e) => e.role_slug).join(', ')}).` : '.'));
+        console.log('');
+    }
+    const roleResults = [];
+    const exitCodes = [];
+    // Run row-sets for locally-declared roles
+    for (let i = 0; i < declaredRoles.length; i++) {
+        const dr = declaredRoles[i];
+        const agentName = dr.filler.identity;
+        if (!opts.json) {
+            console.log(`Preflight (role ${i + 1}/${declaredRoles.length} declared-here): ${dr.role_slug} (agent: ${agentName})`);
+        }
+        const rows = await runRowSet({
+            orgId,
+            orgSlug,
+            projectId,
+            projectSlug: projectSlug,
+            roleSlug: dr.role_slug,
+            agentName,
+            workspace: registry.workspace,
+            workspaceRoot: registry._workspaceRoot,
+            registry,
+            env: envName,
+            region: opts.region,
+        });
+        const summary = summarizeRows(rows);
+        const code = computeExitCode(rows, false);
+        exitCodes.push(code);
+        if (!opts.json) {
+            renderRows(rows);
+            console.log(`  Result: ${renderSummary(summary)}. Exit contribution: ${code}.\n`);
+        }
+        roleResults.push({ role: dr.role_slug, declared: true, agent: agentName, rows, summary });
+    }
+    // XWS_DEFERRED for cross-workspace roles
+    if (xwsEntries.length > 0) {
+        if (!opts.json) {
+            console.log('Cross-workspace roles (XWS_DEFERRED — verify from owning workspace):');
+        }
+        for (const xws of xwsEntries) {
+            exitCodes.push(3);
+            const fixInstruction = `cd ${xws.workspace_path} && fazemos agents preflight ${orgSlug}/${xws.role_slug}`;
+            if (!opts.json) {
+                console.log(chalk.cyan(`  ⌛ ${xws.role_slug}: fix: ${fixInstruction}`));
+            }
+            roleResults.push({
+                role: xws.role_slug,
+                declared: true,
+                declared_cross_workspace: true,
+                fix_instruction: fixInstruction,
+            });
+        }
+        if (!opts.json)
+            console.log('');
+    }
+    const finalCode = mergeExitCodes(exitCodes.length > 0 ? exitCodes : [0]);
+    const failingRoles = roleResults
+        .filter((r) => r.declared && !r.declared_cross_workspace && r.summary && !r.summary.ok)
+        .map((r) => r.role);
+    const hasXwsDeferred = xwsEntries.length > 0;
+    if (!opts.json) {
+        console.log(`Project summary: ${declaredRoles.length} of ${declaredRoles.length} declared-here roles` +
+            (failingRoles.length === 0 ? ' PASS.' : ` — ${failingRoles.length} FAIL: [${failingRoles.join(', ')}].`) +
+            (hasXwsDeferred ? ` ${xwsEntries.length} cross-workspace role(s) XWS_DEFERRED.` : ''));
+        console.log(`Exit ${finalCode}.`);
+    }
+    else {
+        const out = {
+            schema_version: '1.2',
+            target: `${orgSlug}/${projectSlug}`,
+            env: envName,
+            exit_code: finalCode,
+            org: { slug: orgSlug, id: orgId },
+            project: { slug: projectSlug, id: projectId },
+            roster: {
+                source_files: roster.source_files,
+                ...(xwsEntries.length > 0 ? {
+                    cross_workspace_roles: xwsEntries.map((e) => ({
+                        role_slug: e.role_slug,
+                        workspace_path: e.workspace_path,
+                        registry_path: e.registry_path,
+                        fix_instruction: `cd ${e.workspace_path} && fazemos agents preflight ${orgSlug}/${e.role_slug}`,
+                    })),
+                } : {}),
+            },
+            roles: roleResults,
+            project_summary: {
+                total_roles_declared_here: declaredRoles.length,
+                cross_workspace_count: xwsEntries.length,
+                all_declared_here_pass: failingRoles.length === 0,
+                failing_roles: failingRoles,
+            },
+        };
+        process.stdout.write(JSON.stringify(out) + '\n');
+    }
+    return finalCode;
+}
+//# sourceMappingURL=preflight.js.map