@formigio/fazemos-cli 0.10.50 → 0.10.52

package/dist/commands/secrets.d.ts

@@ -0,0 +1,34 @@
+/**
+ * F48 — Project Secrets Vault CLI commands.
+ *
+ * Exports `registerSecretsCommands(program)` which wires the following
+ * subcommands under `fazemos secrets`:
+ *
+ *   fazemos secrets set <NAME> [VALUE]
+ *     → POST /api/projects/:projectId/secrets  {name, value, scope}
+ *     Owner/admin only. Value is written to AWS Secrets Manager and NEVER
+ *     stored in Aurora or echoed in any response (R1/R4).
+ *
+ *   fazemos secrets list
+ *     → GET /api/projects/:projectId/secrets
+ *     All project members. Returns metadata only — never a value field.
+ *
+ *   fazemos secrets get <NAME>
+ *     → GET /api/projects/:projectId/secrets/:name  (owner-only)
+ *     Returns SM path + SM ARN for operator use. Value is NEVER returned
+ *     by this endpoint (SF-4 deliberate divergence from feature-spec AC2).
+ *     Break-glass value inspection is out-of-band via AWS CLI against SM ARN.
+ *
+ *   fazemos secrets delete <NAME>
+ *     → DELETE /api/projects/:projectId/secrets/:name (owner/admin)
+ *     Schedules SM deletion with a 7-day recovery window; soft-deletes Aurora
+ *     row. Prompts for confirmation unless --yes / -y is passed.
+ *
+ * Auth: all commands require a valid Cognito session + active project context.
+ * Project ID is threaded in the URL path (not the X-Fazemos-Project-Id header)
+ * so noProjectHeader: true is passed to api() on every call here.
+ *
+ * Spec: F48-execution-profiles-manifest.yaml §cli / §api (T4)
+ */
+import type { Command } from 'commander';
+export declare function registerSecretsCommands(program: Command): void;

package/dist/commands/secrets.js

@@ -0,0 +1,330 @@
+/**
+ * F48 — Project Secrets Vault CLI commands.
+ *
+ * Exports `registerSecretsCommands(program)` which wires the following
+ * subcommands under `fazemos secrets`:
+ *
+ *   fazemos secrets set <NAME> [VALUE]
+ *     → POST /api/projects/:projectId/secrets  {name, value, scope}
+ *     Owner/admin only. Value is written to AWS Secrets Manager and NEVER
+ *     stored in Aurora or echoed in any response (R1/R4).
+ *
+ *   fazemos secrets list
+ *     → GET /api/projects/:projectId/secrets
+ *     All project members. Returns metadata only — never a value field.
+ *
+ *   fazemos secrets get <NAME>
+ *     → GET /api/projects/:projectId/secrets/:name  (owner-only)
+ *     Returns SM path + SM ARN for operator use. Value is NEVER returned
+ *     by this endpoint (SF-4 deliberate divergence from feature-spec AC2).
+ *     Break-glass value inspection is out-of-band via AWS CLI against SM ARN.
+ *
+ *   fazemos secrets delete <NAME>
+ *     → DELETE /api/projects/:projectId/secrets/:name (owner/admin)
+ *     Schedules SM deletion with a 7-day recovery window; soft-deletes Aurora
+ *     row. Prompts for confirmation unless --yes / -y is passed.
+ *
+ * Auth: all commands require a valid Cognito session + active project context.
+ * Project ID is threaded in the URL path (not the X-Fazemos-Project-Id header)
+ * so noProjectHeader: true is passed to api() on every call here.
+ *
+ * Spec: F48-execution-profiles-manifest.yaml §cli / §api (T4)
+ */
+import chalk from 'chalk';
+import { readFileSync } from 'fs';
+import { createInterface } from 'readline';
+import { api, ApiError, resolveProjectIdBySlug } from '../api.js';
+// ── Project resolution ────────────────────────────────────────────────────────
+/**
+ * Resolve the active project ID for a secrets command.
+ *
+ * Applies the standard F15 resolution chain:
+ *   --project <slug> override → resolveProjectIdBySlug (cache + refresh)
+ *   active project from config → getActiveProjectId()
+ *
+ * Exits 1 with the uniform "requirement missing: project" block (KD9) if
+ * neither a slug override nor an active project can be found.
+ */
+async function requireProjectForSecrets(slugOverride) {
+    let projectId;
+    try {
+        projectId = await resolveProjectIdBySlug(slugOverride);
+    }
+    catch (err) {
+        // resolveProjectIdBySlug throws ApiError(UNKNOWN_PROJECT) on slug miss
+        console.error(chalk.red(err?.message ?? String(err)));
+        process.exit(1);
+    }
+    if (!projectId) {
+        console.error(chalk.red('Error: requirement missing: project'));
+        console.error('');
+        console.error(chalk.gray('Set one with:  fazemos projects switch <slug>'));
+        console.error(chalk.gray('Or pass:       --project <slug>'));
+        process.exit(1);
+    }
+    return projectId;
+}
+// ── Interactive value prompt ──────────────────────────────────────────────────
+/**
+ * Prompt for a secret value on a TTY, masking typed characters with *.
+ * Falls back to reading from piped stdin when process.stdin is not a TTY.
+ *
+ * Manifests the "echoed as ***" behaviour specified in the cli.commands.set
+ * behaviour block — typed input is not echoed in plaintext so the value does
+ * not appear in terminal scrollback.
+ */
+function promptSecretValue(name) {
+    return new Promise((resolve, reject) => {
+        if (!process.stdin.isTTY) {
+            // Piped stdin: accumulate all data, then trim trailing newline.
+            let data = '';
+            process.stdin.setEncoding('utf8');
+            process.stdin.on('data', (chunk) => { data += chunk; });
+            process.stdin.on('end', () => resolve(data.trimEnd()));
+            process.stdin.on('error', reject);
+            return;
+        }
+        // Interactive TTY: mask every typed character with *.
+        const rl = createInterface({
+            input: process.stdin,
+            output: process.stdout,
+            terminal: true,
+        });
+        // Override the readline output writer so typed chars appear as *.
+        // Only suppress the echoed input — the prompt text and the final newline
+        // are still written normally so the UX stays legible.
+        rl._writeToOutput = function (s) {
+            if (s === '\r\n' || s === '\n' || s === '\r') {
+                process.stdout.write('\n');
+            }
+            else if (s && s !== '\u0003') {
+                // Each typed character → one * (mask everything except Ctrl-C)
+                process.stdout.write('*');
+            }
+        };
+        // Write the prompt ourselves (before the readline question) so the
+        // question('') call does not emit a blank prefix.
+        process.stdout.write(`Enter value for ${chalk.cyan(name)}: `);
+        rl.question('', (answer) => {
+            rl.close();
+            resolve(answer);
+        });
+    });
+}
+// ── Confirmation prompt ───────────────────────────────────────────────────────
+/**
+ * Prompt for y/N confirmation. Returns true only if the user types 'y' or 'Y'.
+ * Defaults to NO on empty input or any other key (safe default for destructive
+ * operations like secret deletion).
+ */
+function confirmPrompt(message) {
+    return new Promise((resolve) => {
+        const rl = createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        rl.question(`${message} [y/N] `, (answer) => {
+            rl.close();
+            resolve(answer.trim().toLowerCase() === 'y');
+        });
+    });
+}
+// ── Command registration ──────────────────────────────────────────────────────
+export function registerSecretsCommands(program) {
+    const secrets = program
+        .command('secrets')
+        .description('Project secret management (F48 — secrets vault)');
+    // ── secrets set ────────────────────────────────────────────────────────────
+    secrets
+        .command('set')
+        .description('Write a project secret to the vault (owner/admin only). ' +
+        'Value is stored in AWS Secrets Manager — NEVER in Aurora or echoed back.')
+        .argument('<name>', 'Secret name — letters, numbers, and underscores only (max 256 chars)')
+        .argument('[value]', 'Secret value (omit to prompt interactively or pipe via stdin)')
+        .option('--value-from <file>', 'Read secret value from a file (avoids shell history)')
+        .option('--scope <scope>', "Secret scope (default: 'project'; only valid value in Phase A)", 'project')
+        .option('--project <slug>', 'Override active project for this call')
+        .action(async (name, valueArg, opts) => {
+        try {
+            const projectId = await requireProjectForSecrets(opts.project);
+            // Resolve value in priority order:
+            //   1. Positional arg  (provided inline — user accepts history risk)
+            //   2. --value-from <file>  (avoids shell history)
+            //   3. stdin (piped) or interactive masked prompt
+            let value;
+            if (valueArg !== undefined) {
+                value = valueArg;
+            }
+            else if (opts.valueFrom) {
+                try {
+                    value = readFileSync(opts.valueFrom, 'utf-8').trimEnd();
+                }
+                catch (err) {
+                    console.error(chalk.red(`Error reading --value-from file: ${err.message}`));
+                    process.exit(1);
+                }
+            }
+            else {
+                value = await promptSecretValue(name);
+            }
+            if (!value) {
+                console.error(chalk.red('Error: Secret value cannot be empty'));
+                process.exit(1);
+            }
+            const body = { name, value, scope: opts.scope };
+            // Project ID is in the URL path; suppress the X-Fazemos-Project-Id header
+            // to avoid a duplicate / mismatched header on path-scoped endpoints.
+            const data = await api('POST', `/api/projects/${projectId}/secrets`, body, { noProjectHeader: true });
+            console.log(chalk.green(`Secret ${name} written.`));
+            console.log(`  SM path: ${data.smPath}`);
+        }
+        catch (err) {
+            if (err instanceof ApiError) {
+                if (err.code === 'INSUFFICIENT_ROLE') {
+                    console.error(chalk.red('Error: Only project owners and admins can write secrets'));
+                }
+                else if (err.code === 'INVALID_NAME') {
+                    console.error(chalk.red('Error: Secret name must contain only letters, numbers, and underscores (max 256 chars)'));
+                }
+                else if (err.code === 'INVALID_SCOPE') {
+                    console.error(chalk.red("Error: --scope must be 'project'"));
+                }
+                else {
+                    console.error(chalk.red(err.message));
+                }
+            }
+            else {
+                console.error(chalk.red(err?.message ?? String(err)));
+            }
+            process.exit(1);
+        }
+    });
+    // ── secrets list ──────────────────────────────────────────────────────────
+    secrets
+        .command('list')
+        .description('List project secrets — metadata only, values are never returned')
+        .option('--project <slug>', 'Override active project for this call')
+        .action(async (opts) => {
+        try {
+            const projectId = await requireProjectForSecrets(opts.project);
+            const data = await api('GET', `/api/projects/${projectId}/secrets`, undefined, { noProjectHeader: true });
+            const items = data.secrets ?? [];
+            if (items.length === 0) {
+                console.log(chalk.yellow('No secrets'));
+                return;
+            }
+            // Compute column widths from data (minimum widths from header labels).
+            const nameW = Math.max(4, ...items.map((s) => String(s.name ?? '').length));
+            const scopeW = Math.max(5, ...items.map((s) => String(s.scope ?? '').length));
+            const pathW = Math.max(7, ...items.map((s) => String(s.smPath ?? '').length));
+            const header = [
+                'NAME'.padEnd(nameW),
+                'SCOPE'.padEnd(scopeW),
+                'SM PATH'.padEnd(pathW),
+                'CREATED AT',
+            ].join('  ');
+            console.log(chalk.gray(header));
+            console.log(chalk.gray('─'.repeat(header.length)));
+            for (const s of items) {
+                // Explicitly exclude any `value` field — the API contract forbids it,
+                // but the CLI must never print it even if the response accidentally
+                // includes one (R4: no Fazemos path ever returns plaintext values).
+                const created = s.createdAt
+                    ? new Date(s.createdAt).toLocaleString()
+                    : (s.created_at ?? '');
+                console.log([
+                    String(s.name ?? '').padEnd(nameW),
+                    String(s.scope ?? '').padEnd(scopeW),
+                    String(s.smPath ?? '').padEnd(pathW),
+                    created,
+                ].join('  '));
+            }
+        }
+        catch (err) {
+            console.error(chalk.red(err?.message ?? String(err)));
+            process.exit(1);
+        }
+    });
+    // ── secrets get ───────────────────────────────────────────────────────────
+    secrets
+        .command('get')
+        .description('Get secret metadata (owner-only). ' +
+        'Returns SM path + SM ARN — the value is NEVER returned by this command (SF-4). ' +
+        'Use the AWS CLI against the SM ARN for break-glass value inspection.')
+        .argument('<name>', 'Secret name')
+        .option('--project <slug>', 'Override active project for this call')
+        .action(async (name, opts) => {
+        try {
+            const projectId = await requireProjectForSecrets(opts.project);
+            const data = await api('GET', `/api/projects/${projectId}/secrets/${encodeURIComponent(name)}`, undefined, { noProjectHeader: true });
+            // NEVER print a value field — metadata-only (SF-4 / R4).
+            console.log(chalk.cyan(`Secret: ${data.name}`));
+            console.log(`  Scope:      ${data.scope}`);
+            console.log(`  SM path:    ${data.smPath}`);
+            console.log(`  SM ARN:     ${data.smArn ?? '(not yet populated)'}`);
+            console.log(`  Created by: ${data.createdByMemberId ?? '(unknown)'}`);
+            console.log(`  Created at: ${data.createdAt ? new Date(data.createdAt).toLocaleString() : ''}`);
+            console.log(`  Updated at: ${data.updatedAt ? new Date(data.updatedAt).toLocaleString() : ''}`);
+            console.log('');
+            console.log(chalk.gray('Break-glass value inspection: aws secretsmanager get-secret-value --secret-id <SM ARN above>'));
+        }
+        catch (err) {
+            if (err instanceof ApiError) {
+                if (err.code === 'INSUFFICIENT_ROLE') {
+                    console.error(chalk.red('Error: Only project owners can retrieve secret metadata'));
+                }
+                else if (err.code === 'SECRET_NOT_FOUND') {
+                    console.error(chalk.red(`Error: Secret '${name}' not found`));
+                }
+                else {
+                    console.error(chalk.red(err.message));
+                }
+            }
+            else {
+                console.error(chalk.red(err?.message ?? String(err)));
+            }
+            process.exit(1);
+        }
+    });
+    // ── secrets delete ────────────────────────────────────────────────────────
+    secrets
+        .command('delete')
+        .description('Delete a project secret (owner/admin only). ' +
+        'Schedules 7-day SM recovery window; soft-deletes the Aurora metadata row. ' +
+        'The secret can be re-created at the same name within the window.')
+        .argument('<name>', 'Secret name')
+        .option('--project <slug>', 'Override active project for this call')
+        .option('-y, --yes', 'Skip confirmation prompt')
+        .action(async (name, opts) => {
+        try {
+            const projectId = await requireProjectForSecrets(opts.project);
+            if (!opts.yes) {
+                const confirmed = await confirmPrompt(`Delete secret ${chalk.cyan(name)}? This schedules SM deletion with a 7-day recovery window.`);
+                if (!confirmed) {
+                    console.log('Aborted.');
+                    return;
+                }
+            }
+            await api('DELETE', `/api/projects/${projectId}/secrets/${encodeURIComponent(name)}`, undefined, { noProjectHeader: true });
+            console.log(chalk.green(`Secret ${name} deleted (7-day SM recovery window).`));
+        }
+        catch (err) {
+            if (err instanceof ApiError) {
+                if (err.code === 'INSUFFICIENT_ROLE') {
+                    console.error(chalk.red('Error: Only project owners and admins can delete secrets'));
+                }
+                else if (err.code === 'SECRET_NOT_FOUND') {
+                    console.error(chalk.red(`Error: Secret '${name}' not found`));
+                }
+                else {
+                    console.error(chalk.red(err.message));
+                }
+            }
+            else {
+                console.error(chalk.red(err?.message ?? String(err)));
+            }
+            process.exit(1);
+        }
+    });
+}
+//# sourceMappingURL=secrets.js.map

package/dist/commands/secrets.js.map

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

package/dist/index.js

@@ -25,6 +25,7 @@ import { registerAutoStartCommands } from './autostart.js';
 import { registerFtrCommand } from './ftr.js';
 import { registerScheduleCommands } from './schedule.js';
 import { registerApprovalsCommands } from './approvals.js';
+import { registerSecretsCommands } from './commands/secrets.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';
@@ -1294,6 +1295,72 @@ function readScopeOpts(opts) {
         return { projectSlug: opts.project };
     return {};
 }
+/**
+ * P-TOOL-1 — render a rematerialize reconciliation plan (preview or applied).
+ *
+ * The plan has five step-disposition buckets:
+ *   preserved      completed/skipped steps kept frozen
+ *   rematerialized pending/blocked/failed steps re-derived from the new def
+ *   inserted       brand-new template steps
+ *   removed        step_instances absent from the new def
+ *   reset          completed downstream steps that --reset-downstream-of-new
+ *                  will RE-RUN (empty unless the flag is set) — the
+ *                  preview/apply-fidelity bucket, surfaced under "will RE-RUN".
+ *
+ * Each StepDisposition is { step_instance_id, template_step_id, step_name,
+ * action, from_status, to_status }. Warnings render yellow; blockers render red.
+ */
+function renderRematerializePlan(plan, warnings, blockers, render) {
+    // process.stderr for the blocked-path so the plan travels with the error;
+    // process.stdout otherwise. Commander's console.log/console.error split.
+    const out = render.blockedHeader ? console.error : console.log;
+    const p = plan ?? {};
+    const buckets = [
+        ['preserved', Array.isArray(p.preserved) ? p.preserved : []],
+        ['rematerialized', Array.isArray(p.rematerialized) ? p.rematerialized : []],
+        ['inserted', Array.isArray(p.inserted) ? p.inserted : []],
+        ['removed', Array.isArray(p.removed) ? p.removed : []],
+        ['reset', Array.isArray(p.reset) ? p.reset : []],
+    ];
+    // Count summary line.
+    const counts = buckets.map(([name, rows]) => `${name}: ${rows.length}`).join('  |  ');
+    out(chalk.gray(`  ${counts}`));
+    // Per-step table, grouped by disposition. reset[] gets a distinct
+    // "will RE-RUN" heading so an operator sees what apply will actually do.
+    const rowLine = (d) => {
+        const name = d?.step_name ?? d?.template_step_id ?? '(unknown)';
+        const from = d?.from_status ?? '—';
+        const to = d?.to_status ?? '—';
+        return from === to ? `      ${name}  [${to}]` : `      ${name}  ${from} → ${to}`;
+    };
+    for (const [name, rows] of buckets) {
+        if (rows.length === 0)
+            continue;
+        if (name === 'reset') {
+            out(chalk.magenta(`    will RE-RUN (reset ${rows.length}):`));
+        }
+        else {
+            out(chalk.cyan(`    ${name} (${rows.length}):`));
+        }
+        for (const d of rows)
+            out(rowLine(d));
+    }
+    const warns = Array.isArray(warnings) ? warnings : [];
+    if (warns.length) {
+        out(chalk.yellow(`  warnings (${warns.length}):`));
+        for (const w of warns) {
+            out(chalk.yellow(`    - ${w?.code ?? '?'}${w?.template_step_id ? ` [${w.template_step_id}]` : ''}: ${w?.detail ?? ''}`));
+        }
+    }
+    const blocks = Array.isArray(blockers) ? blockers : [];
+    if (blocks.length) {
+        out(chalk.red(`  blockers (${blocks.length}):`));
+        for (const b of blocks) {
+            const offending = Array.isArray(b?.offending) && b.offending.length ? ` (${b.offending.join(', ')})` : '';
+            out(chalk.red(`    - ${b?.code ?? '?'}: ${b?.detail ?? ''}${offending}`));
+        }
+    }
+}
 /**
  * Uniform error handler for scoped commands. When the API emits
  * MISSING_PROJECT_CONTEXT (§7.3.1), the api helper has already re-shaped
@@ -5419,6 +5486,132 @@ pipelines
         process.exit(1);
     }
 });
+// ── P-TOOL-1 — `pl rematerialize <instanceId>` ──
+// Rebase a live pipeline instance onto the CURRENT template definition without
+// losing completed-step state. Safe-by-default: WITHOUT --apply the verb runs a
+// preview (dry_run=true) and prints the reconciliation plan, mutating nothing.
+//
+//   POST /api/pipeline-instances/:id/rematerialize
+//   Body   : { dry_run | apply, reason?, force_inflight?, reset_downstream_of_new?, keep_failed? }
+//   Header : If-Match: "<n>"   (opt-in via --expect-version; default bypass)
+//
+// The API is itself safe-by-default (dry_run defaults to true server-side), so a
+// bare call previews. We are explicit anyway: send { dry_run: true } on preview
+// and { apply: true } on --apply. Owner/admin-only for apply and for the
+// dangerous --force-inflight / --reset-downstream-of-new flags (D5 SPLIT).
+pipelines
+    .command('rematerialize')
+    .description('Rebase a live pipeline instance onto the current template definition, preserving completed-step state. ' +
+    'Safe default: WITHOUT --apply it previews the reconciliation plan (mutates nothing). ' +
+    'With --apply it reconciles the instance in one transaction. Apply (and the --force-inflight / ' +
+    '--reset-downstream-of-new flags) require org owner or admin.')
+    .argument('<instanceId>', 'Pipeline instance ID')
+    .option('--apply', 'Perform the mutation. WITHOUT it the verb previews (dry_run=true) and prints the plan.')
+    .option('--force-inflight', 'Cancel in-flight step executions and reconcile anyway (D3 override). Owner/admin only.')
+    .option('--reset-downstream-of-new', 'Cascade-reset completed steps downstream of a newly-inserted step so they re-run (D6 override). Owner/admin only.')
+    .option('--keep-failed', 'Leave failed steps in "failed" instead of recovering them to "pending" (D4 opt-out).')
+    .option('-r, --reason <reason>', 'Free-form audit reason (recorded in audit_log on apply).')
+    .option('--expect-version <n>', 'Optimistic-concurrency guard: send If-Match: "<n>" so the API rejects the call (409 VERSION_CONFLICT) ' +
+    'if the current instance version differs. Omit to bypass version checking (default).')
+    .option('--json', 'Print the raw API response as JSON (machine-readable)')
+    .action(async (instanceId, opts) => {
+    try {
+        // Body field names match the API contract verbatim:
+        //   dry_run / apply           — mode select (preview vs mutate)
+        //   reason                    — optional audit string (apply only, but harmless on preview)
+        //   force_inflight            — D3 override
+        //   reset_downstream_of_new   — D6 override
+        //   keep_failed               — D4 opt-out
+        const apply = opts.apply === true;
+        const body = apply ? { apply: true } : { dry_run: true };
+        if (opts.forceInflight)
+            body.force_inflight = true;
+        if (opts.resetDownstreamOfNew)
+            body.reset_downstream_of_new = true;
+        if (opts.keepFailed)
+            body.keep_failed = true;
+        if (opts.reason)
+            body.reason = opts.reason;
+        // --expect-version <n> opts the caller in to optimistic concurrency.
+        // Default is bypass (no header), mirroring force-transition Decision #4.
+        const apiOpts = {};
+        if (opts.expectVersion !== undefined) {
+            const n = Number(opts.expectVersion);
+            if (!Number.isInteger(n)) {
+                console.error(chalk.red(`--expect-version must be an integer; got "${opts.expectVersion}"`));
+                process.exit(1);
+            }
+            apiOpts.headers = { 'If-Match': String(n) };
+        }
+        const path = `/api/pipeline-instances/${instanceId}/rematerialize`;
+        let data;
+        try {
+            data = (await api('POST', path, body, apiOpts));
+        }
+        catch (err) {
+            // 409 REMATERIALIZE_BLOCKED carries the plan + per-step blockers in its
+            // body; surface them so the operator sees exactly what to fix.
+            if (err instanceof ApiError && err.code === 'REMATERIALIZE_BLOCKED') {
+                if (opts.json) {
+                    console.log(JSON.stringify(err.body ?? { code: err.code, error: err.message }, null, 2));
+                    process.exit(1);
+                }
+                const b = (err.body ?? {});
+                console.error(chalk.red(`Rematerialize BLOCKED — instance ${instanceId} (template v${b.from_version} → v${b.to_version})`));
+                renderRematerializePlan(b.plan, b.warnings, b.blockers, { blockedHeader: true });
+                console.error(chalk.red('\nResolve the blockers above and retry.'));
+                process.exit(1);
+            }
+            // 409 VERSION_CONFLICT — the If-Match pin did not match the live version.
+            if (err instanceof ApiError && err.code === 'VERSION_CONFLICT') {
+                console.error(chalk.red(`Version conflict: the instance was modified concurrently (--expect-version mismatch). ${err.message}`));
+                process.exit(1);
+            }
+            // 403 owner/admin gate on apply / dangerous flags (or project-only agent).
+            if (err instanceof ApiError && err.status === 403) {
+                console.error(chalk.red(`Permission denied: ${err.message}`));
+                process.exit(1);
+            }
+            throw err;
+        }
+        if (opts.json) {
+            console.log(JSON.stringify(data, null, 2));
+            return;
+        }
+        // 200 ALREADY_CURRENT — idempotent no-op (returned as 200, not an error).
+        if (data?.already_current === true) {
+            console.log(chalk.green(`Already current: instance ${instanceId} is already on template v${data.to_version}. No changes made.`));
+            return;
+        }
+        if (data?.dry_run === true) {
+            // Preview mode — print the plan and the run-again hint.
+            console.log(chalk.bold(`Rematerialize preview — instance ${instanceId} (template v${data.from_version} → v${data.to_version})`));
+            renderRematerializePlan(data.plan, data.warnings, data.blockers, {});
+            if (Array.isArray(data.blockers) && data.blockers.length > 0) {
+                console.log(chalk.yellow('\nThis plan has blockers — apply would be refused (409 REMATERIALIZE_BLOCKED) until they are resolved.'));
+            }
+            console.log(chalk.gray('\nRun again with --apply to execute.'));
+            return;
+        }
+        // Applied — print the applied summary + forensic echo.
+        console.log(chalk.green(`Rematerialized instance ${instanceId} (template v${data.from_version} → v${data.to_version})`));
+        renderRematerializePlan(data.plan, data.warnings, data.blockers, {});
+        if (data?.audit_log_id) {
+            console.log(chalk.gray(`  audit_log_id: ${data.audit_log_id}`));
+        }
+        const queued = Array.isArray(data?.queued_step_ids) ? data.queued_step_ids : [];
+        if (queued.length) {
+            console.log(chalk.gray(`  queued_step_ids (${queued.length}): ${queued.join(', ')}`));
+        }
+        else {
+            console.log(chalk.gray('  queued_step_ids: (none)'));
+        }
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
 pipelines
     .command('set-params')
     .description('Set instance parameters (atomic update)')
@@ -9997,6 +10190,15 @@ registerScheduleCommands(program);
 // --reason is mandatory for resolve — CLI typed-token equivalent (OBD #1).
 // Auth: requireAuth + org membership (server-side, F37 shipped).
 registerApprovalsCommands(program);
+// ── F48 — Project Secrets Vault: secrets set / list / get / delete ────────────
+// Registers `secrets` top-level command with set, list, get, delete sub-commands.
+// All calls use project ID in the URL path (/api/projects/:projectId/secrets);
+// noProjectHeader: true on every call (path-scoped, not header-scoped).
+// set/delete: owner/admin only. get: owner-only (metadata+smArn, never value).
+// list: all project members (metadata only — values are never returned, R4).
+// set supports interactive masked input, --value-from <file>, positional arg,
+// and piped stdin. delete prompts for confirmation unless --yes / -y is passed.
+registerSecretsCommands(program);
 // Skip auto-parse only when running under Vitest (which sets process.env.VITEST).
 // Tests import `program` and drive it via `program.parseAsync(...)` after mocking
 // `./api.js`. In every other context — direct invocation, npx tsx, OR the bin