@waron97/prbot 3.4.0 → 3.6.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.6.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

package/src/commands/autopr.js

@@ -7,6 +7,7 @@ import { resolveAddonsPath } from '../lib/addons.js';
 import { fuzzyMatch } from '../lib/fuzzy.js';
 import { execGit } from '../lib/git.js';
 import { log } from '../lib/logger.js';
+import { tridentRpc } from '../lib/trident.js';
 import {
     appendPrToLine,
     appendRefsToLine,
@@ -27,42 +28,11 @@ function devopsHeaders() {
 }
 
 async function fetchTask(taskId) {
-    const url = `${process.env.TRIDENT_URL}/jsonrpc`;
-    const body = {
-        jsonrpc: '2.0',
-        method: 'call',
-        id: 1,
-        params: {
-            service: 'object',
-            method: 'execute_kw',
-            args: [
-                process.env.TRIDENT_DB,
-                parseInt(process.env.TRIDENT_UID, 10),
-                process.env.TRIDENT_TOKEN,
-                'project.task',
-                'read',
-                [[parseInt(taskId, 10)]],
-                {
-                    fields: [
-                        'name',
-                        'x_subpackage_id',
-                        'x_workflow',
-                        'x_cluster_id',
-                        'x_release_checklist',
-                    ],
-                },
-            ],
-        },
-    };
-    const res = await fetch(url, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(body),
+    const result = await tridentRpc('project.task', 'read', [[parseInt(taskId, 10)]], {
+        fields: ['name', 'x_subpackage_id', 'x_workflow', 'x_cluster_id', 'x_release_checklist'],
     });
-    const data = await res.json();
-    if (data.error) throw new Error(`Trident error: ${JSON.stringify(data.error)}`);
-    if (!data.result || !data.result[0]) throw new Error(`Task ${taskId} not found`);
-    return data.result[0];
+    if (!result || !result[0]) throw new Error(`Task ${taskId} not found`);
+    return result[0];
 }
 
 function buildPrDescription(taskIds, jiras) {
@@ -124,30 +94,10 @@ async function createDevopsPR(branch, title, description) {
 async function appendChecklistPrLink(taskId, currentChecklist, prUrl) {
     const link = `<a href="${prUrl}">${prUrl}</a><br/>`;
     const updated = currentChecklist ? `${currentChecklist}\n${link}` : link;
-    const url = `${process.env.TRIDENT_URL}/jsonrpc`;
-    const res = await fetch(url, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({
-            jsonrpc: '2.0',
-            method: 'call',
-            id: 2,
-            params: {
-                service: 'object',
-                method: 'execute_kw',
-                args: [
-                    process.env.TRIDENT_DB,
-                    parseInt(process.env.TRIDENT_UID, 10),
-                    process.env.TRIDENT_TOKEN,
-                    'project.task',
-                    'write',
-                    [[parseInt(taskId, 10)], { x_release_checklist: updated }],
-                ],
-            },
-        }),
-    });
-    const data = await res.json();
-    if (data.error) throw new Error(`Trident write error: ${JSON.stringify(data.error)}`);
+    await tridentRpc('project.task', 'write', [
+        [parseInt(taskId, 10)],
+        { x_release_checklist: updated },
+    ]);
 }
 
 function scoreSections(sections, candidates) {

package/src/commands/doc.js

@@ -0,0 +1,93 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { htmlToMarkdown } from '../lib/html.js';
+import { log, warn } from '../lib/logger.js';
+import { tridentRpc } from '../lib/trident.js';
+
+async function fetchTaskDoc(taskId) {
+    const id = parseInt(taskId, 10);
+    const [task] = await tridentRpc('project.task', 'read', [[id]], {
+        fields: ['name', 'description'],
+    });
+    if (!task) throw new Error(`Task ${taskId} not found`);
+
+    const attachments = await tridentRpc(
+        'ir.attachment',
+        'search_read',
+        [
+            [
+                ['res_model', '=', 'project.task'],
+                ['res_id', '=', id],
+            ],
+        ],
+        { fields: ['name', 'datas', 'mimetype'] }
+    );
+
+    return { task, attachments };
+}
+
+// Strips path separators from an Odoo attachment name and de-dupes against
+// names already written into the same folder.
+function safeFilename(name, usedNames) {
+    const cleaned = (name || 'attachment').replace(/[/\\]/g, '_').trim() || 'attachment';
+    if (!usedNames.has(cleaned)) {
+        usedNames.add(cleaned);
+        return cleaned;
+    }
+    const ext = path.extname(cleaned);
+    const base = cleaned.slice(0, cleaned.length - ext.length);
+    let i = 2;
+    let candidate = `${base} (${i})${ext}`;
+    while (usedNames.has(candidate)) {
+        i += 1;
+        candidate = `${base} (${i})${ext}`;
+    }
+    usedNames.add(candidate);
+    return candidate;
+}
+
+async function writeTaskDoc(taskId, { task, attachments }) {
+    const dirName = `trident_${taskId}`;
+    const dir = path.join(process.cwd(), dirName);
+    await fs.mkdir(dir, { recursive: true });
+
+    const usedNames = new Set();
+    const writtenFiles = [];
+    for (const att of attachments) {
+        if (!att.datas) {
+            warn(`Warning: skipping attachment "${att.name}" (no downloadable content)`);
+            continue;
+        }
+        const filename = safeFilename(att.name, usedNames);
+        await fs.writeFile(path.join(dir, filename), Buffer.from(att.datas, 'base64'));
+        writtenFiles.push(filename);
+    }
+
+    const taskUrl = `${process.env.TRIDENT_URL}/odoo/my-tasks/${taskId}`;
+    const lines = [`# ${task.name}`, '', taskUrl, ''];
+    const body = htmlToMarkdown(task.description);
+    if (body) lines.push(body, '');
+
+    lines.push('## Attachments');
+    if (writtenFiles.length === 0) {
+        lines.push('', '_None_');
+    } else {
+        lines.push('', ...writtenFiles.map((f) => `- [${f}](./${f})`));
+    }
+
+    await fs.writeFile(path.join(dir, `${dirName}.md`), lines.join('\n') + '\n');
+    return dir;
+}
+
+async function doc(opts) {
+    const ids = opts.trident ?? [];
+    if (ids.length === 0) throw new Error('No Trident id: provide -t <id>');
+
+    for (const id of ids) {
+        const data = await fetchTaskDoc(id);
+        const dir = await writeTaskDoc(id, data);
+        log(`Wrote ${dir}`);
+    }
+}
+
+export { doc };

package/src/index.js

@@ -5,6 +5,7 @@ import { configDotenv } from 'dotenv';
 import { autopr } from './commands/autopr.js';
 import { changelog } from './commands/changelog.js';
 import { commit } from './commands/commit.js';
+import { doc } from './commands/doc.js';
 import {
     exportEmailTemplates,
     exportImperex,
@@ -143,6 +144,13 @@ program.command('commit').action(async (opts) => {
     await commit(opts);
 });
 
+program
+    .command('doc')
+    .option('-t, --trident <id>', 'Trident task IDs (repeatable)', collect)
+    .action(async (opts) => {
+        await doc(opts);
+    });
+
 const exportCmd = program.command('export');
 
 withQuiet(

package/src/lib/html.js

@@ -0,0 +1,117 @@
+// Small, dependency-free HTML→markdown converter. Not a general-purpose HTML
+// parser — it's sized to the markup Odoo actually produces for `project.task`
+// description fields (paragraphs, line breaks, bold/italic, links, lists,
+// inline images), which is enough to render usefully in a .md file. Anything
+// outside that (tables, nested lists, styled spans, ...) is stripped down to
+// its plain text rather than mis-rendered.
+
+function decodeEntities(str) {
+    return str
+        .replace(/ /gi, ' ')
+        .replace(/&/gi, '&')
+        .replace(/&lt;/gi, '<')
+        .replace(/&gt;/gi, '>')
+        .replace(/&quot;/gi, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&apos;/gi, "'");
+}
+
+function htmlToMarkdown(html) {
+    if (!html) return '';
+
+    let out = '';
+    let lastIndex = 0;
+    let match;
+    const listStack = []; // { type: 'ul' | 'ol', index: number }
+    const linkStack = []; // pending href for the currently-open <a>
+
+    // Raw text between tags: collapse the source's own whitespace/indentation
+    // into single spaces. Paragraph/line breaks are produced by the tag
+    // handling below, not by whitespace in the source.
+    function appendText(text) {
+        const cleaned = text.replace(/\s+/g, ' ');
+        if (cleaned.trim() === '') return;
+        out += cleaned;
+    }
+
+    const tagRe = /<(\/?)([a-zA-Z0-9]+)([^>]*)>/g;
+    while ((match = tagRe.exec(html)) !== null) {
+        const [, closing, rawTag, attrs] = match;
+        const tag = rawTag.toLowerCase();
+        appendText(html.slice(lastIndex, match.index));
+        lastIndex = tagRe.lastIndex;
+        const isClosing = closing === '/';
+
+        switch (tag) {
+            case 'br':
+                out += '\n';
+                break;
+            case 'p':
+            case 'div':
+                // Odoo commonly wraps list-item text in a <p> (<li><p>...</p></li>);
+                // inside a list, let <li> alone own the line breaks.
+                if (listStack.length === 0) out += '\n\n';
+                break;
+            case 'h1':
+            case 'h2':
+            case 'h3':
+            case 'h4':
+            case 'h5':
+            case 'h6':
+                out += isClosing ? '\n\n' : `\n\n${'#'.repeat(Number(tag[1]))} `;
+                break;
+            case 'strong':
+            case 'b':
+                out += '**';
+                break;
+            case 'em':
+            case 'i':
+                out += '_';
+                break;
+            case 'a':
+                if (!isClosing) {
+                    const hrefMatch = attrs.match(/href=["']([^"']*)["']/i);
+                    linkStack.push(hrefMatch ? hrefMatch[1] : '');
+                    out += '[';
+                } else {
+                    const href = linkStack.pop() ?? '';
+                    out += `](${href})`;
+                }
+                break;
+            case 'img': {
+                const srcMatch = attrs.match(/src=["']([^"']*)["']/i);
+                out += `![](${srcMatch ? srcMatch[1] : ''})`;
+                break;
+            }
+            case 'ul':
+            case 'ol':
+                if (!isClosing) listStack.push({ type: tag, index: 0 });
+                else listStack.pop();
+                out += '\n';
+                break;
+            case 'li':
+                if (!isClosing) {
+                    const ctx = listStack[listStack.length - 1];
+                    if (ctx && ctx.type === 'ol') {
+                        ctx.index += 1;
+                        out += `\n${ctx.index}. `;
+                    } else {
+                        out += '\n- ';
+                    }
+                }
+                break;
+            default:
+                // Unknown/unsupported tag (span, table, etc.): drop the tag,
+                // keep its text content via the surrounding appendText calls.
+                break;
+        }
+    }
+    appendText(html.slice(lastIndex));
+
+    return decodeEntities(out)
+        .replace(/[ \t]+\n/g, '\n')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+}
+
+export { htmlToMarkdown };

package/src/lib/trident.js

@@ -0,0 +1,34 @@
+import fetch from 'node-fetch';
+
+// Generic Odoo execute_kw call against Trident. Throws on transport or Odoo error.
+async function tridentRpc(model, method, args, kwargs = {}) {
+    const url = `${process.env.TRIDENT_URL}/jsonrpc`;
+    const body = {
+        jsonrpc: '2.0',
+        method: 'call',
+        id: 1,
+        params: {
+            service: 'object',
+            method: 'execute_kw',
+            args: [
+                process.env.TRIDENT_DB,
+                parseInt(process.env.TRIDENT_UID, 10),
+                process.env.TRIDENT_TOKEN,
+                model,
+                method,
+                args,
+                kwargs,
+            ],
+        },
+    };
+    const res = await fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+    const data = await res.json();
+    if (data.error) throw new Error(`Trident error: ${JSON.stringify(data.error)}`);
+    return data.result;
+}
+
+export { tridentRpc };