@polardbx/pxbaas 0.0.0-stage → 0.1.0-beta.10

package/dist/commands/app/index.js

@@ -0,0 +1,1907 @@
+import axios from "axios";
+import { readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { AppsApiError, AppsDriver, FunctionsDriver, ShareLinksDriver, } from "@polardbx/pxbaas-client";
+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 { 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";
+const SLUG_RE = /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/;
+/**
+ * `pxbaas app` — scaffold, deploy, publish, verify, and share legacy Edge Function
+ * demos or schemaVersion 2 Webapps. Webapp deploys add capability gating, artifact
+ * linting, immutable candidates, and generation-CAS lifecycle operations.
+ */
+export function registerAppCommands(program) {
+    const appCmd = program
+        .command("app")
+        .description("Scaffold, deploy, publish, and manage BaaS apps");
+    // Build the --template help from the bundled manifest so it never drifts from
+    // the real template set (D6). Falls back to a hint when assets are unavailable.
+    const templateIds = listTemplateIdsSync();
+    const templateHelp = templateIds.length
+        ? `Template id (${templateIds.join("|")})`
+        : "Template id (run `pxbaas app templates` for the full list)";
+    appCmd
+        .command("new <name>")
+        .description("Scaffold a legacy Edge Function app or schemaVersion 2 Webapp")
+        .option("--template <id>", templateHelp, "spa")
+        .option("--dir <directory>", "Parent directory for the app", "./apps")
+        .option("--slug <slug>", "Function slug / URL path segment (default: <name>)")
+        .option("--force", "Overwrite an existing scaffold")
+        .option("--json", "Output in JSON format")
+        .action(async (name, options) => {
+        try {
+            await handleNew(name, options, program);
+        }
+        catch (e) {
+            fail(e, options.json);
+        }
+    });
+    appCmd
+        .command("deploy <name>")
+        .description("Deploy a legacy app or upload and publish a schemaVersion 2 Webapp")
+        .option("--dir <directory>", "Parent directory for the app", "./apps")
+        .option("--slug <slug>", "Override function slug")
+        .option("--entrypoint <path>", "Override entrypoint file")
+        .option("--frontend <directory>", "Prebuilt frontend artifact directory for mode=webapp")
+        .option("--backend <directory>", "Backend source directory for mode=webapp")
+        .option("--backend-framework <framework>", "Backend framework (deno|hono)")
+        .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 {
+            await handleDeploy(name, options, program);
+        }
+        catch (e) {
+            fail(e, options.json);
+        }
+    });
+    appCmd
+        .command("capabilities")
+        .description("Show App delivery capabilities reported by the active instance")
+        .option("--json", "Output in JSON format")
+        .action(async (options) => {
+        try {
+            await handleCapabilities(options, program);
+        }
+        catch (e) {
+            fail(e, isJson(options, program));
+        }
+    });
+    for (const action of ["publish", "rollback", "unpublish"]) {
+        appCmd
+            .command(`${action} <name>`)
+            .description(`${action[0].toUpperCase()}${action.slice(1)} a mode=webapp App mount`)
+            .option("--dir <directory>", "Parent directory for the app", "./apps")
+            .option("--json", "Output in JSON format")
+            .action(async (name, options) => {
+            try {
+                await handleLifecycle(action, name, options, program);
+            }
+            catch (e) {
+                fail(e, isJson(options, program));
+            }
+        });
+    }
+    appCmd
+        .command("verify <name>")
+        .description("Verify the deployed webapp (cold-start retry + content-type + API ping)")
+        .option("--dir <directory>", "Parent directory for the app", "./apps")
+        .option("--slug <slug>", "Override function slug")
+        .option("--timeout <seconds>", "Max seconds to wait through cold start", "60")
+        .option("--json", "Output in JSON format")
+        .action(async (name, options) => {
+        try {
+            await handleVerify(name, options, program);
+        }
+        catch (e) {
+            fail(e, options.json);
+        }
+    });
+    appCmd
+        .command("url <name>")
+        .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 {
+            await handleUrl(name, options, program);
+        }
+        catch (e) {
+            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)")
+        .option("--json", "Output in JSON format")
+        .action(async (options) => {
+        try {
+            await handleList(options, program);
+        }
+        catch (e) {
+            fail(e, options.json);
+        }
+    });
+    appCmd
+        .command("remove <name>")
+        .description("Remove a deployed webapp function (destructive; needs --confirm)")
+        .option("--dir <directory>", "Parent directory for the app", "./apps")
+        .option("--slug <slug>", "Override function slug")
+        .option("--confirm", "Actually delete (required)")
+        .option("--json", "Output in JSON format")
+        .action(async (name, options) => {
+        try {
+            await handleRemove(name, options, program);
+        }
+        catch (e) {
+            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")
+        .option("--json", "Output in JSON format")
+        .action(async (options) => {
+        try {
+            const templates = await listTemplates();
+            if (isJson(options, program))
+                console.log(JSON.stringify({ templates }, null, 2));
+            else
+                printGroupedTemplates(templates);
+        }
+        catch (e) {
+            fail(e, options.json);
+        }
+    });
+    appCmd
+        .command("db-init <name>")
+        .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 (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")
+        .action(async (name, options) => {
+        try {
+            await handleDbInit(name, options, program);
+        }
+        catch (e) {
+            fail(e, isJson(options, program));
+        }
+    });
+    registerShareCommands(appCmd, 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";
+    if (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.`);
+    }
+}
+async function readManifest(dir, name) {
+    const p = join(dir, name, "app.json");
+    if (!existsSync(p))
+        return {};
+    try {
+        return JSON.parse(await readFile(p, "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+async function collectFiles(appDir, baseDir = appDir) {
+    const out = [];
+    const entries = await readdir(appDir, { withFileTypes: true });
+    for (const e of entries) {
+        // NOTE: app.json IS collected on purpose — it carries the deploy `mode`
+        // (spa|api|mpa) that the proxy static branch reads back from
+        // edge_function_files to decide whether to serve real static assets.
+        if (e.name.startsWith(".") || e.name === "node_modules")
+            continue;
+        const full = join(appDir, e.name);
+        if (e.isDirectory()) {
+            // Recurse so nested assets (assets/style.css, pages/about.html) keep their
+            // directory structure; relativePath is posix-normalized for the multipart filename.
+            out.push(...(await collectFiles(full, baseDir)));
+        }
+        else if (e.isFile()) {
+            out.push({
+                path: full,
+                relativePath: relative(baseDir, full).split("\\").join("/"),
+            });
+        }
+    }
+    return out;
+}
+async function getDriver() {
+    const profileManager = new ProfileManager();
+    const currentProfile = await profileManager.getCurrentProfile();
+    if (!currentProfile) {
+        throw new Error("No active profile. Run `pxbaas provision` (free Zero instance) or `pxbaas login` first.");
+    }
+    const credentials = await new CredentialStore().getCredentials(currentProfile.name);
+    if (!credentials) {
+        throw new Error(`No credentials for profile '${currentProfile.name}'. Run \`pxbaas provision\` or \`pxbaas login\`.`);
+    }
+    const driver = new FunctionsDriver({
+        endpoint: currentProfile.endpoint,
+        serviceRoleKey: credentials.serviceRoleKey,
+        tenantId: currentProfile.tenantId,
+    });
+    const shareDriver = new ShareLinksDriver({
+        endpoint: currentProfile.endpoint,
+        serviceRoleKey: credentials.serviceRoleKey,
+    });
+    const appsDriver = new AppsDriver({
+        endpoint: currentProfile.endpoint,
+        serviceRoleKey: credentials.serviceRoleKey,
+    });
+    return {
+        driver,
+        shareDriver,
+        appsDriver,
+        endpoint: currentProfile.endpoint,
+        tenantId: currentProfile.tenantId,
+        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 +
+ * 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).
+ */
+async function handleDbInit(name, options, program) {
+    const appDir = join(options.dir, name);
+    const schemaFile = join(appDir, "db", "schema.sql");
+    if (!existsSync(schemaFile)) {
+        throw new AppsApiError("APP_DB_SCHEMA_NOT_FOUND", `No db/schema.sql found for app '${name}' at ${schemaFile}. ` +
+            "This app may not need a database, or --dir is wrong.");
+    }
+    const raw = await readFile(schemaFile, "utf8");
+    const json = isJson(options, program);
+    // 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,
+    }, sink);
+    if (json) {
+        console.log(JSON.stringify({ app: name, ...result }, null, 2));
+    }
+    if (result.failed > 0)
+        process.exit(1);
+}
+function shareUrl(endpoint, slug) {
+    return `${endpoint.replace(/\/$/, "")}/functions/v1/${slug}`;
+}
+async function handleNew(name, options, program) {
+    const slug = options.slug ?? name;
+    validateSlug(slug);
+    const result = await scaffoldApp({
+        name,
+        slug,
+        template: options.template,
+        dir: options.dir,
+        force: options.force,
+    });
+    if (isJson(options, program)) {
+        console.log(JSON.stringify({
+            status: "scaffolded",
+            app: name,
+            slug,
+            appDir: result.appDir,
+            files: result.files,
+            template: options.template,
+            spec: "pxbaas-app-spec",
+            nextSteps: result.nextSteps,
+            note: "Follow the pxbaas-app-spec skill; `pxbaas app deploy` lints the code against it automatically.",
+        }, null, 2));
+        return;
+    }
+    console.log(formatSuccess(`Scaffolded webapp '${name}' (template: ${options.template}) at ${result.appDir}`));
+    console.log(`  Files: ${result.files.join(", ")}`);
+    console.log(`  Spec:  follow the 'pxbaas-app-spec' skill — \`pxbaas app deploy\` lints against it automatically.`);
+    console.log(`  Next:  edit ${join(result.appDir, result.manifest.entrypoint)}, then \`pxbaas app deploy ${name}\`.`);
+    for (const step of result.nextSteps) {
+        console.log(`  TODO:  ${step}`);
+    }
+}
+async function handleCapabilities(options, program) {
+    const { appsDriver } = await getDriver();
+    const capabilities = await appsDriver.capabilities();
+    const exposure = appExposure(capabilities);
+    const output = { status: "ok", exposure, capabilities };
+    if (isJson(options, program)) {
+        console.log(JSON.stringify(output, null, 2));
+        return;
+    }
+    console.log(`App delivery: ${capabilities.schemaVersions.includes(2) ? "available" : "unavailable"}`);
+    console.log(`  Exposure: ${exposure}`);
+    console.log(`  Endpoint: ${capabilities.appEndpoint ?? "-"}`);
+    console.log(`  Static: ${capabilities.publicStatic ? "enabled" : "disabled"}`);
+    console.log(`  Deno: ${capabilities.nativeDeno ? "enabled" : "disabled"}`);
+    console.log(`  Hono: ${capabilities.honoVersion ?? "disabled"}`);
+    console.log(`  SSR libs: ${(capabilities.ssrLibs ?? []).join(", ") || "none"}`);
+    console.log(`  Session: ${capabilities.sessionMode && capabilities.sessionMode !== "none" ? capabilities.sessionMode : "disabled"}`);
+}
+async function handleLifecycle(action, name, options, program) {
+    const manifest = await requireWebappManifest(options.dir, name);
+    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 capabilities = await appsDriver.capabilities();
+    assertWebappCapabilities(capabilities, manifest.backend ?? null);
+    let mount;
+    if (action === "publish") {
+        if (!deployment.candidateFunctionSlug) {
+            throw new AppsApiError("APP_CANDIDATE_NOT_FOUND", `App '${name}' has no candidate to publish`);
+        }
+        mount = await appsDriver.publish(deployment.mountId, {
+            candidateFunctionSlug: deployment.candidateFunctionSlug,
+            expectedGeneration: deployment.generation,
+        });
+    }
+    else {
+        mount = await appsDriver[action](deployment.mountId, {
+            expectedGeneration: deployment.generation,
+        });
+    }
+    manifest.deployment = {
+        mountId: mount.mountId,
+        generation: mount.generation,
+        ...(action === "publish"
+            ? {}
+            : { 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"
+            ? "rolled-back"
+            : "unpublished", name, mount, capabilities, options, program);
+}
+async function handleDeploy(name, options, program) {
+    const json = isJson(options, program);
+    const manifest = await readManifest(options.dir, name);
+    if (manifest.mode === "webapp") {
+        await handleWebappDeploy(name, manifest, options, program);
+        return;
+    }
+    const slug = options.slug ?? manifest.slug ?? name;
+    validateSlug(slug);
+    const entrypoint = options.entrypoint ?? manifest.entrypoint ?? "index.ts";
+    const verifyJwt = options.verifyJwt ?? manifest.verifyJwt ?? false;
+    const appDir = join(options.dir, name);
+    const entryPath = join(appDir, entrypoint);
+    const entrypointExists = existsSync(entryPath);
+    const source = entrypointExists ? await readFile(entryPath, "utf8") : "";
+    // Deploy mode (spa|api|mpa). The proxy enables the static-asset branch only
+    // for mpa; app.json is uploaded so the proxy can read this back.
+    const mode = manifest.mode ?? manifest.template ?? "spa";
+    const files = await collectFiles(appDir);
+    const existingFiles = files.map((f) => f.relativePath);
+    // For mpa, the pages/assets are separate files — scan them too for root-absolute
+    // refs (the entrypoint alone no longer contains the markup).
+    const auxiliarySources = [];
+    if (mode === "mpa") {
+        for (const f of files) {
+            const rel = f.relativePath;
+            if (rel === entrypoint || rel === "app.json")
+                continue;
+            if (/\.(html?|css|js|mjs)$/i.test(rel))
+                auxiliarySources.push(await readFile(f.path, "utf8"));
+        }
+    }
+    const declaredFiles = mode === "mpa"
+        ? [...(manifest.pages ?? []), ...(manifest.assets ?? [])]
+        : [];
+    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: [] }
+        : {
+            skipped: false,
+            ...lintAppSource(source, {
+                verifyJwt,
+                mode,
+                declaredFiles,
+                existingFiles,
+                auxiliarySources,
+            }),
+        };
+    const allBlockers = [...pre.blockers, ...spec.blockers.map(formatFinding)];
+    const allWarnings = [...pre.warnings, ...spec.warnings.map(formatFinding)];
+    if (options.dryRun) {
+        const out = {
+            status: "dry-run",
+            app: name,
+            slug,
+            mode,
+            verifyJwt,
+            shareUrl: shareUrl(endpoint, slug),
+            preflight: pre,
+            specLint: spec,
+        };
+        if (json)
+            console.log(JSON.stringify(out, null, 2));
+        else {
+            console.log(formatWarning(`Dry run for '${name}' -> ${shareUrl(endpoint, slug)}`));
+            for (const b of allBlockers)
+                console.error(formatError(b));
+            for (const w of allWarnings)
+                console.log(formatWarning(w));
+            if (allBlockers.length === 0)
+                console.log("  pxbaas-app-spec review + preflight passed. Re-run without --dry-run to deploy.");
+        }
+        if (allBlockers.length > 0)
+            process.exit(1);
+        return;
+    }
+    if (allBlockers.length > 0) {
+        if (json) {
+            console.log(JSON.stringify({
+                status: "blocked",
+                app: name,
+                slug,
+                preflight: pre,
+                specLint: spec,
+            }, null, 2));
+        }
+        else {
+            console.error(formatError("pxbaas-app-spec compliance review failed — fix these before deploying:"));
+            for (const b of allBlockers)
+                console.error(formatError(b));
+        }
+        process.exit(1);
+    }
+    const info = await driver.deploy({
+        slug,
+        entrypointPath: entrypoint,
+        verifyJwt,
+        files,
+    });
+    const url = shareUrl(endpoint, slug);
+    // deploy is an upsert: version 1 means this call created the function; >1 means it updated an existing one.
+    const action = (info?.version ?? 1) === 1 ? "created" : "updated";
+    const out = {
+        status: "deployed",
+        action,
+        app: name,
+        slug,
+        mode,
+        verifyJwt,
+        shareUrl: url,
+        function: info,
+        preflight: pre,
+        specLint: spec,
+    };
+    if (json) {
+        console.log(JSON.stringify(out, null, 2));
+        return;
+    }
+    console.log(formatSuccess(`${action === "created" ? "Created" : "Updated"} webapp '${name}' (slug: ${slug}, mode: ${mode}, verify_jwt: ${verifyJwt}, version: ${info?.version ?? 1}) — passed pxbaas-app-spec review`));
+    for (const w of allWarnings)
+        console.log(formatWarning(w));
+    console.log(`  Share URL: ${url}`);
+    if (mode === "mpa") {
+        for (const p of manifest.pages ?? [])
+            console.log(`  Page:      ${url.replace(/\/$/, "")}/${p}`);
+    }
+    console.log(`  Verify:    pxbaas app verify ${name}`);
+}
+async function handleWebappDeploy(name, manifestInput, options, program) {
+    const manifest = requireWebappManifestValue(manifestInput, name);
+    const frontend = manifest.frontend;
+    if (!frontend)
+        throw new AppsApiError("APP_MANIFEST_INVALID", "mode=webapp requires a frontend contract");
+    const framework = parseBackendFramework(options.backendFramework ?? manifest.backend?.framework);
+    let backend = manifest.backend
+        ? { ...manifest.backend }
+        : null;
+    if ((options.backend || options.backendFramework) && !backend) {
+        backend = {
+            entrypoint: "backend/index.ts",
+            framework: framework ?? "deno",
+            pathMode: "strip-app-api-prefix",
+            verifyJwt: options.verifyJwt ?? false,
+            secrets: [],
+            egressPolicy: "deny",
+        };
+    }
+    else if (backend) {
+        backend.framework = framework ?? backend.framework;
+        backend.verifyJwt = options.verifyJwt ?? backend.verifyJwt;
+    }
+    const { driver, appsDriver, endpoint, tenantId } = await getDriver();
+    const capabilities = await appsDriver.capabilities();
+    assertWebappCapabilities(capabilities, backend);
+    const appDir = join(options.dir, name);
+    // `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, 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("/"))
+        .map((file) => ({
+        ...file,
+        relativePath: `${frontend.root}/${file.relativePath}`.replace(/\/+/g, "/"),
+    }));
+    const frontendSources = await readTextSources(frontendUpload);
+    const frontendProjectDir = join(appDir, "frontend");
+    const frontendProjectFiles = existsSync(join(frontendProjectDir, "src"))
+        ? await collectStagingFiles(join(frontendProjectDir, "src"))
+        : [];
+    const frontendProjectSources = (await readTextSources(frontendProjectFiles)).map((file) => file.source);
+    const viteConfigPath = join(frontendProjectDir, "vite.config.ts");
+    const frontendConfigSource = existsSync(viteConfigPath)
+        ? await readFile(viteConfigPath, "utf8")
+        : undefined;
+    let backendSource = "";
+    let backendUpload = [];
+    if (backend) {
+        const backendRoot = dirname(backend.entrypoint);
+        const backendDir = options.backend ?? join(appDir, backendRoot);
+        const backendRaw = await collectStagingFiles(backendDir);
+        backendUpload = backendRaw
+            .filter((file) => !file.relativePath.endsWith("/"))
+            .map((file) => ({
+            ...file,
+            relativePath: `${backendRoot}/${file.relativePath}`.replace(/\/+/g, "/"),
+        }));
+        const entryFile = backendUpload.find((file) => file.relativePath === backend.entrypoint);
+        if (!entryFile) {
+            throw new AppsApiError("APP_ARTIFACT_INVALID", `Backend entrypoint not found: ${backend.entrypoint}`);
+        }
+        backendSource = await readFile(entryFile.path, "utf8");
+        if (backend.framework === "hono") {
+            backendSource = backendSource.replaceAll(HONO_VERSION_PLACEHOLDER, capabilities.honoVersion);
+            entryFile.content = backendSource;
+        }
+    }
+    const artifactManifest = {
+        schemaVersion: 2,
+        mode: "webapp",
+        name,
+        frontend,
+        backend,
+        // Preserve the SSR publish-probe path in the uploaded candidate (R2-01);
+        // without it the platform loses the fallback=worker probe contract.
+        ...(manifest.ssrProbePath ? { ssrProbePath: manifest.ssrProbePath } : {}),
+    };
+    const appJson = JSON.stringify(artifactManifest, null, 2) + "\n";
+    const uploadFiles = [
+        ...frontendUpload,
+        ...backendUpload,
+        {
+            path: join(appDir, "app.json"),
+            relativePath: "app.json",
+            content: appJson,
+        },
+    ];
+    const spec = options.skipSpecCheck
+        ? {
+            skipped: true,
+            passed: true,
+            blockers: [],
+            warnings: [],
+        }
+        : {
+            skipped: false,
+            ...lintAppSource("", {
+                mode: "webapp",
+                verifyJwt: backend?.verifyJwt ?? false,
+                frontendFiles,
+                frontendSources,
+                frontendConfigSource,
+                frontendProjectSources,
+                requireHashRouter: manifest.template?.startsWith("react-") ?? false,
+                backendSource,
+                backendFramework: backend?.framework,
+                honoVersion: capabilities.honoVersion,
+                ssrLibs: capabilities.ssrLibs,
+                secrets: backend?.secrets,
+                egressPolicy: backend?.egressPolicy,
+                ssrFallback: manifest.frontend?.fallback === "worker",
+                ssrProbePath: manifest.ssrProbePath,
+                backendSession: backend?.session,
+                sessionMode: capabilities.sessionMode,
+                sessionHeaders: capabilities.sessionHeaders,
+            }),
+        };
+    // 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 {
+            // 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;
+    }
+    // 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}`;
+    await driver.deploy({
+        slug: candidateFunctionSlug,
+        entrypointPath: entrypoint,
+        verifyJwt: backend?.verifyJwt ?? false,
+        files: uploadFiles,
+    });
+    manifest.backend = backend;
+    manifest.deployment = {
+        mountId: mount.mountId,
+        candidateFunctionSlug,
+        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,
+    });
+    manifest.deployment = {
+        mountId: published.mountId,
+        generation: published.generation,
+    };
+    await writeManifest(options.dir, name, manifest);
+    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)
+        return undefined;
+    if (value !== "deno" && value !== "hono") {
+        throw new AppsApiError("APP_MANIFEST_INVALID", "--backend-framework must be deno or hono");
+    }
+    return value;
+}
+function assertWebappCapabilities(capabilities, backend) {
+    if (!capabilities.schemaVersions.includes(2) ||
+        !capabilities.appEndpoint ||
+        !capabilities.publicStatic) {
+        throw new AppsApiError("APP_CAPABILITY_UNSUPPORTED", "Webapp static delivery is not enabled on this instance");
+    }
+    if (backend && !capabilities.nativeDeno) {
+        throw new AppsApiError("APP_CAPABILITY_UNSUPPORTED", "Native Deno App backends are not enabled on this instance");
+    }
+    if (backend?.framework === "hono" &&
+        (!capabilities.honoVersion || capabilities.honoOfflineReady !== true)) {
+        throw new AppsApiError("APP_CAPABILITY_UNSUPPORTED", "Hono is not enabled with an offline-ready exact version on this instance");
+    }
+    if (backend &&
+        (backend.secrets.length > 0 || backend.egressPolicy !== "deny")) {
+        throw new AppsApiError("APP_CAPABILITY_UNSUPPORTED", "The first Webapp release requires no Secrets and egressPolicy=deny");
+    }
+    // 方案 C: session contract gate (mirrors Studio validateCandidate).
+    if (backend?.session === "proxy-injected" &&
+        capabilities.sessionMode !== "proxy-injected-header") {
+        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, hint) {
+    if (!existsSync(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);
+        const relativePath = relative(root, full).split("\\").join("/");
+        if (entry.isDirectory()) {
+            if (entry.name === "node_modules")
+                files.push({ path: full, relativePath: `${relativePath}/` });
+            else if (entry.name !== ".git")
+                files.push(...(await collectStagingFiles(root, full, hint)));
+        }
+        else if (entry.isFile()) {
+            files.push({ path: full, relativePath });
+        }
+    }
+    return files;
+}
+async function readTextSources(files) {
+    const textFiles = files.filter((file) => /\.(?:html?|css|js|mjs|cjs|jsx|ts|tsx|json|svg|txt)$/i.test(file.relativePath));
+    return Promise.all(textFiles.map(async (file) => ({
+        path: file.relativePath,
+        source: await readFile(file.path, "utf8"),
+    })));
+}
+async function assertArtifactLimits(files, capabilities) {
+    if (files.length > capabilities.limits.maxFiles) {
+        throw new AppsApiError("APP_LIMIT_EXCEEDED", `Artifact has ${files.length} files; maximum is ${capabilities.limits.maxFiles}`);
+    }
+    let total = 0;
+    for (const file of files) {
+        const bytes = file.content === undefined
+            ? (await stat(file.path)).size
+            : Buffer.byteLength(file.content);
+        if (bytes > capabilities.limits.maxFileBytes) {
+            throw new AppsApiError("APP_LIMIT_EXCEEDED", `${file.relativePath} exceeds ${capabilities.limits.maxFileBytes} bytes`);
+        }
+        total += bytes;
+    }
+    if (total > capabilities.limits.maxBundleBytes) {
+        throw new AppsApiError("APP_LIMIT_EXCEEDED", `Artifact is ${total} bytes; maximum is ${capabilities.limits.maxBundleBytes}`);
+    }
+}
+function createCandidateSlug(appId) {
+    const deployId = `${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+    return `app_${appId}_r_${deployId}`;
+}
+function appExposure(capabilities) {
+    return capabilities.originMode === "isolated" &&
+        capabilities.hostEnforced === true &&
+        capabilities.publicExposureAllowed === true
+        ? "Public"
+        : "Preview";
+}
+function emitWebappResult(status, name, mount, capabilities, options, program, extra = {}) {
+    const exposure = appExposure(capabilities);
+    const output = {
+        status,
+        app: name,
+        mount,
+        exposure,
+        ...(exposure === "Public"
+            ? { publicUrl: mount.url }
+            : { previewUrl: mount.url }),
+        ...extra,
+    };
+    if (isJson(options, program))
+        console.log(JSON.stringify(output, null, 2));
+    else {
+        console.log(formatSuccess(`${status} Webapp '${name}' (generation ${mount.generation}).`));
+        console.log(`  ${exposure} URL: ${mount.url}`);
+    }
+}
+async function requireWebappManifest(dir, name) {
+    return requireWebappManifestValue(await readManifest(dir, name), name);
+}
+function requireWebappManifestValue(value, name) {
+    if (value.mode !== "webapp" || value.schemaVersion !== 2 || !value.frontend) {
+        throw new AppsApiError("APP_MANIFEST_INVALID", `App '${name}' is not a schemaVersion 2 webapp`);
+    }
+    // R2-09: fully validate a declared backend contract instead of trusting the
+    // cast, so a backend missing framework/entrypoint cannot slip through and
+    // silently skip the backend lint.
+    const backend = value.backend;
+    if (backend !== undefined && backend !== null) {
+        const b = backend;
+        if (typeof b.entrypoint !== "string" ||
+            !b.entrypoint.startsWith("backend/") ||
+            (b.framework !== "deno" && b.framework !== "hono") ||
+            b.pathMode !== "strip-app-api-prefix" ||
+            typeof b.verifyJwt !== "boolean" ||
+            !Array.isArray(b.secrets) ||
+            b.egressPolicy !== "deny") {
+            throw new AppsApiError("APP_MANIFEST_INVALID", `App '${name}' has an invalid backend contract: requires entrypoint under backend/, framework deno|hono, pathMode strip-app-api-prefix, boolean verifyJwt, a secrets array, and egressPolicy "deny"`);
+        }
+    }
+    // R2-01 (defense in depth): fallback="worker" requires a valid ssrProbePath.
+    if (value.frontend.fallback === "worker" &&
+        (typeof value.ssrProbePath !== "string" ||
+            !value.ssrProbePath.startsWith("/"))) {
+        throw new AppsApiError("APP_MANIFEST_INVALID", `App '${name}' declares frontend.fallback="worker" but is missing a valid ssrProbePath`);
+    }
+    return value;
+}
+async function writeManifest(dir, name, manifest) {
+    await writeFile(join(dir, name, "app.json"), JSON.stringify(manifest, null, 2) + "\n", "utf8");
+}
+async function handleVerify(name, options, program) {
+    const json = isJson(options, program);
+    const manifest = await readManifest(options.dir, name);
+    if (manifest.mode === "webapp") {
+        await handleWebappVerify(name, requireWebappManifestValue(manifest, name), options, program);
+        return;
+    }
+    const slug = options.slug ?? manifest.slug ?? name;
+    const { endpoint, tenantId, anonKey } = await getDriver();
+    const url = shareUrl(endpoint, slug);
+    const timeoutSec = Number(options.timeout ?? "60");
+    const deadline = Date.now() + timeoutSec * 1000;
+    // Build auth headers for multi-tenant Kong gateway (key-auth is enforced
+    // even when verify_jwt=false on the function itself).
+    const verifyHeaders = {
+        apikey: anonKey,
+        Authorization: `Bearer ${anonKey}`,
+    };
+    if (tenantId) {
+        verifyHeaders["X-Tenant-Id"] = tenantId;
+    }
+    let httpStatus = 0;
+    let contentType = "";
+    let attempts = 0;
+    const startedAt = Date.now();
+    while (Date.now() < deadline) {
+        attempts++;
+        try {
+            const res = await axios.get(url, {
+                headers: verifyHeaders,
+                validateStatus: () => true,
+                timeout: 10000,
+            });
+            httpStatus = res.status;
+            contentType = String(res.headers["content-type"] ?? "");
+            if (httpStatus === 200)
+                break;
+        }
+        catch {
+            httpStatus = 0;
+        }
+        if (!json)
+            process.stderr.write(`  attempt#${attempts} HTTP ${httpStatus || "---"} (cold start?), retrying in 5s\n`);
+        await new Promise((r) => setTimeout(r, 5000));
+    }
+    const firstByteMs = Date.now() - startedAt;
+    const coldStart = attempts > 1;
+    // Ping the built-in API (spa uses ?action=time, api uses ?action=health).
+    const apiAction = manifest.template === "api" ? "health" : "time";
+    let apiStatus = 0;
+    try {
+        const r = await axios.get(`${url}?action=${apiAction}`, {
+            headers: verifyHeaders,
+            validateStatus: () => true,
+            timeout: 10000,
+        });
+        apiStatus = r.status;
+    }
+    catch {
+        apiStatus = 0;
+    }
+    // MPA: probe every declared page/asset — each must be 200 with a matching
+    // content-type (served by the proxy static branch, not the worker).
+    const mode = manifest.mode ?? manifest.template ?? "spa";
+    const expectedCtype = (f) => {
+        if (/\.html?$/i.test(f))
+            return "text/html";
+        if (/\.css$/i.test(f))
+            return "text/css";
+        if (/\.m?js$/i.test(f))
+            return "javascript";
+        if (/\.json$/i.test(f))
+            return "application/json";
+        if (/\.svg$/i.test(f))
+            return "image/svg+xml";
+        return "";
+    };
+    const assetChecks = [];
+    if (mode === "mpa") {
+        const base = url.replace(/\/$/, "");
+        for (const f of [...(manifest.pages ?? []), ...(manifest.assets ?? [])]) {
+            let s = 0;
+            let ct = "";
+            try {
+                const r = await axios.get(`${base}/${f}`, {
+                    headers: verifyHeaders,
+                    validateStatus: () => true,
+                    timeout: 10000,
+                });
+                s = r.status;
+                ct = String(r.headers["content-type"] ?? "");
+            }
+            catch {
+                s = 0;
+            }
+            const want = expectedCtype(f);
+            assetChecks.push({
+                path: f,
+                httpStatus: s,
+                contentType: ct,
+                ok: s === 200 && (!want || ct.includes(want)),
+            });
+        }
+    }
+    const assetsOk = assetChecks.every((a) => a.ok);
+    const ok = httpStatus === 200 && assetsOk;
+    const out = {
+        status: ok ? "ok" : "failed",
+        shareUrl: url,
+        mode,
+        httpStatus,
+        contentType,
+        attempts,
+        coldStart,
+        firstByteMs,
+        apiPing: { action: apiAction, httpStatus: apiStatus },
+        assets: assetChecks,
+    };
+    if (json) {
+        console.log(JSON.stringify(out, null, 2));
+        process.exit(ok ? 0 : 1);
+    }
+    if (ok)
+        console.log(formatSuccess(`Webapp reachable: ${url} (HTTP 200, ${contentType}${coldStart ? ", cold start" : ""})`));
+    else
+        console.error(formatError(`Webapp not reachable after ${attempts} attempt(s): last HTTP ${httpStatus || "n/a"} — ${url}`));
+    console.log(`  API ping ?action=${apiAction}: HTTP ${apiStatus}`);
+    for (const a of assetChecks) {
+        const line = `  Asset ${a.path}: HTTP ${a.httpStatus || "---"}${a.contentType ? ", " + a.contentType : ""}`;
+        if (a.ok)
+            console.log(line);
+        else
+            console.error(formatError(line + " (expected 200 + matching content-type)"));
+    }
+    process.exit(ok ? 0 : 1);
+}
+async function handleWebappVerify(name, manifest, options, program) {
+    if (!manifest.deployment)
+        throw new AppsApiError("APP_DEPLOYMENT_NOT_FOUND", `App '${name}' has no local deployment state`);
+    const { appsDriver } = await getDriver();
+    const mount = await appsDriver.get(manifest.deployment.mountId);
+    const timeoutSec = Number(options.timeout ?? "60");
+    const deadline = Date.now() + timeoutSec * 1000;
+    let httpStatus = 0;
+    let contentType = "";
+    let attempts = 0;
+    while (Date.now() < deadline) {
+        attempts++;
+        try {
+            const response = await axios.get(mount.url, {
+                validateStatus: () => true,
+                timeout: 10_000,
+            });
+            httpStatus = response.status;
+            contentType = String(response.headers["content-type"] ?? "");
+            if (httpStatus === 200)
+                break;
+        }
+        catch {
+            httpStatus = 0;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 5_000));
+    }
+    // Probe the backend only when app.json declares an explicit backend.healthPath
+    // (P1-2): a valid backend is NOT required to expose a fixed /api/health route.
+    // Without healthPath, verify checks only the mount homepage.
+    let backendStatus = null;
+    const healthPath = manifest.backend?.healthPath;
+    if (manifest.backend && healthPath) {
+        const probePath = healthPath.startsWith("/") ? healthPath : `/${healthPath}`;
+        try {
+            const response = await axios.get(`${mount.url.replace(/\/$/, "")}${probePath}`, { validateStatus: () => true, timeout: 10_000 });
+            backendStatus = response.status;
+        }
+        catch {
+            backendStatus = 0;
+        }
+    }
+    const ok = httpStatus === 200 && (backendStatus === null || backendStatus === 200);
+    const output = {
+        status: ok ? "ok" : "failed",
+        app: name,
+        url: mount.url,
+        httpStatus,
+        contentType,
+        attempts,
+        backendStatus,
+    };
+    if (isJson(options, program))
+        console.log(JSON.stringify(output, null, 2));
+    else if (ok)
+        console.log(formatSuccess(`Webapp reachable: ${mount.url}`));
+    else
+        console.error(formatError(`Webapp verification failed: ${mount.url}`));
+    if (!ok)
+        process.exit(1);
+}
+async function handleUrl(name, options, program) {
+    const manifest = await readManifest(options.dir, name);
+    // 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(mountId),
+            appsDriver.capabilities(),
+        ]);
+        emitWebappResult("url", name, mount, capabilities, options, program);
+        return;
+    }
+    const slug = options.slug ?? manifest.slug ?? name;
+    const { endpoint } = await getDriver();
+    const url = shareUrl(endpoint, slug);
+    const publicReachable = isPublicEndpoint(endpoint);
+    if (isJson(options, program)) {
+        console.log(JSON.stringify({ app: name, slug, shareUrl: url, publicReachable }, null, 2));
+        return;
+    }
+    console.log(url);
+    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();
+    if (isJson(options, program)) {
+        console.log(JSON.stringify({ count: functions.length, functions }, null, 2));
+        return;
+    }
+    if (functions.length === 0) {
+        console.log("No deployed functions.");
+        return;
+    }
+    for (const f of functions) {
+        console.log(`${f.slug}\t${f.status}\tv${f.version}\tverify_jwt=${f.verify_jwt}`);
+    }
+}
+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 = {
+            status: "dry-run",
+            app: name,
+            slug,
+            note: "pass --confirm to delete the deployed function (irreversible)",
+        };
+        if (json)
+            console.log(JSON.stringify(preview, null, 2));
+        else
+            console.log(formatWarning(`Preview: remove function '${slug}'. Re-run with --confirm to delete (irreversible).`));
+        return;
+    }
+    const { driver } = await getDriver();
+    await driver.delete(slug);
+    if (json)
+        console.log(JSON.stringify({ status: "removed", app: name, slug }, null, 2));
+    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")
+        .description("Create, inspect, revoke, and verify secure MPA share links");
+    shareCmd
+        .command("create <slug>")
+        .description("Create a secure MPA share link and print its one-time entry URL")
+        .option("--expires-in <seconds>", "Lifetime in seconds", "86400")
+        .option("--expires-at <iso8601>", "Absolute RFC3339 expiry (instead of --expires-in)")
+        .option("--max-uses <count>", "Maximum ticket redemptions")
+        .option("--tenant-id <tenant>", "Explicit target tenant (required for platform credentials)")
+        .option("--json", "Output in JSON format")
+        .action(async (slug, options) => {
+        try {
+            await handleShareCreate(slug, options, program);
+        }
+        catch (e) {
+            fail(e, isJson(options, program));
+        }
+    });
+    shareCmd
+        .command("list <slug>")
+        .description("List secure MPA share links without exposing tickets or sessions")
+        .option("--tenant-id <tenant>", "Explicit target tenant (required for platform credentials)")
+        .option("--json", "Output in JSON format")
+        .action(async (slug, options) => {
+        try {
+            await handleShareList(slug, options, program);
+        }
+        catch (e) {
+            fail(e, isJson(options, program));
+        }
+    });
+    shareCmd
+        .command("revoke <slug> <share-id>")
+        .description("Revoke a secure MPA share link (requires --confirm)")
+        .option("--tenant-id <tenant>", "Explicit target tenant (required for platform credentials)")
+        .option("--confirm", "Actually revoke the share link")
+        .option("--json", "Output in JSON format")
+        .action(async (slug, shareId, options) => {
+        try {
+            await handleShareRevoke(slug, shareId, options, program);
+        }
+        catch (e) {
+            fail(e, isJson(options, program));
+        }
+    });
+    shareCmd
+        .command("verify <slug> <share-id>")
+        .description("Verify a share link status without revealing a ticket or cookie")
+        .option("--tenant-id <tenant>", "Explicit target tenant (required for platform credentials)")
+        .option("--json", "Output in JSON format")
+        .action(async (slug, shareId, options) => {
+        try {
+            await handleShareVerify(slug, shareId, options, program);
+        }
+        catch (e) {
+            fail(e, isJson(options, program));
+        }
+    });
+}
+function secureShareUrl(endpoint, mountId, ticket) {
+    return `${endpoint.replace(/\/$/, "")}/share/v1/${encodeURIComponent(mountId)}/${encodeURIComponent(ticket)}`;
+}
+function parsePositiveInteger(value, optionName) {
+    if (!/^[1-9]\d*$/.test(value)) {
+        throw new Error(`${optionName} must be a positive integer.`);
+    }
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed > 4_294_967_295) {
+        throw new Error(`${optionName} must be at most 4294967295.`);
+    }
+    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) {
+        const expiresAt = new Date(options.expiresAt);
+        if (!Number.isFinite(expiresAt.getTime()) ||
+            expiresAt.getTime() <= Date.now()) {
+            throw new Error("--expires-at must be a future ISO-8601 timestamp.");
+        }
+    }
+    const maxUses = options.maxUses
+        ? parsePositiveInteger(options.maxUses, "--max-uses")
+        : undefined;
+    const expiresInSeconds = options.expiresAt
+        ? undefined
+        : parsePositiveInteger(options.expiresIn, "--expires-in");
+    const { shareDriver, appsDriver, endpoint } = await getDriver();
+    await assertPrivateShareEnabled(appsDriver, "create");
+    const link = await shareDriver.create(slug, {
+        expiresAt: options.expiresAt,
+        expiresInSeconds,
+        maxUses,
+        tenantId: options.tenantId,
+    });
+    // Do not emit the raw ticket as a separate field or diagnostic. The entry URL
+    // is the only one-time delivery channel; list/verify/revoke never contain it.
+    const { ticket, ...share } = link;
+    const entryUrl = secureShareUrl(endpoint, link.mount_id, ticket);
+    const output = { status: "created", slug, entryUrl, share };
+    if (isJson(options, program)) {
+        console.log(JSON.stringify(output, null, 2));
+        return;
+    }
+    console.log(formatSuccess(`Created secure MPA share for '${slug}'. Save this entry URL now; it cannot be recovered:`));
+    console.log(`  ${entryUrl}`);
+    console.log(`  Expires: ${share.expires_at}`);
+    console.log(`  Share ID: ${share.id}`);
+}
+async function handleShareList(slug, options, program) {
+    validateSlug(slug);
+    const { shareDriver } = await getDriver();
+    const shares = await shareDriver.list(slug, options.tenantId);
+    if (isJson(options, program)) {
+        console.log(JSON.stringify({ slug, count: shares.length, shares }, null, 2));
+        return;
+    }
+    if (shares.length === 0) {
+        console.log("No secure MPA share links.");
+        return;
+    }
+    for (const share of shares) {
+        console.log(`${share.id}\t${share.status}\texpires=${share.expires_at}\tuses=${share.used_count}/${share.max_uses ?? "unlimited"}`);
+    }
+}
+async function handleShareRevoke(slug, shareId, options, program) {
+    validateSlug(slug);
+    if (!options.confirm) {
+        const preview = {
+            status: "dry-run",
+            slug,
+            shareId,
+            note: "pass --confirm to revoke this share link and invalidate all of its active sessions",
+        };
+        if (isJson(options, program))
+            console.log(JSON.stringify(preview, null, 2));
+        else
+            console.log(formatWarning(`Preview: revoke share '${shareId}' for '${slug}'. Re-run with --confirm.`));
+        return;
+    }
+    // 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));
+        return;
+    }
+    console.log(formatSuccess(`Revoked share '${share.id}' for '${slug}'.`));
+}
+async function handleShareVerify(slug, shareId, options, program) {
+    validateSlug(slug);
+    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",
+        slug,
+        share,
+    };
+    if (isJson(options, program)) {
+        console.log(JSON.stringify(output, null, 2));
+        return;
+    }
+    console.log(`${share.id}: ${share.status} (expires ${share.expires_at}, uses ${share.used_count}/${share.max_uses ?? "unlimited"})`);
+}
+//# sourceMappingURL=index.js.map