@pipefy/pipefy-process-coder 0.1.0

package/src/apply/execute.ts

@@ -0,0 +1,336 @@
+import { writeJson } from '../util/fsx.ts';
+import { debug, dim, green, red, yellow } from '../util/log.ts';
+import { Progress } from '../util/tui.ts';
+import type { PipefyClient } from '../pipefy/client.ts';
+import type { InternalApi } from '../pipefy/internal.ts';
+import { IdMap } from './idmap.ts';
+import type { Plan, Step } from './types.ts';
+
+/**
+ * The executor. Non-atomic forward by necessity, so:
+ *
+ *  - every step's status is persisted to `.ppc/plans/<id>.json` as it runs, which
+ *    is what makes a failed apply resumable rather than a mystery
+ *  - ids created by a step are substituted into later steps at send time, not at
+ *    compile time (PLAN.md §9)
+ *  - a step that still depends on an unresolved placeholder is skipped with a
+ *    reason, never sent with a literal `%{_new:...}` in it
+ */
+
+export type ExecuteOpts = {
+  client: PipefyClient;
+  internal: InternalApi;
+  /** Where to persist step status. */
+  planPath: string;
+  dryRun: boolean;
+  /** Stop at the first failure (default) or keep going. */
+  continueOnError?: boolean;
+  onProgress?: (step: Step, plan: Plan) => void;
+};
+
+export type ExecuteResult = {
+  plan: Plan;
+  done: number;
+  failed: number;
+  skipped: number;
+  /** Steps never attempted because an earlier one failed. */
+  pending: number;
+  /**
+   * What each placeholder became. Verification needs it: the intent says
+   * `%{_new:<uuid>}` and the pipe holds the id the server chose, so without this
+   * the only options are to skip those values or to report them as differences.
+   */
+  idMap: IdMap;
+};
+
+const pluck = (obj: unknown, path: string[]): unknown => {
+  let cur: unknown = obj;
+  for (const key of path) {
+    if (cur && typeof cur === 'object' && key in (cur as Record<string, unknown>)) {
+      cur = (cur as Record<string, unknown>)[key];
+    } else {
+      return undefined;
+    }
+  }
+  return cur;
+};
+
+export const execute = async (plan: Plan, opts: ExecuteOpts): Promise<ExecuteResult> => {
+  const idMap = new IdMap(plan.idMap);
+  plan.status = 'running';
+
+  /**
+   * The step list, live. A plan is a queue of network calls whose count and
+   * order the user has already seen in `pipe plan`, so showing that same list
+   * fill in is the honest progress indicator — and in a dry run it shows exactly
+   * what would be sent, in order, without sending it.
+   */
+  const ui = new Progress({
+    title: opts.dryRun ? `dry run · ${plan.steps.length} steps` : `applying ${plan.steps.length} steps`,
+  });
+  for (const s of plan.steps) {
+    ui.add({
+      id: s.id,
+      label: s.description,
+      state: s.status === 'done' ? 'done' : 'pending',
+      tags: [
+        ...(s.destructive ? ['destructive'] : []),
+        ...(s.unverified ? ['unverified'] : []),
+        ...(s.kind.startsWith('internal') ? ['internal-api'] : []),
+      ],
+    });
+  }
+  ui.start();
+
+  const persist = async () => {
+    if (!opts.dryRun) await writeJson(opts.planPath, plan);
+  };
+
+  for (const s of plan.steps) {
+    if (s.status === 'done') {
+      // Resume: a completed create still has to re-register its placeholder so
+      // later steps can resolve against it.
+      if (s.produces && s.result !== undefined) {
+        const id = Number(pluck(s.result, s.produces.path));
+        if (Number.isFinite(id)) idMap.resolvePlaceholder(s.produces.placeholder, id, s.produces.aliases ?? []);
+      }
+      continue;
+    }
+
+    const unresolved = idMap.unresolved(s.request.variables ?? s.request.form ?? s.request.path ?? null);
+    if (unresolved.length) {
+      s.status = 'skipped';
+      s.error = `depends on ids that were never created: ${unresolved.join(', ')}`;
+      ui.update(s.id, { state: 'skipped', detail: s.error });
+      await persist();
+      continue;
+    }
+
+    const request = {
+      ...s.request,
+      variables: s.request.variables ? idMap.rewrite(s.request.variables) : undefined,
+      form: s.request.form ? idMap.rewrite(s.request.form) : undefined,
+      path: s.request.path ? (idMap.rewrite({ p: s.request.path }) as { p: string }).p : undefined,
+    };
+
+    /**
+     * Nothing leaves here still carrying a placeholder.
+     *
+     * A *registered* placeholder passes the unresolved check above, but is only
+     * substituted if its key is known to hold an id — so a new id-bearing key
+     * that nobody added to ID_BEARING_KEYS sends the marker to the API verbatim.
+     * That happened with `fieldConditionIds`, and the resulting error named the
+     * field but said nothing about the cause. This refuses to send, and says
+     * which key.
+     */
+    const leftovers: string[] = [];
+    const findMarkers = (v: unknown, path: string) => {
+      if (typeof v === 'string') {
+        if (v.includes('_new:')) leftovers.push(`${path} = ${v}`);
+        return;
+      }
+      if (Array.isArray(v)) {
+        v.forEach((x, i) => findMarkers(x, `${path}[${i}]`));
+        return;
+      }
+      if (v && typeof v === 'object') {
+        for (const [k, val] of Object.entries(v as Record<string, unknown>)) {
+          findMarkers(val, path ? `${path}.${k}` : k);
+        }
+      }
+    };
+    findMarkers(request.variables ?? null, '');
+    findMarkers(request.form ?? null, '');
+
+    if (leftovers.length) {
+      s.status = 'failed';
+      s.error =
+        `unsubstituted placeholder at ${leftovers.join(', ')} — that key is not in ID_BEARING_KEYS, ` +
+        'so nothing replaced it. Not sent.';
+      s.finishedAt = new Date().toISOString();
+      ui.update(s.id, { state: 'failed', detail: s.error });
+      await persist();
+      if (!opts.continueOnError) break;
+      continue;
+    }
+
+    if (opts.dryRun) {
+      s.status = 'skipped';
+      /**
+       * A dry run marks each step done in the display rather than skipped: the
+       * step is complete as far as this run goes, and painting a whole plan
+       * yellow suggests something went wrong when nothing did. The title says
+       * "dry run", and nothing was sent.
+       */
+      ui.update(s.id, { state: 'done', detail: 'not sent' });
+      debug(JSON.stringify(request.variables ?? request.form ?? {}).slice(0, 400));
+      opts.onProgress?.(s, plan);
+      continue;
+    }
+
+    s.status = 'running';
+    s.startedAt = new Date().toISOString();
+    await persist();
+    ui.update(s.id, { state: 'running' });
+
+    try {
+      let result: unknown;
+      if (s.kind === 'graphql') {
+        try {
+          result = await opts.client.raw(request.query as string, request.variables, s.request.mutation);
+        } catch (e) {
+          /**
+           * `phaseSettings` is known to answer "Something went wrong" for a change
+           * it has just made — observed twice, on two different runs, with the
+           * `phase_team_memberships` row present in the read-back both times and
+           * timestamped to the failing call. Its failures are therefore
+           * inconclusive, not negative, and saying so is the difference between
+           * an operator re-running a harmless write and an operator hunting a
+           * change that already exists.
+           */
+          if (s.request.mutation === 'phaseSettings') {
+            throw new Error(
+              `${(e as Error).message} — note that phaseSettings has been observed reporting this ` +
+                'for a change it did apply. Re-read the phase before assuming nothing happened.',
+            );
+          }
+          throw e;
+        }
+      } else if (s.kind === 'internal-graphql') {
+        result = await runInternalAutomationStep(opts.internal, s, request.variables ?? {});
+      } else if (s.kind === 'internal-rest') {
+        result = await runInternalRestStep(opts.internal, s, request);
+      } else {
+        result = { noop: true };
+      }
+
+      s.result = result;
+      s.status = 'done';
+      s.finishedAt = new Date().toISOString();
+      ui.update(s.id, { state: 'done' });
+
+      if (s.produces) {
+        const raw = pluck(result, s.produces.path);
+        const id = Number(raw);
+        if (Number.isFinite(id)) {
+          idMap.resolvePlaceholder(s.produces.placeholder, id, s.produces.aliases ?? []);
+        } else {
+          ui.note(yellow('! ') + `${s.id} succeeded but produced no id at ${s.produces.path.join('.')} — later steps may skip`);
+        }
+      }
+      opts.onProgress?.(s, plan);
+    } catch (e) {
+      s.status = 'failed';
+      s.error = (e as Error).message;
+      s.finishedAt = new Date().toISOString();
+      ui.update(s.id, { state: 'failed', detail: s.error });
+      await persist();
+      opts.onProgress?.(s, plan);
+      if (!opts.continueOnError) break;
+    }
+    await persist();
+  }
+
+  const counts = plan.steps.reduce(
+    (acc, s) => {
+      acc[s.status] = (acc[s.status] ?? 0) + 1;
+      return acc;
+    },
+    {} as Record<string, number>,
+  );
+
+  plan.status =
+    (counts['failed'] ?? 0) > 0
+      ? (counts['done'] ?? 0) > 0
+        ? 'partially-applied'
+        : 'failed'
+      : opts.dryRun
+        ? 'planned'
+        : 'applied';
+  await persist();
+
+  const done = counts['done'] ?? 0;
+  const failed = counts['failed'] ?? 0;
+  const skipped = counts['skipped'] ?? 0;
+
+  /**
+   * A dry run's steps are recorded as skipped, which is right for the plan file
+   * and wrong as a headline: "0 done, 2 skipped" reads like something went
+   * wrong. Nothing did — nothing was sent.
+   */
+  ui.stop(
+    opts.dryRun
+      ? '  ' + green(`${plan.steps.length} step${plan.steps.length === 1 ? '' : 's'} simulated`) + dim(', nothing sent')
+      : '  ' +
+          [
+            done ? green(`${done} done`) : dim('0 done'),
+            failed ? red(`${failed} failed`) : dim('0 failed'),
+            skipped ? yellow(`${skipped} skipped`) : dim('0 skipped'),
+          ].join(dim(' · ')) +
+          dim(` · ${(ui.elapsed / 1000).toFixed(1)}s`),
+  );
+
+  return {
+    plan,
+    done: counts['done'] ?? 0,
+    failed: counts['failed'] ?? 0,
+    skipped: counts['skipped'] ?? 0,
+    pending: counts['pending'] ?? 0,
+    idMap,
+  };
+};
+
+const runInternalAutomationStep = async (internal: InternalApi, s: Step, variables: Record<string, unknown>) => {
+  if (s.request.mutation === 'createAutomation') {
+    const created = await internal.createAutomation(variables);
+    if (!created) throw new Error('createAutomation returned no automation (internal API unavailable or rejected)');
+    return { createAutomation: { automation: created } };
+  }
+  if (s.request.mutation === 'deleteAutomation') {
+    const success = await internal.deleteAutomation(String(variables['id']));
+    if (!success) throw new Error(`deleteAutomation(${String(variables['id'])}) did not report success`);
+    return { deleteAutomation: { success } };
+  }
+  if (s.request.mutation === 'updateAutomation') {
+    const res = await internal.gql<Record<string, unknown>>(
+      `mutation updateAutomation($input: UpdateAutomationInput!) {
+        updateAutomation(input: $input) { automation { id } error_details { object_key messages } }
+      }`,
+      { input: variables },
+      'updateAutomation',
+    );
+    if (!res) throw new Error('updateAutomation failed on the internal endpoint');
+    return res;
+  }
+  throw new Error(`unknown internal mutation ${s.request.mutation}`);
+};
+
+const runInternalRestStep = async (internal: InternalApi, s: Step, request: Step['request']) => {
+  const phaseId = /\/phases\/([^/?]+)/.exec(request.path ?? '')?.[1];
+  if (!phaseId) throw new Error(`could not read a phase id out of ${request.path}`);
+  const targets = (request.form?.['phase[jump_target_ids][]'] ?? []).filter((t) => t !== '');
+
+  /**
+   * A jump target is an id and nothing else.
+   *
+   * The endpoint answers a malformed target with a bare 404, which reads as
+   * "that phase does not exist" and sends you looking in the wrong place. Every
+   * such 404 so far has been a substitution that did not happen — a placeholder
+   * rewritten to `%{344123894}` rather than to `344123894`. Checking the shape
+   * here names the real cause.
+   */
+  const malformed = targets.filter((t) => !/^[0-9]+$/.test(t));
+  if (malformed.length) {
+    throw new Error(
+      `jump target(s) ${malformed.join(', ')} are not ids — an id substitution did not happen. Not sent.`,
+    );
+  }
+
+  const res = await internal.setPhaseJumpTargets(phaseId, targets);
+  /**
+   * Assert on the echoed next_phase_ids, not on the HTTP status — PLAN.md §2.1.
+   * A 200 from an unversioned endpoint is not evidence that anything changed.
+   */
+  if (!res.ok) throw new Error(res.error ?? 'phase jump write could not be confirmed from the response');
+  return res;
+};