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

package/dist/commands/app/index.js

@@ -0,0 +1,1476 @@
+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 { runPreflight, isPublicEndpoint } from "../../app/preflight.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("--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("--json", "Output in JSON format")
+        .action(async (name, options) => {
+        try {
+            await handleUrl(name, options, program);
+        }
+        catch (e) {
+            fail(e, options.json);
+        }
+    });
+    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("--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
+                for (const t of templates)
+                    console.log(`${t.id}\t${t.description}`);
+        }
+        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);
+}
+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}`));
+    process.exit(1);
+}
+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,
+    };
+}
+/**
+ * `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 deployment = manifest.deployment;
+    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;
+    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);
+    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 } = await getDriver();
+    let functionsCount = 0;
+    try {
+        functionsCount = (await driver.list()).length;
+    }
+    catch {
+        functionsCount = 0; // preflight should not hard-fail if list is unavailable
+    }
+    const pre = runPreflight({
+        source,
+        endpoint,
+        functionsCount,
+        verifyJwt,
+        entrypointExists,
+    });
+    // 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 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)];
+    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 } = 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);
+    const frontendDir = options.frontend ?? defaultFrontendDir;
+    const frontendRaw = await collectStagingFiles(frontendDir);
+    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,
+            }),
+        };
+    if (!spec.passed) {
+        const details = spec.blockers
+            .map((item) => `[${item.rule}] ${item.message}`)
+            .join("; ");
+        throw new AppsApiError("APP_ARTIFACT_INVALID", details);
+    }
+    await assertArtifactLimits(uploadFiles, capabilities);
+    if (options.dryRun) {
+        const output = {
+            status: "dry-run",
+            app: name,
+            mode: "webapp",
+            capabilities,
+            specLint: spec,
+        };
+        if (isJson(options, program))
+            console.log(JSON.stringify(output, null, 2));
+        else
+            console.log(formatSuccess(`Webapp '${name}' passed capability and artifact checks.`));
+        return;
+    }
+    const mount = manifest.deployment
+        ? await appsDriver.get(manifest.deployment.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);
+    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);
+    emitWebappResult("published", name, published, capabilities, options, program, { candidateFunctionSlug, specLint: spec });
+}
+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) {
+    if (!existsSync(root))
+        throw new AppsApiError("APP_ARTIFACT_INVALID", `Artifact directory not found: ${root}`);
+    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)));
+        }
+        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);
+    if (manifest.mode === "webapp") {
+        const webapp = requireWebappManifestValue(manifest, name);
+        if (!webapp.deployment)
+            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.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."));
+}
+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;
+    if (!deployment) {
+        throw new AppsApiError("APP_DEPLOYMENT_NOT_FOUND", `App '${name}' has no local deployment state; nothing to destroy`);
+    }
+    const { appsDriver } = await getDriver();
+    // Phase 1: preview (no --confirm). Pull the live mount so the operator sees
+    // exactly which functions + mount record will be reclaimed.
+    if (!options.confirm) {
+        let mount = null;
+        try {
+            mount = await appsDriver.get(deployment.mountId);
+        }
+        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 (deployment.candidateFunctionSlug)
+            slugs.add(deployment.candidateFunctionSlug);
+        const purgeTables = options.purgeDb
+            ? await deriveAppTables(join(options.dir, name))
+            : [];
+        const preview = {
+            status: "dry-run",
+            app: name,
+            mountId: deployment.mountId,
+            mountStatus: mount?.status ?? "NOT_FOUND",
+            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 ${deployment.mountId}). Re-run with --confirm.`));
+        console.log(`  Functions to delete: ${[...slugs].join(", ") || "(none)"}`);
+        console.log(`  Mount record:        ${deployment.mountId} (${preview.mountStatus})`);
+        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.
+    const result = await appsDriver.destroy(deployment.mountId, {
+        ...(deployment.candidateFunctionSlug
+            ? { candidateFunctionSlug: deployment.candidateFunctionSlug }
+            : {}),
+    });
+    // D5: clear ONLY the local deployment state; keep the source tree so the app
+    // can be re-deployed later.
+    delete webapp.deployment;
+    await writeManifest(options.dir, name, webapp);
+    // 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,
+            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" : ""}).`));
+    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;
+}
+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, endpoint } = await getDriver();
+    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;
+    }
+    const { shareDriver } = await getDriver();
+    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 } = await getDriver();
+    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