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

package/README.md

@@ -1,3 +1,108 @@
-# 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
+```
+
+Every command accepts `--json` for machine-readable output, and `--profile <name>` to select a profile per invocation (`pxbaas profile list / use / import` manage them).
+
+## 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>`, `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 ...` |
+| Storage | `storage ls / cp / mv / rm` |
+| Auth admin | `auth users list / create / invite` |
+| Codegen | `gen types` (TypeScript types from the live schema) |
+| Tooling | `skill install / list / remove`, `completion <shell>` |
+
+### 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 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` 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.
+
+### 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**: destructive writes support `--plan` / `--confirm`.
+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/preflight.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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 interface QuotaCheck {
+    used: number;
+    limit: number;
+    ok: boolean;
+    near: boolean;
+}
+export interface PreflightInput {
+    source: string;
+    endpoint: string;
+    functionsCount: number;
+    quotaLimit?: number;
+    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): QuotaCheck;
+/** 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,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"}

package/dist/app/preflight.js

@@ -0,0 +1,79 @@
+/**
+ * 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).
+ */
+/** 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 = 5) {
+    return { used, limit, ok: used < limit, near: used === limit - 1 };
+}
+/** Run all preflight checks and collect warnings/blockers. */
+export function runPreflight(input) {
+    const quota = checkQuota(input.functionsCount, input.quotaLimit ?? 5);
+    const rootAbsoluteRefs = scanRootAbsoluteRefs(input.source);
+    const publicReachable = isPublicEndpoint(input.endpoint);
+    const warnings = [];
+    const blockers = [];
+    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,
+        // 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

package/dist/app/preflight.js.map

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

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

@@ -0,0 +1,45 @@
+/** Static compliance checks for legacy edge-function apps and manifest-v2 webapps. */
+import type { BackendFramework } from "./templates.js";
+export type Severity = "blocker" | "warning";
+export interface Finding {
+    rule: string;
+    severity: Severity;
+    message: string;
+    specRef: string;
+}
+export interface SpecLintResult {
+    passed: boolean;
+    blockers: Finding[];
+    warnings: Finding[];
+}
+export interface ArtifactSource {
+    path: string;
+    source: string;
+}
+export interface SpecLintOptions {
+    verifyJwt?: boolean;
+    mode?: string;
+    declaredFiles?: string[];
+    existingFiles?: string[];
+    auxiliarySources?: string[];
+    frontendFiles?: string[];
+    frontendSources?: ArtifactSource[];
+    frontendConfigSource?: string;
+    frontendProjectSources?: string[];
+    requireHashRouter?: boolean;
+    backendSource?: string;
+    backendFramework?: BackendFramework;
+    honoVersion?: string | null;
+    /** Capability ssrLibs: curated SSR renderer allow-list (name@version) (W9/D7). */
+    ssrLibs?: string[];
+    secrets?: string[];
+    egressPolicy?: string;
+    ssrFallback?: boolean;
+    ssrProbePath?: string;
+    backendSession?: string;
+    sessionMode?: string;
+    sessionHeaders?: string[];
+}
+/** Lint source and artifact metadata while preserving legacy spa/api/mpa behavior. */
+export declare function lintAppSource(source: string, options?: SpecLintOptions): SpecLintResult;
+//# sourceMappingURL=spec-lint.d.ts.map

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

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