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

package/README.md

@@ -1,3 +1,224 @@
-# Temporary Holding Version
+# @polardbx/pxbaas
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Command-line interface for [PolarDB-X BaaS](https://github.com/polardbx/mysql-supabase) (MySQL-Supabase, Backend as a Service). Run SQL, inspect tables and schemas, query and edit table data over the PostgREST-style REST API, deploy Edge Functions and webapp demos, manage storage objects and auth users, generate TypeScript types — and claim a free disposable BaaS instance — all from your terminal.
+
+## Requirements
+
+- Node.js >= 20
+
+## Installation
+
+```bash
+# Public npm (prerelease line publishes under the `beta` dist-tag)
+npm install -g @polardbx/pxbaas@beta
+
+# From a repository clone (installer checks Node >= 20, never uses sudo,
+# and verifies the binary with --version + --help after install)
+git clone https://github.com/polardbx/mysql-supabase.git
+cd mysql-supabase/cli
+bash install.sh --yes
+
+# Air-gapped environments: build an offline bundle (tarballs + optional Node runtime)
+bash scripts/pack-offline.sh
+```
+
+`@polardbx/pxbaas` depends on `@polardbx/pxbaas-client`; both are published to npm in lockstep, so a plain global install resolves everything. If the OS keychain is unavailable, credentials fall back to an encrypted `~/.baas/credentials.json` (mode 0600).
+
+## Quick Start
+
+```bash
+# No instance yet? Claim a free disposable PolarDB-X Zero BaaS instance.
+# Agent-safe: keys arrive over TLS and only fingerprints are printed.
+pxbaas provision --json
+
+# Already have an endpoint + keys? Interactive login (human-only, requires a TTY).
+pxbaas login
+
+pxbaas whoami     # current profile + key fingerprints (never plaintext keys)
+pxbaas doctor     # connectivity / configuration diagnostics
+pxbaas status     # instance reachability summary
+```
+
+## For coding agents (start here)
+
+Run `pxbaas guide` first: it prints the recommended end-to-end workflow for
+developing, deploying, verifying and sharing an app — instance binding,
+capability checks, scoped approvals, stage-by-stage failure recovery, and
+network/whitelist handling — without needing credentials or network access.
+Then install the bundled skills (`pxbaas skill install --host
+<qoder|claude|cursor|qwen|hermes|codex|gemini|copilot|qwenworkcn|agents>`, or
+`--dir <path>` / `--scope project` for other agent hosts and repo-local
+conventions) and follow `pxbaas-cli` / `pxbaas-app-spec`. `pxbaas login` needs
+a human TTY; agents should bind instances with `pxbaas profile import
+<env-file>` or, with user approval, `pxbaas provision`.
+
+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
+
+| Group | Commands |
+| --- | --- |
+| 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> [--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 / publish / rollback / unpublish`, `app share ...` |
+| Storage | `storage ls / cp / mv / rm` |
+| Auth admin | `auth users list / get / create / delete / invite` |
+| Codegen | `gen types` (TypeScript types from the live schema) |
+| 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)
+
+```bash
+pxbaas provision --json                    # claim a free 15-day Zero BaaS instance -> binds a profile
+pxbaas instance list --json                # Zero instances bound locally
+pxbaas instance release <id> --confirm     # release (two-phase; destroys cloud resources)
+```
+
+Keys come from Zero over TLS and are stored in the keyring; output shows only fingerprints. Unlike `pxbaas login`, `pxbaas provision` is safe for agents to run. One instance = one profile (`source: zero`); select with `pxbaas profile use` or `--profile`.
+
+### Webapp demos (edge-function sandbox)
+
+```bash
+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)
+```
+
+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
+
+```bash
+pxbaas skill install --host qoder --json   # install the bundled pxbaas-cli Agent Skill
+pxbaas skill install --all --dry-run       # preview for every detected host
+pxbaas skill list                          # show install state per host
+pxbaas skill remove --host qoder --confirm # remove (only baas-managed dirs)
+```
+
+Installs into supported Agent hosts (`~/.qoder`, `~/.claude`, `~/.cursor`, `~/.qwen`, `~/.hermes`); fail-closed on foreign directories. When an Agent host is detected but the skill is missing, any `pxbaas` command prints a one-time hint on stderr (skipped under `--json`, silenced with `BAAS_NO_SKILL_HINT=1`). The CLI never writes into agent directories on npm install.
+
+## Security Principles
+
+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**: `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
+
+- Repository & monorepo docs: <https://github.com/polardbx/mysql-supabase> (`cli/` directory)
+- Design documents: `mysql_supbase_design/supabase_cli/spcli/` in the repository (capability scope, engineering organization, test design, delivery plan)
+
+## License
+
+MIT

package/bin/pxbaas.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Import and run the CLI
+import(join(__dirname, '..', 'dist', 'main.js')).catch((err) => {
+  console.error('Failed to start CLI:', err);
+  process.exit(1);
+});

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

@@ -0,0 +1,61 @@
+/**
+ * Preflight guardrails for `pxbaas app deploy`.
+ *
+ * These checks encode the edge-function sandbox constraints (see doc 02 and the
+ * sandbox webapp evaluation): 5-function quota, no root-absolute asset refs
+ * (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;
+}
+export interface PreflightResult {
+    quota: QuotaCheck;
+    rootAbsoluteRefs: string[];
+    publicReachable: boolean;
+    warnings: string[];
+    blockers: string[];
+}
+/** Detect root-absolute references that would escape the /functions/v1/ prefix. */
+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, 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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,115 @@
+/**
+ * Preflight guardrails for `pxbaas app deploy`.
+ *
+ * These checks encode the edge-function sandbox constraints (see doc 02 and the
+ * sandbox webapp evaluation): 5-function quota, no root-absolute asset refs
+ * (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 = [
+        /(href|src|action)\s*=\s*["']\/(?!\/)[^"']*["']/gi,
+        /fetch\(\s*["'`]\/(?!\/)[^"'`]*["'`]/gi,
+        /url\(\s*\/(?!\/)[^)]*\)/gi,
+    ];
+    const hits = [];
+    for (const re of patterns) {
+        const m = source.match(re);
+        if (m)
+            hits.push(...m);
+    }
+    return hits;
+}
+/** True when the endpoint host is publicly reachable (not loopback / RFC1918). */
+export function isPublicEndpoint(endpoint) {
+    const host = endpoint
+        .replace(/^https?:\/\//, "")
+        .split("/")[0]
+        .split(":")[0]
+        .toLowerCase();
+    if (!host)
+        return false;
+    if (["localhost", "127.0.0.1", "::1", "0.0.0.0"].includes(host))
+        return false;
+    if (/^10\./.test(host))
+        return false;
+    if (/^192\.168\./.test(host))
+        return false;
+    if (/^172\.(1[6-9]|2\d|3[01])\./.test(host))
+        return false;
+    return true;
+}
+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 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, blockers } = quotaFindings(quota);
+    if (!input.entrypointExists) {
+        blockers.push("Entrypoint file not found. Run `pxbaas app new <name>` first.");
+    }
+    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,
+        // but do not double-report it as a preflight warning.
+    }
+    if (!publicReachable) {
+        warnings.push(`Endpoint ${input.endpoint} is not publicly reachable (loopback/private). The share URL will NOT work cross-machine.`);
+    }
+    if (!input.verifyJwt) {
+        warnings.push("verify_jwt=false: the share URL is public and the slug is enumerable. Do not co-locate secrets or sensitive logic in this function.");
+    }
+    const bytes = input.sourceBytes ?? Buffer.byteLength(input.source, "utf8");
+    if (bytes > 1_000_000) {
+        warnings.push(`Single-file bundle is large (${Math.round(bytes / 1024)}KB). Worker memory is limited (~150MB); consider hosting static assets via Storage/CDN instead.`);
+    }
+    return { quota, rootAbsoluteRefs, publicReachable, warnings, blockers };
+}
+//# sourceMappingURL=preflight.js.map