@waron97/prbot 3.1.4 → 3.2.0

package/src/agrippa/commands/clonePb.js

@@ -0,0 +1,107 @@
+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 { loadEffectiveEnv, readConfig, writeConfig } from '../lib/config.js';
+import { getProcess, listProcesses } from '../lib/pbApi.js';
+import { comparePayload, decompose, recompose, stableStringify } from '../lib/pbProject.js';
+import { projectReader, writeProject } from '../lib/pbWorkspace.js';
+
+async function clonePb(opts) {
+    const config = readConfig();
+    loadEffectiveEnv(config);
+
+    if (!process.env.PB_URL) {
+        throw new Error('PB_URL is not configured. Run `prbot init` or set it in agrippa.yaml.');
+    }
+
+    console.log('Fetching process list...');
+    const token = await getToken();
+    const processes = await listProcesses(token);
+    if (!processes.length) {
+        console.log('No process-builder wizards found.');
+        return;
+    }
+
+    // Select the process: by --name (document_id) or interactive fuzzy search.
+    let chosen;
+    if (opts.name) {
+        chosen = processes.find((p) => p.document_id === opts.name);
+        if (!chosen) throw new Error(`No process found with document_id "${opts.name}"`);
+    } else {
+        chosen = await search({
+            message: 'Select a process-builder wizard:',
+            source: (input) => {
+                const list = input
+                    ? processes.filter(
+                          (p) =>
+                              fuzzyMatch(p.process_name, input) || fuzzyMatch(p.document_id, input)
+                      )
+                    : processes;
+                return list.map((p) => ({
+                    name: `${p.process_name}  (${p.document_id})`,
+                    value: p,
+                }));
+            },
+        });
+    }
+
+    // Destination directory.
+    let dest = opts.path ?? null;
+    if (!dest) {
+        const { inputPath } = await inquirer.prompt([
+            {
+                type: 'input',
+                name: 'inputPath',
+                message: 'Destination directory:',
+                default: chosen.document_id,
+            },
+        ]);
+        dest = inputPath;
+    }
+
+    console.log(`Fetching "${chosen.process_name}"...`);
+    const payload = await getProcess(token, chosen.guid);
+
+    const { files } = decompose(payload);
+    writeProject(dest, files);
+
+    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))`);
+
+    // 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));
+    } else {
+        console.log('Round-trip verified: recomposed payload is identical (0 information loss).');
+    }
+
+    // Register in the workspace for later pull/push.
+    config.workspace = config.workspace || [];
+    const existing = config.workspace.findIndex(
+        (e) => e.object_type === 'process_builder' && e.guid === chosen.guid
+    );
+    const entry = {
+        path: dest,
+        object_type: 'process_builder',
+        guid: chosen.guid,
+        document_id: chosen.document_id,
+        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)),
+        updated_date: payload.updated_date,
+        status: payload.status,
+    };
+    if (existing >= 0) config.workspace[existing] = entry;
+    else config.workspace.push(entry);
+    writeConfig(config);
+}
+
+export { clonePb };

package/src/agrippa/commands/diff.js

@@ -1,20 +1,29 @@
-import { existsSync, statSync, writeFileSync, unlinkSync } from 'fs';
-import { join } from 'path';
-import { tmpdir } from 'os';
 import { spawnSync } from 'child_process';
-import { readConfig, loadEffectiveEnv } from '../lib/config.js';
-import { fetchRemoteCode } from './pull.js';
+import {
+    cpSync,
+    existsSync,
+    mkdirSync,
+    mkdtempSync,
+    rmSync,
+    statSync,
+    unlinkSync,
+    writeFileSync,
+} from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
 import { getToken } from '../../lib/auth.js';
-import { readCodeFile, fileExists } from '../lib/workspace.js';
 import { computeChecksum } from '../lib/checksum.js';
+import { loadEffectiveEnv, readConfig } from '../lib/config.js';
+import { getProcess } from '../lib/pbApi.js';
+import { decompose, localChecksum } from '../lib/pbProject.js';
+import { projectReader, writeProject } from '../lib/pbWorkspace.js';
+import { fileExists, readCodeFile } from '../lib/workspace.js';
+import { fetchRemoteCode } from './pull.js';
 
 async function diff(targetArg) {
     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.');
-
     if (!config.workspace.length) {
         console.log('No tracked resources. Run `agrippa clone` first.');
         return;
@@ -26,13 +35,40 @@ 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');
+
+    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)
+        throw new Error('PB_URL is not configured. Run `prbot init` or set it in agrippa.yaml.');
+
     console.log('Fetching remote code...');
     const token = await getToken();
-    const remoteCodeMap = await fetchRemoteCode(token, ripUrl, entries);
 
     let diffCount = 0;
-    const tmpFiles = [];
 
+    if (codeEntries.length) {
+        const remoteCodeMap = await fetchRemoteCode(token, process.env.RIP_URL, codeEntries);
+        diffCount += diffCodeEntries(codeEntries, remoteCodeMap);
+    }
+
+    for (const entry of pbEntries) {
+        if (await diffPbEntry(token, entry)) diffCount++;
+    }
+
+    if (diffCount === 0) {
+        console.log('No differences found — all tracked files match the remote.');
+    } else {
+        console.log(`\n${diffCount} file(s) differ from remote.`);
+    }
+}
+
+// Single-file phase/mfa code entries: write the remote body to a tmp file and
+// hand both sides to `git diff --no-index`.
+function diffCodeEntries(entries, remoteCodeMap) {
+    let diffCount = 0;
+    const tmpFiles = [];
     try {
         for (const entry of entries) {
             const key = `${entry.object_type}:${entry.id}`;
@@ -46,7 +82,6 @@ async function diff(targetArg) {
                 continue;
             }
 
-            // Write remote content to a temp file so git diff --no-index can compare
             const tmpPath = join(tmpdir(), `agrippa-remote-${entry.object_type}-${entry.id}.py`);
             writeFileSync(tmpPath, (remoteCode ?? '').trim() + '\n', 'utf-8');
             tmpFiles.push(tmpPath);
@@ -56,7 +91,7 @@ async function diff(targetArg) {
             const result = spawnSync(
                 'git',
                 ['diff', '--no-index', '--color=always', tmpPath, entry.path],
-                { stdio: ['ignore', 'inherit', 'inherit'] },
+                { stdio: ['ignore', 'inherit', 'inherit'] }
             );
             // exit code 1 means differences found (normal), 0 means identical, >1 means error
             if (result.status !== null && result.status > 1) {
@@ -66,14 +101,55 @@ async function diff(targetArg) {
         }
     } finally {
         for (const f of tmpFiles) {
-            try { unlinkSync(f); } catch { /* ignore */ }
+            try {
+                unlinkSync(f);
+            } catch {
+                /* ignore */
+            }
         }
     }
+    return diffCount;
+}
 
-    if (diffCount === 0) {
-        console.log('No differences found — all tracked files match the remote.');
-    } else {
-        console.log(`\n${diffCount} file(s) differ from remote.`);
+// 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) {
+    const upstream = await getProcess(token, entry.guid);
+    if (!upstream) throw new Error(`could not fetch upstream wizard ${entry.guid}`);
+
+    const tmpRoot = mkdtempSync(join(tmpdir(), 'agrippa-pb-diff-'));
+    try {
+        const upstreamDir = join(tmpRoot, 'upstream');
+        const localDir = join(tmpRoot, 'local');
+        mkdirSync(upstreamDir, { recursive: true });
+        writeProject(upstreamDir, decompose(upstream).files);
+
+        cpSync(entry.path, localDir, { recursive: true });
+        rmSync(join(localDir, '.backup'), { recursive: true, force: true });
+        rmSync(join(localDir, 'preview.svg'), { force: true });
+
+        // Compare via the recompose pipeline on both sides (not raw upstream JSON
+        // vs. local): the BPMN xml is regenerated from structure.yaml on rebuild
+        // and never matches the raw upstream xml byte-for-byte even when nothing
+        // structural changed, so it'd otherwise look like a permanent false diff.
+        if (localChecksum(projectReader(upstreamDir)) === localChecksum(projectReader(localDir)))
+            return false;
+
+        console.log(`\n=== ${entry.path}  [${entry.name}] (process-builder) ===`);
+        const result = spawnSync(
+            'git',
+            ['diff', '--no-index', '--color=always', 'upstream', 'local'],
+            { cwd: tmpRoot, stdio: ['ignore', 'inherit', 'inherit'] }
+        );
+        if (result.status !== null && result.status > 1) {
+            console.error(`git diff failed for ${entry.path}`);
+        }
+        return true;
+    } finally {
+        rmSync(tmpRoot, { recursive: true, force: true });
     }
 }
 

package/src/agrippa/commands/init.js

@@ -1,6 +1,13 @@
-import { existsSync, writeFileSync, mkdirSync, copyFileSync } from 'fs';
-import { fileURLToPath } from 'url';
+import {
+    appendFileSync,
+    copyFileSync,
+    existsSync,
+    mkdirSync,
+    readFileSync,
+    writeFileSync,
+} from 'fs';
 import { join } from 'path';
+import { fileURLToPath } from 'url';
 import inquirer from 'inquirer';
 import { WORKSPACE_FILE } from '../lib/config.js';
 
@@ -44,16 +51,17 @@ builtins = [
 ]
 `;
 
-const PYRIGHTCONFIG = JSON.stringify(
-    {
-        pythonVersion: '3.10',
-        stubPath: 'typings',
-        typeCheckingMode: 'standard',
-        reportArgumentType: 'none',
-    },
-    null,
-    2,
-) + '\n';
+const PYRIGHTCONFIG =
+    JSON.stringify(
+        {
+            pythonVersion: '3.10',
+            stubPath: 'typings',
+            typeCheckingMode: 'standard',
+            reportArgumentType: 'none',
+        },
+        null,
+        2
+    ) + '\n';
 
 const TYPING_FILES = [
     '__builtins__.pyi',
@@ -63,6 +71,17 @@ const TYPING_FILES = [
     'b2w_entities.pyi',
 ];
 
+// The copied guidance is wrapped in these sentinels so a re-run can find the
+// managed block and refresh it in place (when agrippa-pb.md changes) without
+// touching the human's own CLAUDE.md content outside the markers.
+const PB_BEGIN = '<!-- BEGIN agrippa-pb guidance (managed by `agrippa init`) -->';
+const PB_END = '<!-- END agrippa-pb guidance -->';
+
+// Wrap the guide in the managed block.
+function pbBlock(guide) {
+    return `${PB_BEGIN}\n\n${guide.trimEnd()}\n\n${PB_END}\n`;
+}
+
 async function init() {
     if (existsSync(WORKSPACE_FILE)) {
         const { overwrite } = await inquirer.prompt([
@@ -115,6 +134,41 @@ async function init() {
         }
         console.log(`Copied ${TYPING_FILES.length} type stubs to typings/`);
     }
+
+    const { importInstructions } = await inquirer.prompt([
+        {
+            type: 'confirm',
+            name: 'importInstructions',
+            message: 'Copy agrippa-pb.md guidance into local CLAUDE.md?',
+            default: true,
+        },
+    ]);
+
+    if (importInstructions) {
+        const guidePath = fileURLToPath(new URL('../../../agrippa-pb.md', import.meta.url));
+        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');
+        } 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');
+            } else {
+                // Replace the existing managed block in place; leave the rest as-is.
+                const endIdx = current.indexOf(PB_END, begin);
+                if (endIdx === -1)
+                    throw new Error(
+                        'CLAUDE.md has a malformed agrippa-pb block (BEGIN without END) — fix it by hand.'
+                    );
+                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');
+            }
+        }
+    }
 }
 
 export { init };

package/src/agrippa/commands/initPhase.js

@@ -1,17 +1,17 @@
-import inquirer from 'inquirer';
 import search from '@inquirer/search';
-import { readConfig, loadEffectiveEnv } from '../lib/config.js';
+import inquirer from 'inquirer';
+import { getToken } from '../../lib/auth.js';
+import { fuzzyMatch } from '../../lib/fuzzy.js';
 import {
-    listWorkflows,
-    getPhasesByWorkflow,
+    createConfigurator,
+    deleteConfigurator,
+    getPhaseConfigurators,
     getPhaseResults,
+    getPhasesByWorkflow,
     initPhaseRemote,
-    getPhaseConfigurators,
-    deleteConfigurator,
-    createConfigurator,
+    listWorkflows,
 } from '../lib/api.js';
-import { getToken } from '../../lib/auth.js';
-import { fuzzyMatch } from '../../lib/fuzzy.js';
+import { loadEffectiveEnv, readConfig } from '../lib/config.js';
 
 const CODE_TEMPLATE = `logs = []
 debug_logs = []
@@ -72,7 +72,8 @@ async function initPhase() {
     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.');
+    if (!ripUrl)
+        throw new Error('RIP_URL is not configured. Run `prbot init` or set it in agrippa.yaml.');
 
     console.log('Fetching workflows...');
     const token = await getToken();
@@ -86,9 +87,7 @@ async function initPhase() {
     const workflow = await search({
         message: 'Select a workflow:',
         source: (input) => {
-            const filtered = input
-                ? workflows.filter((w) => fuzzyMatch(w.name, input))
-                : workflows;
+            const filtered = input ? workflows.filter((w) => fuzzyMatch(w.name, input)) : workflows;
             return filtered.map((w) => ({ name: w.name, value: w }));
         },
     });
@@ -104,9 +103,7 @@ async function initPhase() {
     const phase = await search({
         message: 'Select a phase:',
         source: (input) => {
-            const filtered = input
-                ? phases.filter((p) => fuzzyMatch(p.name, input))
-                : phases;
+            const filtered = input ? phases.filter((p) => fuzzyMatch(p.name, input)) : phases;
             return filtered.map((p) => ({ name: p.name, value: p }));
         },
     });
@@ -156,7 +153,9 @@ async function initPhase() {
     if (results.length > 0) {
         console.log(`  ${results.length} configurator(s) created: ${vars.join(', ')}`);
     }
-    console.log(`Run 'agrippa pull' in workspaces that track this workflow to fetch the updated code.`);
+    console.log(
+        `Run 'agrippa pull' in workspaces that track this workflow to fetch the updated code.`
+    );
 }
 
 export { initPhase };