@formigio/fazemos-cli 0.10.50 → 0.10.51

package/dist/index.js

@@ -1294,6 +1294,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 +5485,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)')