@pipefy/pipefy-process-coder 0.1.0 → 0.1.1

package/dist/commands/plan.js

@@ -0,0 +1,301 @@
+import { resolve } from 'node:path';
+import { loadReference } from "../workspace/reference.js";
+import { bool, str } from "../cli/args.js";
+import { readJson, writeJson } from "../util/fsx.js";
+import { UserError, bold, dim, green, info, ok, out, red, warn, yellow } from "../util/log.js";
+import { readTree } from "../workspace/read.js";
+import { planFile, findPlanFile } from "../workspace/layout.js";
+import { diffTrees } from "../diff/diff.js";
+import { compile } from "../apply/compile.js";
+import { readAutomationCatalogue } from "../pipefy/automations.js";
+import { validateTree, renderFindings, blockingErrors } from "../validate/index.js";
+import { connect, openWorkspace } from "./context.js";
+import { loadBaseline, writeHtml, openViewer } from "./diff.js";
+export const help = `pipe plan [workspace] [options]
+
+  --repo <id>            which repo in the workspace (default: the root pipe)
+  --dry-run              print the plan and do not save it
+  --save                 save the plan to .ppc/plans/ (implied unless --dry-run)
+  --automation-recreate  delete+create automations instead of updating them in place
+  --allow-card-moves     permit phase deletes, which require moving cards first
+  --force                compile a plan even though some changes are unsupported
+  --html <file>          write the diff + plan as an HTML view
+  --open                 open that view
+  --json                 machine-readable output`;
+/**
+ * `pipe plan` — classify every change against the capability registry, refuse the
+ * unsupported ones by name, and order the rest.
+ *
+ * PLAN.md §5: any UNSUPPORTED change aborts here, with the entity and the
+ * reason. That refusal is the product working, not the product failing — the
+ * alternative is an apply that reports success having ignored something.
+ */
+/**
+ * The flow half of a plan.
+ *
+ * Extracted so it is reachable when the pipe half is clean — a flow-only change
+ * is the ordinary case now that flows are in the loop, and the early return for an
+ * empty pipe diff was reporting "nothing to do" over real pending work.
+ *
+ * Returns how much flow work there is, so the caller can decide whether "nothing
+ * to do" is still true.
+ */
+const planFlowHalf = async (p, root, dir, repoId) => {
+    if (bool(p, 'json') || bool(p, 'no-flows'))
+        return 0;
+    const { readFlows } = await import("../workspace/flows.js");
+    if (!(await readFlows(dir)))
+        return 0;
+    try {
+        const { diffFlowsAgainstLive, planFlows, renderFlowPlan } = await import("./flows.js");
+        const net = await connect(p);
+        const { changeSet: flowChanges, live } = await diffFlowsAgainstLive(net.ipaas, repoId, dir);
+        const flowPlan = planFlows(flowChanges, {
+            allowArm: bool(p, 'allow-flow-enable'),
+            connections: live.connections,
+        });
+        const rendered = renderFlowPlan(flowPlan);
+        if (rendered.trim()) {
+            out('');
+            out(bold('flows'));
+            out(rendered);
+        }
+        return flowPlan.steps.length + flowPlan.blocked.length;
+    }
+    catch (e) {
+        info(dim(`   flows not planned: ${e.message}`));
+        return 0;
+    }
+};
+/**
+ * The agent half of a plan. Offline, like the pipe half — the agent baseline is
+ * the file `pipe pull` wrote, not a live read — so unlike `planFlowHalf` this
+ * needs no network for the diff itself; only `planAgents` takes a client, and
+ * only to resolve nested input type names when one is available.
+ */
+const planAgentHalf = async (p, root, dir, repoId) => {
+    if (bool(p, 'json'))
+        return 0;
+    try {
+        const { diffAgentsFor, planAgents, renderAgentPlan } = await import("./agents.js");
+        const agentChanges = await diffAgentsFor(root, repoId, dir);
+        if (!agentChanges.changes.length)
+            return 0;
+        const net = await connect(p).catch(() => null);
+        const agentPlan = await planAgents(net?.client ?? null, agentChanges);
+        const rendered = renderAgentPlan(agentPlan);
+        if (rendered.trim()) {
+            out('');
+            out(bold('agents'));
+            out(rendered);
+        }
+        return agentPlan.steps.length;
+    }
+    catch (e) {
+        info(dim(`   agents not planned: ${e.message}`));
+        return 0;
+    }
+};
+export const run = async (p) => {
+    const { root, lock, repo, repoDir: dir } = await openWorkspace(p);
+    const edited = await readTree(dir);
+    const baseline = await loadBaseline(root, repo.id);
+    // Validation first: planning an invalid tree wastes a network round trip and
+    // produces a worse error message than validate does.
+    const { readAgents } = await import("../workspace/agents.js");
+    const findings = validateTree(edited, {
+        knownRepoIds: lock.repos.map((r) => r.id),
+        baseline,
+        reference: await loadReference(root),
+        agents: await readAgents(dir),
+    });
+    const blocking = blockingErrors(findings);
+    if (blocking.length) {
+        out(renderFindings(findings, `${repo.name ?? repo.id}`));
+        throw new UserError(`${blocking.length} validation error${blocking.length === 1 ? '' : 's'} — fix these before planning`);
+    }
+    const changeSet = diffTrees(baseline, edited);
+    if (!changeSet.changes.length) {
+        /**
+         * The pipe half is clean, which is not the same as nothing to do: a flow-only
+         * change is the ordinary case now that flows are in the loop, and returning
+         * here reported "nothing to do" over real pending work.
+         */
+        const flowWork = await planFlowHalf(p, root, dir, repo.id);
+        const agentWork = await planAgentHalf(p, root, dir, repo.id);
+        if (!flowWork && !agentWork)
+            ok('nothing to do — the workspace matches the baseline');
+        return 0;
+    }
+    const options = {
+        automationStrategy: bool(p, 'automation-recreate') ? 'recreate' : 'update',
+        allowCardMoves: bool(p, 'allow-card-moves'),
+        force: bool(p, 'force'),
+    };
+    /**
+     * Planning offline is a first-class mode, not a fallback: classification is a
+     * pure function of the ChangeSet and the registry, and it is the loop Claude
+     * iterates against. A missing token degrades the plan, it does not block it.
+     */
+    const net = await connect(p).catch((e) => {
+        if (e instanceof UserError) {
+            warn('planning offline — ' + e.message.toLowerCase());
+            return null;
+        }
+        throw e;
+    });
+    const caps = net ? await net.capabilities() : null;
+    const plan = await compile(changeSet, {
+        client: net?.client ?? null,
+        capabilities: caps,
+        repoId: repo.id,
+        repoUuid: repo.uuid,
+        workspace: root,
+        organizationId: lock.organizationId,
+        /**
+         * The automation catalogue, so a wrong event or action parameter is refused
+         * here rather than discovered as "is invalid" mid-apply. Offline planning has
+         * no client, and then the check is simply skipped.
+         */
+        automationCatalogue: net
+            ? await readAutomationCatalogue(net.client, repo.id).catch(() => undefined)
+            : undefined,
+        livePhaseIds: edited.phases.map((ph) => Number(ph['id'])).filter(Number.isFinite),
+        repoKind: repo.kind,
+        /** A database has one form, so its column order is that form's fields by index. */
+        tableFieldOrder: repo.kind === 'table'
+            ? [...(edited.phases[0]?.fields ?? [])].sort((a, b) => Number(a['index'] ?? 0) - Number(b['index'] ?? 0))
+            : undefined,
+        baselineTableFieldOrder: repo.kind === 'table'
+            ? [...(baseline?.phases[0]?.fields ?? [])]
+                .sort((a, b) => Number(a['index'] ?? 0) - Number(b['index'] ?? 0))
+                .map((f) => String(f['slug'] ?? ''))
+            : undefined,
+        fieldUuidById: Object.fromEntries(edited.phases
+            .flatMap((ph) => ph.fields)
+            .filter((fl) => fl['id'] && fl['uuid'])
+            .map((fl) => [String(fl['id']), String(fl['uuid'])])),
+        /** For `updateTable.title_field_id`, which refuses the numeric id. */
+        fieldSlugById: Object.fromEntries(edited.phases
+            .flatMap((ph) => ph.fields)
+            .filter((fl) => fl['id'] && fl['slug'])
+            .map((fl) => [String(fl['id']), String(fl['slug'])])),
+        startFormPhaseId: edited.phases.find((ph) => Number(ph['index'] ?? -1) === 0)?.['id'] ?? null,
+        conditionOrder: Object.fromEntries([...new Set(edited.field_conditions.map((fc) => String(fc['phase_id'] ?? '')))]
+            .filter((phaseId) => phaseId !== '')
+            .map((phaseId) => [
+            phaseId,
+            edited.field_conditions
+                .filter((fc) => String(fc['phase_id'] ?? '') === phaseId)
+                .slice()
+                .sort((a, b) => Number(a['index'] ?? 0) - Number(b['index'] ?? 0))
+                .map((fc) => ({ name: String(fc['name'] ?? ''), id: fc['id'] ? Number(fc['id']) : null })),
+        ])),
+        baselineConditionOrder: Object.fromEntries([...new Set((baseline?.field_conditions ?? []).map((fc) => String(fc['phase_id'] ?? '')))]
+            .filter((phaseId) => phaseId !== '')
+            .map((phaseId) => [
+            phaseId,
+            (baseline?.field_conditions ?? [])
+                .filter((fc) => String(fc['phase_id'] ?? '') === phaseId)
+                .slice()
+                .sort((a, b) => Number(a['index'] ?? 0) - Number(b['index'] ?? 0))
+                .map((fc) => String(fc['id'])),
+        ])),
+    }, options);
+    if (bool(p, 'json')) {
+        out(JSON.stringify(plan, null, 2));
+    }
+    else {
+        out(renderPlan(plan));
+    }
+    await planFlowHalf(p, root, dir, repo.id);
+    await planAgentHalf(p, root, dir, repo.id);
+    const htmlPath = str(p, 'html') ?? (bool(p, 'open') ? resolve(root, '.ppc', 'plan.html') : undefined);
+    if (htmlPath) {
+        await writeHtml(htmlPath, changeSet, root, plan);
+        info('');
+        ok(`HTML view written to ${htmlPath}`);
+        if (bool(p, 'open'))
+            await openViewer(htmlPath);
+    }
+    const dryRun = bool(p, 'dry-run');
+    if (!dryRun) {
+        const path = planFile(root, plan.id);
+        await writeJson(path, plan);
+        info('');
+        ok(`plan saved — ${dim(path)}`);
+        info(`${yellow('next')}  pipe apply ${dim(`--plan ${plan.id}`)}`);
+    }
+    if (plan.blocked.length && !options.force)
+        return 2;
+    return 0;
+};
+export const renderPlan = (plan) => {
+    const lines = [];
+    lines.push(bold(`plan ${plan.id}`));
+    lines.push(dim(`repo ${plan.repoId} · ${plan.mode} · automations: ${plan.options.automationStrategy}` +
+        `${plan.options.allowCardMoves ? ' · card moves allowed' : ''}`));
+    lines.push('');
+    if (plan.blocked.length) {
+        lines.push(red(`${plan.blocked.length} change${plan.blocked.length === 1 ? '' : 's'} cannot be applied:`));
+        for (const b of plan.blocked) {
+            lines.push(`  ${red('x')} ${bold(`${b.entity}.${b.op}`)} — ${b.label}`);
+            lines.push(`      ${dim(b.reason ?? 'no write path is registered')}`);
+            if (b.ask)
+                lines.push(`      ${dim(`would be fixed by platform ask ${b.ask} (ROUTE-B-V2.md §8)`)}`);
+        }
+        lines.push('');
+        lines.push(plan.options.force
+            ? yellow('--force given: the unsupported changes will be skipped and the rest applied')
+            : red('the apply is blocked. Revert these edits, or run with --force to apply only the rest.'));
+        lines.push('');
+    }
+    const partial = plan.classifications.filter((c) => c.status === 'PARTIAL');
+    if (partial.length) {
+        lines.push(yellow(`${partial.length} change${partial.length === 1 ? '' : 's'} apply through a partial path:`));
+        for (const c of partial)
+            lines.push(`  ${yellow('!')} ${c.entity}.${c.op} — ${c.label} ${dim(`(${c.via ?? ''})`)}`);
+        lines.push('');
+    }
+    if (plan.warnings.length) {
+        for (const w of plan.warnings)
+            lines.push(`${yellow('!')} ${w}`);
+        lines.push('');
+    }
+    lines.push(bold(`${plan.steps.length} step${plan.steps.length === 1 ? '' : 's'}`));
+    for (const s of plan.steps) {
+        const marks = [
+            s.destructive ? red('destructive') : '',
+            s.unverified ? yellow('unverified') : '',
+            s.kind.startsWith('internal') ? dim('internal-api') : '',
+            s.needs.length ? dim(`needs ${s.needs.length} id${s.needs.length === 1 ? '' : 's'}`) : '',
+        ]
+            .filter(Boolean)
+            .join(' ');
+        lines.push(`  ${dim(s.id)} ${s.description}${marks ? '  ' + marks : ''}`);
+    }
+    lines.push('');
+    const destructive = plan.steps.filter((s) => s.destructive).length;
+    lines.push(destructive
+        ? red(`${destructive} destructive step${destructive === 1 ? '' : 's'} — these delete configuration or data`)
+        : green('no destructive steps'));
+    return lines.join('\n');
+};
+export const loadPlan = async (root, planId) => {
+    try {
+        // A finished plan carries its outcome in the filename, so resolve rather
+        // than assume the bare `<id>.json`.
+        const found = await findPlanFile(root, planId);
+        return await readJson(found ?? planFile(root, planId));
+    }
+    catch {
+        throw new UserError(`no saved plan "${planId}" in ${root}/.ppc/plans`, 'run `pipe plan` first, or check `pipe status`');
+    }
+};
+export const warnUnverifiedSteps = (plan) => {
+    const unverified = plan.steps.filter((s) => s.unverified);
+    if (!unverified.length)
+        return;
+    warn(`${unverified.length} step${unverified.length === 1 ? '' : 's'} use a call whose shape could not be verified ` +
+        `against this schema (phase jumps, phase settings, public form). They report their own failure rather than silently no-op.`);
+};