bkper 4.12.14 → 4.12.16

package/lib/agent/system-prompt.d.ts

@@ -1,3 +1,3 @@
 export declare function getBkperAgentSystemPrompt(): string;
-export declare const BKPER_AGENT_SYSTEM_PROMPT = "# Bkper Context\n\nYou are a Bkper team member.\n\nProtect the zero-sum invariant above all else.\n\nYou help users by reading files, executing commands, editing code, and writing new files.\n\nAvailable tools:\n- read: read file contents\n- bash: run shell commands for search and discovery\n- edit: make precise file edits\n- write: create or replace files\n\nIMPORTANT Guidelines:\n- Use bash for discovery and search like ls, rg, and find. Use it to run bkper CLI commands when relevant.\n- Use read to inspect file contents instead of cat or sed.\n- Use edit for precise changes.\n- When changing multiple separate locations in one file, use one edit call with multiple entries in edits[].\n- Each edits[].oldText is matched against the original file, not after earlier edits are applied. Do not use overlapping or nested edits. Merge nearby changes into one edit.\n- Keep edits[].oldText as small as possible while still being unique in the file.\n- Use write only for new files or complete rewrites.\n- Do not claim builds, tests, or command results unless you actually ran them.\n\n## Operating Principles\n\n- Preserve invariants and data integrity first, then user intent, then implementation convenience.\n- Think in resources, movements, and balances \u2014 not debits and credits.\n- Extend meaning with properties before adding structural complexity.\n- Model domain and flows before coding; represent business reality, not technical shortcuts.\n- Prefer simplicity over cleverness; choose small, boring, maintainable solutions.\n- Design for global readiness from day one: currencies, timezones, units, and formats.\n";
+export declare const BKPER_AGENT_SYSTEM_PROMPT: string;
 //# sourceMappingURL=system-prompt.d.ts.map

package/lib/agent/system-prompt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"system-prompt.d.ts","sourceRoot":"","sources":["../../src/agent/system-prompt.ts"],"names":[],"mappings":"AAqBA,wBAAgB,yBAAyB,IAAI,MAAM,CAsDlD;AAED,eAAO,MAAM,yBAAyB,qmDAgCrC,CAAC"}
+{"version":3,"file":"system-prompt.d.ts","sourceRoot":"","sources":["../../src/agent/system-prompt.ts"],"names":[],"mappings":"AA0FA,wBAAgB,yBAAyB,IAAI,MAAM,CA0ClD;AAED,eAAO,MAAM,yBAAyB,QAkBrC,CAAC"}

package/lib/agent/system-prompt.js

@@ -1,6 +1,7 @@
+import { createBashToolDefinition, createEditToolDefinition, createReadToolDefinition, createWriteToolDefinition, } from '@mariozechner/pi-coding-agent';
 import { existsSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 function resolveDocPath(filename) {
     const thisDir = path.dirname(fileURLToPath(import.meta.url));
     return path.resolve(thisDir, '..', 'docs', filename);
@@ -16,11 +17,65 @@ function resolvePiPackageRoot() {
     }
     return path.dirname(piIndexPath);
 }
+function normalizePromptSnippet(text) {
+    if (!text) {
+        return undefined;
+    }
+    const oneLine = text.replace(/[\r\n]+/g, ' ').replace(/\s+/g, ' ').trim();
+    return oneLine.length > 0 ? oneLine : undefined;
+}
+function normalizePromptGuidelines(guidelines) {
+    if (!guidelines || guidelines.length === 0) {
+        return [];
+    }
+    const unique = new Set();
+    for (const guideline of guidelines) {
+        const normalized = guideline.trim();
+        if (normalized.length > 0) {
+            unique.add(normalized);
+        }
+    }
+    return Array.from(unique);
+}
+function getCodingToolDefinitions() {
+    return [
+        createReadToolDefinition(process.cwd()),
+        createBashToolDefinition(process.cwd()),
+        createEditToolDefinition(process.cwd()),
+        createWriteToolDefinition(process.cwd()),
+    ];
+}
+function buildToolPromptSection() {
+    const toolDefinitions = getCodingToolDefinitions();
+    const toolLines = toolDefinitions
+        .flatMap(definition => {
+        const snippet = normalizePromptSnippet(definition.promptSnippet);
+        return snippet ? [`- ${definition.name}: ${snippet}`] : [];
+    })
+        .join('\n');
+    const guidelineLines = [];
+    const seenGuidelines = new Set();
+    const addGuideline = (guideline) => {
+        const normalized = guideline.trim();
+        if (normalized.length === 0 || seenGuidelines.has(normalized)) {
+            return;
+        }
+        seenGuidelines.add(normalized);
+        guidelineLines.push(`- ${normalized}`);
+    };
+    addGuideline('Use bash for discovery and search like ls, rg, and find. Use it to run bkper CLI commands when relevant.');
+    for (const definition of toolDefinitions) {
+        for (const guideline of normalizePromptGuidelines(definition.promptGuidelines)) {
+            addGuideline(guideline);
+        }
+    }
+    addGuideline('Do not claim builds, tests, or command results unless you actually ran them.');
+    const toolsList = toolLines.length > 0 ? toolLines : '(none)';
+    return `Available tools:\n${toolsList}\n\nIn addition to the tools above, you may have access to other custom tools depending on the project.\n\nGuidelines:\n${guidelineLines.join('\n')}`;
+}
 export function getBkperAgentSystemPrompt() {
-    const cliRefPath = resolveDocPath('cli-reference.md');
     const coreConceptsPath = resolveDocPath('core-concepts.md');
-    const bkperJsPath = resolveDocPath('bkper-js.md');
-    const bkperApiTypesPath = resolveDocPath('bkper-api-types.md');
+    const indexPath = resolveDocPath('index.md');
     const piRoot = resolvePiPackageRoot();
     const piDocsPath = path.resolve(piRoot, 'docs');
     const piExamplesPath = path.resolve(piRoot, 'examples');
@@ -28,28 +83,20 @@ export function getBkperAgentSystemPrompt() {
 ## Reference Routing
 
 - Read local \`AGENTS.md\`, nearby files, and existing tests first for project-specific work.
-- If the task touches Bkper accounting semantics or data modeling — such as Accounts, Transactions, balances, account types, groups, books, or mapping real-world flows into Bkper — read full file:
+- For any Bkper question or task — accounting concepts, CLI usage, SDK code, data management, or financial reports — start by reading both:
 
 \`\`\`
 ${coreConceptsPath}
 \`\`\`
 
-- If the task involves using, generating, or executing \`bkper\` CLI commands, read full file:
-
 \`\`\`
-${cliRefPath}
+${indexPath}
 \`\`\`
 
-- If the task involves writing, reviewing, or debugging code that uses the \`bkper-js\` library — such as Bkper, Book, Account, Transaction, Group classes, or any import from \`bkper-js\` — read both files:
-
-\`\`\`
-${bkperJsPath}
-\`\`\`
-
-\`\`\`
-${bkperApiTypesPath}
-\`\`\`
+  Then load the additional specific doc(s) the index points to based on what is relevant to the task.
 
+- For generic engineering work unrelated to Bkper, do not load Bkper reference docs unless directly relevant.
+- When scope is unclear, inspect local files and project instructions first; load reference docs only after identifying a concrete need.
 - If the task involves building or debugging pi extensions, custom tools, themes, or skills — read the pi docs directory and follow cross-references within:
 
 \`\`\`
@@ -62,13 +109,11 @@ Check extension examples at:
 ${piExamplesPath}
 \`\`\`
 
-- For generic engineering work, do not load Bkper reference docs unless directly relevant.
-- When scope is unclear, inspect local files and project instructions first; load reference docs only after identifying a concrete need.
-- For any other question about Bkper — product features, accounting guides, app architecture, integrations, or general usage — fetch and read:
+- For anything not covered by the local docs index, fetch and read:
 
   https://bkper.com/llms.txt
 
-  Then follow the most relevant link to find the answer.
+  And follow the most relevant link to find the answer.
 `;
 }
 export const BKPER_AGENT_SYSTEM_PROMPT = `# Bkper Context
@@ -79,21 +124,7 @@ Protect the zero-sum invariant above all else.
 
 You help users by reading files, executing commands, editing code, and writing new files.
 
-Available tools:
-- read: read file contents
-- bash: run shell commands for search and discovery
-- edit: make precise file edits
-- write: create or replace files
-
-IMPORTANT Guidelines:
-- Use bash for discovery and search like ls, rg, and find. Use it to run bkper CLI commands when relevant.
-- Use read to inspect file contents instead of cat or sed.
-- Use edit for precise changes.
-- When changing multiple separate locations in one file, use one edit call with multiple entries in edits[].
-- Each edits[].oldText is matched against the original file, not after earlier edits are applied. Do not use overlapping or nested edits. Merge nearby changes into one edit.
-- Keep edits[].oldText as small as possible while still being unique in the file.
-- Use write only for new files or complete rewrites.
-- Do not claim builds, tests, or command results unless you actually ran them.
+${buildToolPromptSection()}
 
 ## Operating Principles
 

package/lib/agent/system-prompt.js.map

@@ -1 +1 @@
-{"version":3,"file":"system-prompt.js","sourceRoot":"","sources":["../../src/agent/system-prompt.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,SAAS,cAAc,CAAC,QAAgB;IACpC,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7D,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;AACzD,CAAC;AAED,SAAS,oBAAoB;IACzB,MAAM,WAAW,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,+BAA+B,CAAC,CAAC,CAAC;IACxF,IAAI,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IACpC,OAAO,GAAG,KAAK,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/B,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC;YAC7C,OAAO,GAAG,CAAC;QACf,CAAC;QACD,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC5B,CAAC;IACD,OAAO,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;AACrC,CAAC;AAED,MAAM,UAAU,yBAAyB;IACrC,MAAM,UAAU,GAAG,cAAc,CAAC,kBAAkB,CAAC,CAAC;IACtD,MAAM,gBAAgB,GAAG,cAAc,CAAC,kBAAkB,CAAC,CAAC;IAC5D,MAAM,WAAW,GAAG,cAAc,CAAC,aAAa,CAAC,CAAC;IAClD,MAAM,iBAAiB,GAAG,cAAc,CAAC,oBAAoB,CAAC,CAAC;IAC/D,MAAM,MAAM,GAAG,oBAAoB,EAAE,CAAC;IACtC,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChD,MAAM,cAAc,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACxD,OAAO,GAAG,yBAAyB;;;;;;;EAOrC,gBAAgB;;;;;;EAMhB,UAAU;;;;;;EAMV,WAAW;;;;EAIX,iBAAiB;;;;;;EAMjB,UAAU;;;;;;EAMV,cAAc;;;;;;;;;;CAUf,CAAC;AACF,CAAC;AAED,MAAM,CAAC,MAAM,yBAAyB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgCxC,CAAC"}
+{"version":3,"file":"system-prompt.js","sourceRoot":"","sources":["../../src/agent/system-prompt.ts"],"names":[],"mappings":"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"}

package/lib/docs/app-management.md

@@ -0,0 +1,345 @@
+[bkper.yaml reference]: #bkperyaml-reference
+[App Template]: https://github.com/bkper/bkper-app-template
+
+# App Management
+
+Build, deploy, and manage Bkper apps using the `bkper` CLI.
+
+---
+
+## Development Workflow
+
+```bash
+# Scaffold a new app from the template
+bkper app init my-app
+
+# Start the worker runtime (Miniflare + tunnel + file watching)
+# In your project, use "npm run dev" to run both Vite and workers concurrently
+bkper app dev
+
+# Build worker bundles (web server + events handler)
+# In your project, use "npm run build" to build both client (Vite) and workers
+bkper app build
+
+# Sync configuration and deploy to production
+bkper app sync && bkper app deploy
+
+# Deploy to development environment
+bkper app deploy --preview
+
+# Deploy only the events handler
+bkper app deploy --events
+
+# Check deployment status
+bkper app status
+```
+
+> **Note:** `bkper app dev` runs the worker runtime only — Miniflare, file watching, and the Cloudflare tunnel. The Vite client dev server is configured in the project's `vite.config.ts` and run separately. The project template composes both via `npm run dev` using `concurrently`.
+
+---
+
+## Install Apps on Books
+
+```bash
+# Install an app on a book
+bkper app install my-app -b abc123
+
+# Uninstall an app from a book
+bkper app uninstall my-app -b abc123
+```
+
+---
+
+## Secrets
+
+```bash
+# Store a secret (prompts for value)
+bkper app secrets put API_KEY
+
+# List all secrets
+bkper app secrets list
+
+# Delete a secret
+bkper app secrets delete API_KEY
+```
+
+---
+
+## Configuration
+
+Apps are configured via a `bkper.yaml` file in the project root. See the complete **[bkper.yaml reference]** below.
+
+<details>
+<summary>bkper.yaml reference</summary>
+
+```yaml
+# =============================================================================
+# bkper.yaml Reference
+# =============================================================================
+# This file documents all available configuration options for Bkper Apps.
+# Copy the fields you need to your app's bkper.yaml file.
+#
+# For a minimal working template, see:
+# https://github.com/bkper/bkper-app-template
+# =============================================================================
+
+# -----------------------------------------------------------------------------
+# APP IDENTITY
+# -----------------------------------------------------------------------------
+# The app id is permanent and cannot be changed after creation.
+# Use lowercase letters, numbers, and hyphens only.
+id: my-app
+
+# Display name shown in the Bkper UI
+name: My App
+
+# Brief description of what the app does
+description: A Bkper app that does something useful
+
+# -----------------------------------------------------------------------------
+# BRANDING
+# -----------------------------------------------------------------------------
+# App logo for light mode (SVG recommended, PNG/JPG supported)
+logoUrl: https://example.com/logo.svg
+
+# App logo for dark mode (required for proper theming)
+logoUrlDark: https://example.com/logo-dark.svg
+
+# App website or documentation URL
+website: https://example.com
+
+# -----------------------------------------------------------------------------
+# OWNERSHIP
+# -----------------------------------------------------------------------------
+# Developer/company name
+ownerName: Your Name
+
+# Owner's logo/avatar URL
+ownerLogoUrl: https://example.com/owner-logo.png
+
+# Owner's website
+ownerWebsite: https://yoursite.com
+
+# Source code repository URL
+repoUrl: https://github.com/you/my-app
+
+# Whether the repository is private
+repoPrivate: true
+
+# Mark as deprecated (hides from app listings, existing installs continue working)
+deprecated: false
+
+# -----------------------------------------------------------------------------
+# ACCESS CONTROL
+# -----------------------------------------------------------------------------
+# Who can update the app configuration and deploy new versions.
+# Comma-separated list of Bkper usernames (not emails).
+# Supports domain wildcards for registered custom domains: *@yourdomain.com
+developers: victor, aldo, *@bkper.com
+
+# Who can install and use the app.
+# Same format as developers. Leave empty for public apps.
+users: maria, *@acme.com
+
+# -----------------------------------------------------------------------------
+# MENU INTEGRATION (optional)
+# -----------------------------------------------------------------------------
+# When configured, adds a menu item to Bkper's "More" menu.
+# Clicking opens a popup with the specified URL.
+
+# Production menu URL (supports variable substitution)
+menuUrl: https://${id}.bkper.app?bookId=${book.id}
+
+# Development menu URL (used when developer runs the app)
+menuUrlDev: http://localhost:8787?bookId=${book.id}
+
+# Custom menu text (defaults to app name if not specified)
+menuText: Open My App
+
+# Popup dimensions in pixels
+menuPopupWidth: 500
+menuPopupHeight: 300
+
+# -----------------------------------------------------------------------------
+# Menu URL Variables
+# -----------------------------------------------------------------------------
+# The following variables can be used in menuUrl and menuUrlDev:
+#
+# ${book.id}                - Current book ID
+# ${book.properties.xxx}    - Book property value (replace xxx with property key)
+# ${account.id}             - Selected account ID (in account context)
+# ${account.properties.xxx} - Account property value
+# ${group.id}               - Selected group ID (in group context)
+# ${group.properties.xxx}   - Group property value
+# ${transactions.ids}       - Comma-separated selected transaction IDs
+# ${transactions.query}     - Current search query
+# -----------------------------------------------------------------------------
+
+# -----------------------------------------------------------------------------
+# EVENT HANDLING (optional)
+# -----------------------------------------------------------------------------
+# When configured, Bkper calls your webhook URL when subscribed events occur.
+
+# Production webhook URL
+webhookUrl: https://${id}.bkper.app/events
+
+# Development webhook URL (auto-updated by bkper app dev)
+webhookUrlDev: https://<random>.trycloudflare.com/events
+
+# API version for event payloads
+apiVersion: v5
+
+# Events to subscribe to (remove events you don't need)
+events:
+    # Transaction
+    - TRANSACTION_CREATED
+    - TRANSACTION_POSTED
+    - TRANSACTION_CHECKED
+    - TRANSACTION_UNCHECKED
+    - TRANSACTION_UPDATED
+    - TRANSACTION_DELETED
+    - TRANSACTION_RESTORED
+    # Account
+    - ACCOUNT_CREATED
+    - ACCOUNT_UPDATED
+    - ACCOUNT_DELETED
+    # Group
+    - GROUP_CREATED
+    - GROUP_UPDATED
+    - GROUP_DELETED
+    # File
+    - FILE_CREATED
+    - FILE_UPDATED
+    # Query
+    - QUERY_CREATED
+    - QUERY_UPDATED
+    - QUERY_DELETED
+    # Comment
+    - COMMENT_CREATED
+    - COMMENT_DELETED
+    # Collaborator
+    - COLLABORATOR_ADDED
+    - COLLABORATOR_UPDATED
+    - COLLABORATOR_REMOVED
+    # Integration
+    - INTEGRATION_CREATED
+    - INTEGRATION_UPDATED
+    - INTEGRATION_DELETED
+    # Book
+    - BOOK_CREATED
+    - BOOK_UPDATED
+    - BOOK_DELETED
+    - BOOK_AUDITED
+
+# -----------------------------------------------------------------------------
+# FILE PATTERNS (optional)
+# -----------------------------------------------------------------------------
+# For file processing apps. When a file matching these patterns is uploaded,
+# a FILE_CREATED event is triggered with the file content.
+filePatterns:
+    - '*.ofx'
+    - '*.csv'
+
+# -----------------------------------------------------------------------------
+# PROPERTIES SCHEMA (optional)
+# -----------------------------------------------------------------------------
+# Defines autocomplete suggestions for custom properties in the Bkper UI.
+# Helps users discover and use the correct property keys/values for your app.
+propertiesSchema:
+    book:
+        keys:
+            - my_app_enabled
+            - my_app_config
+        values:
+            - 'true'
+            - 'false'
+    group:
+        keys:
+            - my_app_category
+        values:
+            - category_a
+            - category_b
+    account:
+        keys:
+            - my_app_sync_id
+    transaction:
+        keys:
+            - my_app_reference
+
+# -----------------------------------------------------------------------------
+# DEPLOYMENT CONFIGURATION (optional)
+# -----------------------------------------------------------------------------
+# For apps deployed to Bkper's Workers for Platforms infrastructure.
+deployment:
+    # Web handler (serves UI and API)
+    web:
+        bundle: packages/web/server/dist
+        # assets: packages/web/client/dist  # Static assets (when supported)
+
+    # Events handler (processes webhooks)
+    events:
+        bundle: packages/events/dist
+
+    # Platform services available to your app (one per type, auto-provisioned)
+    # See: https://developers.cloudflare.com/kv/
+    services:
+        - KV # Key-value storage
+```
+
+</details>
+
+**Environment variables:**
+
+-   `BKPER_API_KEY` -- Optional. If not set, uses the Bkper API proxy with a managed API key. Set it for direct API access with your own quotas. Follow [these steps](https://bkper.com/docs/#rest-api-enabling) to enable.
+
+---
+
+## Command Reference
+
+### Authentication
+
+-   `auth login` - Authenticate with Bkper, storing credentials locally
+-   `auth logout` - Revoke the stored refresh token and clear local credentials
+-   `auth token` - Print the current OAuth access token to stdout (requires prior login)
+
+### Agent
+
+-   `agent` - Start the interactive Bkper Agent
+-   `agent <pi-args...>` - Run Pi CLI with Bkper defaults (system prompt/resources)
+
+### App Lifecycle
+
+-   `app init <name>` - Scaffold a new app from the template
+-   `app list` - List all apps you have access to
+-   `app sync` - Sync [bkper.yaml][bkper.yaml reference] configuration (URLs, description) to Bkper API
+-   `app build` - Build worker bundles for deployment
+-   `app deploy` - Deploy built artifacts to Cloudflare Workers for Platforms
+    -   `-p, --preview` - Deploy to preview environment
+    -   `--events` - Deploy events handler instead of web handler
+-   `app status` - Show deployment status
+-   `app undeploy` - Remove app from platform
+    -   `-p, --preview` - Remove from preview environment
+    -   `--events` - Remove events handler instead of web handler
+    -   `--delete-data` - Permanently delete all associated data (requires confirmation)
+    -   `--force` - Skip confirmation prompts (use with `--delete-data` for automation)
+-   `app dev` - Start the worker runtime for local development
+    -   `--sp, --server-port <port>` - Server simulation port (default: `8787`)
+    -   `--ep, --events-port <port>` - Events handler port (default: `8791`)
+    -   `-w, --web` - Run only the web handler
+    -   `-e, --events` - Run only the events handler
+
+> **Note:** `sync` and `deploy` are independent operations. Use `sync` to update your app's URLs in Bkper (required for webhooks and menu integration). Use `deploy` to push code to Cloudflare. For a typical deployment workflow, run both: `bkper app sync && bkper app deploy`
+
+### App Installation
+
+-   `app install <appId> -b <bookId>` - Install an app on a book
+-   `app uninstall <appId> -b <bookId>` - Uninstall an app from a book
+
+### Secrets Management
+
+-   `app secrets put <name>` - Store a secret
+    -   `-p, --preview` - Set in preview environment
+-   `app secrets list` - List all secrets
+    -   `-p, --preview` - List from preview environment
+-   `app secrets delete <name>` - Delete a secret
+    -   `-p, --preview` - Delete from preview environment