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

package/README.md

@@ -39,7 +39,81 @@ pxbaas doctor     # connectivity / configuration diagnostics
 pxbaas status     # instance reachability summary
 ```
 
-Every command accepts `--json` for machine-readable output, and `--profile <name>` to select a profile per invocation (`pxbaas profile list / use / import` manage them).
+Every command accepts `--json` for machine-readable output, and `--profile <name>` to select a profile per invocation (`pxbaas profile ls / use / rm / import` manage them).
+
+### Non-interactive credential setup
+
+Agents and CI have two TTY-free paths; keys never pass through argv or shell history:
+
+```bash
+# 1) stdin mode: pipe exactly two lines - anon key, then service_role key.
+#    --anon-key-stdin and --service-key-stdin must always be given together.
+pxbaas login --endpoint https://baas.example.com \
+  [--tenant-id <tenant>] \
+  --anon-key-stdin --service-key-stdin <<'EOF'
+<anon-key>
+<service-role-key>
+EOF
+
+# 2) import from a Supabase-convention .env file (single- or multi-tenant)
+pxbaas profile import ./instance.env --name prod --json
+```
+
+`profile import` resolves variables in first-match order and validates JWT expiry + tenant consistency before storing the profile:
+
+| Field | Accepted env variable names (first match wins) |
+| --- | --- |
+| Endpoint | `SUPABASE_URL`, `SUPABASE_PUBLIC_URL`, `SUPABASE_INTRANET_URL` (`--intranet` prefers the intranet URL) |
+| anon key | `SUPABASE_ANON_KEY`, `ANON_KEY`, `GLOBAL_ANON_KEY` |
+| service_role key | `SUPABASE_SERVICE_ROLE_KEY`, `SERVICE_ROLE_KEY`, `GLOBAL_SERVICE_ROLE_KEY` |
+
+For a **multi-tenant** instance the env file must carry tenant-level credentials — `MULTI_TENANT_MODE=true`, `DEFAULT_TENANT_ID`, `TENANT_ANON_KEY`, `TENANT_SERVICE_ROLE_KEY`. Platform-global keys (`GLOBAL_*`, whose JWTs have no `tenant_id` claim) are reported as present-but-not-imported: they cannot reach tenant resources.
+
+An env file that is multi-tenant but lacks the tenant keys is refused **with a diagnosis and a route**: if the machine can open the tenant admin channel it points you at `pxbaas tenant …`; otherwise it prints a checklist to send to the instance operator. Nothing is created and nothing is imported in that branch.
+
+`DASHBOARD_USERNAME` / `DASHBOARD_PASSWORD` in an env file are never absorbed silently — pass `--with-admin` to bind them, and only after they actually authenticate against the admin channel.
+
+## Multi-tenant
+
+On a `MULTI_TENANT_MODE=true` instance, authenticate with that tenant's own keys:
+
+```bash
+pxbaas login --tenant-id <tenant>   # paste the tenant's per-tenant anon + service_role keys
+```
+
+A tenant-level key is one whose JWT payload contains `tenant_id`; a platform-global key does not and will be rejected on tenant resources.
+
+With a multi-tenant profile, `db query`, `db tables`, `db schema`, `db create-table`, `db add-column`, `db push`, and `gen types` all run through `/api/tenant-ddl` against the tenant's **own** database using its per-tenant `service_role` key (these previously returned 401 in multi-tenant mode). Notes:
+
+- `db query` always executes as the tenant `service_role` in multi-tenant mode; `--role anon` is not applicable (warned and ignored). `/pg/query` remains platform-admin only.
+- `db push` / `app db-init` register RLS via the structured `/api/tenant-ddl/rls/*` endpoints (the tenant account has no grant on the central `supabase` registry); `table_schema` is bound server-side and the `__SCHEMA__` placeholder is de-qualified automatically. RLS source is hybrid: declarative `db/rls.json` preferred, else RLS INSERTs parsed from `schema.sql`.
+- `db create-table` / `db add-column` work for a tenant too: the DDL lands in the tenant database, so `--schema` is ignored (the effective database is printed) and `--role anon` is ignored.
+- A normal tenant can run the full webapp lifecycle (`db-init` → `deploy` → `publish/rollback/unpublish` → `destroy`) with only its per-tenant key; cross-tenant access is rejected.
+
+## Tenant administration (instance operators)
+
+Ordinary tenants never use this. It requires the instance dashboard credentials (HTTP Basic), which live in a
+separate keyring account from your tenant API keys and are refused in argv.
+
+```bash
+pxbaas tenant login --endpoint https://<gateway>     # masked prompt, or --user-stdin --password-stdin
+pxbaas tenant probe --json                           # admin / not-admin / single-tenant / metadata-unreadable / unreachable
+pxbaas tenant ls --json                              # redacted: ids, status, plan, db, key-presence booleans
+
+# hand an existing tenant's keys to its user
+pxbaas tenant keys acme --as-profile                 # into this machine's keyring
+pxbaas tenant keys acme --bundle ./acme.pxbaas.env    # 0600 file to hand over
+
+# only when a tenant really must be created
+pxbaas tenant create acme --dry-run --json
+pxbaas tenant create acme --as-profile --bundle ./acme.pxbaas.env
+pxbaas tenant repair-keys                            # preview; --confirm to run
+```
+
+- `tenant create` shows a plan and requires authorization, and **refuses a colliding tenant id** — reusing a soft-deleted id resurrects that tenant and regenerates its keys, so it needs an explicit `--reactivate`.
+- After creating, the CLI verifies the tenant is actually usable (`SELECT DATABASE()`, table count, RLS registry, Realtime registration), because the platform treats those provisioning steps as non-fatal. A failing check exits non-zero.
+- An **access bundle** contains exactly `MULTI_TENANT_MODE`, `SUPABASE_URL`, `DEFAULT_TENANT_ID`, `TENANT_ANON_KEY`, `TENANT_SERVICE_ROLE_KEY` — never `jwt_secret`, `DASHBOARD_*` or `GLOBAL_*` — and is consumed directly by `pxbaas profile import`. The command prints a handoff note with both key fingerprints so the receiver can prove nothing was swapped in transit; `pxbaas tenant handoffs` keeps a local ledger of fingerprints and file hashes.
+- Bundles hold **plaintext, ~10-year, currently irrevocable** credentials. Transmit them over a secure channel and delete the file after import. Rotation is not available: the platform does not accept `jwt_secret` updates, and re-signing keys does not invalidate old ones.
 
 ## Command Reference
 
@@ -47,14 +121,15 @@ Every command accepts `--json` for machine-readable output, and `--profile <name
 | --- | --- |
 | Onboarding & diagnostics | `login`, `logout`, `whoami`, `status`, `doctor`, `profile` |
 | Disposable instances (Zero) | `provision` (alias `instance claim`), `instance list / current / credentials / release` |
-| Database | `db query <sql>`, `db tables`, `db schema <table>`, `db push <file>`, `db create-table`, `db add-column` |
+| Database | `db query <sql>`, `db tables`, `db schema <table>`, `db push <file> [--rls <rls.json>]`, `db create-table`, `db add-column` |
 | Data (REST) | `data select / insert / update / delete <table>`, `rest <method> <path>` |
 | Edge Functions | `functions new / deploy / list / delete` |
-| Webapp demos | `app new / deploy / verify / url / list / remove / destroy / templates / db-init / capabilities`, `app share ...` |
+| Webapp demos | `app new / deploy / verify / url / list / remove / destroy / templates / db-init / capabilities / publish / rollback / unpublish`, `app share ...` |
 | Storage | `storage ls / cp / mv / rm` |
-| Auth admin | `auth users list / create / invite` |
+| Auth admin | `auth users list / get / create / delete / invite` |
 | Codegen | `gen types` (TypeScript types from the live schema) |
-| Tooling | `skill install / list / remove`, `completion <shell>` |
+| Tenant administration (operator) | `tenant login / logout / probe / ls / create / keys / repair-keys / handoffs` |
+| Tooling | `skill install / list / remove`, `completion <shell>` (not yet implemented) |
 
 ### Provisioning (PolarDB-X Zero)
 
@@ -69,15 +144,43 @@ Keys come from Zero over TLS and are stored in the keyring; output shows only fi
 ### Webapp demos (edge-function sandbox)
 
 ```bash
-pxbaas app new shop --template spa --json   # scaffold a self-contained single-file webapp
-pxbaas app deploy shop --dry-run --json     # preflight (quota / root-abs refs / public reachability)
-pxbaas app deploy shop --json               # deploy -> share URL
-pxbaas app verify shop --json               # cold-start retry + content-type + API ping
-pxbaas app url shop --json                  # {endpoint}/functions/v1/{slug}
-pxbaas app destroy shop --confirm --json    # delete edge funcs + mount record (DB tables kept)
+pxbaas app new shop --template ssr-shop --json        # scaffold a schemaVersion-2 webapp (ships db/)
+pxbaas app db-init shop --dry-run --json              # preview the db/schema.sql + db/rls.json plan
+pxbaas app db-init shop --yes --json                  # create tables + register RLS + seed (authorized)
+pxbaas app deploy shop --dry-run --json               # preflight (quota / root-abs refs / public reachability)
+pxbaas app deploy shop --json                         # upload + publish -> mount URL
+pxbaas app verify shop --json                         # cold-start retry + content-type + API ping
+pxbaas app url shop --json                            # webapp: {appEndpoint}/apps/{mount}/; legacy spa/api/mpa: {endpoint}/functions/v1/{slug}
+pxbaas app publish shop --json                        # publish a new candidate (generation CAS)
+pxbaas app rollback shop --json                       # roll back one generation
+pxbaas app unpublish shop --json                      # take the mount offline (reversible)
+pxbaas app destroy shop --confirm --json              # delete edge funcs + mount record (DB tables kept)
+pxbaas app destroy shop --confirm --purge-db --json   # also drop tables + RLS registry rows (destructive)
+```
+
+`pxbaas app` is a higher-level convenience over `pxbaas functions` for lightweight demos. Templates ship under `templates/` (npm/source install only); `pxbaas app templates` is the authoritative list. The CLI scaffolds but does not generate demo code — fill the scaffold yourself or let your coding agent do it. `app db-init` applies to templates that ship `db/schema.sql` (+ optional `db/rls.json`); `app publish / rollback / unpublish / destroy` operate on schemaVersion-2 webapps (legacy `spa/api/mpa` use `app remove`).
+
+### Secure sharing (`app share`)
+
+A default deploy (`verify_jwt=false`) is fully public. For time-boxed, revocable, audience-limited sharing, use secure share links:
+
+```bash
+pxbaas app share create shop --json                                  # default 86400s lifetime; prints the one-time entry URL
+pxbaas app share create shop --expires-in 3600 --json                # relative expiry (1 hour)
+pxbaas app share create shop --expires-at 2026-12-31T00:00:00Z --json # absolute RFC3339 expiry (must be in the future)
+pxbaas app share create shop --max-uses 5 --json                     # cap ticket redemptions (positive int, max 4294967295)
+pxbaas app share list shop --json                                    # never exposes tickets or sessions
+pxbaas app share verify shop <share-id> --json                       # status check without revealing the link
+pxbaas app share revoke shop <share-id> --confirm --json             # disable a link (two-phase)
 ```
 
-`pxbaas app` is a higher-level convenience over `pxbaas functions` for lightweight demos. Templates ship under `templates/` (npm/source install only); `pxbaas app templates` is the authoritative list. The CLI scaffolds but does not generate demo code — fill the scaffold yourself or let your coding agent do it.
+How it works:
+
+- `share create` prints a one-time entry URL of the form `{endpoint}/share/v1/{mountId}/{ticket}`; the first visit exchanges the ticket for a share session cookie, and later page/resource requests ride that session.
+- `--expires-in` and `--expires-at` are mutually exclusive; `--max-uses` is a positive integer.
+- With platform credentials on a multi-tenant instance, pass `--tenant-id <tenant>` explicitly.
+- ⚠️ Redeploying the same slug (`app deploy`) immediately revokes **all** of its active share links — re-create them afterwards.
+- `list` / `verify` never return the ticket or cookie; only `create`'s one-time output contains the entry URL — hand it over right away.
 
 ### Agent Skill
 
@@ -95,7 +198,7 @@ Installs into supported Agent hosts (`~/.qoder`, `~/.claude`, `~/.cursor`, `~/.q
 1. **Human-only login**: `pxbaas login` requires an interactive TTY; agents cannot execute it.
 2. **Agent commands never accept key parameters**: post-login commands read credentials from the keyring.
 3. **Output masking**: commands show only key fingerprints (sha256 prefix 8 + suffix 4), never plaintext.
-4. **Two-phase operations**: destructive writes support `--plan` / `--confirm`.
+4. **Two-phase operations**: `db push` / `app db-init` / `data delete` / `tenant create` preview first and require `--dry-run` + `--yes`, and `app remove` / `app destroy` / `app share revoke` / `instance release` / `skill remove` / `tenant repair-keys` require `--confirm`. Commands with **no** gate — `db create-table` / `db add-column`, `functions deploy` / `delete`, `storage rm` / `mv`, `auth users delete`, `rest` writes — execute immediately, so verify the target yourself first.
 5. **Tenant isolation**: commands validate that the key's tenant matches the profile's tenant before executing.
 
 ## Documentation

package/dist/app/local-index.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Workspace-level side index of deployed App mounts (`.pxbaas/apps.json`).
+ *
+ * The lifecycle commands address a mount solely through `app.json`'s
+ * `deployment` block, so losing that block (instance reinstall, hand edit,
+ * re-scaffold, working from another machine) turns a live mount into an orphan:
+ * deploy then dies on APP_MOUNT_CONFLICT while destroy dies on
+ * APP_DEPLOYMENT_NOT_FOUND, and nothing in the CLI can reach the mount again.
+ *
+ * This index mirrors `deployment` one level up, keyed by app name, so the CLI can
+ * recover the mountId on its own. It is a CACHE, never a source of truth:
+ * `app.json` always wins, and an entry is ignored unless it was written against
+ * the same endpoint + tenant as the active profile (one workspace can be pointed
+ * at several instances, and a mountId from instance A must never be replayed
+ * against instance B).
+ */
+export declare const LOCAL_INDEX_DIRNAME = ".pxbaas";
+export declare const LOCAL_INDEX_FILENAME = "apps.json";
+export interface LocalAppIndexEntry {
+    mountId: string;
+    generation: number;
+    /** Endpoint the entry was recorded against; guards cross-instance reuse. */
+    endpoint: string;
+    /** Tenant the entry was recorded against; null for single-tenant profiles. */
+    tenantId: string | null;
+    updatedAt: string;
+}
+export type LocalAppIndex = Record<string, LocalAppIndexEntry>;
+/** The instance the active profile points at. */
+export interface ProfileScope {
+    endpoint: string;
+    tenantId?: string | null;
+}
+export interface LocalMountLookup {
+    /** The usable entry, or null when there is none / it was ignored. */
+    entry: LocalAppIndexEntry | null;
+    /** Human-readable reason when an entry existed but was NOT used. */
+    ignored: string | null;
+    path: string;
+}
+/** Absolute-ish path of the index for an apps directory (`--dir`). */
+export declare function localIndexPath(appsDir: string): string;
+/**
+ * Read the raw index. A missing, unreadable or corrupt file degrades to an empty
+ * index: the cache must never be able to break a command that would otherwise
+ * work off `app.json`.
+ */
+export declare function readLocalIndex(appsDir: string): Promise<LocalAppIndex>;
+/**
+ * Look up an app's recorded mount, rejecting entries that belong to a different
+ * instance or tenant. `ignored` carries the reason so callers can tell the user
+ * why a stale entry was skipped instead of silently dropping it.
+ */
+export declare function lookupLocalMount(appsDir: string, name: string, scope: ProfileScope): Promise<LocalMountLookup>;
+/**
+ * Record a mount after a successful deploy/publish/rollback/adopt. Best effort:
+ * returns an error message instead of throwing so a cache write can never fail
+ * the operation that already succeeded server-side.
+ */
+export declare function recordLocalMount(appsDir: string, name: string, mount: {
+    mountId: string;
+    generation: number;
+}, scope: ProfileScope): Promise<string | null>;
+/**
+ * Drop an app's entry after a successful destroy. `expectedMountId` makes the
+ * delete conditional so destroying one mount never erases the record of a
+ * different one (e.g. `destroy --mount-id` overriding stale local state).
+ */
+export declare function forgetLocalMount(appsDir: string, name: string, expectedMountId?: string): Promise<string | null>;
+//# sourceMappingURL=local-index.d.ts.map

package/dist/app/local-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-index.d.ts","sourceRoot":"","sources":["../../src/app/local-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,eAAO,MAAM,mBAAmB,YAAY,CAAC;AAC7C,eAAO,MAAM,oBAAoB,cAAc,CAAC;AAEhD,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;AAE/D,iDAAiD;AACjD,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,qEAAqE;IACrE,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACjC,oEAAoE;IACpE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,sEAAsE;AACtE,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEtD;AAUD;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CA2B5E;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,gBAAgB,CAAC,CA2B3B;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,EAC9C,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiBxB;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,eAAe,CAAC,EAAE,MAAM,GACvB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAcxB"}

package/dist/app/local-index.js

@@ -0,0 +1,140 @@
+/**
+ * Workspace-level side index of deployed App mounts (`.pxbaas/apps.json`).
+ *
+ * The lifecycle commands address a mount solely through `app.json`'s
+ * `deployment` block, so losing that block (instance reinstall, hand edit,
+ * re-scaffold, working from another machine) turns a live mount into an orphan:
+ * deploy then dies on APP_MOUNT_CONFLICT while destroy dies on
+ * APP_DEPLOYMENT_NOT_FOUND, and nothing in the CLI can reach the mount again.
+ *
+ * This index mirrors `deployment` one level up, keyed by app name, so the CLI can
+ * recover the mountId on its own. It is a CACHE, never a source of truth:
+ * `app.json` always wins, and an entry is ignored unless it was written against
+ * the same endpoint + tenant as the active profile (one workspace can be pointed
+ * at several instances, and a mountId from instance A must never be replayed
+ * against instance B).
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+export const LOCAL_INDEX_DIRNAME = ".pxbaas";
+export const LOCAL_INDEX_FILENAME = "apps.json";
+/** Absolute-ish path of the index for an apps directory (`--dir`). */
+export function localIndexPath(appsDir) {
+    return join(appsDir, LOCAL_INDEX_DIRNAME, LOCAL_INDEX_FILENAME);
+}
+function normalizeEndpoint(endpoint) {
+    return endpoint.replace(/\/+$/, "");
+}
+function normalizeTenant(tenantId) {
+    return tenantId == null || tenantId === "" ? null : tenantId;
+}
+/**
+ * Read the raw index. A missing, unreadable or corrupt file degrades to an empty
+ * index: the cache must never be able to break a command that would otherwise
+ * work off `app.json`.
+ */
+export async function readLocalIndex(appsDir) {
+    try {
+        const parsed = JSON.parse(await readFile(localIndexPath(appsDir), "utf8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return {};
+        const index = {};
+        for (const [name, value] of Object.entries(parsed)) {
+            const entry = value;
+            if (typeof entry?.mountId !== "string" || !entry.mountId)
+                continue;
+            index[name] = {
+                mountId: entry.mountId,
+                generation: typeof entry.generation === "number" && Number.isFinite(entry.generation)
+                    ? entry.generation
+                    : 0,
+                endpoint: typeof entry.endpoint === "string" ? entry.endpoint : "",
+                tenantId: normalizeTenant(entry.tenantId),
+                updatedAt: typeof entry.updatedAt === "string" ? entry.updatedAt : "",
+            };
+        }
+        return index;
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Look up an app's recorded mount, rejecting entries that belong to a different
+ * instance or tenant. `ignored` carries the reason so callers can tell the user
+ * why a stale entry was skipped instead of silently dropping it.
+ */
+export async function lookupLocalMount(appsDir, name, scope) {
+    const path = localIndexPath(appsDir);
+    const entry = (await readLocalIndex(appsDir))[name];
+    if (!entry)
+        return { entry: null, ignored: null, path };
+    const wantEndpoint = normalizeEndpoint(scope.endpoint);
+    if (normalizeEndpoint(entry.endpoint) !== wantEndpoint) {
+        return {
+            entry: null,
+            ignored: `Ignoring the ${path} entry for '${name}': it was recorded against endpoint ` +
+                `${entry.endpoint || "(unknown)"} but the active profile points at ${wantEndpoint}. ` +
+                `A mountId is only valid on the instance that issued it.`,
+            path,
+        };
+    }
+    const wantTenant = normalizeTenant(scope.tenantId);
+    if (entry.tenantId !== wantTenant) {
+        return {
+            entry: null,
+            ignored: `Ignoring the ${path} entry for '${name}': it was recorded for tenant ` +
+                `${entry.tenantId ?? "(none)"} but the active profile is ${wantTenant ?? "(single-tenant)"}.`,
+            path,
+        };
+    }
+    return { entry, ignored: null, path };
+}
+/**
+ * Record a mount after a successful deploy/publish/rollback/adopt. Best effort:
+ * returns an error message instead of throwing so a cache write can never fail
+ * the operation that already succeeded server-side.
+ */
+export async function recordLocalMount(appsDir, name, mount, scope) {
+    const path = localIndexPath(appsDir);
+    try {
+        const index = await readLocalIndex(appsDir);
+        index[name] = {
+            mountId: mount.mountId,
+            generation: mount.generation,
+            endpoint: normalizeEndpoint(scope.endpoint),
+            tenantId: normalizeTenant(scope.tenantId),
+            updatedAt: new Date().toISOString(),
+        };
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, JSON.stringify(index, null, 2) + "\n", "utf8");
+        return null;
+    }
+    catch (e) {
+        return `Could not update the local mount index ${path}: ${e instanceof Error ? e.message : String(e)}`;
+    }
+}
+/**
+ * Drop an app's entry after a successful destroy. `expectedMountId` makes the
+ * delete conditional so destroying one mount never erases the record of a
+ * different one (e.g. `destroy --mount-id` overriding stale local state).
+ */
+export async function forgetLocalMount(appsDir, name, expectedMountId) {
+    const path = localIndexPath(appsDir);
+    try {
+        const index = await readLocalIndex(appsDir);
+        const entry = index[name];
+        if (!entry)
+            return null;
+        if (expectedMountId && entry.mountId !== expectedMountId)
+            return null;
+        delete index[name];
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, JSON.stringify(index, null, 2) + "\n", "utf8");
+        return null;
+    }
+    catch (e) {
+        return `Could not update the local mount index ${path}: ${e instanceof Error ? e.message : String(e)}`;
+    }
+}
+//# sourceMappingURL=local-index.js.map

package/dist/app/local-index.js.map

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

package/dist/app/preflight.d.ts

@@ -6,17 +6,28 @@
  * (they escape the /functions/v1/ prefix onto Studio), and cross-machine sharing
  * requires a public endpoint (sandbox URLs are internal).
  */
+export type QuotaLimitSource = "platform" | "flag" | "fallback";
+/**
+ * Client-side fallback limit, used ONLY when the instance did not report its
+ * real quota (capabilities.maxFunctions) and no --quota-limit was given. It never
+ * hard-blocks on its own; the server-side quota trigger is authoritative (弯路5).
+ */
+export declare const FALLBACK_QUOTA_LIMIT = 5;
 export interface QuotaCheck {
     used: number;
     limit: number;
     ok: boolean;
     near: boolean;
+    source: QuotaLimitSource;
+    /** True when the limit is authoritative (platform/flag) so a violation blocks. */
+    authoritative: boolean;
 }
 export interface PreflightInput {
     source: string;
     endpoint: string;
     functionsCount: number;
     quotaLimit?: number;
+    quotaLimitSource?: QuotaLimitSource;
     verifyJwt: boolean;
     entrypointExists: boolean;
     sourceBytes?: number;
@@ -32,7 +43,19 @@ export interface PreflightResult {
 export declare function scanRootAbsoluteRefs(source: string): string[];
 /** True when the endpoint host is publicly reachable (not loopback / RFC1918). */
 export declare function isPublicEndpoint(endpoint: string): boolean;
-export declare function checkQuota(used: number, limit?: number): QuotaCheck;
+export declare function checkQuota(used: number, limit?: number, source?: QuotaLimitSource): QuotaCheck;
+/**
+ * Split a quota check into the blocker/warning text the deploy gates report.
+ *
+ * Exported separately from runPreflight because the schemaVersion 2 webapp path
+ * has no single-file `source`/entrypoint to feed runPreflight — it still needs
+ * the identical quota wording, so both paths share this one implementation
+ * instead of the webapp branch re-deriving (or skipping) the check.
+ */
+export declare function quotaFindings(quota: QuotaCheck): {
+    warnings: string[];
+    blockers: string[];
+};
 /** Run all preflight checks and collect warnings/blockers. */
 export declare function runPreflight(input: PreflightInput): PreflightResult;
 //# sourceMappingURL=preflight.d.ts.map

package/dist/app/preflight.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"preflight.d.ts","sourceRoot":"","sources":["../../src/app/preflight.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,UAAU,CAAC;IAClB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,eAAe,EAAE,OAAO,CAAC;IACzB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,mFAAmF;AACnF,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAY7D;AAED,kFAAkF;AAClF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAY1D;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,SAAI,GAAG,UAAU,CAE9D;AAED,8DAA8D;AAC9D,wBAAgB,YAAY,CAAC,KAAK,EAAE,cAAc,GAAG,eAAe,CAiDnE"}
+{"version":3,"file":"preflight.d.ts","sourceRoot":"","sources":["../../src/app/preflight.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,MAAM,GAAG,UAAU,CAAC;AAEhE;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAEtC,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,gBAAgB,CAAC;IACzB,kFAAkF;IAClF,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,SAAS,EAAE,OAAO,CAAC;IACnB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,UAAU,CAAC;IAClB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,eAAe,EAAE,OAAO,CAAC;IACzB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,mFAAmF;AACnF,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAY7D;AAED,kFAAkF;AAClF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAY1D;AAED,wBAAgB,UAAU,CACxB,IAAI,EAAE,MAAM,EACZ,KAAK,SAAuB,EAC5B,MAAM,GAAE,gBAA6B,GACpC,UAAU,CASZ;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG;IAChD,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CA0BA;AAED,8DAA8D;AAC9D,wBAAgB,YAAY,CAAC,KAAK,EAAE,cAAc,GAAG,eAAe,CA4CnE"}

package/dist/app/preflight.js

@@ -6,6 +6,12 @@
  * (they escape the /functions/v1/ prefix onto Studio), and cross-machine sharing
  * requires a public endpoint (sandbox URLs are internal).
  */
+/**
+ * Client-side fallback limit, used ONLY when the instance did not report its
+ * real quota (capabilities.maxFunctions) and no --quota-limit was given. It never
+ * hard-blocks on its own; the server-side quota trigger is authoritative (弯路5).
+ */
+export const FALLBACK_QUOTA_LIMIT = 5;
 /** Detect root-absolute references that would escape the /functions/v1/ prefix. */
 export function scanRootAbsoluteRefs(source) {
     const patterns = [
@@ -40,25 +46,55 @@ export function isPublicEndpoint(endpoint) {
         return false;
     return true;
 }
-export function checkQuota(used, limit = 5) {
-    return { used, limit, ok: used < limit, near: used === limit - 1 };
+export function checkQuota(used, limit = FALLBACK_QUOTA_LIMIT, source = "fallback") {
+    return {
+        used,
+        limit,
+        ok: used < limit,
+        near: used === limit - 1,
+        source,
+        authoritative: source !== "fallback",
+    };
+}
+/**
+ * Split a quota check into the blocker/warning text the deploy gates report.
+ *
+ * Exported separately from runPreflight because the schemaVersion 2 webapp path
+ * has no single-file `source`/entrypoint to feed runPreflight — it still needs
+ * the identical quota wording, so both paths share this one implementation
+ * instead of the webapp branch re-deriving (or skipping) the check.
+ */
+export function quotaFindings(quota) {
+    const warnings = [];
+    const blockers = [];
+    if (quota.ok) {
+        if (quota.near) {
+            warnings.push(`Approaching the Edge Function quota (${quota.used}/${quota.limit}, source: ${quota.source}).`);
+        }
+        return { warnings, blockers };
+    }
+    const detail = `${quota.used}/${quota.limit}, source: ${quota.source}`;
+    if (quota.authoritative) {
+        blockers.push(`Edge Function quota reached (${detail}). Remove an existing function (\`pxbaas app remove\` / \`pxbaas functions delete\`) or request a higher quota.`);
+    }
+    else {
+        // No authoritative limit could be read (the instance did not report its
+        // quota and no --quota-limit was given). Do NOT hard-block on a client-side
+        // guess — the server-side quota trigger is authoritative. Warn instead. (弯路5)
+        warnings.push(`Edge Function count is at the client fallback limit (${detail}); the platform limit could not be read. Proceeding — the server enforces the real quota. Pass --quota-limit <n> to make this check authoritative.`);
+    }
+    return { warnings, blockers };
 }
 /** Run all preflight checks and collect warnings/blockers. */
 export function runPreflight(input) {
-    const quota = checkQuota(input.functionsCount, input.quotaLimit ?? 5);
+    const quotaSource = input.quotaLimitSource ?? (input.quotaLimit != null ? "flag" : "fallback");
+    const quota = checkQuota(input.functionsCount, input.quotaLimit ?? FALLBACK_QUOTA_LIMIT, quotaSource);
     const rootAbsoluteRefs = scanRootAbsoluteRefs(input.source);
     const publicReachable = isPublicEndpoint(input.endpoint);
-    const warnings = [];
-    const blockers = [];
+    const { warnings, blockers } = quotaFindings(quota);
     if (!input.entrypointExists) {
         blockers.push("Entrypoint file not found. Run `pxbaas app new <name>` first.");
     }
-    if (!quota.ok) {
-        blockers.push(`Edge Function quota reached (${quota.used}/${quota.limit}). Remove an existing function (\`pxbaas app remove\` / \`pxbaas functions delete\`) or request a higher quota.`);
-    }
-    else if (quota.near) {
-        warnings.push(`Approaching the Edge Function quota (${quota.used}/${quota.limit}).`);
-    }
     if (rootAbsoluteRefs.length > 0) {
         // Root-absolute refs are a hard spec violation and are reported as a BLOCKER
         // by spec-lint (pxbaas-app-spec). We still surface the raw list here for data,

package/dist/app/preflight.js.map

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

package/dist/app/spec-lint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spec-lint.d.ts","sourceRoot":"","sources":["../../src/app/spec-lint.ts"],"names":[],"mappings":"AAAA,sFAAsF;AAGtF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;AAE7C,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,eAAe,CAAC,EAAE,cAAc,EAAE,CAAC;IACnC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,sBAAsB,CAAC,EAAE,MAAM,EAAE,CAAC;IAClC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAmaD,sFAAsF;AACtF,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,eAAoB,GAC5B,cAAc,CA6GhB"}
+{"version":3,"file":"spec-lint.d.ts","sourceRoot":"","sources":["../../src/app/spec-lint.ts"],"names":[],"mappings":"AAAA,sFAAsF;AAGtF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;AAE7C,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,eAAe,CAAC,EAAE,cAAc,EAAE,CAAC;IACnC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,sBAAsB,CAAC,EAAE,MAAM,EAAE,CAAC;IAClC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAubD,sFAAsF;AACtF,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,eAAoB,GAC5B,cAAc,CA6GhB"}

package/dist/app/spec-lint.js

@@ -216,6 +216,22 @@ function lintBackend(source, options, blockers, warnings) {
             specRef: `${SPEC}/references/guardrails-pitfalls.md`,
         });
     }
+    // C2: with APP_WORKER_PATH_REWRITE off (the default) the proxy forwards every
+    // request as /<candidateSlug>/<logical>, so a Hono backend that registers fixed
+    // literal routes (app.get("/data")) without a wildcard dispatcher or slug
+    // normalization will 404 at runtime. Warn (never block) so authors normalize.
+    const honoBackend = /new\s+Hono\s*\(/.test(code);
+    const literalRoute = /app\.(get|post|put|delete|patch)\s*\(\s*["']\/[^"']*["']/.test(code);
+    const wildcardDispatch = /app\.(all|get|post)\s*\(\s*["']\*["']/.test(code);
+    const slugNormalized = /\bnorm\s*\(/.test(code) || /\/app_/.test(code);
+    if (honoBackend && literalRoute && !wildcardDispatch && !slugNormalized) {
+        warnings.push({
+            rule: "worker-path-normalize",
+            severity: "warning",
+            message: 'Backend registers fixed literal routes (e.g. app.get("/data")), but with APP_WORKER_PATH_REWRITE off (the default) the worker receives a /<candidateSlug>-prefixed path, so these routes 404. Normalize the leading slug (path.replace(/^\\/app_[^/]+/, "")) and dispatch on the logical path, or use a wildcard app.get("*").',
+            specRef: `${SPEC}/references/runtime-contract.md`,
+        });
+    }
 }
 function lintWebappFrontend(options, blockers) {
     const files = options.frontendFiles ?? [];