@polardbx/pxbaas 0.1.0-beta.2 → 0.1.0-beta.4

package/dist/commands/app/index.js

@@ -7,7 +7,8 @@ import { ProfileManager } from "../../credentials/profile.js";
 import { CredentialStore } from "../../credentials/credential-store.js";
 import { formatError, formatSuccess, formatWarning, } from "../../credentials/index.js";
 import { HONO_VERSION_PLACEHOLDER, scaffoldApp, listTemplates, listTemplateIdsSync, } from "../../app/templates.js";
-import { runPreflight, isPublicEndpoint } from "../../app/preflight.js";
+import { checkQuota, FALLBACK_QUOTA_LIMIT, isPublicEndpoint, quotaFindings, runPreflight, } from "../../app/preflight.js";
+import { forgetLocalMount, lookupLocalMount, recordLocalMount, } from "../../app/local-index.js";
 import { lintAppSource } from "../../app/spec-lint.js";
 import { applySchema, getSchemaSink, } from "../../db/apply-schema.js";
 import { parseRlsJson, extractCreateTableNames } from "../../db/sql-file.js";
@@ -55,6 +56,7 @@ export function registerAppCommands(program) {
         .option("--verify-jwt", "Require JWT (safer, but the URL is no longer publicly openable)")
         .option("--dry-run", "Run preflight + spec review and show the plan without deploying")
         .option("--skip-spec-check", "Skip the pxbaas-app-spec compliance lint (not recommended)")
+        .option("--quota-limit <n>", "Override the Edge Function quota limit for the preflight check (authoritative). Defaults to the instance-reported limit.")
         .option("--json", "Output in JSON format")
         .action(async (name, options) => {
         try {
@@ -111,6 +113,7 @@ export function registerAppCommands(program) {
         .description("Print the shareable URL for a deployed webapp")
         .option("--dir <directory>", "Parent directory for the app", "./apps")
         .option("--slug <slug>", "Override function slug")
+        .option("--mount-id <mountId>", "Query this server-side mount directly (works when app.json lost its deployment state)")
         .option("--json", "Output in JSON format")
         .action(async (name, options) => {
         try {
@@ -120,6 +123,21 @@ export function registerAppCommands(program) {
             fail(e, options.json);
         }
     });
+    appCmd
+        .command("adopt <name>")
+        .description("Adopt an existing server-side App mount into the local app.json deployment state (recovery for a lost or stale mountId)")
+        .option("--dir <directory>", "Parent directory for the app", "./apps")
+        .requiredOption("--mount-id <mountId>", "Server-side mount id (m-...) to adopt; take it from the last successful deploy output or `pxbaas app url <name> --json`")
+        .option("--generation <n>", "Generation to record for the CAS lifecycle ops (default: the server-reported value)")
+        .option("--json", "Output in JSON format")
+        .action(async (name, options) => {
+        try {
+            await handleAdopt(name, options, program);
+        }
+        catch (e) {
+            fail(e, isJson(options, program));
+        }
+    });
     appCmd
         .command("list")
         .description("List deployed edge functions (apps)")
@@ -152,6 +170,7 @@ export function registerAppCommands(program) {
         .description("Permanently destroy a mode=webapp App: delete its edge functions + mount record (needs --confirm). By default DB tables are kept; pass --purge-db to also drop the app's tables + RLS.")
         .option("--dir <directory>", "Parent directory for the app", "./apps")
         .option("--confirm", "Actually destroy (required)")
+        .option("--mount-id <mountId>", "Destroy this server-side mount even when app.json has no (or a stale) deployment state")
         .option("--purge-db", "Also drop the app's DB tables and remove its RLS registry rows (destructive)")
         .option("--schema <schema>", "Single-tenant schema the app's tables live in (used with --purge-db)", "public")
         .option("--json", "Output in JSON format")
@@ -201,6 +220,37 @@ export function registerAppCommands(program) {
 function isJson(options, program) {
     return Boolean(options.json || program.opts().json);
 }
+/**
+ * Recovery guidance for the local-state/server-state desync errors.
+ *
+ * These three used to dead-end the operator: the app is still live on the
+ * instance, but with no usable mountId the CLI can neither publish nor destroy
+ * it, and the bare server message ("App mount not found") gives no way out. The
+ * hints are printed separately instead of being folded into `message` so the
+ * server-owned `{code,message}` payload stays untouched for `--json` consumers.
+ */
+const RECOVERY_HINTS = {
+    APP_MOUNT_NOT_FOUND: [
+        "  The mountId recorded locally does not exist on this instance (reinstalled instance, or the mount was cleaned up elsewhere). Do not keep re-running deploy.",
+        "  Get the real mountId from the last successful deploy output, `pxbaas app url <name> --json`, or `.pxbaas/apps.json`, then:",
+        "    pxbaas app url <name> --mount-id <m-...>                      # is the app still live?",
+        "    pxbaas app adopt <name> --mount-id <m-...> [--generation <n>] # take it over; deploy/publish/rollback/destroy work again",
+        "    pxbaas app destroy <name> --confirm --mount-id <m-...>        # or reclaim it",
+        "  Only when the server truly has no such App: delete the `deployment` block from app.json and re-run `pxbaas app deploy <name>`.",
+    ].join("\n"),
+    APP_MOUNT_CONFLICT: [
+        "  The server already has an App with this name but app.json holds no deployment state, so this working copy lost track of a live mount. Re-running deploy will keep failing, and `app destroy <name>` alone cannot help either.",
+        "  Get the real mountId from the last successful deploy output, `pxbaas app url <name> --json`, or `.pxbaas/apps.json`, then either:",
+        "    pxbaas app adopt <name> --mount-id <m-...>                    # take the existing mount over, then deploy again",
+        "    pxbaas app destroy <name> --confirm --mount-id <m-...>        # reclaim it; the next deploy creates a fresh mount",
+    ].join("\n"),
+    APP_DEPLOYMENT_NOT_FOUND: [
+        "  No local deployment state, so the CLI has no mountId to act on. Recover the mount instead of re-deploying (a re-deploy will hit APP_MOUNT_CONFLICT and orphan the live app):",
+        "    pxbaas app destroy <name> --confirm --mount-id <m-...>        # destroy without any local state",
+        "    pxbaas app adopt <name> --mount-id <m-...>                    # write the server mount back into app.json",
+        "    pxbaas app url <name> --mount-id <m-...>                      # just check whether it is still live",
+    ].join("\n"),
+};
 function fail(error, json) {
     const message = error instanceof Error ? error.message : String(error);
     const code = error instanceof AppsApiError ? error.code : "CLI_ERROR";
@@ -208,8 +258,19 @@ function fail(error, json) {
         console.log(JSON.stringify({ code, message }, null, 2));
     else
         console.error(formatError(`${code}: ${message}`));
+    const hint = RECOVERY_HINTS[code];
+    if (hint)
+        console.error(hint);
     process.exit(1);
 }
+/** Surface a best-effort side effect (the workspace index) without failing. */
+function warnIfFailed(message) {
+    if (message)
+        console.error(formatWarning(message));
+}
+function formatFinding(f) {
+    return `[${f.rule}] ${f.message} (see ${f.specRef})`;
+}
 function validateSlug(slug) {
     if (!SLUG_RE.test(slug) || slug.length > 128) {
         throw new Error(`Invalid slug '${slug}'. Must match ^[a-zA-Z0-9][a-zA-Z0-9_-]*$ and be <=128 chars.`);
@@ -282,6 +343,98 @@ async function getDriver() {
         anonKey: credentials.anonKey,
     };
 }
+/**
+ * Resolve the effective Edge Function quota limit and its source for preflight.
+ * Precedence: --quota-limit (flag) > instance capabilities.maxFunctions
+ * (platform) > client fallback (advisory, non-blocking). Never throws — an
+ * unavailable capabilities read degrades to the fallback so a quota lookup can
+ * never block a deploy; the server-side DB trigger remains the authoritative
+ * gate. (gomoku retrospective 弯路5)
+ */
+async function resolveQuotaLimit(appsDriver, flagValue) {
+    const parsed = flagValue != null ? Number(flagValue) : NaN;
+    if (Number.isFinite(parsed) && parsed > 0) {
+        return { quotaLimit: Math.floor(parsed), quotaLimitSource: "flag" };
+    }
+    let quotaLimit;
+    let quotaLimitSource = "fallback";
+    try {
+        const caps = await appsDriver.capabilities();
+        const max = caps?.maxFunctions;
+        if (typeof max === "number" && Number.isFinite(max) && max > 0) {
+            quotaLimit = max;
+            quotaLimitSource = "platform";
+        }
+    }
+    catch {
+        // fall through to the advisory client fallback
+    }
+    return {
+        quotaLimit,
+        quotaLimitSource,
+        // The flag is documented as authoritative, so a value the CLI cannot honor
+        // must never be dropped without a word (缺陷3 Q2).
+        ...(flagValue != null
+            ? {
+                flagWarning: `--quota-limit '${flagValue}' was NOT consumed: it must be a positive integer. ` +
+                    `This run fell back to the ${quotaLimitSource} limit (${quotaLimit ?? FALLBACK_QUOTA_LIMIT}). ` +
+                    `Re-run with e.g. --quota-limit 500 to make the quota check authoritative.`,
+            }
+            : {}),
+    };
+}
+/**
+ * Edge Function count for the quota gate. A failing `list` degrades to 0 rather
+ * than hard-failing: preflight must never be the reason a deploy breaks, and an
+ * unreadable count only weakens an advisory check (弯路5).
+ */
+async function safeFunctionsCount(driver) {
+    try {
+        return (await driver.list()).length;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Resolve the deployment state a lifecycle command should act on: `app.json`
+ * first, then the workspace index (缺陷5 A4).
+ *
+ * Without the index fallback, a manifest that lost its `deployment` block leaves
+ * a live mount unreachable — deploy answers APP_MOUNT_CONFLICT and destroy
+ * answers APP_DEPLOYMENT_NOT_FOUND. An index entry whose mount is gone
+ * server-side is dropped on the spot so the caller can create a fresh one.
+ * Returns undefined when neither source knows the app.
+ */
+async function resolveDeployment(appsDriver, manifest, dir, name, scope) {
+    if (manifest.deployment) {
+        return { ...manifest.deployment, source: "manifest" };
+    }
+    const found = await lookupLocalMount(dir, name, scope);
+    if (found.ignored)
+        console.error(formatWarning(found.ignored));
+    if (!found.entry)
+        return undefined;
+    try {
+        const mount = await appsDriver.get(found.entry.mountId);
+        console.error(formatWarning(`↻ Recovered the deployment state for '${name}' from ${found.path} ` +
+            `(mount ${mount.mountId}, generation ${mount.generation}); app.json has none. ` +
+            `Run \`pxbaas app adopt ${name} --mount-id ${mount.mountId}\` to write it back permanently.`));
+        return {
+            mountId: mount.mountId,
+            generation: mount.generation,
+            source: "index",
+            mount,
+        };
+    }
+    catch (e) {
+        if (!(e instanceof AppsApiError) || e.code !== "APP_MOUNT_NOT_FOUND")
+            throw e;
+        warnIfFailed(await forgetLocalMount(dir, name, found.entry.mountId));
+        console.error(formatWarning(`Dropping the ${found.path} entry for '${name}': mount ${found.entry.mountId} no longer exists server-side.`));
+        return undefined;
+    }
+}
 /**
  * `pxbaas app db-init <name>` — apply the app's bundled db/schema.sql (plus an
  * optional declarative db/rls.json) so a freshly published app has its tables +
@@ -380,10 +533,10 @@ async function handleCapabilities(options, program) {
 }
 async function handleLifecycle(action, name, options, program) {
     const manifest = await requireWebappManifest(options.dir, name);
-    const deployment = manifest.deployment;
+    const { appsDriver, endpoint, tenantId } = await getDriver();
+    const deployment = await resolveDeployment(appsDriver, manifest, options.dir, name, { endpoint, tenantId });
     if (!deployment)
         throw new AppsApiError("APP_DEPLOYMENT_NOT_FOUND", `App '${name}' has no local deployment state`);
-    const { appsDriver } = await getDriver();
     const capabilities = await appsDriver.capabilities();
     assertWebappCapabilities(capabilities, manifest.backend ?? null);
     let mount;
@@ -409,6 +562,7 @@ async function handleLifecycle(action, name, options, program) {
             : { candidateFunctionSlug: deployment.candidateFunctionSlug }),
     };
     await writeManifest(options.dir, name, manifest);
+    warnIfFailed(await recordLocalMount(options.dir, name, { mountId: mount.mountId, generation: mount.generation }, { endpoint, tenantId }));
     emitWebappResult(action === "publish"
         ? "published"
         : action === "rollback"
@@ -450,21 +604,23 @@ async function handleDeploy(name, options, program) {
     const declaredFiles = mode === "mpa"
         ? [...(manifest.pages ?? []), ...(manifest.assets ?? [])]
         : [];
-    const { driver, endpoint } = await getDriver();
-    let functionsCount = 0;
-    try {
-        functionsCount = (await driver.list()).length;
-    }
-    catch {
-        functionsCount = 0; // preflight should not hard-fail if list is unavailable
-    }
+    const { driver, endpoint, appsDriver } = await getDriver();
+    const functionsCount = await safeFunctionsCount(driver);
+    // Resolve the authoritative Edge Function quota: --quota-limit (flag) wins,
+    // else the instance-reported capabilities.maxFunctions (platform), else the
+    // client fallback (advisory only). Fixes the hardcoded-5 false block (弯路5).
+    const { quotaLimit, quotaLimitSource, flagWarning } = await resolveQuotaLimit(appsDriver, options.quotaLimit);
     const pre = runPreflight({
         source,
         endpoint,
         functionsCount,
+        quotaLimit,
+        quotaLimitSource,
         verifyJwt,
         entrypointExists,
     });
+    if (flagWarning)
+        pre.warnings.unshift(flagWarning);
     // Automatic pxbaas-app-spec compliance review (skip with --skip-spec-check).
     const spec = options.skipSpecCheck
         ? { skipped: true, passed: true, blockers: [], warnings: [] }
@@ -478,9 +634,8 @@ async function handleDeploy(name, options, program) {
                 auxiliarySources,
             }),
         };
-    const fmt = (f) => `[${f.rule}] ${f.message} (see ${f.specRef})`;
-    const allBlockers = [...pre.blockers, ...spec.blockers.map(fmt)];
-    const allWarnings = [...pre.warnings, ...spec.warnings.map(fmt)];
+    const allBlockers = [...pre.blockers, ...spec.blockers.map(formatFinding)];
+    const allWarnings = [...pre.warnings, ...spec.warnings.map(formatFinding)];
     if (options.dryRun) {
         const out = {
             status: "dry-run",
@@ -582,7 +737,7 @@ async function handleWebappDeploy(name, manifestInput, options, program) {
         backend.framework = framework ?? backend.framework;
         backend.verifyJwt = options.verifyJwt ?? backend.verifyJwt;
     }
-    const { driver, appsDriver } = await getDriver();
+    const { driver, appsDriver, endpoint, tenantId } = await getDriver();
     const capabilities = await appsDriver.capabilities();
     assertWebappCapabilities(capabilities, backend);
     const appDir = join(options.dir, name);
@@ -680,29 +835,91 @@ async function handleWebappDeploy(name, manifestInput, options, program) {
                 sessionHeaders: capabilities.sessionHeaders,
             }),
         };
-    if (!spec.passed) {
+    // A dry-run reports every finding instead of aborting on the first one, so the
+    // spec blockers are only fatal on the real deploy path (order preserved there:
+    // spec review before the artifact size limits).
+    if (!spec.passed && !options.dryRun) {
         const details = spec.blockers
             .map((item) => `[${item.rule}] ${item.message}`)
             .join("; ");
         throw new AppsApiError("APP_ARTIFACT_INVALID", details);
     }
     await assertArtifactLimits(uploadFiles, capabilities);
+    // Q1: this path used to skip preflight entirely, so --quota-limit was silently
+    // ignored on every webapp deploy. Only the quota half of runPreflight is reused:
+    // a webapp has no single-file `source`/entrypoint, and inventing those fields
+    // just to call runPreflight would fake checks the artifact lint already owns.
+    const functionsCount = await safeFunctionsCount(driver);
+    const { quotaLimit, quotaLimitSource, flagWarning } = await resolveQuotaLimit(appsDriver, options.quotaLimit);
+    const quota = checkQuota(functionsCount, quotaLimit, quotaLimitSource);
+    const quotaReport = quotaFindings(quota);
+    const preflight = {
+        quota,
+        quotaLimitSource,
+        blockers: quotaReport.blockers,
+        warnings: [...(flagWarning ? [flagWarning] : []), ...quotaReport.warnings],
+    };
     if (options.dryRun) {
         const output = {
             status: "dry-run",
             app: name,
             mode: "webapp",
             capabilities,
+            preflight,
             specLint: spec,
         };
+        const allBlockers = [
+            ...preflight.blockers,
+            ...spec.blockers.map(formatFinding),
+        ];
+        const allWarnings = [
+            ...preflight.warnings,
+            ...spec.warnings.map(formatFinding),
+        ];
         if (isJson(options, program))
             console.log(JSON.stringify(output, null, 2));
-        else
-            console.log(formatSuccess(`Webapp '${name}' passed capability and artifact checks.`));
+        else {
+            // Q2: the human-mode dry-run used to print a single success line and swallow
+            // every specLint/preflight warning the JSON payload carried.
+            console.log(formatWarning(`Dry run for webapp '${name}'`));
+            for (const b of allBlockers)
+                console.error(formatError(b));
+            for (const w of allWarnings)
+                console.log(formatWarning(w));
+            if (allBlockers.length === 0)
+                console.log(formatSuccess(`Webapp '${name}' passed capability and artifact checks. Re-run without --dry-run to deploy.`));
+        }
+        if (allBlockers.length > 0)
+            process.exit(1);
         return;
     }
-    const mount = manifest.deployment
-        ? await appsDriver.get(manifest.deployment.mountId)
+    // Q3: a real deploy consumes the quota result too. Only an authoritative limit
+    // (flag/platform) blocks; the client fallback stays a warning, so an instance
+    // that does not report maxFunctions is never gated by a client-side guess.
+    if (preflight.blockers.length > 0) {
+        if (isJson(options, program)) {
+            console.log(JSON.stringify({
+                status: "blocked",
+                app: name,
+                mode: "webapp",
+                preflight,
+                specLint: spec,
+            }, null, 2));
+        }
+        else {
+            console.error(formatError("Edge Function quota check failed — fix these before deploying:"));
+            for (const b of preflight.blockers)
+                console.error(formatError(b));
+            for (const w of preflight.warnings)
+                console.log(formatWarning(w));
+        }
+        process.exit(1);
+    }
+    const resolved = await resolveDeployment(appsDriver, manifest, options.dir, name, { endpoint, tenantId });
+    // Neither app.json nor the workspace index knows this app -> first deploy, so a
+    // fresh mount is created (a name clash surfaces as APP_MOUNT_CONFLICT).
+    const mount = resolved
+        ? (resolved.mount ?? (await appsDriver.get(resolved.mountId)))
         : await appsDriver.create({ appName: name });
     const candidateFunctionSlug = createCandidateSlug(mount.id);
     const entrypoint = backend?.entrypoint ?? `${frontend.root}/${frontend.index}`;
@@ -719,6 +936,10 @@ async function handleWebappDeploy(name, manifestInput, options, program) {
         generation: mount.generation,
     };
     await writeManifest(options.dir, name, manifest);
+    // A4: mirror the deployment state into the workspace index as soon as the
+    // candidate is uploaded, so a mount is recoverable even if the publish below
+    // fails and app.json is later lost.
+    warnIfFailed(await recordLocalMount(options.dir, name, { mountId: mount.mountId, generation: mount.generation }, { endpoint, tenantId }));
     const published = await appsDriver.publish(mount.mountId, {
         candidateFunctionSlug,
         expectedGeneration: mount.generation,
@@ -728,7 +949,14 @@ async function handleWebappDeploy(name, manifestInput, options, program) {
         generation: published.generation,
     };
     await writeManifest(options.dir, name, manifest);
-    emitWebappResult("published", name, published, capabilities, options, program, { candidateFunctionSlug, specLint: spec });
+    warnIfFailed(await recordLocalMount(options.dir, name, { mountId: published.mountId, generation: published.generation }, { endpoint, tenantId }));
+    emitWebappResult("published", name, published, capabilities, options, program, { candidateFunctionSlug, specLint: spec, preflight });
+    // The quota advisories (fallback tier, an unconsumed --quota-limit) must not be
+    // JSON-only: a human-mode deploy that silently ignored the flag is the bug Q2
+    // is about.
+    if (!isJson(options, program))
+        for (const w of preflight.warnings)
+            console.log(formatWarning(w));
 }
 function parseBackendFramework(value) {
     if (value === undefined)
@@ -1068,13 +1296,18 @@ async function handleWebappVerify(name, manifest, options, program) {
 }
 async function handleUrl(name, options, program) {
     const manifest = await readManifest(options.dir, name);
-    if (manifest.mode === "webapp") {
-        const webapp = requireWebappManifestValue(manifest, name);
-        if (!webapp.deployment)
+    // A2: --mount-id makes `app url` usable with no local state at all, which is
+    // exactly when an operator needs to check whether the app is still live.
+    if (options.mountId || manifest.mode === "webapp") {
+        const webapp = manifest.mode === "webapp"
+            ? requireWebappManifestValue(manifest, name)
+            : null;
+        const mountId = options.mountId ?? webapp?.deployment?.mountId;
+        if (!mountId)
             throw new AppsApiError("APP_DEPLOYMENT_NOT_FOUND", `App '${name}' has no local deployment state`);
         const { appsDriver } = await getDriver();
         const [mount, capabilities] = await Promise.all([
-            appsDriver.get(webapp.deployment.mountId),
+            appsDriver.get(mountId),
             appsDriver.capabilities(),
         ]);
         emitWebappResult("url", name, mount, capabilities, options, program);
@@ -1092,6 +1325,75 @@ async function handleUrl(name, options, program) {
     if (!publicReachable)
         console.log(formatWarning("Endpoint is not publicly reachable; this URL will not work cross-machine."));
 }
+/**
+ * `pxbaas app adopt <name> --mount-id <m-...>` (缺陷5 A2) — write a mount that
+ * already exists server-side back into the local `app.json` deployment block.
+ *
+ * This is the escape hatch for the deadlock where the app is live but this
+ * working copy lost its mountId: deploy answers APP_MOUNT_CONFLICT and destroy
+ * answers APP_DEPLOYMENT_NOT_FOUND, so nothing else can reach the mount. The
+ * mount is verified with a GET before anything is written — adopting an unknown
+ * mountId would only move the deadlock to the next lifecycle call.
+ */
+async function handleAdopt(name, options, program) {
+    const mountId = options.mountId?.trim();
+    if (!mountId) {
+        throw new AppsApiError("APP_MOUNT_ID_REQUIRED", `--mount-id is required: \`pxbaas app adopt ${name} --mount-id <m-...>\`. ` +
+            "Find the id in the last successful deploy output or `pxbaas app url <name> --json`.");
+    }
+    let generation;
+    if (options.generation != null) {
+        if (!/^\d+$/.test(options.generation)) {
+            throw new Error("--generation must be a non-negative integer.");
+        }
+        generation = Number(options.generation);
+    }
+    const manifestPath = join(options.dir, name, "app.json");
+    if (!existsSync(manifestPath)) {
+        throw new AppsApiError("APP_MANIFEST_NOT_FOUND", `No app.json for app '${name}' at ${manifestPath}. ` +
+            `Scaffold it first (\`pxbaas app new ${name} --dir ${options.dir}\`) or fix --dir, ` +
+            `then re-run \`pxbaas app adopt ${name} --mount-id ${mountId}\`.`);
+    }
+    const manifest = requireWebappManifestValue(await readManifest(options.dir, name), name);
+    const { appsDriver, endpoint, tenantId } = await getDriver();
+    const mount = await appsDriver.get(mountId);
+    const warnings = [];
+    if (mount.appName && mount.appName !== name) {
+        warnings.push(`Server mount ${mount.mountId} is registered as appName '${mount.appName}', not '${name}'. ` +
+            "Adopted anyway — double-check this is the right mount before you publish or destroy it.");
+    }
+    if (generation != null && generation !== mount.generation) {
+        warnings.push(`Recording generation ${generation} while the server reports ${mount.generation}. ` +
+            "publish/rollback/unpublish are CAS-guarded on this value and will fail if it is wrong.");
+    }
+    if (manifest.deployment && manifest.deployment.mountId !== mount.mountId) {
+        warnings.push(`Replacing the previous local deployment state (mount ${manifest.deployment.mountId}, ` +
+            `generation ${manifest.deployment.generation}).`);
+    }
+    manifest.deployment = {
+        mountId: mount.mountId,
+        generation: generation ?? mount.generation,
+    };
+    await writeManifest(options.dir, name, manifest);
+    warnIfFailed(await recordLocalMount(options.dir, name, { mountId: mount.mountId, generation: manifest.deployment.generation }, { endpoint, tenantId }));
+    const output = {
+        status: "adopted",
+        app: name,
+        mount,
+        deployment: manifest.deployment,
+        warnings,
+    };
+    if (isJson(options, program)) {
+        console.log(JSON.stringify(output, null, 2));
+        return;
+    }
+    console.log(formatSuccess(`↻ Adopted existing mount ${mount.mountId} (generation ${manifest.deployment.generation}) from server for '${name}'.`));
+    console.log(`  Mount status: ${mount.status}`);
+    console.log(`  URL:          ${mount.url}`);
+    for (const w of warnings)
+        console.log(formatWarning(w));
+    console.log(`  Next:         pxbaas app url ${name} | pxbaas app deploy ${name} | pxbaas app destroy ${name} --confirm`);
+}
 async function handleList(options, program) {
     const { driver } = await getDriver();
     const functions = await driver.list();
@@ -1205,16 +1507,48 @@ async function handleDestroy(name, options, program) {
     }
     const webapp = requireWebappManifestValue(manifest, name);
     const deployment = webapp.deployment;
-    if (!deployment) {
+    const { appsDriver, endpoint, tenantId } = await getDriver();
+    // A2: `--mount-id` is the escape hatch for a lost/stale local state, so an
+    // explicit flag wins over app.json — but a disagreement is announced, never
+    // silent, because destroy is irreversible.
+    const flagMountId = options.mountId?.trim();
+    let targetMountId = flagMountId ?? deployment?.mountId;
+    let mountIdSource = flagMountId
+        ? "flag"
+        : "app.json";
+    if (flagMountId && deployment && flagMountId !== deployment.mountId) {
+        console.error(formatWarning(`--mount-id ${flagMountId} overrides the local deployment record (${deployment.mountId}); ` +
+            "the local record is left untouched."));
+    }
+    if (!targetMountId) {
+        // A4: last chance before declaring the mount unreachable.
+        const found = await lookupLocalMount(options.dir, name, {
+            endpoint,
+            tenantId,
+        });
+        if (found.ignored)
+            console.error(formatWarning(found.ignored));
+        if (found.entry) {
+            targetMountId = found.entry.mountId;
+            mountIdSource = "workspace-index";
+            console.error(formatWarning(`↻ Using mount ${targetMountId} recovered from ${found.path}; app.json has no deployment state.`));
+        }
+    }
+    if (!targetMountId) {
         throw new AppsApiError("APP_DEPLOYMENT_NOT_FOUND", `App '${name}' has no local deployment state; nothing to destroy`);
     }
-    const { appsDriver } = await getDriver();
+    // Only a local record matching the mount being destroyed may supply the orphan
+    // candidate slug and be cleared afterwards.
+    const localMatchesTarget = deployment != null && deployment.mountId === targetMountId;
+    const candidateFunctionSlug = localMatchesTarget
+        ? deployment?.candidateFunctionSlug
+        : undefined;
     // Phase 1: preview (no --confirm). Pull the live mount so the operator sees
     // exactly which functions + mount record will be reclaimed.
     if (!options.confirm) {
         let mount = null;
         try {
-            mount = await appsDriver.get(deployment.mountId);
+            mount = await appsDriver.get(targetMountId);
         }
         catch {
             mount = null; // already gone server-side; preview is still informative
@@ -1224,16 +1558,18 @@ async function handleDestroy(name, options, program) {
             slugs.add(mount.activeFunctionSlug);
         if (mount?.previousFunctionSlug)
             slugs.add(mount.previousFunctionSlug);
-        if (deployment.candidateFunctionSlug)
-            slugs.add(deployment.candidateFunctionSlug);
+        if (candidateFunctionSlug)
+            slugs.add(candidateFunctionSlug);
         const purgeTables = options.purgeDb
             ? await deriveAppTables(join(options.dir, name))
             : [];
         const preview = {
             status: "dry-run",
             app: name,
-            mountId: deployment.mountId,
+            mountId: targetMountId,
+            mountIdSource,
             mountStatus: mount?.status ?? "NOT_FOUND",
+            mountGeneration: mount?.generation ?? null,
             functions: [...slugs],
             tablesUntouched: !options.purgeDb,
             ...(options.purgeDb ? { purgeDb: { tables: purgeTables } } : {}),
@@ -1245,9 +1581,9 @@ async function handleDestroy(name, options, program) {
             console.log(JSON.stringify(preview, null, 2));
             return;
         }
-        console.log(formatWarning(`Preview: destroy webapp '${name}' (mount ${deployment.mountId}). Re-run with --confirm.`));
+        console.log(formatWarning(`Preview: destroy webapp '${name}' (mount ${targetMountId} from ${mountIdSource}). Re-run with --confirm.`));
         console.log(`  Functions to delete: ${[...slugs].join(", ") || "(none)"}`);
-        console.log(`  Mount record:        ${deployment.mountId} (${preview.mountStatus})`);
+        console.log(`  Mount record:        ${targetMountId} (${preview.mountStatus}${mount?.generation != null ? `, generation ${mount.generation}` : ""})`);
         if (options.purgeDb) {
             console.log(formatWarning(`  --purge-db will DROP tables: ${purgeTables.join(", ") || "(none detected)"}`));
             console.log(formatWarning("  Their RLS rows are removed too (policies + the central rls_tables toggle). On instances predating the tenant RLS-table DELETE endpoint the toggle row is left — harmless, and re-created on the next db-init."));
@@ -1259,15 +1595,28 @@ async function handleDestroy(name, options, program) {
     }
     // Phase 2: destroy. Pass the local orphan candidate (if any) so an uploaded
     // but never-published function is reclaimed too.
-    const result = await appsDriver.destroy(deployment.mountId, {
-        ...(deployment.candidateFunctionSlug
-            ? { candidateFunctionSlug: deployment.candidateFunctionSlug }
-            : {}),
+    //
+    // A2: echo the live mount identity (status/generation) next to the result —
+    // `--mount-id` bypasses every local safeguard, so the operator must be able to
+    // see exactly which mount was reclaimed.
+    let snapshot = null;
+    try {
+        snapshot = await appsDriver.get(targetMountId);
+    }
+    catch {
+        snapshot = null; // already gone server-side; destroy is idempotent
+    }
+    const result = await appsDriver.destroy(targetMountId, {
+        ...(candidateFunctionSlug ? { candidateFunctionSlug } : {}),
     });
-    // D5: clear ONLY the local deployment state; keep the source tree so the app
-    // can be re-deployed later.
-    delete webapp.deployment;
-    await writeManifest(options.dir, name, webapp);
+    // D5: clear ONLY the local deployment state (and only when it points at the
+    // mount that was actually destroyed); keep the source tree so the app can be
+    // re-deployed later.
+    if (localMatchesTarget) {
+        delete webapp.deployment;
+        await writeManifest(options.dir, name, webapp);
+    }
+    warnIfFailed(await forgetLocalMount(options.dir, name, targetMountId));
     // Optional DB purge (Q4): drop the app's own tables + RLS rows via the
     // mode-appropriate channel. Runs AFTER the mount/functions are reclaimed.
     const purge = options.purgeDb
@@ -1279,6 +1628,9 @@ async function handleDestroy(name, options, program) {
             status: "destroyed",
             app: name,
             mountId: result.mountId,
+            mountIdSource,
+            mountStatusBeforeDestroy: snapshot?.status ?? "NOT_FOUND",
+            mountGenerationBeforeDestroy: snapshot?.generation ?? null,
             alreadyGone: result.alreadyGone ?? false,
             deletedFunctions: result.deletedFunctions,
             tablesUntouched: !purge,
@@ -1289,6 +1641,7 @@ async function handleDestroy(name, options, program) {
         return;
     }
     console.log(formatSuccess(`Destroyed webapp '${name}' (mount ${result.mountId}${result.alreadyGone ? ", already gone" : ""}).`));
+    console.log(`  Mount destroyed:     ${targetMountId} (from ${mountIdSource}; was ${snapshot?.status ?? "NOT_FOUND"}${snapshot?.generation != null ? `, generation ${snapshot.generation}` : ""})`);
     for (const f of result.deletedFunctions) {
         if (f.deleted)
             console.log(`  Deleted function: ${f.slug}`);
@@ -1383,6 +1736,31 @@ function parsePositiveInteger(value, optionName) {
     }
     return parsed;
 }
+/**
+ * Precheck `capabilities.privateShare` before touching the share API (缺陷6 §7).
+ *
+ * On an instance with sharing disabled every `/share/v1/*` call answers a bare
+ * `404 Secure MPA sharing is disabled`, which reads like a bad slug or a CLI bug
+ * rather than an instance setting. Say so locally, and say that nothing was sent.
+ *
+ * A failing capabilities read must NOT block: the instance stays authoritative,
+ * so an unreachable capability endpoint degrades to "let the share call speak".
+ */
+async function assertPrivateShareEnabled(appsDriver, action) {
+    let capabilities;
+    try {
+        capabilities = await appsDriver.capabilities();
+    }
+    catch {
+        return;
+    }
+    if (capabilities?.privateShare === false) {
+        throw new Error(`This instance has secure MPA sharing disabled (capabilities.privateShare=false), ` +
+            `so \`pxbaas app share ${action}\` cannot work here. Enable private sharing on the ` +
+            `platform side and re-run — no share API request was sent. ` +
+            `Check the current setting with \`pxbaas app capabilities --json\`.`);
+    }
+}
 async function handleShareCreate(slug, options, program) {
     validateSlug(slug);
     if (options.expiresAt) {
@@ -1398,7 +1776,8 @@ async function handleShareCreate(slug, options, program) {
     const expiresInSeconds = options.expiresAt
         ? undefined
         : parsePositiveInteger(options.expiresIn, "--expires-in");
-    const { shareDriver, endpoint } = await getDriver();
+    const { shareDriver, appsDriver, endpoint } = await getDriver();
+    await assertPrivateShareEnabled(appsDriver, "create");
     const link = await shareDriver.create(slug, {
         expiresAt: options.expiresAt,
         expiresInSeconds,
@@ -1450,7 +1829,11 @@ async function handleShareRevoke(slug, shareId, options, program) {
             console.log(formatWarning(`Preview: revoke share '${shareId}' for '${slug}'. Re-run with --confirm.`));
         return;
     }
-    const { shareDriver } = await getDriver();
+    // The branch without --confirm stays a purely local preview (no profile, no
+    // network); the capability precheck belongs to the branch that really calls the
+    // share API.
+    const { shareDriver, appsDriver } = await getDriver();
+    await assertPrivateShareEnabled(appsDriver, "revoke");
     const share = await shareDriver.revoke(slug, shareId, options.tenantId);
     if (isJson(options, program)) {
         console.log(JSON.stringify({ status: "revoked", slug, share }, null, 2));
@@ -1460,7 +1843,8 @@ async function handleShareRevoke(slug, shareId, options, program) {
 }
 async function handleShareVerify(slug, shareId, options, program) {
     validateSlug(slug);
-    const { shareDriver } = await getDriver();
+    const { shareDriver, appsDriver } = await getDriver();
+    await assertPrivateShareEnabled(appsDriver, "verify");
     const share = await shareDriver.get(slug, shareId, options.tenantId);
     const output = {
         status: share.status === "ACTIVE" ? "active" : "inactive",