@waron97/prbot 3.4.0 → 3.5.0

package/README.md

@@ -4,6 +4,8 @@ CLI tool for managing PRs, changelogs, and Odoo workflow XML files in the addons
 
 ## Install
 
+Requires Node >= 20.
+
 ```bash
 npm install -g @waron97/prbot
 ```
@@ -129,9 +131,11 @@ prbot export workflow --no-commit
 
 Options:
 
-| Flag          | Description              |
-| ------------- | ------------------------ |
-| `--no-commit` | Skip the git commit step |
+| Flag           | Description                                                   |
+| -------------- | ------------------------------------------------------------- |
+| `--no-commit`  | Skip the git commit step                                      |
+| `-q, --quiet`  | Suppress informational output — errors still fail the command |
+| `-s, --silent` | Deprecated alias of `--quiet`; no longer swallows errors      |
 
 ### `prbot export pb`
 
@@ -144,9 +148,11 @@ prbot export pb --no-commit
 
 Options:
 
-| Flag          | Description              |
-| ------------- | ------------------------ |
-| `--no-commit` | Skip the git commit step |
+| Flag           | Description                                                   |
+| -------------- | ------------------------------------------------------------- |
+| `--no-commit`  | Skip the git commit step                                      |
+| `-q, --quiet`  | Suppress informational output — errors still fail the command |
+| `-s, --silent` | Deprecated alias of `--quiet`; no longer swallows errors      |
 
 ### `prbot export imperex`
 
@@ -159,9 +165,11 @@ prbot export imperex --no-commit
 
 Options:
 
-| Flag          | Description              |
-| ------------- | ------------------------ |
-| `--no-commit` | Skip the git commit step |
+| Flag           | Description                                                   |
+| -------------- | ------------------------------------------------------------- |
+| `--no-commit`  | Skip the git commit step                                      |
+| `-q, --quiet`  | Suppress informational output — errors still fail the command |
+| `-s, --silent` | Deprecated alias of `--quiet`; no longer swallows errors      |
 
 ### `prbot export email-templates`
 
@@ -174,9 +182,11 @@ prbot export email-templates --no-commit
 
 Options:
 
-| Flag          | Description              |
-| ------------- | ------------------------ |
-| `--no-commit` | Skip the git commit step |
+| Flag           | Description                                                   |
+| -------------- | ------------------------------------------------------------- |
+| `--no-commit`  | Skip the git commit step                                      |
+| `-q, --quiet`  | Suppress informational output — errors still fail the command |
+| `-s, --silent` | Deprecated alias of `--quiet`; no longer swallows errors      |
 
 ### `prbot init`
 
@@ -184,10 +194,11 @@ Interactive setup: writes `~/.config/prbot/config`.
 
 ### `prbot update`
 
-Reinstalls the latest published version from npm.
+Reinstalls prbot from npm — latest by default, or a pinned version.
 
 ```bash
-prbot update
+prbot update           # latest
+prbot update 3.4.0     # pin an exact version
 ```
 
 ---
@@ -225,26 +236,27 @@ agrippa clone --lrp --name B2WA_ml_IFS_passive_trigger --path my-lrp/
 
 Options:
 
-| Flag              | Description                                                                |
-| ----------------- | --------------------------------------------------------------------------- |
-| `--phase`         | Clone a phase (select a workflow)                                          |
-| `--mfa`           | Clone an MFA record                                                        |
-| `--pb`            | Clone a process-builder wizard                                             |
-| `--lrp`           | Clone a long-running process                                               |
-| `--id <id>`       | Skip selection, clone by ID (phase/mfa)                                    |
-| `--name <name>`   | Skip selection: `document_id` (with `--pb`) or process name (with `--lrp`) |
-| `--path <path>`   | Destination path (base dir for phases/wizard/lrp, file for MFA)            |
+| Flag            | Description                                                                |
+| --------------- | -------------------------------------------------------------------------- |
+| `--phase`       | Clone a phase (select a workflow)                                          |
+| `--mfa`         | Clone an MFA record                                                        |
+| `--pb`          | Clone a process-builder wizard                                             |
+| `--lrp`         | Clone a long-running process                                               |
+| `--id <id>`     | Skip selection, clone by ID (phase/mfa)                                    |
+| `--name <name>` | Skip selection: `document_id` (with `--pb`) or process name (with `--lrp`) |
+| `--path <path>` | Destination path (base dir for phases/wizard/lrp, file for MFA)            |
 
 ### `agrippa pull`
 
-Fetches remote code for all tracked entries and shows what changed. Classifies each as `fast-forward` (safe overwrite) or `conflict` (local edits would be lost). Lets you select which to pull.
+Fetches remote code for all tracked entries and shows what changed. Classifies each as `fast-forward` (safe overwrite) or `conflict` (local edits would be lost). `conflict` entries are shown but **not** preselected — you opt in explicitly. Lets you select which to pull.
 
 After pulling, also checks tracked workflows for newly added `from_code` phases and auto-clones any not yet present locally.
 
-Tracked **process-builder wizards** and **long-running processes** are also refreshed from upstream: the local project is re-decomposed from the latest payload (orphan script files pruned; PB wizards also prune orphan pages), with the same `fast-forward`/`conflict` classification (PB: upstream `updated_date`; LRP: re-resolved-by-name payload checksum vs. the last pulled state — LRPs have no stable id, so every pull re-resolves the current id/tenantId by name first). The current local state is backed up to `.backup/<timestamp>/<path>/local.json` first.
+Tracked **process-builder wizards** and **long-running processes** are also refreshed from upstream: the local project is re-decomposed from the latest payload (orphan script files pruned; PB wizards also prune orphan pages), with the same `fast-forward`/`conflict` classification — a semantic checksum of the recomposed payload (not raw `updated_date`), canonicalized so cosmetic noise never triggers a false conflict: whitespace-only BPMN text nodes, `format`-only `labelPos`, page ordering, and the `updated_date`/`modified_by` audit fields Odoo/Symple bump on any server touch are all excluded from the comparison. The current local state is backed up to `.backup/<timestamp>/<path>/local.json` first.
 
 ```bash
 agrippa pull
+agrippa pull --non-interactive  # no prompts: auto-select fast-forward, fail if any conflict
 ```
 
 ### `agrippa push`
@@ -257,18 +269,21 @@ Pushing a wizard saves it as a **draft**; publish it so live consumers see the c
 agrippa push                 # prompts whether to publish/deploy each pushed wizard/LRP
 agrippa push --publish       # auto-publish wizards, auto-deploy LRPs
 agrippa push --skip-publish  # never publish/deploy (no prompt)
+agrippa push --non-interactive  # no prompts: auto-select fast-forward, fail if any conflict;
+                                 # publish/deploy defaults to skip unless --publish is also passed
 ```
 
-### `agrippa diff [path]`
+### `agrippa diff [target]`
 
-Shows a diff between local files and remote code. Optionally filter to a specific file path.
+Shows a diff between local files and remote code. `[target]` optionally narrows it to a single file, a workflow folder, a cloned project directory, or a `document_id`/name; omit it for the whole workspace.
 
-For process-builder wizards, diffs the whole project tree against what the workspace would look like if the wizard were decomposed fresh from upstream right now (`.backup/` and `preview.svg` are excluded as local-only artifacts).
+For process-builder wizards and long-running processes, diffs the whole project tree against what the workspace would look like if the project were decomposed fresh from upstream right now (`.backup/` and `preview.svg` are excluded as local-only artifacts).
 
 ```bash
 agrippa diff
 agrippa diff my-workflow/some-phase.py
 agrippa diff ml_review_billing      # a cloned wizard's directory
+agrippa diff B2WA_M2C_passthrough   # a cloned LRP, by directory or name
 ```
 
 ### `agrippa init-phase`
@@ -295,15 +310,16 @@ These commands exist mainly so an **AI agent** can add/remove/connect blocks wit
 
 Newly added blocks get placeholder geometry. `pb format` re-lays-out the **whole** diagram (discarding any hand-tuned layout), so running it is a deliberate **human decision** — the alternative is positioning the new blocks by hand in the UI. Agents are expected to make structural edits but **not** to run `format` or to `pull`/`push`; a human reviews and syncs.
 
-| Command         | Purpose                                                                              |
-| --------------- | ------------------------------------------------------------------------------------ |
-| `pb format`     | Re-lay-out the **entire** diagram (elkjs, left→right); overwrites existing layout    |
-| `pb add`        | Add a node (`--type`, `--name`, `--parent`); scaffolds script/page files             |
-| `pb rm`         | Remove a node (`--id`), its edges, and its script/page files                         |
-| `pb connect`    | Add a flow (`--from`, `--to`, `--condition`, `--default`); enforces the gateway rule |
-| `pb disconnect` | Remove a flow (`--id`, or `--from`/`--to`)                                           |
-| `pb ls`         | List nodes and edges with their ids (discover targets without reading the YAML)      |
-| `pb preview`    | Render the diagram to an SVG (`--out`) for a quick visual check                      |
+| Command         | Purpose                                                                                                                                            |
+| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `pb format`     | Re-lay-out the **entire** diagram (elkjs, left→right); overwrites existing layout                                                                  |
+| `pb add`        | Add a node (`--type`, `--name`, `--parent`); scaffolds script/page files                                                                           |
+| `pb rm`         | Remove a node (`--id`), its edges, and its script/page files                                                                                       |
+| `pb connect`    | Add a flow (`--from`, `--to`, `--condition`, `--default`); enforces the gateway rule                                                               |
+| `pb disconnect` | Remove a flow (`--id`, or `--from`/`--to`); clears the source gateway's `default` if it pointed at that flow                                       |
+| `pb lint`       | Check the structural rules: gateway defaults/conditions, branch names, incoming-flow limits, and `default`s pointing at flows that no longer exist |
+| `pb ls`         | List nodes and edges with their ids (discover targets without reading the YAML)                                                                    |
+| `pb preview`    | Render the diagram to an SVG (`--out`) for a quick visual check                                                                                    |
 
 ```bash
 agrippa pb ls --pb ml_review_billing

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@waron97/prbot",
-    "version": "3.4.0",
+    "version": "3.5.0",
     "description": "",
     "main": "index.js",
     "engines": {

package/src/agrippa/commands/diff.js

@@ -15,6 +15,7 @@ import { getToken } from '../../lib/auth.js';
 import { error, log } from '../../lib/logger.js';
 import { computeChecksum } from '../lib/checksum.js';
 import { loadEffectiveEnv, readConfig } from '../lib/config.js';
+import { fetchUpstream } from '../lib/lrpApi.js';
 import { getProcess } from '../lib/pbApi.js';
 import { decompose, localChecksum } from '../lib/pbProject.js';
 import { projectReader, writeProject } from '../lib/pbWorkspace.js';
@@ -36,13 +37,24 @@ async function diff(targetArg) {
         return;
     }
 
-    const pbEntries = entries.filter((e) => e.object_type === 'process_builder');
-    const codeEntries = entries.filter((e) => e.object_type !== 'process_builder');
+    // Decomposed projects (pb + lrp) diff as whole directory trees; phases and
+    // MFAs are single code files. An LRP left in the code bucket used to reach
+    // readCodeFile() with a directory path and blow up with EISDIR, so the
+    // split is by "is this a project" rather than "is this a wizard".
+    const projectEntries = entries.filter((e) => PROJECT_TYPES.has(e.object_type));
+    const codeEntries = entries.filter((e) => !PROJECT_TYPES.has(e.object_type));
 
     if (codeEntries.length && !process.env.RIP_URL)
         throw new Error('RIP_URL is not configured. Run `prbot init` or set it in agrippa.yaml.');
-    if (pbEntries.length && !process.env.PB_URL)
+    if (projectEntries.some((e) => e.object_type === 'process_builder') && !process.env.PB_URL)
         throw new Error('PB_URL is not configured. Run `prbot init` or set it in agrippa.yaml.');
+    if (
+        projectEntries.some((e) => e.object_type === 'long_running_process') &&
+        !process.env.IMPORTEXPORT_URL
+    )
+        throw new Error(
+            'IMPORTEXPORT_URL is not configured. Run `prbot init` or set it in agrippa.yaml.'
+        );
 
     log('Fetching remote code...');
     const token = await getToken();
@@ -57,8 +69,8 @@ async function diff(targetArg) {
         chunks.push(...cs);
     }
 
-    for (const entry of pbEntries) {
-        const { hasDiff, chunk } = await diffPbEntry(token, entry);
+    for (const entry of projectEntries) {
+        const { hasDiff, chunk } = await diffProjectEntry(token, entry);
         if (hasDiff) {
             diffCount++;
             chunks.push(chunk);
@@ -124,14 +136,33 @@ function diffCodeEntries(entries, remoteCodeMap) {
     return { diffCount, chunks };
 }
 
-// Process-builder wizard: decompose the upstream payload into a throwaway
-// project tree (exactly what re-cloning now would produce) and diff it against
-// a copy of the local project, recursively. `.backup/` and `preview.svg` are
-// local-only artifacts (push backups, dev preview render) with no upstream
-// counterpart, so they're stripped from the local copy before diffing.
-async function diffPbEntry(token, entry) {
+// Decomposed project (process-builder wizard or long-running process): fetch
+// the upstream payload, decompose it into a throwaway project tree (exactly
+// what re-cloning now would produce) and diff it against a copy of the local
+// project, recursively. `.backup/` and `preview.svg` are local-only artifacts
+// (push backups, dev preview render) with no upstream counterpart, so they're
+// stripped from the local copy before diffing.
+//
+// The two types differ only in how upstream is reached: a wizard by guid, an
+// LRP by name (its tabulator id changes on every save — never a stable key,
+// see pullLrpEntry). Everything downstream is the shared decompose pipeline.
+const PROJECT_TYPES = new Set(['process_builder', 'long_running_process']);
+
+async function fetchProjectUpstream(token, entry) {
+    if (entry.object_type === 'long_running_process') {
+        const res = await fetchUpstream(token, entry.name);
+        if (!res?.payload) throw new Error(`could not fetch upstream LRP "${entry.name}"`);
+        return res.payload;
+    }
     const upstream = await getProcess(token, entry.guid);
     if (!upstream) throw new Error(`could not fetch upstream wizard ${entry.guid}`);
+    return upstream;
+}
+
+async function diffProjectEntry(token, entry) {
+    const upstream = await fetchProjectUpstream(token, entry);
+    const label =
+        entry.object_type === 'long_running_process' ? 'long-running process' : 'process-builder';
 
     const tmpRoot = mkdtempSync(join(tmpdir(), 'agrippa-pb-diff-'));
     try {
@@ -159,7 +190,7 @@ async function diffPbEntry(token, entry) {
         if (result.status !== null && result.status > 1) {
             error(`git diff failed for ${entry.path}`);
         }
-        const header = Buffer.from(`\n=== ${entry.path}  [${entry.name}] (process-builder) ===\n`);
+        const header = Buffer.from(`\n=== ${entry.path}  [${entry.name}] (${label}) ===\n`);
         const chunk = Buffer.concat([header, result.stdout ?? Buffer.alloc(0)]);
         return { hasDiff: true, chunk };
     } finally {
@@ -173,14 +204,21 @@ function filterEntries(workspace, targetArg) {
     // Normalise: strip trailing slash
     const target = targetArg.replace(/\/$/, '');
 
-    // If it exists on disk and is a directory, filter by prefix
+    // If it exists on disk and is a directory, take both the entries *under* it
+    // (a workflow folder holding one file per phase) and any entry that *is* it
+    // — a pb/lrp project is tracked as the directory itself, so prefix matching
+    // alone silently returned nothing for the most common target.
     if (existsSync(target) && statSync(target).isDirectory()) {
-        const prefix = target.endsWith('/') ? target : target + '/';
-        return workspace.filter((e) => e.path.startsWith(prefix));
+        const prefix = target + '/';
+        const matches = workspace.filter((e) => e.path === target || e.path.startsWith(prefix));
+        if (matches.length) return matches;
     }
 
-    // Otherwise treat as exact file path (whether it exists yet or not)
-    return workspace.filter((e) => e.path === target);
+    // Exact file path (whether it exists yet or not), else fall back to the
+    // identifiers the other commands accept — document_id (`--pb`) and name.
+    const byPath = workspace.filter((e) => e.path === target);
+    if (byPath.length) return byPath;
+    return workspace.filter((e) => e.document_id === target || e.name === target);
 }
 
 export { diff };

package/src/agrippa/commands/pb.js

@@ -218,6 +218,8 @@ async function pbRemove(opts) {
         `Removed ${result.removed.length} node(s) [${result.removed.join(', ')}], ` +
             `${result.removedEdges} dangling edge(s), ${deletes.length} file(s).`
     );
+    for (const c of result.clearedDefaults || [])
+        log(`  cleared dangling default ${c.edge} on ${c.node}.`);
 }
 
 async function pbConnect(opts) {
@@ -250,6 +252,8 @@ async function pbDisconnect(opts) {
     saveStructure(dir, structure);
     validate(dir);
     log(`Removed ${result.removed} edge(s)${result.id ? ` (${result.id})` : ''}.`);
+    for (const c of result.clearedDefaults || [])
+        log(`  cleared dangling default ${c.edge} on ${c.node}.`);
 }
 
 async function pbSetDefault(opts) {

package/src/agrippa/index.js

@@ -91,8 +91,11 @@ program
     );
 
 program
-    .command('diff [path]')
-    .description('Show differences between local files and remote code')
+    .command('diff [target]')
+    .description(
+        'Show differences between local files and remote code. [target] = file, folder, ' +
+            'project dir, document_id or name; omit for the whole workspace'
+    )
     .action((path) =>
         diff(path).catch((err) => {
             error(`Error: ${err.message}`);

package/src/agrippa/lib/pbEdit.js

@@ -317,7 +317,13 @@ function removeNode(structure, manifest, { id }) {
         );
     }
 
-    return { writes: {}, deletes, result: { removed: [...victimIds], removedEdges } };
+    const clearedDefaults = clearDanglingDefaults(structure);
+
+    return {
+        writes: {},
+        deletes,
+        result: { removed: [...victimIds], removedEdges, clearedDefaults },
+    };
 }
 
 // ---------- connect / disconnect ----------
@@ -492,15 +498,55 @@ function lintIncomingEdges(structure) {
     return issues;
 }
 
+// Flag `attrs.default` values that don't name an outgoing edge of their own
+// node. lintGateways only covers the inverse (a gateway that needs a default
+// and hasn't got a valid one), so a node left with a single outgoing flow and a
+// default pointing at a deleted one used to pass clean — and then fail at
+// publish with Activiti's null-reference NPE. The edits that delete edges now
+// clear these themselves (clearDanglingDefaults); this rule is the net for
+// hand-edited structure.yaml and for projects predating that fix.
+function lintDanglingDefaults(structure) {
+    const issues = [];
+    eachNode(structure.nodes, null, (n) => {
+        const def = n.attrs?.default;
+        if (!def) return;
+        if ((n.edges || []).some((e) => e.id === def)) return;
+        issues.push(
+            `${n.id} (${n.name || n.type}): default flow ${def} does not exist on this node — ` +
+                `Activiti fails the deploy on the dangling reference.`
+        );
+    });
+    return issues;
+}
+
 // Run all lint rules and return combined issues.
 function lintAll(structure) {
     return [
         ...lintGateways(structure),
+        ...lintDanglingDefaults(structure),
         ...lintEdgeNames(structure),
         ...lintIncomingEdges(structure),
     ];
 }
 
+// Drop every `attrs.default` that no longer names an outgoing edge of its own
+// node. Must run after any edit that deletes edges: a default referencing a
+// removed flow recomposes fine and passes the other lint rules, but Activiti
+// resolves the reference at deploy time, gets null, and the publish fails with
+// an unattributed `Could not deploy the XML: null. Error: null`. Returns the
+// cleared [nodeId, edgeId] pairs so callers can report them.
+function clearDanglingDefaults(structure) {
+    const cleared = [];
+    eachNode(structure.nodes, null, (n) => {
+        const def = n.attrs?.default;
+        if (!def) return;
+        if ((n.edges || []).some((e) => e.id === def)) return;
+        delete n.attrs.default;
+        cleared.push({ node: n.id, edge: def });
+    });
+    return cleared;
+}
+
 // Remove an edge by id, or by --from/--to pair.
 function disconnect(structure, { id, from, to }) {
     let removed = 0;
@@ -516,7 +562,8 @@ function disconnect(structure, { id, from, to }) {
         removed += before - n.edges.length;
     });
     if (!removed) throw new Error(id ? `edge not found: ${id}` : `no edge from ${from} to ${to}`);
-    return { writes: {}, deletes: [], result: { removed, id: removedId } };
+    const clearedDefaults = clearDanglingDefaults(structure);
+    return { writes: {}, deletes: [], result: { removed, id: removedId, clearedDefaults } };
 }
 
 // ---------- list ----------

package/src/agrippa/lib/pbProject.js

@@ -391,9 +391,29 @@ function stableStringify(value) {
 // to resync.
 const VOLATILE_AUDIT_FIELDS = ['updated_date', 'modified_by'];
 
+// `status`/`version` are the server's publication lifecycle, not content —
+// excluded for the same reason as the audit fields above, but only at the top
+// level (page wrappers carry neither). They surface in process.yaml via
+// EDITABLE_SCALARS and are still sent on push; they just don't count as a
+// change. Every PATCH flips the wizard server-side to draft/modified while
+// process.yaml keeps whatever status was recorded at the last clone/pull, and
+// push stores the *local* checksum as the new baseline — so a push not
+// followed by a publish guaranteed a phantom `conflict` on the next push,
+// with zero content difference on either side (observed live 2026-07-21 on
+// ml_voltura_fibra_data_input: upstream came back `modified` against a
+// `published` process.yaml, shifting the remote checksum off the baseline on
+// its own). `version` is worse still: a publish that bumps it server-side
+// pins the object to `conflict` permanently, since nothing local resyncs it.
+const VOLATILE_LIFECYCLE_FIELDS = ['status', 'version'];
+
 function canonicalForChecksum(payload) {
     const { process, decls } = normalizeProcessTree(payload.built_page);
-    const rest = omit(payload, ['built_page', 'pages', ...VOLATILE_AUDIT_FIELDS]);
+    const rest = omit(payload, [
+        'built_page',
+        'pages',
+        ...VOLATILE_AUDIT_FIELDS,
+        ...VOLATILE_LIFECYCLE_FIELDS,
+    ]);
     // Page order is not a stable identity — locally it's whatever order the
     // manifest happened to record at last decompose, while a live upstream
     // fetch can return the same set of pages in a different order (observed