@waron97/prbot 3.3.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,8 +1,12 @@
 {
     "name": "@waron97/prbot",
-    "version": "3.3.0",
+    "version": "3.5.0",
     "description": "",
     "main": "index.js",
+    "engines": {
+        "node": ">=20.0.0"
+    },
+    "packageManager": "npm@10.9.8",
     "scripts": {
         "test": "echo \"Error: no test specified\" && exit 1"
     },

package/src/agrippa/commands/clone.js

@@ -3,6 +3,7 @@ import select from '@inquirer/select';
 import inquirer from 'inquirer';
 import { getToken } from '../../lib/auth.js';
 import { fuzzyMatch } from '../../lib/fuzzy.js';
+import { log, warn } from '../../lib/logger.js';
 import { describeWorkflow, getPhasesByWorkflow, listMfas, listWorkflows } from '../lib/api.js';
 import { computeChecksum } from '../lib/checksum.js';
 import { loadEffectiveEnv, readConfig, writeConfig } from '../lib/config.js';
@@ -42,7 +43,7 @@ async function clone(opts) {
     if (!ripUrl)
         throw new Error('RIP_URL is not configured. Run `prbot init` or set it in agrippa.yaml.');
 
-    console.log('Fetching records...');
+    log('Fetching records...');
     const token = await getToken();
 
     let records;
@@ -53,7 +54,7 @@ async function clone(opts) {
     }
 
     if (!records.length) {
-        console.log(`No ${objectType} records found.`);
+        log(`No ${objectType} records found.`);
         return;
     }
 
@@ -92,11 +93,11 @@ async function clone(opts) {
             basePath = inputPath;
         }
 
-        console.log(`Fetching phases for "${record.name}"...`);
+        log(`Fetching phases for "${record.name}"...`);
         const phases = await getPhasesByWorkflow(token, ripUrl, record.id, { fromCode: true });
 
         if (!phases.length) {
-            console.log('No phases found.');
+            log('No phases found.');
             return;
         }
 
@@ -112,19 +113,19 @@ async function clone(opts) {
                 checksum_at_pull: computeChecksum(phase.code),
                 name: `${record.name} / ${phase.name}`,
             });
-            console.log(`  wrote ${filePath}`);
+            log(`  wrote ${filePath}`);
         }
 
         // Drop the workflow graph alongside the phase files as read-only context.
         try {
             const structure = await describeWorkflow(token, ripUrl, record.id);
             const docPath = writeWorkflowDoc(basePath, structure);
-            console.log(`  wrote ${docPath}`);
+            log(`  wrote ${docPath}`);
         } catch (err) {
-            console.warn(`  could not fetch workflow structure: ${err.message}`);
+            warn(`  could not fetch workflow structure: ${err.message}`);
         }
 
-        console.log(`Cloned ${phases.length} phase(s) to ${basePath}/`);
+        log(`Cloned ${phases.length} phase(s) to ${basePath}/`);
     } else {
         const defaultPath = defaultMfaPath(record.model_name, record.name);
         if (!basePath) {
@@ -147,7 +148,7 @@ async function clone(opts) {
             checksum_at_pull: computeChecksum(record.code),
             name: `${record.model_name} / ${record.name}`,
         });
-        console.log(`Cloned MFA to ${basePath}`);
+        log(`Cloned MFA to ${basePath}`);
     }
 
     writeConfig(config);

package/src/agrippa/commands/cloneLrp.js

@@ -1,10 +1,10 @@
 import search from '@inquirer/search';
 import inquirer from 'inquirer';
 import { getToken } from '../../lib/auth.js';
-import { computeChecksum } from '../lib/checksum.js';
+import { log, warn } from '../../lib/logger.js';
 import { loadEffectiveEnv, readConfig, writeConfig } from '../lib/config.js';
 import { getLrpXml, listLrps, resolveLrpByName } from '../lib/lrpApi.js';
-import { comparePayload, decompose, recompose, stableStringify } from '../lib/pbProject.js';
+import { checksumOfPayload, comparePayload, decompose, recompose } from '../lib/pbProject.js';
 import { projectReader, writeProject } from '../lib/pbWorkspace.js';
 
 // Clone a long-running process (LRP). Structurally identical to a PB clone
@@ -32,7 +32,7 @@ async function cloneLrp(opts) {
     if (opts.name) {
         chosen = await resolveLrpByName(token, opts.name);
     } else {
-        console.log('Fetching long-running process list...');
+        log('Fetching long-running process list...');
         const initial = await listLrps(token, null);
         let controller = null;
         chosen = await search({
@@ -65,7 +65,7 @@ async function cloneLrp(opts) {
         dest = inputPath;
     }
 
-    console.log(`Fetching "${chosen.name}"...`);
+    log(`Fetching "${chosen.name}"...`);
     const { xml, description } = await getLrpXml(token, chosen.id);
     const payload = { built_page: xml };
 
@@ -73,7 +73,7 @@ async function cloneLrp(opts) {
     writeProject(dest, files);
 
     const scriptCount = Object.keys(files).filter((p) => p.startsWith('scripts/')).length;
-    console.log(`Cloned to ${dest}/  (${scriptCount} script(s)).`);
+    log(`Cloned to ${dest}/  (${scriptCount} script(s)).`);
 
     // Prove the clone reconstructs the original XML (0-loss bar A). LRPs have
     // no `pages` at all — recompose always synthesizes `pages: []`, which
@@ -82,10 +82,10 @@ async function cloneLrp(opts) {
     const rebuilt = recompose(projectReader(dest));
     const diffs = comparePayload(payload, rebuilt).filter((d) => !d.startsWith('pages:'));
     if (diffs.length) {
-        console.warn('WARNING: round-trip verification found differences:');
-        diffs.forEach((d) => console.warn('  - ' + d));
+        warn('WARNING: round-trip verification found differences:');
+        diffs.forEach((d) => warn('  - ' + d));
     } else {
-        console.log('Round-trip verified: recomposed payload is identical (0 information loss).');
+        log('Round-trip verified: recomposed payload is identical (0 information loss).');
     }
 
     // Register in the workspace for later pull/push — keyed by NAME, not id.
@@ -102,7 +102,7 @@ async function cloneLrp(opts) {
         description,
         // Baseline for push classification (see pull.js/push.js): checksum of
         // the *recomposed* payload, changes only when local files change.
-        checksum_at_pull: computeChecksum(stableStringify(rebuilt)),
+        checksum_at_pull: checksumOfPayload(rebuilt),
         version: chosen.version,
         status: chosen.status,
     };

package/src/agrippa/commands/clonePb.js

@@ -2,10 +2,10 @@ import search from '@inquirer/search';
 import inquirer from 'inquirer';
 import { getToken } from '../../lib/auth.js';
 import { fuzzyMatch } from '../../lib/fuzzy.js';
-import { computeChecksum } from '../lib/checksum.js';
+import { log, warn } from '../../lib/logger.js';
 import { loadEffectiveEnv, readConfig, writeConfig } from '../lib/config.js';
 import { getProcess, listProcesses } from '../lib/pbApi.js';
-import { comparePayload, decompose, recompose, stableStringify } from '../lib/pbProject.js';
+import { checksumOfPayload, comparePayload, decompose, recompose } from '../lib/pbProject.js';
 import { projectReader, writeProject } from '../lib/pbWorkspace.js';
 
 async function clonePb(opts) {
@@ -16,11 +16,11 @@ async function clonePb(opts) {
         throw new Error('PB_URL is not configured. Run `prbot init` or set it in agrippa.yaml.');
     }
 
-    console.log('Fetching process list...');
+    log('Fetching process list...');
     const token = await getToken();
     const processes = await listProcesses(token);
     if (!processes.length) {
-        console.log('No process-builder wizards found.');
+        log('No process-builder wizards found.');
         return;
     }
 
@@ -61,7 +61,7 @@ async function clonePb(opts) {
         dest = inputPath;
     }
 
-    console.log(`Fetching "${chosen.process_name}"...`);
+    log(`Fetching "${chosen.process_name}"...`);
     const payload = await getProcess(token, chosen.guid);
 
     const { files } = decompose(payload);
@@ -69,17 +69,17 @@ async function clonePb(opts) {
 
     const scriptCount = Object.keys(files).filter((p) => p.startsWith('scripts/')).length;
     const pageCount = Object.keys(files).filter((p) => p.startsWith('pages/')).length;
-    console.log(`Cloned to ${dest}/  (${scriptCount} script(s), ${pageCount} page(s))`);
+    log(`Cloned to ${dest}/  (${scriptCount} script(s), ${pageCount} page(s))`);
 
     // Prove the clone reconstructs the original payload (0-loss bar A) by
     // reading the files back from disk and recomposing.
     const rebuilt = recompose(projectReader(dest));
     const diffs = comparePayload(payload, rebuilt);
     if (diffs.length) {
-        console.warn('WARNING: round-trip verification found differences:');
-        diffs.forEach((d) => console.warn('  - ' + d));
+        warn('WARNING: round-trip verification found differences:');
+        diffs.forEach((d) => warn('  - ' + d));
     } else {
-        console.log('Round-trip verified: recomposed payload is identical (0 information loss).');
+        log('Round-trip verified: recomposed payload is identical (0 information loss).');
     }
 
     // Register in the workspace for later pull/push.
@@ -95,7 +95,7 @@ async function clonePb(opts) {
         name: chosen.process_name,
         // Baselines for `push` classification: checksum of the *recomposed* payload
         // (changes only when local files change) + upstream updated_date/status.
-        checksum_at_pull: computeChecksum(stableStringify(rebuilt)),
+        checksum_at_pull: checksumOfPayload(rebuilt),
         updated_date: payload.updated_date,
         status: payload.status,
     };

package/src/agrippa/commands/diff.js

@@ -12,8 +12,10 @@ import {
 import { tmpdir } from 'os';
 import { join } from 'path';
 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';
@@ -25,25 +27,36 @@ async function diff(targetArg) {
     loadEffectiveEnv(config);
 
     if (!config.workspace.length) {
-        console.log('No tracked resources. Run `agrippa clone` first.');
+        log('No tracked resources. Run `agrippa clone` first.');
         return;
     }
 
     const entries = filterEntries(config.workspace, targetArg);
     if (!entries.length) {
-        console.log('No tracked files match the given path.');
+        log('No tracked files match the given path.');
         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.'
+        );
 
-    console.log('Fetching remote code...');
+    log('Fetching remote code...');
     const token = await getToken();
 
     let diffCount = 0;
@@ -56,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);
@@ -65,13 +78,13 @@ async function diff(targetArg) {
     }
 
     if (diffCount === 0) {
-        console.log('No differences found — all tracked files match the remote.');
+        log('No differences found — all tracked files match the remote.');
     } else {
         const combined = Buffer.concat(chunks);
         const pager = process.env.PAGER || 'less';
         const pagerArgs = pager === 'less' ? ['-R', '-F'] : [];
         spawnSync(pager, pagerArgs, { input: combined, stdio: ['pipe', 'inherit', 'inherit'] });
-        console.log(`\n${diffCount} file(s) differ from remote.`);
+        log(`\n${diffCount} file(s) differ from remote.`);
     }
 }
 
@@ -90,7 +103,7 @@ function diffCodeEntries(entries, remoteCodeMap) {
             if (computeChecksum(localCode) === computeChecksum(remoteCode)) continue;
 
             if (!fileExists(entry.path)) {
-                console.log(`\n--- ${entry.path} (local file missing)`);
+                log(`\n--- ${entry.path} (local file missing)`);
                 continue;
             }
 
@@ -105,7 +118,7 @@ function diffCodeEntries(entries, remoteCodeMap) {
             );
             // exit code 1 means differences found (normal), 0 means identical, >1 means error
             if (result.status !== null && result.status > 1) {
-                console.error(`git diff failed for ${entry.path}`);
+                error(`git diff failed for ${entry.path}`);
             }
             const header = Buffer.from(`\n=== ${entry.path}  [${entry.name}] ===\n`);
             chunks.push(Buffer.concat([header, result.stdout ?? Buffer.alloc(0)]));
@@ -123,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 {
@@ -156,9 +188,9 @@ async function diffPbEntry(token, entry) {
             { cwd: tmpRoot, stdio: ['ignore', 'pipe', 'pipe'] }
         );
         if (result.status !== null && result.status > 1) {
-            console.error(`git diff failed for ${entry.path}`);
+            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 {
@@ -172,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/init.js

@@ -9,6 +9,7 @@ import {
 import { join } from 'path';
 import { fileURLToPath } from 'url';
 import inquirer from 'inquirer';
+import { log } from '../../lib/logger.js';
 import { WORKSPACE_FILE } from '../lib/config.js';
 
 const TEMPLATE = `# agrippa workspace configuration
@@ -93,23 +94,23 @@ async function init() {
             },
         ]);
         if (!overwrite) {
-            console.log('Skipped workspace file.');
+            log('Skipped workspace file.');
         } else {
             writeFileSync(WORKSPACE_FILE, TEMPLATE, 'utf-8');
-            console.log(`Created ${WORKSPACE_FILE}`);
-            console.log(`Run 'agrippa clone' to add resources to this workspace.`);
-            console.log(`Add ${WORKSPACE_FILE} to .gitignore if it contains credentials.`);
+            log(`Created ${WORKSPACE_FILE}`);
+            log(`Run 'agrippa clone' to add resources to this workspace.`);
+            log(`Add ${WORKSPACE_FILE} to .gitignore if it contains credentials.`);
         }
     } else {
         writeFileSync(WORKSPACE_FILE, TEMPLATE, 'utf-8');
-        console.log(`Created ${WORKSPACE_FILE}`);
-        console.log(`Run 'agrippa clone' to add resources to this workspace.`);
-        console.log(`Add ${WORKSPACE_FILE} to .gitignore if it contains credentials.`);
+        log(`Created ${WORKSPACE_FILE}`);
+        log(`Run 'agrippa clone' to add resources to this workspace.`);
+        log(`Add ${WORKSPACE_FILE} to .gitignore if it contains credentials.`);
     }
 
     if (!existsSync('pyproject.toml')) {
         writeFileSync('pyproject.toml', PYPROJECT_TOML, 'utf-8');
-        console.log('Created pyproject.toml (ruff builtins)');
+        log('Created pyproject.toml (ruff builtins)');
     }
 
     const { importTypings } = await inquirer.prompt([
@@ -124,7 +125,7 @@ async function init() {
     if (importTypings) {
         if (!existsSync('pyrightconfig.json')) {
             writeFileSync('pyrightconfig.json', PYRIGHTCONFIG, 'utf-8');
-            console.log('Created pyrightconfig.json');
+            log('Created pyrightconfig.json');
         }
 
         const typingsDir = fileURLToPath(new URL('../../../agrippa_typings', import.meta.url));
@@ -132,7 +133,7 @@ async function init() {
         for (const file of TYPING_FILES) {
             copyFileSync(join(typingsDir, file), join('typings', file));
         }
-        console.log(`Copied ${TYPING_FILES.length} type stubs to typings/`);
+        log(`Copied ${TYPING_FILES.length} type stubs to typings/`);
     }
 
     const { importInstructions } = await inquirer.prompt([
@@ -149,13 +150,13 @@ async function init() {
         const block = pbBlock(readFileSync(guidePath, 'utf-8'));
         if (!existsSync('CLAUDE.md')) {
             writeFileSync('CLAUDE.md', block, 'utf-8');
-            console.log('Created CLAUDE.md with agrippa-pb guidance');
+            log('Created CLAUDE.md with agrippa-pb guidance');
         } else {
             const current = readFileSync('CLAUDE.md', 'utf-8');
             const begin = current.indexOf(PB_BEGIN);
             if (begin === -1) {
                 appendFileSync('CLAUDE.md', `\n${block}`, 'utf-8');
-                console.log('Appended agrippa-pb guidance to CLAUDE.md');
+                log('Appended agrippa-pb guidance to CLAUDE.md');
             } else {
                 // Replace the existing managed block in place; leave the rest as-is.
                 const endIdx = current.indexOf(PB_END, begin);
@@ -165,7 +166,7 @@ async function init() {
                     );
                 const after = current.slice(endIdx + PB_END.length).replace(/^\n/, '');
                 writeFileSync('CLAUDE.md', current.slice(0, begin) + block + after, 'utf-8');
-                console.log('Refreshed agrippa-pb guidance in CLAUDE.md');
+                log('Refreshed agrippa-pb guidance in CLAUDE.md');
             }
         }
     }