@formigio/fazemos-cli 0.10.35 → 0.10.38

package/dist/index.js

@@ -3,9 +3,12 @@ import { Command } from 'commander';
 import chalk from 'chalk';
 import { config, getEnv, getToken, getActiveOrgId, setActiveOrgId, addEnvironment, hasEnvironments, 
 // F15 — project context helpers
-getActiveProjectId, setActiveProjectId, clearActiveProjectId, findProjectBySlug, findProjectById, findOrgById, } from './config.js';
+getActiveProjectId, setActiveProjectId, clearActiveProjectId, findProjectBySlug, findProjectById, findOrgById, 
+// Directory-scoped context override (.fazemos.json)
+setOrgOverride, setProjectOverride, setDirContextSource, getDirContextSource, } from './config.js';
+import { findDirContextFile, readDirContextFile, writeDirContextFile, removeDirContextFile, DIR_CONFIG_FILENAME, } from './dircontext.js';
 import { login, signup, confirmSignup, adminLogin } from './auth.js';
-import { api, ApiError, refreshAuthMeCache, invalidateAuthMeCache, resolveOrgIdMaybeSlug } from './api.js';
+import { api, ApiError, refreshAuthMeCache, invalidateAuthMeCache, resolveOrgIdMaybeSlug, resolveProjectIdBySlug } from './api.js';
 import { isProjectConnectionUnavailable, renderProjectConnectionUnavailableCopy, } from './connectionErrorCopy.js';
 import { loadYaml, summarize } from './yaml/load.js';
 import { printFindings, printJson } from './yaml/format.js';
@@ -21,7 +24,7 @@ import { registerGovernanceCommands } from './governance.js';
 import { parseExecutionsJson, resolveWaitOptions, waitForPipelines, buildAwsCommand, validateExecutionEntry, } from './wait-for-pipeline.js';
 import { readFileSync, readdirSync, writeFileSync, mkdirSync, existsSync, statSync } from 'fs';
 import { fileURLToPath } from 'url';
-import { dirname, resolve, basename } from 'path';
+import { dirname, resolve, basename, relative } from 'path';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(resolve(__dirname, '..', 'package.json'), 'utf-8'));
 function parseNumber(val) {
@@ -110,6 +113,32 @@ function parseJson(val, flag) {
         process.exit(1);
     }
 }
+/**
+ * Parse JSON from an inline string or `@filepath`. Empty string returns null (clears the field).
+ * Used by --verification and --uat flags.
+ */
+function parseJsonOrFile(val, flag) {
+    if (val === '')
+        return null;
+    let raw = val;
+    if (val.startsWith('@')) {
+        const filePath = resolve(val.slice(1));
+        try {
+            raw = readFileSync(filePath, 'utf-8');
+        }
+        catch (err) {
+            console.error(chalk.red(`Cannot read ${flag} file "${filePath}": ${err.message}`));
+            process.exit(1);
+        }
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        console.error(chalk.red(`Invalid JSON for ${flag}. Check quoting and syntax.`));
+        process.exit(1);
+    }
+}
 /** Resolve a value that may be `@filepath` (reads file contents) or inline text. */
 function resolveFileOrInline(val) {
     if (val.startsWith('@')) {
@@ -167,6 +196,81 @@ program
     .name('fazemos')
     .description('Fazemos CLI — Team Accomplishment Platform')
     .version(pkg.version);
+// ── Directory-scoped default org/project (.fazemos.json) ─────
+//
+// Before any command action runs, discover the nearest `.fazemos.json`
+// (walking up from the cwd) and resolve its org/project slugs to ids, holding
+// them as in-memory overrides for the process. This scopes every call to the
+// pinned org/project without a manual `orgs switch` / `projects switch`.
+//
+// Resolution is best-effort: if a slug can't be resolved (not logged in, slug
+// not in your memberships, stale cache) we leave the override unset and let the
+// normal active-selection + API error path take over. Network resolution is
+// skipped for the bootstrap commands that don't need a scoped context.
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Top-level commands that never need (and shouldn't trigger) context resolution. */
+const DIR_CONTEXT_SKIP = new Set(['use', 'auth', 'env', 'init']);
+let dirContextApplied = false;
+async function applyDirContext(topCommand) {
+    if (dirContextApplied)
+        return;
+    dirContextApplied = true;
+    let found;
+    try {
+        found = findDirContextFile();
+    }
+    catch (err) {
+        // Malformed .fazemos.json — surface it for normal commands, but don't
+        // abort. The bootstrap commands (notably `use`) report it themselves, so
+        // stay silent for them to avoid a double warning.
+        if (!DIR_CONTEXT_SKIP.has(topCommand))
+            console.error(chalk.yellow(err.message));
+        return;
+    }
+    if (!found)
+        return;
+    // Record the source so whoami/config can show where the scope came from.
+    setDirContextSource({ path: found.path, ...found.context });
+    // Bootstrap commands (auth/env/init/use) operate without a resolved scope.
+    if (DIR_CONTEXT_SKIP.has(topCommand))
+        return;
+    const { org, project } = found.context;
+    if (org) {
+        try {
+            setOrgOverride(await resolveOrgIdMaybeSlug(org));
+        }
+        catch {
+            // Unresolved org slug — leave unset; the command's own "no active org"
+            // check or the API will report the problem with full context.
+        }
+    }
+    if (project) {
+        try {
+            if (UUID_RE.test(project)) {
+                setProjectOverride(project);
+            }
+            else {
+                // Resolves against the active org, which now reflects the org override.
+                const projectId = await resolveProjectIdBySlug(project);
+                if (projectId)
+                    setProjectOverride(projectId);
+            }
+        }
+        catch {
+            // Unresolved project slug — leave unset; surfaced downstream.
+        }
+    }
+}
+program.hook('preAction', async (_thisCommand, actionCommand) => {
+    // Resolve the top-level command name (e.g. `worksheets list` → `worksheets`).
+    let c = actionCommand;
+    let top = c?.name?.();
+    while (c?.parent && c.parent !== program) {
+        c = c.parent;
+        top = c.name();
+    }
+    await applyDirContext(top ?? '');
+});
 // ── Init ────────────────────────────────────────────────────
 program
     .command('init')
@@ -375,6 +479,94 @@ program
         else {
             console.log(`  Project: ${chalk.gray('(none set — fazemos projects switch <slug>)')}`);
         }
+        // Note when the org/project scope is coming from a directory .fazemos.json
+        // rather than the persisted active selection, so the source is obvious.
+        const dirSource = getDirContextSource();
+        if (dirSource) {
+            const rel = relative(process.cwd(), dirSource.path) || dirSource.path;
+            console.log(chalk.gray(`  Scope:   from ${rel} (fazemos use)`));
+        }
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+// ── Directory context (`fazemos use`) ───────────────────────
+program
+    .command('use')
+    .description(`Set the default org/project for the current directory (writes ${DIR_CONFIG_FILENAME}). Running the CLI anywhere under that directory scopes calls to this org/project automatically.`)
+    .option('-o, --org <slug>', 'Org slug to pin for this directory')
+    .option('-p, --project <slug>', 'Project slug to pin for this directory')
+    .option('--show', 'Show the directory context in effect and which file provides it')
+    .option('--clear', `Remove ${DIR_CONFIG_FILENAME} from the current directory`)
+    .action(async (opts) => {
+    try {
+        // --show (also the default when no flags are given): report the nearest
+        // .fazemos.json and the effective scope.
+        if (opts.show || (!opts.org && !opts.project && !opts.clear)) {
+            const found = findDirContextFile();
+            if (!found) {
+                console.log(chalk.gray(`No ${DIR_CONFIG_FILENAME} found in this directory or any parent.`));
+                console.log(chalk.gray('Set one with: fazemos use --org <slug> --project <slug>'));
+                return;
+            }
+            const rel = relative(process.cwd(), found.path) || found.path;
+            console.log(`Directory context (${chalk.cyan(rel)}):`);
+            console.log(`  Org:     ${found.context.org ? chalk.cyan(found.context.org) : chalk.gray('(not set)')}`);
+            console.log(`  Project: ${found.context.project ? chalk.cyan(found.context.project) : chalk.gray('(not set)')}`);
+            return;
+        }
+        // --clear: remove the .fazemos.json in the cwd (not a parent's).
+        if (opts.clear) {
+            const removed = removeDirContextFile(process.cwd());
+            if (removed) {
+                console.log(chalk.green(`Removed ${DIR_CONFIG_FILENAME} from this directory.`));
+            }
+            else {
+                console.log(chalk.gray(`No ${DIR_CONFIG_FILENAME} in this directory to remove.`));
+            }
+            return;
+        }
+        // Merge onto any existing file in the cwd so `use --project x` keeps a
+        // previously-pinned org (and vice versa).
+        const existing = readDirContextFile(process.cwd())?.context ?? {};
+        const orgSlug = opts.org ?? existing.org;
+        const projectSlug = opts.project ?? existing.project;
+        if (opts.project && !orgSlug) {
+            console.error(chalk.red('Cannot pin a project without an org. Pass --org <slug> too.'));
+            process.exit(1);
+        }
+        // Validate the org slug against your memberships (resolves + caches
+        // /auth/me). resolveOrgIdMaybeSlug throws a clear error on an unknown slug.
+        let orgName = orgSlug;
+        let resolvedOrgId = null;
+        if (orgSlug) {
+            resolvedOrgId = await resolveOrgIdMaybeSlug(orgSlug);
+            orgName = findOrgById(resolvedOrgId)?.name ?? orgSlug;
+        }
+        // Validate the project slug within that org.
+        let projectName = projectSlug;
+        if (projectSlug && resolvedOrgId) {
+            let project = findProjectBySlug(resolvedOrgId, projectSlug);
+            if (!project) {
+                await refreshAuthMeCache();
+                project = findProjectBySlug(resolvedOrgId, projectSlug);
+            }
+            if (!project) {
+                console.error(chalk.red(`Unknown project "${projectSlug}" in org ${orgName}.`));
+                console.log(chalk.gray('Run: fazemos projects list'));
+                process.exit(1);
+            }
+            projectName = project.name;
+        }
+        const path = writeDirContextFile(process.cwd(), { org: orgSlug, project: projectSlug });
+        const rel = relative(process.cwd(), path) || path;
+        console.log(chalk.green(`✓ Wrote ${rel}`));
+        if (orgSlug)
+            console.log(`  Org:     ${chalk.cyan(orgName)} (${orgSlug})`);
+        if (projectSlug)
+            console.log(`  Project: ${chalk.cyan(projectName)} (${projectSlug})`);
     }
     catch (err) {
         console.error(chalk.red(err.message));
@@ -1108,7 +1300,8 @@ projects
 });
 projects
     .command('create')
-    .description('Create a new project in the active organization. Owner/admin only. Slug is immutable after creation — pick carefully.')
+    .description('Create a new project in the active organization. Owner/admin only. Slug is immutable after creation — pick carefully.\n\n' +
+    'Next: `fazemos projects setup <slug>` to bind docs and connection.')
     .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)')
@@ -1337,7 +1530,8 @@ projects
 // ── 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.')
+    .description('If this is a fresh project, use `fazemos projects setup` instead — that command binds docs + connection together.\n\n' +
+    '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) => {
@@ -1390,6 +1584,200 @@ projects
         process.exit(1);
     }
 });
+// ── F42 — projects setup (binds docs + connection in one call) ──────────────
+projects
+    .command('setup')
+    .description('Bind docs repo, docs root, and/or VCS connection to an existing project in one audited admin call. ' +
+    'Owner/admin only — agent identities are rejected. At least one flag required.')
+    .argument('<slug>', 'Project slug')
+    .option('--docs-repo <owner/repo>', 'Docs repository in <owner>/<repo> format (omit to leave unchanged)')
+    .option('--docs-root <ROOT|path>', 'Docs root path. Pass ROOT (case-insensitive) for repo root. Omit to leave unchanged.')
+    .option('--vcs-connection-id <uuid>', 'VCS connection UUID to bind (omit to leave unchanged)')
+    .option('--json', 'Emit JSON instead of human-readable output')
+    .action(async (slug, opts) => {
+    // ── Client-side validation ──────────────────────────────────
+    const hasDocsRepo = opts.docsRepo !== undefined;
+    const hasDocsRoot = opts.docsRoot !== undefined;
+    const hasVcsConnectionId = opts.vcsConnectionId !== undefined;
+    if (!hasDocsRepo && !hasDocsRoot && !hasVcsConnectionId) {
+        const msg = 'No flags passed. Provide at least one of --docs-repo, --docs-root, --vcs-connection-id.';
+        if (opts.json) {
+            console.log(JSON.stringify({ error: { code: 'NO_FLAGS_PASSED', message: msg } }));
+        }
+        else {
+            console.error(chalk.red(msg));
+            console.error(chalk.gray('Run: fazemos projects setup --help'));
+        }
+        process.exit(1);
+        return; // guard: process.exit is mocked in tests
+    }
+    if (hasDocsRoot) {
+        const rawRoot = opts.docsRoot;
+        if (rawRoot.trim() === '') {
+            const msg = 'docs_root_empty: --docs-root cannot be an empty string or whitespace. Pass ROOT for repo root or a valid subpath.';
+            if (opts.json) {
+                console.log(JSON.stringify({ error: { code: 'docs_root_empty', message: msg } }));
+            }
+            else {
+                console.error(chalk.red(msg));
+                console.error(chalk.gray('See: docs/architecture/repo-root-vs-subdir-docs.md'));
+            }
+            process.exit(1);
+            return; // guard: process.exit is mocked in tests
+        }
+        if (rawRoot.length > 500) {
+            const msg = `docs_root_too_long: --docs-root exceeds 500 characters (got ${rawRoot.length}).`;
+            if (opts.json) {
+                console.log(JSON.stringify({ error: { code: 'docs_root_too_long', message: msg } }));
+            }
+            else {
+                console.error(chalk.red(msg));
+            }
+            process.exit(1);
+            return; // guard: process.exit is mocked in tests
+        }
+    }
+    if (hasDocsRepo && opts.docsRepo !== null) {
+        const repoPattern = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
+        if (!repoPattern.test(opts.docsRepo)) {
+            const msg = `docs_repo_shape: --docs-repo must be in <owner>/<repo> format (got: ${opts.docsRepo}).`;
+            if (opts.json) {
+                console.log(JSON.stringify({ error: { code: 'docs_repo_shape', message: msg } }));
+            }
+            else {
+                console.error(chalk.red(msg));
+            }
+            process.exit(1);
+            return; // guard: process.exit is mocked in tests
+        }
+    }
+    // ── Resolve slug → project ID ──────────────────────────────
+    const orgId = requireActiveOrgOrExit();
+    let project = findProjectBySlug(orgId, slug);
+    if (!project) {
+        await refreshAuthMeCache();
+        project = findProjectBySlug(orgId, slug);
+    }
+    if (!project) {
+        const msg = `Unknown project: ${slug}`;
+        if (opts.json) {
+            console.log(JSON.stringify({ error: { code: 'PROJECT_NOT_FOUND', message: msg } }));
+        }
+        else {
+            console.error(chalk.red(msg));
+            console.log(chalk.gray('Run: fazemos projects list'));
+        }
+        process.exit(1);
+        return; // guard: process.exit is mocked in tests
+    }
+    // ── Build request body ─────────────────────────────────────
+    // OQ-3: ROOT (case-insensitive) → null (means "repo root" at API)
+    const body = {};
+    if (hasDocsRepo)
+        body.docsRepo = opts.docsRepo ?? null;
+    if (hasDocsRoot) {
+        body.docsRoot = opts.docsRoot.toUpperCase() === 'ROOT' ? null : opts.docsRoot;
+    }
+    if (hasVcsConnectionId)
+        body.vcsConnectionId = opts.vcsConnectionId ?? null;
+    // ── API call ───────────────────────────────────────────────
+    try {
+        const data = await api('POST', `/api/admin/projects/${project.id}/setup`, body, { noProjectHeader: true });
+        if (opts.json) {
+            console.log(JSON.stringify({
+                status: 'ok',
+                project: data.project,
+                auditLogId: data.auditLogId,
+                changes: data.changes,
+            }));
+            return;
+        }
+        // ── Human-readable success output (Sage UX §"Success output") ──
+        const p = data.project;
+        const changes = data.changes ?? {};
+        const changedFields = Object.keys(changes);
+        const passedFields = Object.keys(body);
+        const unchangedFields = passedFields.filter(f => !changedFields.includes(f));
+        console.log(chalk.green(`✓ ${p.name} (${p.slug}) — onboarded`));
+        if (changedFields.includes('docsRepo') || passedFields.includes('docsRepo')) {
+            const val = p.docsRepo ?? '(cleared)';
+            const marker = changedFields.includes('docsRepo') ? '' : chalk.gray(' (unchanged)');
+            console.log(`  docs_repo:           ${val}${marker}`);
+        }
+        if (changedFields.includes('docsRoot') || passedFields.includes('docsRoot')) {
+            const val = p.docsRoot === null ? 'ROOT  (repo root — no subdirectory)' : p.docsRoot;
+            const marker = changedFields.includes('docsRoot') ? '' : chalk.gray(' (unchanged)');
+            console.log(`  docs_root:           ${val}${marker}`);
+        }
+        if (changedFields.includes('vcsConnectionId') || passedFields.includes('vcsConnectionId')) {
+            const val = p.vcsConnectionId ?? '(cleared)';
+            const marker = changedFields.includes('vcsConnectionId') ? '' : chalk.gray(' (unchanged)');
+            console.log(`  vcs_connection_id:   ${val}${marker}`);
+        }
+        if (unchangedFields.length > 0) {
+            console.log(chalk.gray(`  (unchanged: ${unchangedFields.join(', ')})`));
+        }
+        console.log(`  Audit:               logged as project_setup (id: ${data.auditLogId})`);
+    }
+    catch (err) {
+        if (opts.json) {
+            console.log(JSON.stringify({ error: { code: err.code ?? 'ERROR', message: err.message } }));
+            process.exit(1);
+        }
+        if (err instanceof ApiError) {
+            switch (err.code) {
+                case 'PROJECT_NOT_FOUND':
+                    console.error(chalk.red(`Project not found: ${slug}`));
+                    console.log(chalk.gray('Run: fazemos projects list'));
+                    break;
+                case 'FORBIDDEN_ROLE':
+                    console.error(chalk.red('Access denied. Owner or admin role required. Agent identities are not permitted.'));
+                    break;
+                case 'AT_LEAST_ONE_FIELD_REQUIRED':
+                    console.error(chalk.red('At least one of --docs-repo, --docs-root, --vcs-connection-id must be provided.'));
+                    break;
+                case 'VALIDATION_ERROR': {
+                    const body2 = (err.body ?? {});
+                    const sub = body2.subCode ?? '';
+                    if (sub === 'docs_root_empty') {
+                        console.error(chalk.red('docs_root_empty: --docs-root cannot be empty or whitespace. Pass ROOT for repo root.'));
+                        console.error(chalk.gray('See: docs/architecture/repo-root-vs-subdir-docs.md'));
+                    }
+                    else if (sub === 'docs_root_too_long') {
+                        console.error(chalk.red('docs_root_too_long: --docs-root exceeds 500 characters.'));
+                    }
+                    else if (sub === 'docs_repo_shape') {
+                        console.error(chalk.red('docs_repo_shape: --docs-repo must be in <owner>/<repo> format.'));
+                    }
+                    else if (sub === 'vcs_connection_uuid') {
+                        console.error(chalk.red('vcs_connection_uuid: --vcs-connection-id must be a valid UUID.'));
+                    }
+                    else {
+                        console.error(chalk.red(`Validation error: ${err.message}`));
+                    }
+                    break;
+                }
+                case 'CONNECTION_NOT_FOUND':
+                    console.error(chalk.red('VCS connection not found.'));
+                    console.log(chalk.gray('List your connections: fazemos connections list'));
+                    break;
+                case 'CONNECTION_CROSS_ORG':
+                    console.error(chalk.red('That VCS connection belongs to a different organization.'));
+                    break;
+                case 'CONNECTION_NOT_ACTIVE':
+                    console.error(chalk.red('VCS connection is not active and cannot be bound.'));
+                    console.log(chalk.gray('Pick an active connection: fazemos connections list'));
+                    break;
+                default:
+                    console.error(chalk.red(err.message));
+            }
+        }
+        else {
+            console.error(chalk.red(err.message));
+        }
+        process.exit(1);
+    }
+});
 // ── F16 — Connections ───────────────────────────────────────
 const connections = program.command('connections').alias('conn').description('GitHub Connection commands');
 /**
@@ -3039,10 +3427,17 @@ templates
     .command('show')
     .description('Show template detail including phases, steps, I/O declarations, pipeline inputs, and revision number. Use this to inspect the full structure of a template and discover phase/step IDs needed by other commands.')
     .argument('<id>', 'Template ID (use "tpl list" to find IDs)')
-    .action(async (id) => {
+    .option('--json', 'Output the template definition as JSON (same as tpl export). Useful for piping/inspecting without a temp file.')
+    .option('--show-sections', 'Print full sections content for all steps (default: truncated at 200 chars)')
+    .action(async (id, opts) => {
     try {
         const data = await api('GET', `/api/pipeline-templates/${id}`);
         const t = data.template;
+        // --json mode: emit definition JSON (same as tpl export)
+        if (opts.json) {
+            console.log(JSON.stringify(t.definition, null, 2));
+            return;
+        }
         console.log(chalk.cyan(t.name));
         console.log(`  ID:      ${t.id}`);
         console.log(`  Status:  ${t.status}`);
@@ -3063,7 +3458,9 @@ templates
                 for (const step of phase.steps || []) {
                     const reviewer = step.reviewer ? ` reviewer:${step.reviewer}` : '';
                     const cycles = step.reviewer && step.max_review_cycles ? ` max-cycles:${step.max_review_cycles}` : '';
-                    console.log(`    Step: ${step.name} [${step.role || 'unassigned'}] (${step.step_type || step.stepType || 'human'})${reviewer}${cycles}`);
+                    // gate and human_approval are equivalent; normalise display
+                    const displayType = step.step_type || step.stepType || 'human';
+                    console.log(`    Step: ${step.name} [${step.role || 'unassigned'}] (${displayType})${reviewer}${cycles}`);
                     if (step.outputs?.length) {
                         console.log('      Outputs:');
                         for (const o of step.outputs) {
@@ -3125,9 +3522,101 @@ templates
                         if (ac.repos)
                             console.log(`        repos: ${JSON.stringify(ac.repos)}`);
                     }
+                    // sections (agent instructions) — truncated at 200 chars unless --show-sections
+                    if (step.sections) {
+                        const full = step.sections;
+                        if (opts.showSections || full.length <= 200) {
+                            console.log(`      Sections:\n${full.split('\n').map((l) => `        ${l}`).join('\n')}`);
+                        }
+                        else {
+                            console.log(`      Sections: ${full.slice(0, 200)}... (${full.length} chars total)`);
+                        }
+                    }
+                    // verification block
+                    if (step.verification) {
+                        console.log(`      Verification: ${JSON.stringify(step.verification)}`);
+                    }
+                    // uat block
+                    if (step.uat) {
+                        console.log(`      UAT: ${JSON.stringify(step.uat)}`);
+                    }
+                }
+            }
+        }
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+templates
+    .command('export')
+    .description('Export a template\'s full definition JSON to stdout or a file. Includes all phases, steps, sections, verification, uat, agent_config, I/O wires, and pipeline inputs. The exported JSON is the canonical input to "tpl update-definition". Round-trip: tpl export <id> > def.json && tpl update-definition <id> def.json is a no-op.')
+    .argument('<id>', 'Template ID (use "tpl list" to find IDs)')
+    .option('--out <file>', 'Write output to file instead of stdout')
+    .action(async (id, opts) => {
+    try {
+        const data = await api('GET', `/api/pipeline-templates/${id}`);
+        const t = data.template;
+        const json = JSON.stringify(t.definition, null, 2);
+        if (opts.out) {
+            const outPath = resolve(opts.out);
+            writeFileSync(outPath, json, 'utf-8');
+            console.log(chalk.green(`Definition written to ${outPath}`));
+        }
+        else {
+            console.log(json);
+        }
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+templates
+    .command('clone')
+    .description('Clone a template into a new draft. The cloned template has the same definition as the source (all phases, steps, sections, verification, uat, I/O wires) but fresh UUIDs for all step/phase IDs. The source template is unchanged. After cloning, use "tpl validate <new-id>" to verify, then "tpl activate" when ready.')
+    .argument('<sourceId>', 'Source template ID to clone from')
+    .requiredOption('--name <name>', 'Name for the new draft template')
+    .option('--description <desc>', 'Description for the new draft template')
+    .action(async (sourceId, opts) => {
+    try {
+        // Fetch source definition
+        const data = await api('GET', `/api/pipeline-templates/${sourceId}`);
+        const src = data.template;
+        // Deep-clone and remap all step/phase UUIDs so no shared IDs exist
+        const srcDef = JSON.parse(JSON.stringify(src.definition));
+        // Build a UUID remap table: old id → new id for phases and steps
+        const idMap = new Map();
+        for (const phase of srcDef.phases || []) {
+            idMap.set(phase.id, crypto.randomUUID());
+            for (const step of phase.steps || []) {
+                idMap.set(step.id, crypto.randomUUID());
+            }
+        }
+        // Apply remapping throughout the definition
+        for (const phase of srcDef.phases || []) {
+            phase.id = idMap.get(phase.id);
+            for (const step of phase.steps || []) {
+                step.id = idMap.get(step.id);
+                // Remap step input source_step_id references
+                for (const inp of step.inputs || []) {
+                    if (inp.source_step_id && idMap.has(inp.source_step_id)) {
+                        inp.source_step_id = idMap.get(inp.source_step_id);
+                    }
                 }
             }
         }
+        // Create new draft template
+        const body = { name: opts.name, definition: srcDef };
+        if (opts.description)
+            body.description = opts.description;
+        const created = await api('POST', '/api/pipeline-templates', body);
+        const newTpl = created.template;
+        console.log(chalk.green(`Cloned: ${newTpl.name}`));
+        console.log(`  ID: ${newTpl.id}`);
+        console.log(`  Source: ${src.name} (${sourceId})`);
+        console.log(chalk.dim(`  Run "fazemos tpl validate ${newTpl.id}" to verify the clone.`));
     }
     catch (err) {
         console.error(chalk.red(err.message));
@@ -3432,7 +3921,7 @@ templates
     .argument('<templateId>', 'Template ID')
     .requiredOption('--phase <phaseId>', 'Phase ID (from "tpl phases", "tpl show", or "tpl add-phase" output)')
     .requiredOption('--name <name>', 'Step name (must be unique within the phase)')
-    .option('--type <type>', 'Step type: human (manual task), agent (AI agent), script (automated), gate (approval checkpoint)', 'human')
+    .option('--type <type>', 'Step type: human (manual task), agent (AI agent), script (automated), gate/human_approval (approval checkpoint — gate and human_approval are equivalent aliases)', 'human')
     .option('--role <role>', 'Role or agent name (e.g., "kate", "marco", "dev-team")')
     .option('--description <desc>', 'Step description')
     .option('--reviewer <reviewer>', 'Reviewer role for review steps')
@@ -3449,6 +3938,8 @@ templates
     .option('--agent-config <json>', 'Per-step agent config overrides as JSON (e.g., \'{"model":"opus","maxBudgetUsd":20}\'). Overrides agent member defaults for: model, maxBudgetUsd, maxTurns, timeoutMs, cwd, repos')
     .option('--stream-silence-abort-ms <ms>', 'Stream silence abort threshold in milliseconds (30000-1800000)', parseStreamSilenceAbortMs)
     .option('--eval-max-turns <n>', 'Evaluator turn budget for tool-enabled (agent) evals on this step (8-30). Has no effect on script-typed steps (rejected by API).', parseEvalMaxTurns)
+    .option('--verification <json>', 'Step-level verification config as JSON or @filepath (e.g., \'{"type":"endpoint","target":"{{pipeline.backend_endpoint_target}}",...}\'). Used for TOOL-3 Tooth-1 deploy-guard verification.')
+    .option('--uat <json>', 'Step-level UAT config as JSON or @filepath (e.g., \'{"primary_path":"{{pipeline.uat_primary_path}}","reachable_env":"dev",...}\'). Used for TOOL-3 Tooth-3 UAT replay.')
     .action(async (templateId, opts) => {
     try {
         if (!VALID_STEP_TYPES.includes(opts.type)) {
@@ -3512,6 +4003,16 @@ templates
             step.stream_silence_abort_ms = opts.streamSilenceAbortMs;
         if (opts.evalMaxTurns !== undefined)
             step.eval_max_turns = opts.evalMaxTurns;
+        if (opts.verification != null) {
+            const v = parseJsonOrFile(opts.verification, '--verification');
+            if (v !== null)
+                step.verification = v;
+        }
+        if (opts.uat != null) {
+            const u = parseJsonOrFile(opts.uat, '--uat');
+            if (u !== null)
+                step.uat = u;
+        }
         // Positioning: --after or --sort-order
         if (opts.after && opts.sortOrder !== undefined) {
             console.error(chalk.red('Cannot use both --after and --sort-order'));
@@ -3598,7 +4099,7 @@ templates
     .argument('<templateId>', 'Template ID')
     .requiredOption('--step <stepId>', 'Step ID (from "tpl steps" output)')
     .option('--name <name>', 'New step name (must be unique within the phase)')
-    .option('--type <type>', 'Step type: human, agent, script, gate')
+    .option('--type <type>', 'Step type: human, agent, script, gate/human_approval (gate and human_approval are equivalent aliases for approval checkpoint steps)')
     .option('--role <role>', 'Role or agent name')
     .option('--description <desc>', 'Description')
     .option('--reviewer <reviewer>', 'Reviewer role (empty string to clear)')
@@ -3614,6 +4115,8 @@ templates
     .option('--stream-silence-abort-ms <ms>', 'Stream silence abort threshold in milliseconds (30000-1800000)', parseStreamSilenceAbortMs)
     .option('--eval-max-turns <n>', 'Evaluator turn budget for tool-enabled (agent) evals on this step (8-30). Mutually exclusive with --clear-eval-max-turns.', parseEvalMaxTurns)
     .option('--clear-eval-max-turns', 'Remove a previously-set eval_max_turns from this step, reverting to runner default. Mutually exclusive with --eval-max-turns.')
+    .option('--verification <json>', 'Step-level verification config as JSON or @filepath. Empty string clears the field. (e.g., \'{"type":"endpoint","target":"{{pipeline.backend_endpoint_target}}",...}\')')
+    .option('--uat <json>', 'Step-level UAT config as JSON or @filepath. Empty string clears the field. (e.g., \'{"primary_path":"{{pipeline.uat_primary_path}}","reachable_env":"dev",...}\')')
     .action(async (templateId, opts) => {
     try {
         if (opts.evalMaxTurns !== undefined && opts.clearEvalMaxTurns) {
@@ -3625,7 +4128,8 @@ templates
             || opts.reviewer != null || opts.maxReviewCycles != null || opts.parallelGroup != null
             || opts.image || opts.command || opts.timeout !== undefined || opts.workingDir || opts.env
             || opts.agentConfig || opts.sections != null || opts.streamSilenceAbortMs !== undefined
-            || opts.evalMaxTurns !== undefined || opts.clearEvalMaxTurns;
+            || opts.evalMaxTurns !== undefined || opts.clearEvalMaxTurns
+            || opts.verification != null || opts.uat != null;
         if (!hasUpdate) {
             console.error(chalk.red('Provide at least one field to update'));
             process.exit(1);
@@ -3705,6 +4209,26 @@ templates
         else if (opts.clearEvalMaxTurns) {
             delete step.eval_max_turns;
         }
+        // verification block — empty string clears, any other value replaces
+        if (opts.verification != null) {
+            const v = parseJsonOrFile(opts.verification, '--verification');
+            if (v === null) {
+                delete step.verification;
+            }
+            else {
+                step.verification = v;
+            }
+        }
+        // uat block — empty string clears, any other value replaces
+        if (opts.uat != null) {
+            const u = parseJsonOrFile(opts.uat, '--uat');
+            if (u === null) {
+                delete step.uat;
+            }
+            else {
+                step.uat = u;
+            }
+        }
         await api('PUT', `/api/pipeline-templates/${templateId}`, { definition: t.definition });
         console.log(chalk.green(`Updated step: ${step.name}`));
     }
@@ -5828,25 +6352,127 @@ async function resolveAgentId(nameOrId) {
 }
 agentsCmd
     .command('register')
-    .description('Register an agent')
+    .description('Register an agent and optionally provision an API credential (fzm_ key) in the same call. ' +
+    'Credential provisioning is on by default (pass --no-provision-credential to opt out). ' +
+    'Owner/admin only when provisioning credentials; agent identities are rejected.')
     .requiredOption('-n, --name <name>', 'Agent display name')
     .option('-r, --roles <roles>', 'Comma-separated roles', (v) => v.split(','))
     .option('--model <model>', 'Model (e.g., opus, sonnet, system)', 'sonnet')
+    .option('--project <slug>', 'Project slug to scope the credential to (defaults to active project). Required when provisioning a credential.')
+    .option('--no-provision-credential', 'Skip credential provisioning. Default: credential IS provisioned (pass this flag to opt out).')
+    .option('--force-rotate', 'Rotate an existing credential — revoke the old key and mint a new one in the same transaction.')
+    .option('--json', 'Emit JSON instead of human-readable output')
+    // NOTE: --no-provision-credential is the sole option definition; Commander v12 automatically
+    // creates --provision-credential as the positive form and defaults provisionCredential to true.
     .action(async (opts) => {
     try {
+        // F42 — CLI defaults --provision-credential to true (Sage UX lock).
+        // opts.provisionCredential is `true` unless --no-provision-credential was passed (sets it to false).
+        const provisionCredential = opts.provisionCredential !== false;
+        // Resolve credentialProjectId from --project or active project when provisioning.
+        let credentialProjectId;
+        if (provisionCredential) {
+            if (opts.project) {
+                // Resolve slug → id via cache; refresh once on miss.
+                const orgId = getActiveOrgId();
+                if (orgId) {
+                    let proj = findProjectBySlug(orgId, opts.project);
+                    if (!proj) {
+                        await refreshAuthMeCache();
+                        proj = findProjectBySlug(orgId, opts.project);
+                    }
+                    if (proj) {
+                        credentialProjectId = proj.id;
+                    }
+                    else {
+                        const msg = `Unknown project: ${opts.project}`;
+                        if (opts.json) {
+                            console.log(JSON.stringify({ error: { code: 'UNKNOWN_PROJECT', message: msg } }));
+                        }
+                        else {
+                            console.error(chalk.red(msg));
+                            console.log(chalk.gray('Run: fazemos projects list'));
+                        }
+                        process.exit(1);
+                        return; // guard: process.exit is mocked in tests
+                    }
+                }
+            }
+            else {
+                credentialProjectId = getActiveProjectId() ?? undefined;
+            }
+            if (!credentialProjectId) {
+                const msg = 'No active Project. Pass --project <slug> or fazemos projects switch <slug>.';
+                if (opts.json) {
+                    console.log(JSON.stringify({ error: { code: 'NO_ACTIVE_PROJECT', message: msg } }));
+                }
+                else {
+                    console.error(chalk.red(msg));
+                }
+                process.exit(1);
+                return; // guard: process.exit is mocked in tests
+            }
+        }
+        const agentEntry = {
+            displayName: opts.name,
+            roles: opts.roles || [opts.name],
+            config: { model: opts.model },
+            provisionCredential,
+        };
+        if (provisionCredential) {
+            agentEntry.credentialProjectId = credentialProjectId;
+            if (opts.forceRotate)
+                agentEntry.forceRotate = true;
+        }
         const data = await api('POST', '/api/agents/register', {
-            agents: [{
-                    displayName: opts.name,
-                    roles: opts.roles || [opts.name],
-                    config: { model: opts.model },
-                }],
+            agents: [agentEntry],
         });
+        if (opts.json) {
+            console.log(JSON.stringify({ agents: data.agents }));
+            return;
+        }
         for (const a of data.agents) {
             const icon = a.status === 'created' ? chalk.green('✓') : a.status === 'updated' ? chalk.yellow('↻') : '○';
             console.log(`  ${icon} ${a.display_name} (${a.status}) — ${a.member_id}`);
+            // F42 — credential block (matches `fazemos api-keys create` rendering per Sage UX)
+            if (a.credential) {
+                const cred = a.credential;
+                if (cred.status === 'minted' || cred.status === 'rotated') {
+                    console.log('');
+                    console.log(chalk.green(`  API credential ${cred.status}: ${opts.name}-key`));
+                    console.log(`    Key:  ${chalk.yellow(cred.rawKey)}`);
+                    console.log(`    ID:   ${cred.apiKeyId}`);
+                    console.log('');
+                    console.log(chalk.red('    ⚠ Save this key now — it will not be shown again.'));
+                }
+                else if (cred.status === 'exists') {
+                    console.log(chalk.gray(`    (credential already provisioned — use --force-rotate to rotate)`));
+                }
+            }
+            if (a.auditLogId) {
+                console.log(chalk.gray(`    Audit: ${a.auditLogId}`));
+            }
         }
     }
     catch (err) {
+        if (opts.json) {
+            console.log(JSON.stringify({ error: { code: err.code ?? 'ERROR', message: err.message } }));
+            process.exit(1);
+        }
+        if (err instanceof ApiError) {
+            if (err.code === 'FORBIDDEN_ROLE') {
+                console.error(chalk.red('Access denied. Owner or admin role required to provision credentials. Agent identities are not permitted.'));
+                process.exit(1);
+            }
+            if (err.code === 'CREDENTIAL_PROJECT_REQUIRED') {
+                console.error(chalk.red('credentialProjectId is required when provisionCredential=true. Pass --project <slug>.'));
+                process.exit(1);
+            }
+            if (err.code === 'CREDENTIAL_PROVISION_FAILED') {
+                console.error(chalk.red('Credential provisioning failed — transaction rolled back. Try again or contact your admin.'));
+                process.exit(1);
+            }
+        }
         console.error(chalk.red(err.message));
         process.exit(1);
     }
@@ -8809,7 +9435,13 @@ registerGovernanceCommands(program);
 // Earlier `import.meta.url === file://${process.argv[1]}` check was wrong: the
 // bin shim's argv[1] is the shim path, not the dist/index.js path, so the guard
 // returned false and silently skipped parse.
-if (!process.env.VITEST)
-    program.parse();
+// parseAsync (not parse) so the async preAction hook that resolves the
+// directory-scoped org/project context can be awaited before any action runs.
+if (!process.env.VITEST) {
+    program.parseAsync().catch((err) => {
+        console.error(chalk.red(err?.message ?? String(err)));
+        process.exit(1);
+    });
+}
 export { program };
 //# sourceMappingURL=index.js.map