@pipefy/pipefy-process-coder 0.1.0

package/src/commands/plan.ts

@@ -0,0 +1,331 @@
+import { resolve } from 'node:path';
+import { loadReference } from '../workspace/reference.ts';
+import { bool, str, type Parsed } from '../cli/args.ts';
+import { readJson, writeJson } from '../util/fsx.ts';
+import { UserError, bold, dim, green, info, ok, out, red, warn, yellow } from '../util/log.ts';
+import { readTree } from '../workspace/read.ts';
+import { planFile, findPlanFile } from '../workspace/layout.ts';
+import { diffTrees } from '../diff/diff.ts';
+import { compile } from '../apply/compile.ts';
+import { readAutomationCatalogue } from '../pipefy/automations.ts';
+import type { Plan, PlanOptions } from '../apply/types.ts';
+import { validateTree, renderFindings, blockingErrors } from '../validate/index.ts';
+import { connect, openWorkspace } from './context.ts';
+import { loadBaseline, writeHtml, openViewer } from './diff.ts';
+
+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: Parsed, root: string, dir: string, repoId: number): Promise<number> => {
+  if (bool(p, 'json') || bool(p, 'no-flows')) return 0;
+  const { readFlows } = await import('../workspace/flows.ts');
+  if (!(await readFlows(dir))) return 0;
+  try {
+    const { diffFlowsAgainstLive, planFlows, renderFlowPlan } = await import('./flows.ts');
+    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 as Error).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: Parsed, root: string, dir: string, repoId: number): Promise<number> => {
+  if (bool(p, 'json')) return 0;
+  try {
+    const { diffAgentsFor, planAgents, renderAgentPlan } = await import('./agents.ts');
+    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 as Error).message}`));
+    return 0;
+  }
+};
+
+export const run = async (p: Parsed) => {
+  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.ts');
+  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: PlanOptions = {
+    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: unknown) => {
+    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'] as number | undefined) ?? 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: Plan): string => {
+  const lines: string[] = [];
+  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: string, planId: string): Promise<Plan> => {
+  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<Plan>(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: 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.`,
+  );
+};