@waron97/prbot 3.1.4 → 3.2.0

package/src/agrippa/commands/push.js

@@ -1,26 +1,27 @@
 import { mkdirSync, writeFileSync } from 'fs';
 import { dirname, join } from 'path';
 import inquirer from 'inquirer';
-import { readConfig, writeConfig, loadEffectiveEnv } from '../lib/config.js';
-import { updatePhase, updateMfa } from '../lib/api.js';
 import { getToken } from '../../lib/auth.js';
+import { updateMfa, updatePhase } from '../lib/api.js';
 import { computeChecksum } from '../lib/checksum.js';
-import { readCodeFile, fileExists } from '../lib/workspace.js';
+import { loadEffectiveEnv, readConfig, writeConfig } from '../lib/config.js';
+import { getProcess } from '../lib/pbApi.js';
+import { localChecksum } from '../lib/pbProject.js';
+import { projectReader } from '../lib/pbWorkspace.js';
+import { fileExists, readCodeFile } from '../lib/workspace.js';
 import { fetchRemoteCode, selectEntries } from './pull.js';
+import { publish, pushPbEntry } from './pushPb.js';
 
 const BACKUP_DIR = '.backup';
 
-async function push() {
+async function push(opts = {}) {
     const config = readConfig();
     loadEffectiveEnv(config);
 
-    const ripUrl = process.env.RIP_URL;
-    if (!ripUrl) throw new Error('RIP_URL is not configured. Run `prbot init` or set it in agrippa.yaml.');
-
-    // Stale-file check
+    // Stale-entry check (a path may be a file for phase/mfa or a dir for pb).
     const stale = config.workspace.filter((e) => !fileExists(e.path));
     if (stale.length) {
-        console.log('\nThe following tracked files no longer exist on disk:');
+        console.log('\nThe following tracked resources no longer exist on disk:');
         stale.forEach((e) => console.log(`  - ${e.path}  (${e.name})`));
         const { cleanup } = await inquirer.prompt([
             {
@@ -41,86 +42,150 @@ async function push() {
         return;
     }
 
-    console.log('Fetching remote code...');
+    const hasCode = config.workspace.some(
+        (e) => e.object_type === 'phase' || e.object_type === 'mfa'
+    );
+    const hasPb = config.workspace.some((e) => e.object_type === 'process_builder');
+    const ripUrl = process.env.RIP_URL;
+    if (hasCode && !ripUrl)
+        throw new Error('RIP_URL is not configured. Run `prbot init` or set it in agrippa.yaml.');
+    if (hasPb && !process.env.PB_URL)
+        throw new Error('PB_URL is not configured. Run `prbot init` or set it in agrippa.yaml.');
+
+    console.log('Fetching remote state...');
     const token = await getToken();
 
-    const remoteCodeMap = await fetchRemoteCode(token, ripUrl, config.workspace);
+    const remoteCodeMap = hasCode
+        ? await fetchRemoteCode(token, ripUrl, config.workspace)
+        : new Map();
+    const upstreamMap = new Map();
+    for (const e of config.workspace.filter((x) => x.object_type === 'process_builder')) {
+        try {
+            upstreamMap.set(e.guid, await getProcess(token, e.guid));
+        } catch {
+            upstreamMap.set(e.guid, null);
+        }
+    }
 
-    // Classify — concern here is remote work being overwritten
+    // Classify every entry to a status badge — concern: overwriting remote work.
     const classified = config.workspace.map((entry) => {
+        if (entry.object_type === 'process_builder') {
+            const upstream = upstreamMap.get(entry.guid) ?? null;
+            const local = localChecksum(projectReader(entry.path));
+            const localChanged = entry.checksum_at_pull !== local;
+            const remoteChanged = !upstream || upstream.updated_date !== entry.updated_date;
+            let status;
+            if (!localChanged && !remoteChanged) status = 'unchanged';
+            else if (!remoteChanged) status = 'fast-forward';
+            else status = 'conflict';
+            return { ...entry, upstream, status };
+        }
+
         const key = `${entry.object_type}:${entry.id}`;
         const remoteCode = remoteCodeMap.get(key) ?? null;
         const localCode = readCodeFile(entry.path);
-
         const remoteChecksum = computeChecksum(remoteCode ?? '');
-        const localChecksum = computeChecksum(localCode ?? '');
+        const localChecksumVal = computeChecksum(localCode ?? '');
         const pullChecksum = entry.checksum_at_pull;
-
         let status;
-        if (pullChecksum === localChecksum && pullChecksum === remoteChecksum) {
+        if (pullChecksum === localChecksumVal && pullChecksum === remoteChecksum)
             status = 'unchanged';
-        } else if (pullChecksum === remoteChecksum) {
-            // remote untouched since last pull, local has new changes
-            status = 'fast-forward';
-        } else {
-            // remote changed since last pull — pushing will overwrite remote work
-            status = 'conflict';
-        }
-
+        else if (pullChecksum === remoteChecksum) status = 'fast-forward';
+        else status = 'conflict';
         return { ...entry, remoteCode, localCode, status };
     });
 
     const changed = classified.filter((e) => e.status !== 'unchanged');
-
     if (!changed.length) {
-        console.log('Nothing to push — local files match the last-pulled state.');
+        console.log('Nothing to push — everything matches the last-pulled state.');
         return;
     }
 
-    const selected = await selectEntries(changed, 'push (overwrites remote code)', 'push');
-
+    const selected = await selectEntries(changed, 'push (overwrites remote)', 'push');
     if (!selected.length) {
         console.log('Nothing selected. No changes made.');
         return;
     }
 
-    // Write backups of remote code before overwriting
-    const backupTs = new Date()
-        .toISOString()
-        .replace(/:/g, '-')
-        .replace('T', '_')
-        .slice(0, 19);
+    const backupTs = new Date().toISOString().replace(/:/g, '-').replace('T', '_').slice(0, 19);
 
+    // Back up remote code for phase/mfa before overwriting (pb backs up its own
+    // full upstream payload inside pushPbEntry).
     for (const entry of selected) {
-        if (entry.remoteCode !== null) {
+        if (entry.object_type !== 'process_builder' && entry.remoteCode != null) {
             const backupPath = join(BACKUP_DIR, backupTs, entry.path);
             mkdirSync(dirname(backupPath), { recursive: true });
             writeFileSync(backupPath, (entry.remoteCode ?? '').trim() + '\n', 'utf-8');
         }
     }
-    console.log(`Remote backups written to ${BACKUP_DIR}/${backupTs}/`);
 
-    // Push local code to API
+    const pushedPb = [];
     let pushed = 0;
     for (const entry of selected) {
-        const code = entry.localCode ?? '';
-        if (entry.object_type === 'phase') {
-            await updatePhase(token, ripUrl, entry.id, code);
-        } else {
-            await updateMfa(token, ripUrl, entry.id, code);
-        }
-
         const idx = config.workspace.findIndex(
-            (e) => e.id === entry.id && e.object_type === entry.object_type,
+            (e) =>
+                e.object_type === entry.object_type &&
+                (entry.object_type === 'process_builder'
+                    ? e.guid === entry.guid
+                    : e.id === entry.id)
         );
-        if (idx !== -1) {
-            config.workspace[idx].checksum_at_pull = computeChecksum(code);
+
+        if (entry.object_type === 'process_builder') {
+            const res = await pushPbEntry(token, entry, BACKUP_DIR, backupTs);
+            const note = [
+                res.created && `${res.created} new page(s)`,
+                res.updated && `${res.updated} page(s) updated`,
+            ]
+                .filter(Boolean)
+                .join(', ');
+            console.log(`  ${entry.name} → saved (draft)${note ? ` [${note}]` : ''}`);
+            if (idx !== -1) {
+                config.workspace[idx].checksum_at_pull = res.newChecksum;
+                if (res.newUpdatedDate) config.workspace[idx].updated_date = res.newUpdatedDate;
+                config.workspace[idx].status = res.newStatus || 'draft';
+            }
+            pushedPb.push({ entry, idx });
+        } else {
+            const code = entry.localCode ?? '';
+            if (entry.object_type === 'phase') await updatePhase(token, ripUrl, entry.id, code);
+            else await updateMfa(token, ripUrl, entry.id, code);
+            if (idx !== -1) config.workspace[idx].checksum_at_pull = computeChecksum(code);
         }
         pushed++;
     }
 
+    console.log(`\nRemote backups written to ${BACKUP_DIR}/${backupTs}/`);
+
+    // Publish step for pushed wizards (now in "draft").
+    if (pushedPb.length) {
+        await handlePublish(token, pushedPb, config, opts);
+    }
+
     writeConfig(config);
     console.log(`\nPushed ${pushed} record(s).`);
 }
 
+async function handlePublish(token, pushedPb, config, opts) {
+    for (const { entry, idx } of pushedPb) {
+        let doPublish;
+        if (opts.skipPublish) doPublish = false;
+        else if (opts.publish) doPublish = true;
+        else {
+            ({ doPublish } = await inquirer.prompt([
+                {
+                    type: 'confirm',
+                    name: 'doPublish',
+                    message: `Publish "${entry.name}" now?`,
+                    default: false,
+                },
+            ]));
+        }
+        if (doPublish) {
+            await publish(token, entry.guid);
+            if (idx !== -1) config.workspace[idx].status = 'published';
+            console.log(`  published ${entry.name}`);
+        }
+    }
+}
+
 export { push };

package/src/agrippa/commands/pushPb.js

@@ -0,0 +1,87 @@
+import { mkdirSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { createPage, publishProcess, updatePage, updateProcess } from '../lib/pbApi.js';
+import {
+    enumeratePages,
+    localChecksum,
+    MANIFEST_FILE,
+    recompose,
+    stableStringify,
+} from '../lib/pbProject.js';
+import { listPageFiles, projectReader } from '../lib/pbWorkspace.js';
+
+function stepkeyOf(wrapper) {
+    return wrapper?.page?._id?.stepkey ?? wrapper?.name;
+}
+
+// Persist a newly-created page's guid into the local manifest so future pushes
+// treat it as an existing page (PATCH, not POST).
+function recordPageGuid(projectPath, stepkey, file, createdWrapper) {
+    const manifestPath = join(projectPath, MANIFEST_FILE);
+    const read = projectReader(projectPath);
+    const manifest = JSON.parse(read(MANIFEST_FILE));
+    manifest.pages = manifest.pages || {};
+    const wrapper = { ...createdWrapper };
+    delete wrapper.page;
+    manifest.pages[stepkey] = { file, wrapper };
+    writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), 'utf-8');
+}
+
+// Push one process_builder entry: backup upstream, sync pages, PATCH the wizard.
+// `entry.upstream` is the upstream payload fetched during classification.
+// Returns a summary; the wizard is left in "draft".
+async function pushPbEntry(token, entry, backupDir, backupTs) {
+    const read = projectReader(entry.path);
+    const localPayload = recompose(read);
+    const upstream = entry.upstream;
+
+    // 1. Backup the full upstream payload before applying edits.
+    if (upstream) {
+        const backupPath = join(backupDir, backupTs, entry.path, 'upstream.json');
+        mkdirSync(dirname(backupPath), { recursive: true });
+        writeFileSync(backupPath, JSON.stringify(upstream, null, 2), 'utf-8');
+    }
+
+    // 2. Page sync (independent of the wizard save, mirroring the UI page popup).
+    const localPages = enumeratePages(read, listPageFiles(entry.path));
+    const upstreamByStep = new Map((upstream?.pages || []).map((w) => [stepkeyOf(w), w]));
+
+    let created = 0;
+    let updated = 0;
+    const pagesForPatch = [];
+    for (const lp of localPages) {
+        const body = { name: lp.stepkey, page: lp.page };
+        if (lp.guid) {
+            const up = upstreamByStep.get(lp.stepkey);
+            if (!up || stableStringify(up.page) !== stableStringify(lp.page)) {
+                await updatePage(token, entry.guid, lp.guid, body);
+                updated++;
+            }
+            pagesForPatch.push({ ...(lp.wrapper || {}), name: lp.stepkey, page: lp.page });
+        } else {
+            const createdWrapper = (await createPage(token, entry.guid, body)) || {};
+            recordPageGuid(entry.path, lp.stepkey, lp.file, createdWrapper);
+            pagesForPatch.push({ ...createdWrapper, name: lp.stepkey, page: lp.page });
+            created++;
+        }
+    }
+    // Ensure the wizard PATCH body carries every current page (incl. new ones).
+    localPayload.pages = pagesForPatch;
+
+    // 3. Save the whole wizard (blocks/structure/scalars). Wizard -> draft.
+    const saved = await updateProcess(token, entry.guid, localPayload);
+
+    return {
+        created,
+        updated,
+        newChecksum: localChecksum(read),
+        newUpdatedDate: saved?.updated_date,
+        newStatus: saved?.status,
+    };
+}
+
+function publish(token, guid) {
+    return publishProcess(token, guid);
+}
+
+export { pushPbEntry, publish };

package/src/agrippa/commands/repair.js

@@ -18,7 +18,9 @@ async function repair() {
     }
 
     writeConfig(config);
-    console.log(`Removed ${stale.length} stale entr${stale.length === 1 ? 'y' : 'ies'} (${before} → ${config.workspace.length}).`);
+    console.log(
+        `Removed ${stale.length} stale entr${stale.length === 1 ? 'y' : 'ies'} (${before} → ${config.workspace.length}).`
+    );
 }
 
 export { repair };

package/src/agrippa/index.js

@@ -1,12 +1,22 @@
 #!/usr/bin/env node
 import { createRequire } from 'module';
 import { program } from 'commander';
-import { init } from './commands/init.js';
 import { clone } from './commands/clone.js';
-import { pull } from './commands/pull.js';
-import { push } from './commands/push.js';
 import { diff } from './commands/diff.js';
+import { init } from './commands/init.js';
 import { initPhase } from './commands/initPhase.js';
+import {
+    pbAdd,
+    pbConnect,
+    pbDisconnect,
+    pbFormat,
+    pbList,
+    pbPreview,
+    pbRemove,
+    pbSetDefault,
+} from './commands/pb.js';
+import { pull } from './commands/pull.js';
+import { push } from './commands/push.js';
 import { repair } from './commands/repair.js';
 
 const require = createRequire(import.meta.url);
@@ -22,40 +32,154 @@ program.name('agrippa').version(version);
 program
     .command('init')
     .description('Create agrippa.yaml workspace config in the current directory')
-    .action(() => init().catch((err) => { console.error(`Error: ${err.message}`); process.exit(1); }));
+    .action(() =>
+        init().catch((err) => {
+            console.error(`Error: ${err.message}`);
+            process.exit(1);
+        })
+    );
 
 program
     .command('clone')
-    .description('Clone a phase or MFA from RIP into this workspace')
+    .description('Clone a phase, MFA, or process-builder wizard into this workspace')
     .option('--phase', 'Clone a phase (select a workflow)')
     .option('--mfa', 'Clone a Model Function Access record')
-    .option('--id <id>', 'Record ID to clone')
-    .option('--path <path>', 'Destination path (file for MFA, base dir for workflow)')
-    .action((opts) => clone(opts).catch((err) => { console.error(`Error: ${err.message}`); process.exit(1); }));
+    .option('--pb', 'Clone a process-builder wizard')
+    .option('--id <id>', 'Record ID to clone (phase/mfa)')
+    .option('--name <document_id>', 'Process-builder document_id to clone (with --pb)')
+    .option('--path <path>', 'Destination path (file for MFA, base dir for workflow/pb)')
+    .action((opts) =>
+        clone(opts).catch((err) => {
+            console.error(`Error: ${err.message}`);
+            process.exit(1);
+        })
+    );
 
 program
     .command('pull')
     .description('Pull remote changes into local files')
-    .action(() => pull().catch((err) => { console.error(`Error: ${err.message}`); process.exit(1); }));
+    .action(() =>
+        pull().catch((err) => {
+            console.error(`Error: ${err.message}`);
+            process.exit(1);
+        })
+    );
 
 program
     .command('push')
-    .description('Push local changes to RIP (backs up remote code first)')
-    .action(() => push().catch((err) => { console.error(`Error: ${err.message}`); process.exit(1); }));
+    .description('Push local changes to RIP / Process Builder (backs up remote first)')
+    .option('--publish', 'Auto-publish pushed process-builder wizards')
+    .option('--skip-publish', 'Skip publishing pushed wizards (no prompt)')
+    .action((opts) =>
+        push(opts).catch((err) => {
+            console.error(`Error: ${err.message}`);
+            process.exit(1);
+        })
+    );
 
 program
     .command('diff [path]')
     .description('Show differences between local files and remote code')
-    .action((path) => diff(path).catch((err) => { console.error(`Error: ${err.message}`); process.exit(1); }));
+    .action((path) =>
+        diff(path).catch((err) => {
+            console.error(`Error: ${err.message}`);
+            process.exit(1);
+        })
+    );
 
 program
     .command('init-phase')
     .description('Initialize a phase with default code template and result vars')
-    .action(() => initPhase().catch((err) => { console.error(`Error: ${err.message}`); process.exit(1); }));
+    .action(() =>
+        initPhase().catch((err) => {
+            console.error(`Error: ${err.message}`);
+            process.exit(1);
+        })
+    );
 
 program
     .command('repair')
     .description('Remove stale workspace entries where local file no longer exists')
-    .action(() => repair().catch((err) => { console.error(`Error: ${err.message}`); process.exit(1); }));
+    .action(() =>
+        repair().catch((err) => {
+            console.error(`Error: ${err.message}`);
+            process.exit(1);
+        })
+    );
+
+// ---- pb: local editing helpers for a cloned process-builder wizard ----
+const die = (err) => {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+};
+const pb = program
+    .command('pb')
+    .description('Edit a cloned process-builder wizard (local; run `pb format` after edits)');
+
+pb.command('format')
+    .description('Auto-lay-out the diagram (left→right) and rewrite geometry')
+    .option('--pb <document_id>', 'Target wizard (else single-entry / fuzzy prompt)')
+    .action((opts) => pbFormat(opts).catch(die));
+
+pb.command('add')
+    .description('Add a node (scaffolds script/page); stub geometry, run format after')
+    .requiredOption(
+        '--type <type>',
+        'Node type: scriptTask|serviceTask|userTask|exclusiveGateway|subProcess|transaction|startEvent|endEvent|boundaryEvent'
+    )
+    .option('--name <name>', 'Node name')
+    .option('--parent <id>', 'Place inside this subProcess/transaction')
+    .option(
+        '--from <id>',
+        'Insert between two already-connected nodes: source id (requires --to; ' +
+            'exactly one edge must already run --from → --to)'
+    )
+    .option('--to <id>', 'Insert between two already-connected nodes: target id (requires --from)')
+    .option('--pb <document_id>', 'Target wizard')
+    .action((opts) => pbAdd(opts).catch(die));
+
+pb.command('rm')
+    .description('Remove a node, its edges, and its script/page files')
+    .requiredOption('--id <id>', 'Node id to remove')
+    .option('--pb <document_id>', 'Target wizard')
+    .action((opts) => pbRemove(opts).catch(die));
+
+pb.command('connect')
+    .description('Add a sequenceFlow between two nodes')
+    .requiredOption('--from <id>', 'Source node id')
+    .requiredOption('--to <id>', 'Target node id')
+    .option('--name <name>', 'Flow name (label)')
+    .option('--condition <expr>', 'Condition expression, e.g. ${isAlive}')
+    .option('--condition-type <type>', 'xsi:type for the condition (default tFormalExpression)')
+    .option('--default', 'Mark this as the source gateway default flow')
+    .option('--pb <document_id>', 'Target wizard')
+    .action((opts) => pbConnect(opts).catch(die));
+
+pb.command('disconnect')
+    .description('Remove a sequenceFlow by id, or by --from/--to')
+    .option('--id <id>', 'Edge id to remove')
+    .option('--from <id>', 'Source node id')
+    .option('--to <id>', 'Target node id')
+    .option('--pb <document_id>', 'Target wizard')
+    .action((opts) => pbDisconnect(opts).catch(die));
+
+pb.command('set-default')
+    .description("Mark an existing flow as the source gateway's default (by --id or --from/--to)")
+    .option('--id <id>', 'Edge id to mark default')
+    .option('--from <id>', 'Source gateway id')
+    .option('--to <id>', 'Target node id')
+    .option('--pb <document_id>', 'Target wizard')
+    .action((opts) => pbSetDefault(opts).catch(die));
+
+pb.command('ls')
+    .description('List nodes and edges (discover ids without reading the YAML)')
+    .option('--pb <document_id>', 'Target wizard')
+    .action((opts) => pbList(opts).catch(die));
+
+pb.command('preview')
+    .description('Render the diagram to an SVG (dev check of format output)')
+    .option('--out <file>', 'Output path (default <project>/preview.svg)')
+    .option('--pb <document_id>', 'Target wizard')
+    .action((opts) => pbPreview(opts).catch(die));
 
 program.parse();

package/src/agrippa/lib/api.js

@@ -32,7 +32,7 @@ function getPhasesByIds(token, ripUrl, ids) {
         'GET',
         `/symple.triplet.phase/*?_filter_=[('id', 'in', [${ids.join(',')}])]`,
         token,
-        ripUrl,
+        ripUrl
     );
 }
 
@@ -44,6 +44,19 @@ function listMfas(token, ripUrl) {
     return makeRequest('GET', '/symple.workflow/get_mfas', token, ripUrl);
 }
 
+// Structure (graph) of a workflow: phases, results/edges, processes, triplets.
+// Backed by the `agrippa_describe_workflow` MFA on helpdesk.ticket. Returns no
+// phase code -- the editable phase code already lives on disk as .py files.
+// Registered as a GET MFA, so workflow_id rides the query string.
+function describeWorkflow(token, ripUrl, workflowId) {
+    return makeRequest(
+        'GET',
+        `/helpdesk.ticket/agrippa_describe_workflow?workflow_id=${workflowId}`,
+        token,
+        ripUrl
+    );
+}
+
 function updateMfa(token, ripUrl, mfaId, code) {
     return makeRequest('POST', '/symple.workflow/update_mfa', token, ripUrl, { id: mfaId, code });
 }
@@ -55,7 +68,7 @@ async function getPhaseResults(token, ripUrl, ids) {
             'GET',
             `/symple.triplet.phase.result/*?_filter_=[('id', 'in', [${ids.join(',')}])]`,
             token,
-            ripUrl,
+            ripUrl
         );
     } catch (err) {
         if (err.message.includes('404')) return [];
@@ -76,7 +89,7 @@ async function getPhaseConfigurators(token, ripUrl, phaseId) {
             'GET',
             `/result.code.configurator/*?_filter_=[('code_phase_id', '=', ${phaseId})]`,
             token,
-            ripUrl,
+            ripUrl
         );
     } catch (err) {
         if (err.message.includes('404')) return [];
@@ -98,6 +111,7 @@ export {
     getPhasesByIds,
     updatePhase,
     listMfas,
+    describeWorkflow,
     updateMfa,
     getPhaseResults,
     initPhaseRemote,

package/src/agrippa/lib/checksum.js

@@ -1,7 +1,9 @@
 import { createHash } from 'crypto';
 
 function computeChecksum(code) {
-    return createHash('md5').update((code ?? '').trim()).digest('hex');
+    return createHash('md5')
+        .update((code ?? '').trim())
+        .digest('hex');
 }
 
 export { computeChecksum };

package/src/agrippa/lib/config.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync, writeFileSync } from 'fs';
-import { parse, stringify } from 'yaml';
 import { configDotenv } from 'dotenv';
+import { parse, stringify } from 'yaml';
 import { CONFIG_FILE } from '../../config.js';
 
 const WORKSPACE_FILE = 'agrippa.yaml';
@@ -24,7 +24,7 @@ function loadEffectiveEnv(localConfig) {
 
     // Overlay workspace-level overrides from agrippa.yaml's agrippa: section
     const overrides = localConfig?.agrippa ?? {};
-    const keys = ['KC_URL', 'KC_USER', 'KC_PASSWORD', 'KC_ID', 'KC_SECRET', 'RIP_URL'];
+    const keys = ['KC_URL', 'KC_USER', 'KC_PASSWORD', 'KC_ID', 'KC_SECRET', 'RIP_URL', 'PB_URL'];
     for (const key of keys) {
         if (overrides[key]) {
             process.env[key] = overrides[key];

package/src/agrippa/lib/pbApi.js

@@ -0,0 +1,71 @@
+// Process-builder API client. Base URL = PB_URL, e.g.
+//   https://sorgenia-test-02.symple.cloud/api/processbuilder/v1
+// Auth uses the same Keycloak bearer as import-export (getToken()).
+
+import fetch from 'node-fetch';
+
+function pbBase() {
+    const base = process.env.PB_URL;
+    if (!base) {
+        throw new Error('PB_URL is not configured. Run `prbot init` or set it in agrippa.yaml.');
+    }
+    return base.replace(/\/+$/, '');
+}
+
+async function pbRequest(method, path, token, body) {
+    const hasBody = body !== undefined;
+    const res = await fetch(`${pbBase()}${path}`, {
+        method,
+        headers: {
+            Authorization: `Bearer ${token}`,
+            ...(hasBody ? { 'Content-Type': 'application/json' } : {}),
+        },
+        body: hasBody ? JSON.stringify(body) : undefined,
+    });
+    if (!res.ok) {
+        throw new Error(`PB API ${method} ${path} failed with ${res.status}: ${await res.text()}`);
+    }
+    const text = await res.text();
+    return text ? JSON.parse(text) : null;
+}
+
+// List processes. The endpoint returns full objects; we keep only the
+// identity fields needed for selection.
+async function listProcesses(token) {
+    const data = await pbRequest('GET', '/builder/process', token);
+    const arr = Array.isArray(data) ? data : (data.data ?? data.results ?? []);
+    return arr.map((p) => ({
+        guid: p.guid,
+        document_id: p.document_id,
+        process_name: p.process_name,
+        status: p.status,
+        version: p.version,
+    }));
+}
+
+// Fetch the full payload for one process by guid.
+function getProcess(token, guid) {
+    return pbRequest('GET', `/builder/process/${guid}`, token);
+}
+
+// Save the whole wizard (blocks/structure/scalars). Body = full payload. Wizard → draft.
+function updateProcess(token, guid, payload) {
+    return pbRequest('PATCH', `/builder/process/${guid}`, token, payload);
+}
+
+// Create a new user-task page. Body = { name, page }. Returns the created page (with guid).
+function createPage(token, guid, body) {
+    return pbRequest('POST', `/builder/process/${guid}/page`, token, body);
+}
+
+// Update an existing user-task page. Body = { name, page }.
+function updatePage(token, guid, pageGuid, body) {
+    return pbRequest('PATCH', `/builder/process/${guid}/page/${pageGuid}`, token, body);
+}
+
+// Publish the wizard so live consumers see the latest saved state.
+function publishProcess(token, guid) {
+    return pbRequest('POST', `/builder/process/publish/${guid}`, token, null);
+}
+
+export { listProcesses, getProcess, updateProcess, createPage, updatePage, publishProcess };