bkper 4.24.2 → 4.24.3

package/lib/commands/apps/sync.js

@@ -10,6 +10,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 import { BkperError } from 'bkper-js';
 import { getBkperInstance } from '../../bkper-factory.js';
 import { createConfiguredApp } from './config.js';
+import { syncManagedAppSource } from './source-workflow.js';
 /**
  * Creates a new app from the configuration in the current directory.
  *
@@ -63,14 +64,18 @@ export function syncApp() {
                 throw err;
             }
         }
-        if (exists) {
-            yield app.update();
-            return { id: appId, action: 'updated' };
-        }
-        else {
-            yield app.create();
-            return { id: appId, action: 'created' };
-        }
+        return syncManagedAppSource({
+            appId,
+            coreAppExists: exists,
+            syncCore: (action) => __awaiter(this, void 0, void 0, function* () {
+                if (action === 'updated') {
+                    yield app.update();
+                }
+                else {
+                    yield app.create();
+                }
+            }),
+        });
     });
 }
 //# sourceMappingURL=sync.js.map

package/lib/commands/apps/sync.js.map

@@ -1 +1 @@
-{"version":3,"file":"sync.js","sourceRoot":"","sources":["../../../src/commands/apps/sync.ts"],"names":[],"mappings":";;;;;;;;;AAAA,OAAO,EAAO,UAAU,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAGlD;;;;GAIG;AACH,MAAM,UAAgB,SAAS;;QAC3B,MAAM,GAAG,GAAG,mBAAmB,EAAE,CAAC;QAClC,MAAM,UAAU,GAAG,MAAM,GAAG,CAAC,MAAM,EAAE,CAAC;QACtC,OAAO,UAAU,CAAC;IACtB,CAAC;CAAA;AAED;;;;GAIG;AACH,MAAM,UAAgB,SAAS;;QAC3B,MAAM,GAAG,GAAG,mBAAmB,EAAE,CAAC;QAClC,MAAM,UAAU,GAAG,MAAM,GAAG,CAAC,MAAM,EAAE,CAAC;QACtC,OAAO,UAAU,CAAC;IACtB,CAAC;CAAA;AAED;;;;GAIG;AACH,MAAM,UAAgB,OAAO;;QACzB,MAAM,KAAK,GAAG,gBAAgB,EAAE,CAAC;QACjC,MAAM,GAAG,GAAG,mBAAmB,EAAE,CAAC;QAClC,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,EAAE,CAAC;QAE1B,IAAI,CAAC,KAAK,EAAE,CAAC;YACT,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;QACxD,CAAC;QAED,sBAAsB;QACtB,IAAI,MAAM,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC;YACD,MAAM,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC1B,MAAM,GAAG,IAAI,CAAC;QAClB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACX,IAAI,GAAG,YAAY,UAAU,IAAI,GAAG,CAAC,IAAI,KAAK,GAAG,EAAE,CAAC;gBAChD,iCAAiC;gBACjC,OAAO,CAAC,GAAG,CAAC,iCAAiC,CAAC,CAAC;gBAC/C,MAAM,GAAG,KAAK,CAAC;YACnB,CAAC;iBAAM,CAAC;gBACJ,MAAM,GAAG,CAAC;YACd,CAAC;QACL,CAAC;QAED,IAAI,MAAM,EAAE,CAAC;YACT,MAAM,GAAG,CAAC,MAAM,EAAE,CAAC;YACnB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;QAC5C,CAAC;aAAM,CAAC;YACJ,MAAM,GAAG,CAAC,MAAM,EAAE,CAAC;YACnB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;QAC5C,CAAC;IACL,CAAC;CAAA"}
+{"version":3,"file":"sync.js","sourceRoot":"","sources":["../../../src/commands/apps/sync.ts"],"names":[],"mappings":";;;;;;;;;AAAA,OAAO,EAAO,UAAU,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAElD,OAAO,EAAC,oBAAoB,EAAC,MAAM,sBAAsB,CAAC;AAE1D;;;;GAIG;AACH,MAAM,UAAgB,SAAS;;QAC3B,MAAM,GAAG,GAAG,mBAAmB,EAAE,CAAC;QAClC,MAAM,UAAU,GAAG,MAAM,GAAG,CAAC,MAAM,EAAE,CAAC;QACtC,OAAO,UAAU,CAAC;IACtB,CAAC;CAAA;AAED;;;;GAIG;AACH,MAAM,UAAgB,SAAS;;QAC3B,MAAM,GAAG,GAAG,mBAAmB,EAAE,CAAC;QAClC,MAAM,UAAU,GAAG,MAAM,GAAG,CAAC,MAAM,EAAE,CAAC;QACtC,OAAO,UAAU,CAAC;IACtB,CAAC;CAAA;AAED;;;;GAIG;AACH,MAAM,UAAgB,OAAO;;QACzB,MAAM,KAAK,GAAG,gBAAgB,EAAE,CAAC;QACjC,MAAM,GAAG,GAAG,mBAAmB,EAAE,CAAC;QAClC,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,EAAE,CAAC;QAE1B,IAAI,CAAC,KAAK,EAAE,CAAC;YACT,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;QACxD,CAAC;QAED,sBAAsB;QACtB,IAAI,MAAM,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC;YACD,MAAM,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC1B,MAAM,GAAG,IAAI,CAAC;QAClB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACX,IAAI,GAAG,YAAY,UAAU,IAAI,GAAG,CAAC,IAAI,KAAK,GAAG,EAAE,CAAC;gBAChD,iCAAiC;gBACjC,OAAO,CAAC,GAAG,CAAC,iCAAiC,CAAC,CAAC;gBAC/C,MAAM,GAAG,KAAK,CAAC;YACnB,CAAC;iBAAM,CAAC;gBACJ,MAAM,GAAG,CAAC;YACd,CAAC;QACL,CAAC;QAED,OAAO,oBAAoB,CAAC;YACxB,KAAK;YACL,aAAa,EAAE,MAAM;YACrB,QAAQ,EAAE,CAAM,MAAM,EAAC,EAAE;gBACrB,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;oBACvB,MAAM,GAAG,CAAC,MAAM,EAAE,CAAC;gBACvB,CAAC;qBAAM,CAAC;oBACJ,MAAM,GAAG,CAAC,MAAM,EAAE,CAAC;gBACvB,CAAC;YACL,CAAC,CAAA;SACJ,CAAC,CAAC;IACP,CAAC;CAAA"}

package/lib/docs/cli/app-management.md

@@ -7,6 +7,21 @@ Build, deploy, and manage Bkper apps using the `bkper` CLI.
 
 ---
 
+## Source control modes
+
+Bkper selects source mode without changing the local-build deployment model:
+
+- **Managed source:** the first `bkper app sync` activates private Bkper-managed Git only when that same sync creates the Core App, `bkper.yaml` is at the root of a standalone Git repository, the current clean committed branch is `main`, and no Git remote exists. Bkper configures the managed repository as `origin` and pushes the committed source.
+- **External source:** an App keeps direct sync/deploy behavior when it has an external Git remote, is nested in a monorepo, is not rooted at `bkper.yaml`, or already existed in Core without a pending activation marker. Existing no-remote Apps are not migrated automatically. The CLI never changes an existing external remote.
+
+To opt out for a new standalone App, add a GitHub, GitLab, or other provider remote before its first sync. Managed mode is sticky after activation; adding another remote later does not change it, and Artifacts remains `origin`.
+
+Source and deployment remain separate. `git push` stores source only and **never deploys**. `bkper app sync` pushes managed source before syncing local metadata. `bkper app deploy` pushes managed source, verifies that the exact commit exists in the linked repository, and then uploads the existing local `dist/server` and optional `dist/client` output. Builds remain local and explicit; Bkper does not claim reproducible remote CI or prove that the local bundle was built from the declared commit. Source linkage is best-effort provenance for already-authorized developers.
+
+CLI-managed pushes are clean-tree and fast-forward-only. The CLI never commits, merges, rebases, force-pushes, resets, or discards files. Authorized developers may use ordinary Git commands, including an intentional force-push, but a push still never deploys.
+
+Configured App developers, including matches such as `*@example.com`, can read and modify private managed source under the existing owner/developer policy. App users and Book collaborators do not receive source access unless they also satisfy that developer policy. Repository credentials are exact URL/path-scoped, noninteractive, and valid for five minutes; they are never persisted by Bkper.
+
 ## Verification Workflow
 
 When scaffolding, developing, or deploying an app, verify each step before proceeding. This prevents broken deployments and silent failures.
@@ -18,13 +33,14 @@ bkper app init my-app
 cd my-app
 ```
 
-`bkper app init <name>` creates and scaffolds `./<name>` using the same value as the app id. Run `bkper app init` with no name inside an existing empty or VCS-only directory to use the current folder name as the app id.
+`bkper app init <name>` creates and scaffolds `./<name>` using the same value as the app id. Run `bkper app init` with no name inside an existing empty or VCS-only directory to use the current folder name as the app id. Init initializes Git on `main` when needed, but does not create commits.
 
 Verify:
 
 - `client/` and `server/` exist
 - `bkper.yaml` has `id`, `name`, `description`, and `developers`
 - `package.json` scripts include `dev` and `build`
+- `.git` exists on branch `main` with no automatic commit
 
 ### 2. Develop
 
@@ -53,14 +69,24 @@ Verify:
 
 ### 4. Sync & Deploy
 
+Commit source before the first eligible managed sync:
+
 ```bash
-bkper app sync && bkper app deploy
+git add .
+git commit -m "Initial app"
+bkper app sync
+npm run build
+bkper app deploy
 ```
 
+For a managed App, sync and deploy safely push the current committed branch. For an external App, both commands preserve direct local metadata and bundle upload behavior without changing remotes.
+
 Verify:
 
 - `bkper app status` shows the deployed version
+- managed status shows the declared branch and exact verified SHA
 - URLs in `bkper.yaml` match the deployed domain (`https://{appId}.bkper.app`)
+- an ordinary `git push` did not deploy anything
 
 #### Preview testing with menu and events
 
@@ -139,6 +165,66 @@ bkper app status
 
 ---
 
+## Clone managed source
+
+Clone an existing managed App explicitly:
+
+```bash
+bkper app clone <appId> [path]
+cd <path-or-appId>
+bun install
+```
+
+Clone authenticates with Bkper, uses a temporary sibling directory, validates the cloned App ID, and atomically installs the destination. It never installs dependencies or executes repository lifecycle scripts. External-source Apps must be cloned from their configured provider instead.
+
+If Git authentication fails:
+
+1. Run `bkper auth login` when the Bkper session is missing or expired.
+2. Retry the Git operation; a five-minute repository credential is minted automatically.
+3. If the managed `origin` is missing or incorrect, inspect `git remote -v` and use a fresh `bkper app clone <appId>` as the safe reference. Never replace an unrelated external remote automatically.
+4. Request App owner/developer access when Platform denies source access. Domain-pattern developers have the same private source read/write capability.
+
+The helper command is intentionally `bkper app git-credential <appId> [operation]`. It is internal Git plumbing, not a root `git` command or an `app git` group.
+
+## Managed Git preflight recovery
+
+Managed sync and deploy require `bkper.yaml` at the Git root, an attached branch, committed `HEAD`, and a clean tree. Ignored build output such as `dist/` is allowed.
+
+| Failure | Safe recovery |
+| --- | --- |
+| No Git repository | For a new standalone App, run `git init -b main`, review files, commit, and retry. Existing Apps are not migrated merely because they lack a remote. |
+| `bkper.yaml` below Git root | Keep the monorepo/external workflow; managed monorepos are not supported. |
+| No commits | Review, then run `git add .` and `git commit -m "Initial app"`. |
+| Detached `HEAD` | Attach a branch with `git switch -c <branch>`; use `main` for first activation. |
+| First activation is not on `main` | Switch to the existing `main` branch. The CLI does not rename or rewrite branches. |
+| Staged changes | Inspect `git diff --cached`; commit them or intentionally unstage them before retrying. |
+| Modified tracked files | Inspect `git diff`; commit or intentionally restore them before retrying. |
+| Non-ignored untracked files | Inspect `git status`; commit, ignore, or intentionally remove them before retrying. |
+| Missing or incorrect managed `origin` | Inspect `git remote -v`; compare with a fresh managed clone. Do not overwrite an external remote. |
+| Authentication or expired credential | Run `bkper auth login` if needed, then retry the Git operation for a new five-minute token. |
+| Remote branch ahead or divergent | Run `git fetch origin <branch>` and inspect `git log --oneline --left-right HEAD...origin/<branch>`; merge or rebase by your own choice, then push and retry. The CLI never force-resolves divergence. |
+| App ID or repository mismatch | Stop and use the clone/config belonging to the requested App; do not rewrite repository identity. |
+| Managed record temporarily missing | Retry sync/deploy. A managed marker never silently downgrades to external mode after a transient KV miss. |
+| Exact commit missing | Ensure the current clean commit was pushed to the registered managed `origin`, then retry. |
+
+## Roll back a managed deployment
+
+There is no hidden rollback ref, retained build archive, or automatic rollback API. Create an ordinary attached rollback branch at the selected committed source, build locally, and deploy explicitly:
+
+```bash
+git switch -c rollback/<name> <older-commit>
+bun run build
+bkper app deploy --preview
+# verify, then optionally deploy production
+bkper app deploy
+```
+
+The rollback branch is pushed normally. Preview remains optional; production does not require promotion from preview.
+
+`bkper app undeploy` removes only the selected runtime and optional runtime data. It never deletes managed source.
+
+---
+
 ## Install Apps on Books
 
 ```bash
@@ -425,11 +511,13 @@ Inside the interactive agent:
 
 ### App Lifecycle
 
--   `app init [name]` - Scaffold a new app from the template. With `name`, creates `./<name>` and uses it as the app id. Without `name`, initializes the current directory and derives the app id from the folder name.
+-   `app init [name]` - Scaffold a new app from the template. With `name`, creates `./<name>` and uses it as the app id. Without `name`, initializes the current directory and derives the app id from the folder name. Initializes Git on `main` when the target is not already a repository, without staging or committing files.
+-   `app clone <appId> [path]` - Clone a Bkper-managed App source repository. Does not install dependencies; run `bun install` explicitly afterward. External-source Apps must be cloned from their provider instead.
+-   `app git-credential <appId> [operation]` - Internal noninteractive Git credential helper for managed Artifacts source. Generated repository config pins the App ID and exact remote URL/path; Git appends `get`, `store`, or `erase`. Never persists tokens.
 -   `app list` - List all apps you have access to
--   `app sync` - Sync [bkper.yaml][bkper.yaml reference] configuration (URLs, description) to Bkper API
+-   `app sync` - Sync [bkper.yaml][bkper.yaml reference] configuration. If this sync creates an eligible new standalone App, activate managed source; if already managed, cleanly fast-forward-push the current committed branch first.
 -   `app build` - Build the server Worker bundle for deployment
--   `app deploy` - Deploy built artifacts to Cloudflare Workers for Platforms
+-   `app deploy` - For managed Apps, cleanly fast-forward-push and verify the current commit, then explicitly deploy the existing local build. External Apps keep direct upload behavior.
     -   `-p, --preview` - Deploy to preview environment
 -   `app status` - Show deployment status
 -   `app logs [appId]` - View recent app logs. When `appId` is omitted, the app id is read from local app config.
@@ -449,7 +537,7 @@ Inside the interactive agent:
     -   `--sp, --server-port <port>` - Server simulation port (default: `8787`)
     -   `--cp, --client-port <port>` - Client dev server port for local static assets (default: `5173`)
 
-> **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`
+> **Note:** `sync` and `deploy` are independent explicit operations. `sync` updates App metadata and, for managed Apps, safely pushes committed source. `deploy` uploads an existing local build and never runs a build command. An ordinary Git push never deploys.
 
 ### App Installation
 

package/lib/docs/index.md

@@ -6,7 +6,7 @@ For Bkper data, accounting, reporting, tax, or financial-flow tasks, read `core/
 
 - `core/core-concepts.md` — canonical Bkper data model: resources, movements, balances, accounts, groups, books, transactions, properties, and the zero-sum invariant.
 - `cli/data-management.md` — CLI reference for managing financial data and files: books, accounts, groups, files, transactions, per-account balance queries, query operators (on:, after:, before:, account:, group:), output formats (table/json/csv), human-review Bkper UI links, batch operations via stdin/piping, collections.
-- `cli/app-management.md` — CLI reference for building and deploying Bkper apps: dev/build/deploy workflow, app install/uninstall, secrets management, app logs, bkper.yaml configuration reference (identity, branding, events, menu integration, deployment).
+- `cli/app-management.md` — CLI reference for building and deploying Bkper apps: init/git clone/credential helpers, dev/build/deploy workflow, app install/uninstall, secrets management, app logs, bkper.yaml configuration reference (identity, branding, events, menu integration, deployment).
 - `apps/app-building.md` — Full app-building reference: single Worker app architecture (`client/` + `server/`), development loop, `/api/*` routes, `/events` handlers, deployment patterns, the Bkper Platform, and self-hosted alternatives. Includes authentication patterns for web clients (`@bkper/web-auth`), server API routes (`Authorization: Bearer` on `/api/*` with outbound auth injection), platform event handlers (`new Bkper()` with outbound auth injection), and local development.
 - `reporting/financial-statements.md` — Deterministic reporting principles and Bkper query semantics for balance sheet and P&L: trusted routes, root reporting groups, permanent vs period date rules, and provisional query patterns.
 - `reporting/taxes.md` — Deterministic tax reporting principles: trusted routes, external tax-rule loading/discovery, user-approved tax-relevant groups/accounts, period activity queries, explicit jurisdiction assumptions, and provisional query patterns.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "bkper",
-    "version": "4.24.2",
+    "version": "4.24.3",
     "description": "Command line client for Bkper",
     "bin": {
         "bkper": "./lib/cli.js"