@polardbx/pxbaas 0.1.0-beta.1 → 0.1.0-beta.10

package/dist/commands/app/index.js

@@ -7,9 +7,11 @@ 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 { applySqlStatements, getSingleTenantMetaDriver, } from "../../db/apply-schema.js";
+import { applySchema, getSchemaSink, } from "../../db/apply-schema.js";
+import { parseRlsJson, extractCreateTableNames } from "../../db/sql-file.js";
 const SLUG_RE = /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/;
 /**
  * `pxbaas app` — scaffold, deploy, publish, verify, and share legacy Edge Function
@@ -54,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 {
@@ -110,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 {
@@ -119,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)")
@@ -146,6 +165,23 @@ export function registerAppCommands(program) {
             fail(e, options.json);
         }
     });
+    appCmd
+        .command("destroy <name>")
+        .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")
+        .action(async (name, options) => {
+        try {
+            await handleDestroy(name, options, program);
+        }
+        catch (e) {
+            fail(e, isJson(options, program));
+        }
+    });
     appCmd
         .command("templates")
         .description("List available webapp templates")
@@ -156,8 +192,7 @@ export function registerAppCommands(program) {
             if (isJson(options, program))
                 console.log(JSON.stringify({ templates }, null, 2));
             else
-                for (const t of templates)
-                    console.log(`${t.id}\t${t.description}`);
+                printGroupedTemplates(templates);
         }
         catch (e) {
             fail(e, options.json);
@@ -165,9 +200,9 @@ export function registerAppCommands(program) {
     });
     appCmd
         .command("db-init <name>")
-        .description("Apply the app's db/schema.sql to the single-tenant database (tables + RLS + seed). Shows the plan and requires authorization.")
+        .description("Apply the app's db/schema.sql (+ optional db/rls.json) to the active database (tables + RLS + seed) — single-tenant, or your tenant db in multi-tenant. Shows the plan and requires authorization.")
         .option("--dir <directory>", "Parent directory for the app", "./apps")
-        .option("--schema <schema>", "Target schema for the __SCHEMA__ placeholder", "public")
+        .option("--schema <schema>", "Target schema for the __SCHEMA__ placeholder (single-tenant only)", "public")
         .option("--dry-run", "Show the statements without executing them")
         .option("--yes", "Authorize non-interactively (skip the confirm prompt)")
         .option("--json", "Output in JSON format")
@@ -184,6 +219,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";
@@ -191,8 +257,66 @@ 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})`;
+}
+/** Compact capability tag so templates can be picked by metadata, not by id. */
+function templateMetaTag(t) {
+    const m = t.meta;
+    if (!m)
+        return "";
+    const parts = [m.render, m.frontend, m.backend];
+    if (m.session !== "none")
+        parts.push(`session=${m.session}`);
+    if (m.hasDb)
+        parts.push("db");
+    if (m.coldStart !== "light")
+        parts.push(`cold=${m.coldStart}`);
+    return `[${parts.join(" ")}]`;
+}
+/** Group templates by delivery mode and purpose; ids stay unchanged. */
+function printGroupedTemplates(templates) {
+    const groups = [
+        {
+            title: "Legacy Edge Function demos (single worker at /functions/v1/<slug>):",
+            match: (t) => t.meta?.delivery === "legacy",
+        },
+        {
+            title: "Webapp starters and validation (schemaVersion 2 at /apps/<mount>):",
+            match: (t) => t.meta?.delivery === "webapp" &&
+                (t.meta.purpose === "starter" || t.meta.purpose === "validation"),
+        },
+        {
+            title: "Webapp reference apps (session contract and/or db/schema.sql):",
+            match: (t) => t.meta?.delivery === "webapp" && t.meta.purpose === "reference",
+        },
+        {
+            title: "Webapp showcases:",
+            match: (t) => t.meta?.delivery === "webapp" && t.meta.purpose === "showcase",
+        },
+    ];
+    for (const g of groups) {
+        const rows = templates.filter(g.match);
+        if (rows.length === 0)
+            continue;
+        console.log(g.title);
+        for (const t of rows)
+            console.log(`  ${t.id.padEnd(16)} ${templateMetaTag(t).padEnd(48)} ${t.description}`);
+        console.log();
+    }
+    for (const t of templates.filter((x) => !groups.some((g) => g.match(x))))
+        console.log(`  ${t.id}\t${t.description}`);
+}
 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.`);
@@ -266,10 +390,105 @@ async function getDriver() {
     };
 }
 /**
- * `pxbaas app db-init <name>` — apply the app's bundled db/schema.sql to the
- * single-tenant database so a freshly published app has its tables + RLS + seed.
+ * 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 +
+ * RLS + seed. Mode-aware: single-tenant runs through /pg/query (global admin);
+ * multi-tenant runs through /api/tenant-ddl with the per-tenant service_role key
+ * (DDL on the tenant's own db, RLS via the structured central-registry endpoints).
  * Delegates to the shared apply engine (show plan -> authorize -> run -> stop on
- * first error, no rollback). Multi-tenant profiles are rejected there.
+ * first error, no rollback).
  */
 async function handleDbInit(name, options, program) {
     const appDir = join(options.dir, name);
@@ -280,14 +499,25 @@ async function handleDbInit(name, options, program) {
     }
     const raw = await readFile(schemaFile, "utf8");
     const json = isJson(options, program);
-    // Single-tenant only; getSingleTenantMetaDriver rejects multi-tenant profiles.
-    const { driver } = await getSingleTenantMetaDriver("service_role");
-    const result = await applySqlStatements(raw, schemaFile, {
+    // Preferred declarative RLS source (db/rls.json); absent -> the engine falls
+    // back to parsing RLS INSERTs embedded in schema.sql (multi-tenant) or runs
+    // them verbatim (single-tenant).
+    const rlsFile = join(appDir, "db", "rls.json");
+    let rls = null;
+    if (existsSync(rlsFile)) {
+        rls = parseRlsJson(await readFile(rlsFile, "utf8"));
+    }
+    // Mode-aware sink: single-tenant /pg/query, or multi-tenant /api/tenant-ddl.
+    const sink = await getSchemaSink("service_role");
+    const result = await applySchema({
+        rawSql: raw,
+        source: schemaFile,
+        rls,
         schema: options.schema,
         dryRun: Boolean(options.dryRun),
         assumeYes: Boolean(options.yes),
         json,
-    }, (sql) => driver.query(sql, true));
+    }, sink);
     if (json) {
         console.log(JSON.stringify({ app: name, ...result }, null, 2));
     }
@@ -349,10 +579,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;
@@ -378,6 +608,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"
@@ -419,21 +650,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: [] }
@@ -447,9 +680,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",
@@ -551,15 +783,16 @@ 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);
-    const defaultFrontendDir = manifest.template === "vanilla-static"
-        ? join(appDir, "frontend")
-        : join(appDir, frontend.root);
+    // `frontend.root` is both the local artifact directory and the uploaded key
+    // prefix (the platform resolves a public path as join(root, asset)), so every
+    // template must ship its uploadable files under that same directory.
+    const defaultFrontendDir = join(appDir, frontend.root);
     const frontendDir = options.frontend ?? defaultFrontendDir;
-    const frontendRaw = await collectStagingFiles(frontendDir);
+    const frontendRaw = await collectStagingFiles(frontendDir, undefined, "Pass --frontend <prebuilt-dir>, or point app.json frontend.root at the directory that holds your build output.");
     const frontendFiles = frontendRaw.map((file) => `${frontend.root}/${file.relativePath}`.replace(/\/+/g, "/"));
     const frontendUpload = frontendRaw
         .filter((file) => !file.relativePath.endsWith("/"))
@@ -649,29 +882,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}`;
@@ -688,6 +983,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,
@@ -697,7 +996,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)
@@ -730,9 +1036,9 @@ function assertWebappCapabilities(capabilities, backend) {
         throw new AppsApiError("APP_CAPABILITY_UNSUPPORTED", "This instance does not enable App session injection (capabilities.sessionMode != proxy-injected-header). Use backend.session=\"browser-side\" or \"none\".");
     }
 }
-async function collectStagingFiles(root, current = root) {
+async function collectStagingFiles(root, current = root, hint) {
     if (!existsSync(root))
-        throw new AppsApiError("APP_ARTIFACT_INVALID", `Artifact directory not found: ${root}`);
+        throw new AppsApiError("APP_ARTIFACT_INVALID", `Artifact directory not found: ${root}. ${hint ?? "Create it (build the frontend) before deploying."}`);
     const files = [];
     for (const entry of await readdir(current, { withFileTypes: true })) {
         const full = join(current, entry.name);
@@ -741,7 +1047,7 @@ async function collectStagingFiles(root, current = root) {
             if (entry.name === "node_modules")
                 files.push({ path: full, relativePath: `${relativePath}/` });
             else if (entry.name !== ".git")
-                files.push(...(await collectStagingFiles(root, full)));
+                files.push(...(await collectStagingFiles(root, full, hint)));
         }
         else if (entry.isFile()) {
             files.push({ path: full, relativePath });
@@ -1037,13 +1343,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);
@@ -1061,6 +1372,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();
@@ -1079,6 +1459,13 @@ async function handleList(options, program) {
 async function handleRemove(name, options, program) {
     const json = isJson(options, program);
     const manifest = await readManifest(options.dir, name);
+    // D6: `app remove` deletes ONE legacy Edge Function by slug. A webapp owns
+    // auto-generated `app_<id>_r_` candidates plus a mount record; the old path
+    // took slug=name, missed the real candidate, and left the mount behind. Route
+    // webapps to `app destroy` instead of silently doing the wrong thing.
+    if (manifest.mode === "webapp") {
+        throw new AppsApiError("APP_MANIFEST_INVALID", `'${name}' is a schemaVersion 2 webapp. Use \`pxbaas app destroy ${name} --confirm\` to delete its edge functions and mount record (app remove only handles legacy spa/api/mpa functions).`);
+    }
     const slug = options.slug ?? manifest.slug ?? name;
     if (!options.confirm) {
         const preview = {
@@ -1100,6 +1487,228 @@ async function handleRemove(name, options, program) {
     else
         console.log(formatSuccess(`Removed function '${slug}'.`));
 }
+/**
+ * `pxbaas app destroy <name>` — permanently tear down a schemaVersion 2 webapp:
+ * delete its edge-func candidates and its mount-id record. Two-phase: without
+ * --confirm it only previews what will be reclaimed. Idempotent server-side.
+ *
+ * DB business tables are kept by default (scope decision 2026-10-16). With
+ * `--purge-db` the app's own tables + RLS registry rows are also removed via the
+ * helpers below (mode-aware: single-tenant /pg/query, multi-tenant /api/tenant-ddl).
+ */
+/**
+ * Derive the DB tables an app owns, from its bundled db/schema.sql (CREATE TABLE
+ * names) and db/rls.json (declared tables/policies). Used by `destroy --purge-db`.
+ */
+async function deriveAppTables(appDir) {
+    const set = new Set();
+    const schemaFile = join(appDir, "db", "schema.sql");
+    if (existsSync(schemaFile)) {
+        for (const t of extractCreateTableNames(await readFile(schemaFile, "utf8"))) {
+            set.add(t);
+        }
+    }
+    const rlsFile = join(appDir, "db", "rls.json");
+    if (existsSync(rlsFile)) {
+        const rls = parseRlsJson(await readFile(rlsFile, "utf8"));
+        for (const t of rls.tables)
+            set.add(t.table_name);
+        for (const p of rls.policies)
+            set.add(p.table_name);
+    }
+    return [...set];
+}
+/**
+ * Drop the app's tables + remove its RLS registry rows via the mode-appropriate
+ * channel. RLS is purged before the DROP so policy cleanup still resolves.
+ */
+async function purgeAppDatabase(appDir, schema) {
+    const tables = await deriveAppTables(appDir);
+    const sink = await getSchemaSink("service_role");
+    const ctx = { schema };
+    const dropped = [];
+    const errors = [];
+    let policiesDeleted = 0;
+    let toggleRowsRemoved = true;
+    for (const t of tables) {
+        try {
+            const r = await sink.purgeRlsForTable(t, ctx);
+            policiesDeleted += r.policiesDeleted;
+            if (!r.toggleRemoved)
+                toggleRowsRemoved = false;
+            await sink.dropTable(t, ctx);
+            dropped.push(t);
+        }
+        catch (e) {
+            errors.push(`${t}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    return { tables, dropped, policiesDeleted, toggleRowsRemoved, errors };
+}
+async function handleDestroy(name, options, program) {
+    const json = isJson(options, program);
+    const manifest = await readManifest(options.dir, name);
+    // D6: destroy is webapp-only; legacy spa/api/mpa keep using `app remove`.
+    if (manifest.mode !== "webapp") {
+        throw new AppsApiError("APP_MANIFEST_INVALID", `App '${name}' is not a schemaVersion 2 webapp. Use \`pxbaas app remove ${name} --confirm\` to delete a legacy Edge Function.`);
+    }
+    const webapp = requireWebappManifestValue(manifest, name);
+    const deployment = webapp.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`);
+    }
+    // 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(targetMountId);
+        }
+        catch {
+            mount = null; // already gone server-side; preview is still informative
+        }
+        const slugs = new Set();
+        if (mount?.activeFunctionSlug)
+            slugs.add(mount.activeFunctionSlug);
+        if (mount?.previousFunctionSlug)
+            slugs.add(mount.previousFunctionSlug);
+        if (candidateFunctionSlug)
+            slugs.add(candidateFunctionSlug);
+        const purgeTables = options.purgeDb
+            ? await deriveAppTables(join(options.dir, name))
+            : [];
+        const preview = {
+            status: "dry-run",
+            app: name,
+            mountId: targetMountId,
+            mountIdSource,
+            mountStatus: mount?.status ?? "NOT_FOUND",
+            mountGeneration: mount?.generation ?? null,
+            functions: [...slugs],
+            tablesUntouched: !options.purgeDb,
+            ...(options.purgeDb ? { purgeDb: { tables: purgeTables } } : {}),
+            note: options.purgeDb
+                ? "pass --confirm to destroy: deletes the edge functions + mount record (irreversible) AND drops the listed DB tables + their RLS rows."
+                : "pass --confirm to destroy: deletes the edge functions + mount record (irreversible). DB business tables are NOT dropped.",
+        };
+        if (json) {
+            console.log(JSON.stringify(preview, null, 2));
+            return;
+        }
+        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:        ${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."));
+        }
+        else {
+            console.log(formatWarning("  DB business tables are NOT dropped; clean them up yourself if needed."));
+        }
+        return;
+    }
+    // Phase 2: destroy. Pass the local orphan candidate (if any) so an uploaded
+    // but never-published function is reclaimed too.
+    //
+    // 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 (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
+        ? await purgeAppDatabase(join(options.dir, name), options.schema ?? "public")
+        : null;
+    const failed = result.deletedFunctions.filter((f) => !f.deleted);
+    if (json) {
+        console.log(JSON.stringify({
+            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,
+            ...(purge ? { purgeDb: purge } : {}),
+        }, null, 2));
+        if (failed.length > 0 || (purge && purge.errors.length > 0))
+            process.exit(1);
+        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}`);
+        else
+            console.error(formatError(`  Failed to delete function: ${f.slug} — ${f.error}`));
+    }
+    if (purge) {
+        console.log(formatSuccess(`  Purged DB: dropped ${purge.dropped.length}/${purge.tables.length} table(s), removed ${purge.policiesDeleted} RLS policy/policies.`));
+        if (!purge.toggleRowsRemoved) {
+            console.log(formatWarning("  Some central rls_tables toggle rows remain (this instance predates the tenant RLS-table DELETE endpoint); harmless and re-created on the next db-init."));
+        }
+        for (const e of purge.errors)
+            console.error(formatError(`  Purge failed for ${e}`));
+    }
+    else {
+        console.log(formatWarning("  DB business tables were NOT dropped; clean them up yourself if needed."));
+    }
+    if (failed.length > 0 || (purge && purge.errors.length > 0))
+        process.exit(1);
+}
 function registerShareCommands(appCmd, program) {
     const shareCmd = appCmd
         .command("share")
@@ -1174,6 +1783,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) {
@@ -1189,7 +1823,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,
@@ -1241,7 +1876,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));
@@ -1251,7 +1890,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",