@pipefy/pipefy-process-coder 0.1.0

package/src/commands/context.ts

@@ -0,0 +1,119 @@
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { LIMITS, credentialProvider, readOrgId, type Credential } from '../config.ts';
+import { exists } from '../util/fsx.ts';
+import { UserError, debug } from '../util/log.ts';
+import { PipefyClient } from '../pipefy/client.ts';
+import { InternalApi } from '../pipefy/internal.ts';
+import { SnapshotClient } from '../pipefy/snapshot.ts';
+import { Reconstructor } from '../pipefy/reconstruct.ts';
+import { IpaasClient } from '../pipefy/ipaas.ts';
+import { detect, type Capabilities } from '../pipefy/capability.ts';
+import { paths } from '../workspace/layout.ts';
+import { readLock, type Lock, type LockRepo } from '../workspace/lock.ts';
+import type { Parsed } from '../cli/args.ts';
+import { str } from '../cli/args.ts';
+
+/** Shared plumbing for every command that talks to Pipefy or to a workspace. */
+
+export type Net = {
+  client: PipefyClient;
+  internal: InternalApi;
+  snapshots: SnapshotClient;
+  reconstructor: Reconstructor;
+  /**
+   * A pipe's iPaaS workspace. Built from the internal API adapter, because the
+   * pipe-scoped token it needs is minted there — no second credential.
+   */
+  ipaas: IpaasClient;
+  organizationId: string | null;
+  /** Which credential won, for `pipe doctor` and the verbose log. */
+  credential: Credential;
+  capabilities: () => Promise<Capabilities>;
+};
+
+export const connect = async (p: Parsed): Promise<Net> => {
+  /**
+   * One credential, shared by the public client and the internal adapter, and
+   * expressed as a provider so a short-lived toolkit token can be refreshed
+   * mid-run rather than failing at step 90 of an apply.
+   */
+  const { provider, initial } = await credentialProvider();
+  debug(`credential source: ${initial.source}${initial.detail ? ` (${initial.detail})` : ''}`);
+
+  const client = new PipefyClient({ token: provider });
+  const internal = new InternalApi(provider);
+  const snapshots = new SnapshotClient(client);
+  const reconstructor = new Reconstructor(client, internal);
+  const ipaas = new IpaasClient(internal);
+  const organizationId = str(p, 'org') ?? (await readOrgId());
+
+  let caps: Capabilities | null = null;
+  return {
+    client,
+    internal,
+    snapshots,
+    reconstructor,
+    ipaas,
+    organizationId,
+    credential: initial,
+    capabilities: async () => {
+      caps ??= await detect(client, internal);
+      return caps;
+    },
+  };
+};
+
+/** Walk up from a directory looking for a workspace. */
+export const findWorkspace = async (start: string): Promise<string | null> => {
+  let dir = resolve(start);
+  for (;;) {
+    if (await exists(paths(dir).workspaceFile)) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+};
+
+export const resolveWorkspace = async (p: Parsed, positionalIndex = 0): Promise<string> => {
+  const explicit = p.positionals[positionalIndex] ?? str(p, 'workspace');
+  const start = explicit ? (isAbsolute(explicit) ? explicit : resolve(process.cwd(), explicit)) : process.cwd();
+  const found = await findWorkspace(start);
+  if (!found) {
+    throw new UserError(
+      `no pipe workspace found at or above ${start}`,
+      'run `pipe pull <pipeId> --out <dir>` first, or pass the workspace directory',
+    );
+  }
+  debug(`workspace: ${found}`);
+  return found;
+};
+
+export type WorkspaceContext = {
+  root: string;
+  lock: Lock;
+  /** The repo a command acts on: --repo, or the root repo. */
+  repo: LockRepo;
+  repoDir: string;
+};
+
+export const openWorkspace = async (p: Parsed, positionalIndex = 0): Promise<WorkspaceContext> => {
+  const root = await resolveWorkspace(p, positionalIndex);
+  const lock = await readLock(root);
+  if (!lock) throw new UserError(`${root} has no .ppc/lock.json`, 'the workspace is incomplete — re-run `pipe pull`');
+
+  const wanted = str(p, 'repo');
+  const repo = wanted
+    ? lock.repos.find((r) => String(r.id) === wanted || r.apiId === wanted || (r.name ?? '').toLowerCase() === wanted.toLowerCase())
+    : lock.repos.find((r) => r.id === lock.rootRepoId);
+
+  if (!repo) {
+    throw new UserError(
+      wanted ? `no repo "${wanted}" in this workspace` : 'the workspace lock names no root repo',
+      `available: ${lock.repos.map((r) => `${r.id} (${r.name})`).join(', ')}`,
+    );
+  }
+
+  return { root, lock, repo, repoDir: join(root, repo.dir) };
+};
+
+export const readConcurrency = () => LIMITS.readConcurrency;

package/src/commands/create.ts

@@ -0,0 +1,79 @@
+import { requirePositional, str, type Parsed } from '../cli/args.ts';
+import { bold, dim, info, ok, out, UserError, yellow } from '../util/log.ts';
+import { readOrgId } from '../config.ts';
+import { connect } from './context.ts';
+
+export const help = `pipe create <name> [options]
+
+  --org <id>       organization to create the pipe in (default: the stored org)
+  --icon <name>    pipe icon, e.g. rocket, target, chat
+  --out <dir>      workspace directory for the new pipe
+  --no-pull        just create it; do not build a workspace
+
+Creates an empty pipe and pulls it, so the next step is editing files. The
+structure — phases, fields, labels, automations — is then authored in the
+workspace and applied like any other change, which is the point: a pipe built
+this way is described by files from its first day rather than reverse-engineered
+into them later.`;
+
+export const run = async (p: Parsed) => {
+  const name = requirePositional(p, 0, 'a name for the new pipe');
+  const net = await connect(p);
+  const organizationId = str(p, 'org') ?? (await readOrgId());
+  if (!organizationId) {
+    throw new UserError(
+      'no organization id',
+      'pass --org <id>, or run `pipe login` again so the organization is stored',
+    );
+  }
+
+  const icon = str(p, 'icon');
+
+  info('');
+  info(bold(`pipe create ${JSON.stringify(name)}`));
+  info(dim(`organization ${organizationId}${icon ? ` · icon ${icon}` : ''}`));
+
+  /**
+   * Only name, organization and icon are sent, even though `CreatePipeInput`
+   * also takes phases, labels, start_form_fields and preferences.
+   *
+   * That is deliberate. Everything this tool can build, it should build through
+   * the same compile-and-apply path as any other change, so that the pipe's
+   * structure has a diff, a plan, and a run report behind it. Passing the whole
+   * structure to `createPipe` would produce a pipe nothing in the workspace can
+   * account for.
+   */
+  const res = await net.client.raw<{ createPipe: { pipe: { id: string; name: string } } }>(
+    `mutation createPipe($input: CreatePipeInput!) {
+      createPipe(input: $input) { pipe { id name } }
+    }`,
+    { input: { name, organization_id: organizationId, ...(icon ? { icon } : {}) } },
+    'createPipe',
+  );
+
+  const pipe = res?.createPipe?.pipe;
+  if (!pipe?.id) throw new UserError('createPipe returned no pipe', 'the endpoint accepted the call but answered with nothing');
+
+  ok(`pipe ${pipe.id} ${bold(pipe.name)} created`);
+
+  if (str(p, 'no-pull') !== undefined || p.flags['no-pull'] === true) {
+    out('');
+    out(`${yellow('next')}  pipe pull ${pipe.id} --out ./<dir>`);
+    return 0;
+  }
+
+  /**
+   * Pull it immediately. A new pipe is not empty — Pipefy gives it a start form
+   * and default phases — so the only honest starting point for editing is a read
+   * of what was actually created, not an assumption about it.
+   */
+  const pull = await import('./pull.ts');
+  await pull.run({
+    ...p,
+    command: 'pull',
+    positionals: [pipe.id],
+    flags: { ...p.flags, org: organizationId },
+  });
+
+  return 0;
+};

package/src/commands/diff.ts

@@ -0,0 +1,314 @@
+import { resolve } from 'node:path';
+import { spawn } from 'node:child_process';
+import { bool, str, type Parsed } from '../cli/args.ts';
+import { readJson, writeFile } from '../util/fsx.ts';
+import { UserError, bold, dim, info, ok, out, warn } from '../util/log.ts';
+import type { PayloadEnvelope } from '../model/payload.ts';
+import { unpack } from '../codec/unpack.ts';
+import { readTree } from '../workspace/read.ts';
+import { baselineFile, repoDir } from '../workspace/layout.ts';
+import { diffTrees, type ChangeSet } from '../diff/diff.ts';
+import { renderChangeSet, toJson } from '../diff/render.ts';
+import { renderHtml } from '../diff/html.ts';
+import { connect, openWorkspace } from './context.ts';
+import { diffFlowsFor } from './flows.ts';
+import { renderFlowChanges } from '../diff/flow.ts';
+import { diffAgentsFor } from './agents.ts';
+import type { RepoRef } from '../pipefy/discovery.ts';
+import type { Plan } from '../apply/types.ts';
+
+export const help = `pipe diff [workspace] [options]
+
+  --repo <id>          which repo in the workspace (default: the root pipe)
+  --against <target>   what to compare the edited tree against:
+                         baseline  (default) the payload captured by the last pull
+                         live                re-read the pipe now
+                         <pipeId>            another pipe — a cross-repo migration diff
+  --html <file>        write a standalone HTML diff view
+  --open               open the HTML view in the browser
+  --json               machine-readable output
+  --verbose-deltas     show every changed field, not the first six`;
+
+/**
+ * `pipe diff` — what changed, and against what.
+ *
+ * `--against <pipeId>` is the recipes' actual use case: comparing a dev pipe to
+ * a prod pipe and producing the change list to migrate. That runs in cross-repo
+ * mode, where matching falls back to the natural key (phase name, phase+label)
+ * exactly as the recipes match, and the resulting id map is what lets embedded
+ * field references be rewritten on apply.
+ */
+export const run = async (p: Parsed) => {
+  const { root, lock, repo, repoDir: dir } = await openWorkspace(p);
+  const against = str(p, 'against') ?? 'baseline';
+
+  const edited = await readTree(dir);
+  let baseline = await loadBaseline(root, repo.id);
+  let mode: ChangeSet['mode'] = 'same-repo';
+
+  if (against === 'live') {
+    const net = await connect(p);
+    const caps = await net.capabilities();
+    info(dim(`re-reading pipe ${repo.id} (${caps.snapshots ? 'snapshot' : 'GraphQL reconstruction'})`));
+    const env = caps.snapshots
+      ? await liveSnapshot(net, repo.id)
+      : await net.reconstructor.reconstruct(repo.id, { organizationId: lock.organizationId });
+    baseline = unpack(env);
+  } else if (against !== 'baseline') {
+    const otherId = Number(against);
+    if (!Number.isFinite(otherId)) {
+      throw new UserError(`--against must be baseline, live, or a numeric pipe id (got "${against}")`);
+    }
+    mode = 'cross-repo';
+    const inWorkspace = lock.repos.find((r) => r.id === otherId);
+    if (inWorkspace) {
+      baseline = await readTree(resolve(root, inWorkspace.dir));
+      info(dim(`comparing against ${inWorkspace.name} (${otherId}) from this workspace`));
+    } else {
+      const net = await connect(p);
+      const caps = await net.capabilities();
+      info(dim(`reading pipe ${otherId} live for a cross-repo diff`));
+      const env = caps.snapshots ? await liveSnapshot(net, otherId) : await net.reconstructor.reconstruct(otherId, { organizationId: lock.organizationId });
+      baseline = unpack(env);
+    }
+  }
+
+  /**
+   * In cross-repo mode the *target* is the pipe named by --against and the
+   * source is the workspace: "make that pipe look like this one". Same-repo mode
+   * is the ordinary edit loop: baseline -> edited.
+   */
+  const changeSet =
+    mode === 'cross-repo' ? diffTrees(baseline, edited, { mode }) : diffTrees(baseline, edited, { mode });
+
+  if (bool(p, 'json')) {
+    out(JSON.stringify(toJson(changeSet), null, 2));
+  } else {
+    out(renderChangeSet(changeSet, { verbose: bool(p, 'verbose-deltas') }));
+  }
+
+  /**
+   * The flow half.
+   *
+   * Reported in the same command because a pipe can diff clean while its actual
+   * behaviour changed entirely — the change was in a flow. A diff that stays
+   * silent about that is telling the user something false.
+   *
+   * Needs the network, unlike the pipe diff, since the flow baseline is the live
+   * workspace rather than a stored envelope. Skipped for --json and when there is
+   * no flows/ directory at all.
+   */
+  let flowExit = 0;
+  if (!bool(p, 'json') && !bool(p, 'no-flows') && mode === 'same-repo') {
+    const { readFlows } = await import('../workspace/flows.ts');
+    if (await readFlows(dir)) {
+      try {
+        // Only `--against live` needs the network; the baseline diff is offline.
+        const wantLive = against === 'live';
+        const net = wantLive ? await connect(p) : null;
+        const { changeSet: flowChanges } = await diffFlowsFor(net?.ipaas ?? null, repo.id, dir, {
+          against: wantLive ? 'live' : 'baseline',
+          workspaceRoot: root,
+        });
+        const rendered = renderFlowChanges(flowChanges);
+        if (rendered.trim()) {
+          out('');
+          out(bold('flows'));
+          out(rendered);
+        }
+        flowExit = flowChanges.changes.length;
+      } catch (e) {
+        info(dim(`   flows not compared: ${(e as Error).message}`));
+      }
+    }
+  }
+
+  /**
+   * The agent half. Offline, same as the pipe half — the agent baseline is a
+   * recorded file (workspace/agents.ts), not a live read, so `--against live`
+   * does not change anything here yet.
+   */
+  let agentExit = 0;
+  if (!bool(p, 'json') && mode === 'same-repo') {
+    try {
+      const { renderAgentChanges } = await import('../diff/agents.ts');
+      const agentChanges = await diffAgentsFor(root, repo.id, dir, { tree: edited });
+      const rendered = renderAgentChanges(agentChanges);
+      if (rendered.trim()) {
+        out('');
+        out(bold('agents'));
+        out(rendered);
+      }
+      agentExit = agentChanges.changes.length;
+    } catch (e) {
+      info(dim(`   agents not compared: ${(e as Error).message}`));
+    }
+  }
+
+  const htmlPath = str(p, 'html') ?? (bool(p, 'open') ? resolve(root, '.ppc', 'diff.html') : undefined);
+  if (htmlPath) {
+    await writeHtml(htmlPath, changeSet, root, null);
+    info('');
+    ok(`HTML diff written to ${htmlPath}`);
+    if (bool(p, 'open')) await openViewer(htmlPath);
+  }
+
+  /**
+   * The rest of the workspace, when no `--repo` narrowed it.
+   *
+   * `pipe diff` diffs one repo — the root, unless told otherwise — and a
+   * workspace holds several. That was a quiet trap even before databases: edit a
+   * connected pipe, run `pipe diff`, read "nothing to do". Databases make it
+   * routine, because a database is never the root: it is reached through a
+   * connector field or a relation, so every database edit lands in a repo this
+   * command was not looking at.
+   *
+   * Reported the way flows are: a repo with changes prints its **actual diff**
+   * under a heading, and the clean ones collapse to one line. A count plus a
+   * "now run this" was the first attempt and it was worse — you cannot review a
+   * change you have to run a second command to see, and the whole point of this
+   * command is to be the thing you read before applying.
+   *
+   * Offline: a tree read and a diff per repo, no network. Their changes count
+   * towards the exit code, because a workspace with pending edits is not clean
+   * just because the root happens to be.
+   */
+  let othersPending = 0;
+  if (!str(p, 'repo') && against === 'baseline' && lock.repos.length > 1) {
+    const clean: string[] = [];
+    const failed: string[] = [];
+    const changed: Array<{ label: string; rendered: string; count: number }> = [];
+
+    for (const other of lock.repos.filter((r) => r.id !== repo.id)) {
+      try {
+        const otherChanges = diffTrees(
+          await loadBaseline(root, other.id),
+          await readTree(resolve(root, other.dir)),
+          { mode: 'same-repo' },
+        );
+        if (otherChanges.changes.length) {
+          othersPending += otherChanges.changes.length;
+          changed.push({
+            /**
+             * `renderChangeSet` already names the repo and its numeric id, so this
+             * adds only what it cannot know: which kind of repo it is, and the api
+             * id you would pass to `--repo`.
+             */
+            label: `${other.kind}${other.apiId !== String(other.id) ? ` · ${other.apiId}` : ''}`,
+            rendered: renderChangeSet(otherChanges, { verbose: bool(p, 'verbose-deltas') }),
+            count: otherChanges.changes.length,
+          });
+        } else {
+          clean.push(String(other.name ?? other.id));
+        }
+      } catch (e) {
+        failed.push(`${other.name ?? other.id}: ${(e as Error).message}`);
+      }
+    }
+
+    for (const c of changed) {
+      out('');
+      out(bold(c.label));
+      out(c.rendered);
+    }
+    if (clean.length) {
+      out('');
+      out(dim(`${clean.length} other repo(s) clean: ${clean.join(', ')}`));
+    }
+    for (const f of failed) info(dim(`   not compared — ${f}`));
+    if (othersPending) {
+      out('');
+      info(dim('   each of those applies on its own: pipe apply --repo <id>'));
+    }
+  }
+
+  return changeSet.changes.length === 0 && flowExit === 0 && agentExit === 0 && othersPending === 0 ? 0 : 1;
+};
+
+/**
+ * The baseline as the envelope it is stored as, coverage and read path intact.
+ *
+ * `loadBaseline` unpacks to a tree, which is what the diff wants and what a run
+ * report does not: a report keeps the payload verbatim so the run folder is a
+ * usable copy of the pipe, not a reshaped one.
+ */
+export const loadBaselineEnvelope = async (root: string, repoId: number): Promise<PayloadEnvelope | null> => {
+  try {
+    return await readJson<PayloadEnvelope>(baselineFile(root, repoId));
+  } catch {
+    return null;
+  }
+};
+
+export const loadBaseline = async (root: string, repoId: number) => {
+  const path = baselineFile(root, repoId);
+  try {
+    const env = await readJson<PayloadEnvelope>(path);
+    return unpack(env);
+  } catch {
+    throw new UserError(
+      `no baseline for repo ${repoId} at ${path}`,
+      'the baseline is written by `pipe pull` — re-pull the workspace',
+    );
+  }
+};
+
+/** The baseline, or null, for callers where its absence is not an error. */
+export const loadBaselineQuiet = async (root: string, repoId: number) => {
+  try {
+    return await loadBaseline(root, repoId);
+  } catch {
+    return null;
+  }
+};
+
+const liveSnapshot = async (net: Awaited<ReturnType<typeof connect>>, repoId: number): Promise<PayloadEnvelope> => {
+  const { payload, versionId } = await net.snapshots.pull(repoId);
+  const { fullCoverage } = await import('../model/payload.ts');
+  return {
+    source: 'snapshot',
+    versionId,
+    readAt: new Date().toISOString(),
+    repoKind: 'pipe',
+    coverage: fullCoverage('complete'),
+    notes: [],
+    payload,
+  };
+};
+
+export const writeHtml = async (path: string, changeSet: ChangeSet, workspace: string, plan: Plan | null) => {
+  const html = renderHtml({ changeSet, plan, workspace, generatedAt: new Date().toISOString() });
+  await writeFile(path, html);
+  return path;
+};
+
+/**
+ * Open the HTML view in the OS browser, which needs no install at all.
+ *
+ * There was an Electron branch here that ran the page in a desktop shell when the
+ * dependency happened to be present. It went: this is a CLI, the browser renders
+ * the same file, and a GUI shell is a second product to keep working — including
+ * the only heavy devDependency in a repo whose whole point is having none.
+ */
+export const openViewer = async (htmlPath: string) => {
+  const cmd =
+    process.platform === 'win32' ? ['cmd', '/c', 'start', '', htmlPath] : process.platform === 'darwin' ? ['open', htmlPath] : ['xdg-open', htmlPath];
+  try {
+    spawn(cmd[0] as string, cmd.slice(1), { detached: true, stdio: 'ignore' }).unref();
+  } catch (e) {
+    warn(`could not open a viewer: ${(e as Error).message}`);
+    info(dim(`open this file manually: ${htmlPath}`));
+  }
+};
+
+export const refFor = (repo: { kind: 'pipe' | 'table'; id: number; apiId: string; name: string | null }): RepoRef => ({
+  kind: repo.kind,
+  id: repo.id,
+  apiId: repo.apiId,
+  name: repo.name,
+  uuid: null,
+  via: [],
+  depth: 0,
+});
+
+export const dirFor = (root: string, repo: Parameters<typeof refFor>[0]) => repoDir(root, refFor(repo));