bkper 4.24.2 → 4.25.0

package/lib/commands/apps/source-workflow.js

@@ -0,0 +1,180 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { configureManagedOrigin, createPlatformSourceApi, detectSourceMode, ensurePendingSourceMarker, inspectGitRepository, ManagedGitError, pushAllLocalRefsAtomic, pushCurrentBranchSafe, readSourceMarker, requireManagedGitPreflight, writeManagedSourceMarker, } from './git/index.js';
+function platformStatus(status) {
+    return typeof status === 'string' ? null : status;
+}
+function pushManagedRepository(options_1, remote_1) {
+    return __awaiter(this, arguments, void 0, function* (options, remote, requireMainBranch = false, upload = 'main') {
+        var _a, _b;
+        const appDir = (_a = options.appDir) !== null && _a !== void 0 ? _a : process.cwd();
+        if (options.push) {
+            return options.push({
+                appDir,
+                expectedOriginRemote: remote,
+                requireMainBranch,
+                upload,
+            });
+        }
+        const preflight = yield requireManagedGitPreflight({
+            appDir,
+            expectedOriginRemote: remote,
+            requireMainBranch,
+        });
+        yield ((_b = options.configureOrigin) !== null && _b !== void 0 ? _b : configureManagedOrigin)(preflight.repo.root, remote, options.appId);
+        const push = upload === 'all_refs' ? pushAllLocalRefsAtomic : pushCurrentBranchSafe;
+        return push({
+            appDir,
+            expectedOriginRemote: remote,
+            requireMainBranch,
+            upload,
+        });
+    });
+}
+function validateLocalManagedMarker(appDir, appId) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const repo = yield inspectGitRepository(appDir);
+        if (!repo)
+            return;
+        const marker = readSourceMarker(repo.root);
+        if ((marker === null || marker === void 0 ? void 0 : marker.state) === 'managed' && marker.appId !== appId) {
+            throw new ManagedGitError('APP_ID_MISMATCH', [
+                'The local managed-source marker does not match bkper.yaml.',
+                `Config App ID: ${appId}`,
+                `Marker App ID: ${marker.appId}`,
+                'Use the clone that belongs to this App or repair the local marker intentionally.',
+            ].join('\n'));
+        }
+    });
+}
+/**
+ * Integrates managed activation and source pushes into direct Core metadata sync.
+ * Core remains the metadata authority; Artifacts pushes never deploy.
+ */
+export function syncManagedAppSource(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c, _d;
+        const appDir = (_a = options.appDir) !== null && _a !== void 0 ? _a : process.cwd();
+        const api = (_b = options.api) !== null && _b !== void 0 ? _b : createPlatformSourceApi();
+        const statusResult = yield api.getStatus(options.appId);
+        const status = platformStatus(statusResult);
+        const decision = yield detectSourceMode({
+            appDir,
+            appId: options.appId,
+            platformStatus: status,
+            coreAppExists: options.coreAppExists,
+            featureDisabled: statusResult === 'feature_disabled',
+        });
+        const action = options.coreAppExists ? 'updated' : 'created';
+        if (decision.mode === 'external') {
+            yield options.syncCore(action);
+            return { id: options.appId, action };
+        }
+        yield validateLocalManagedMarker(appDir, options.appId);
+        if (statusResult === 'feature_disabled') {
+            throw new ManagedGitError('MANAGED_SOURCE_UNAVAILABLE', 'This repository has a managed-source marker, but managed source is disabled. Retry when the Platform feature is available.');
+        }
+        if (decision.mode === 'activate_managed' || decision.reason === 'pending_marker') {
+            const preflight = yield requireManagedGitPreflight({
+                appDir,
+                requireMainBranch: true,
+            });
+            const upload = (_c = decision.upload) !== null && _c !== void 0 ? _c : 'main';
+            const pending = ensurePendingSourceMarker(preflight.repo.root, upload);
+            console.log(upload === 'all_refs'
+                ? 'Enabling Bkper-managed source and uploading local branches and tags...'
+                : 'Enabling Bkper-managed source and uploading committed main...');
+            yield options.syncCore(action);
+            const activation = yield api.activate(options.appId, pending.activationId);
+            if (activation.source.appId !== options.appId) {
+                throw new ManagedGitError('APP_ID_MISMATCH', 'Managed source activation returned a different App ID.');
+            }
+            yield ((_d = options.configureOrigin) !== null && _d !== void 0 ? _d : configureManagedOrigin)(preflight.repo.root, activation.source.remote, options.appId);
+            yield pushManagedRepository(options, activation.source.remote, true, pending.upload);
+            writeManagedSourceMarker(preflight.repo.root, options.appId, activation.source.remote);
+            return { id: options.appId, action };
+        }
+        if ((status === null || status === void 0 ? void 0 : status.mode) !== 'managed') {
+            throw new ManagedGitError('MANAGED_SOURCE_UNAVAILABLE', 'The local repository is managed, but the Platform record is not visible yet. Retry the sync.');
+        }
+        if (status.appId !== options.appId) {
+            throw new ManagedGitError('APP_ID_MISMATCH', 'Platform managed source does not match the local App ID.');
+        }
+        const pushed = yield pushManagedRepository(options, status.remote);
+        const repo = yield inspectGitRepository(appDir);
+        if (repo)
+            writeManagedSourceMarker(repo.root, options.appId, status.remote);
+        yield options.syncCore(action);
+        return { id: options.appId, action };
+    });
+}
+/**
+ * Pushes managed source before the caller reads and uploads existing local build output.
+ * External Apps remain source-less and retain direct-upload behavior.
+ */
+export function prepareManagedDeploySource(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        const appDir = (_a = options.appDir) !== null && _a !== void 0 ? _a : process.cwd();
+        const api = (_b = options.api) !== null && _b !== void 0 ? _b : createPlatformSourceApi();
+        let statusResult;
+        try {
+            statusResult = yield api.getStatus(options.appId);
+        }
+        catch (error) {
+            if (error instanceof ManagedGitError && error.code === 'AUTHENTICATION_REQUIRED') {
+                const repo = yield inspectGitRepository(appDir);
+                const marker = repo ? readSourceMarker(repo.root) : null;
+                if (!marker)
+                    return undefined;
+            }
+            throw error;
+        }
+        if (statusResult === 'feature_disabled' || statusResult === 'app_not_found') {
+            const repo = yield inspectGitRepository(appDir);
+            const marker = repo ? readSourceMarker(repo.root) : null;
+            if (marker) {
+                throw new ManagedGitError('MANAGED_SOURCE_UNAVAILABLE', statusResult === 'feature_disabled'
+                    ? 'This repository is managed, but managed source is disabled in this Platform environment.'
+                    : 'This repository is managed, but its Platform linkage is not visible. Retry the deployment.');
+            }
+            return undefined;
+        }
+        const decision = yield detectSourceMode({
+            appDir,
+            appId: options.appId,
+            platformStatus: statusResult,
+            coreAppExists: true,
+        });
+        if (decision.mode === 'external' || decision.mode === 'activate_managed') {
+            return undefined;
+        }
+        if (decision.reason === 'pending_marker') {
+            throw new ManagedGitError('MANAGED_SOURCE_UNAVAILABLE', 'Managed source activation is pending. Run `bkper app sync` to finish uploading source before deploying.');
+        }
+        yield validateLocalManagedMarker(appDir, options.appId);
+        if (statusResult.mode !== 'managed') {
+            throw new ManagedGitError('MANAGED_SOURCE_UNAVAILABLE', 'Managed source linkage is not visible yet. Run `bkper app sync` or retry the deployment.');
+        }
+        if (statusResult.appId !== options.appId) {
+            throw new ManagedGitError('APP_ID_MISMATCH', 'Platform managed source does not match the local App ID.');
+        }
+        const pushed = yield pushManagedRepository(options, statusResult.remote);
+        const repo = yield inspectGitRepository(appDir);
+        if (repo)
+            writeManagedSourceMarker(repo.root, options.appId, statusResult.remote);
+        return {
+            mode: 'managed',
+            declaredBranch: pushed.branch,
+            commitSha: pushed.head,
+        };
+    });
+}
+//# sourceMappingURL=source-workflow.js.map

package/lib/commands/apps/source-workflow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-workflow.js","sourceRoot":"","sources":["../../../src/commands/apps/source-workflow.ts"],"names":[],"mappings":"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"}

package/lib/commands/apps/sync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../../src/commands/apps/sync.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAc,MAAM,UAAU,CAAC;AAG3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;;;GAIG;AACH,wBAAsB,SAAS,IAAI,OAAO,CAAC,GAAG,CAAC,CAI9C;AAED;;;;GAIG;AACH,wBAAsB,SAAS,IAAI,OAAO,CAAC,GAAG,CAAC,CAI9C;AAED;;;;GAIG;AACH,wBAAsB,OAAO,IAAI,OAAO,CAAC,UAAU,CAAC,CA+BnD"}
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../../src/commands/apps/sync.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAc,MAAM,UAAU,CAAC;AAG3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7C;;;;GAIG;AACH,wBAAsB,SAAS,IAAI,OAAO,CAAC,GAAG,CAAC,CAI9C;AAED;;;;GAIG;AACH,wBAAsB,SAAS,IAAI,OAAO,CAAC,GAAG,CAAC,CAI9C;AAED;;;;GAIG;AACH,wBAAsB,OAAO,IAAI,OAAO,CAAC,UAAU,CAAC,CAmCnD"}

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,41 @@ 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:** `bkper app sync` activates private Bkper-managed Git for a new or existing App when `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`. New Apps initially upload `main`; existing Apps atomically upload all local branches and tags.
+- **External source:** an App keeps direct sync/deploy behavior when it has an external Git remote, is nested in a monorepo, or is not rooted at `bkper.yaml`. The CLI never changes an existing external remote.
+
+To opt out, keep a GitHub, GitLab, or other provider remote configured. Managed mode is sticky after activation; adding another remote later does not change it, and Artifacts remains `origin`. The App listing `repoUrl` metadata does not select source mode.
+
+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.
+
+### Migrate from an external Git provider
+
+Source changes remain the user or coding agent's responsibility; the CLI never removes or renames provider remotes. Before migration, verify that `main` is clean and committed, the provider has the latest source, and every desired provider-only branch and tag is available locally. A coding agent must show the exact mutating commands and obtain explicit user approval before continuing.
+
+Inspect first:
+
+```bash
+git status --short --branch
+git remote -v
+```
+
+After approval, remove every external remote and sync. For a repository whose only external remote is `origin`:
+
+```bash
+git remote remove origin
+bkper app sync
+```
+
+Sync preserves the existing App identity, activates managed source, configures it as `origin`, and atomically uploads all local branches and tags. If that upload fails, the pending marker makes the next `bkper app sync` retry the complete upload. `bkper app deploy` never activates migration.
+
 ## Verification Workflow
 
 When scaffolding, developing, or deploying an app, verify each step before proceeding. This prevents broken deployments and silent failures.
@@ -18,13 +53,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 +89,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 +185,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 standalone App, run `git init -b main`, review files, commit, and retry. An eligible new or existing App activates managed source on sync when no remote exists. |
+| `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 +531,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. For an eligible standalone repository with no remote, activate managed source for a new or existing App; existing migrations atomically upload all local branches and tags. 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 +557,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.25.0",
     "description": "Command line client for Bkper",
     "bin": {
         "bkper": "./lib/cli.js"