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

package/dist/app/templates.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Webapp template resolution & scaffolding for `pxbaas app`.
+ *
+ * Templates ship as package files under `apps/baas/templates/webapp/` (route A,
+ * same as the bundled skill). We resolve the package root by walking up from this
+ * module until we find `templates/webapp/manifest.json`. The standalone single-file
+ * binary does not carry these assets; scaffolding then fails with a clear error.
+ */
+export type AppMode = "spa" | "api" | "mpa" | "webapp";
+export type BackendFramework = "deno" | "hono";
+export interface AppFrontend {
+    root: string;
+    routing: "files";
+    index: string;
+    /** null = static-only; "worker" = static-miss falls through to the worker (SSR). */
+    fallback: null | "worker";
+}
+export interface AppBackend {
+    entrypoint: string;
+    framework: BackendFramework;
+    pathMode: "strip-app-api-prefix";
+    verifyJwt: boolean;
+    secrets: string[];
+    egressPolicy: "deny";
+    /** 方案 C: session delivery. none | proxy-injected | browser-side. */
+    session?: "none" | "proxy-injected" | "browser-side";
+    /**
+     * Optional backend health probe path for `pxbaas app verify` (a mount-relative
+     * logical path such as "/api/health"). When absent, verify checks only the
+     * mount homepage and does NOT probe a fixed backend route.
+     */
+    healthPath?: string;
+}
+export interface TemplateMeta {
+    /** Delivery path: legacy single worker or schemaVersion 2 webapp mount. */
+    delivery: "legacy" | "webapp";
+    /** Rendering model of the delivered app. */
+    render: "static" | "csr" | "ssr" | "headless";
+    /** Frontend stack shipped by the template. */
+    frontend: "none" | "inline" | "html" | "vanilla" | "react" | "static-shell";
+    /** Backend framework inside the worker(s). */
+    backend: "none" | "deno" | "hono";
+    /** Session delivery contract. */
+    session: "none" | "proxy-injected" | "browser-side";
+    /** Ships db/schema.sql + db/rls.json (requires app db-init before deploy). */
+    hasDb: boolean;
+    /** Cold-start weight of the worker's npm import graph. */
+    coldStart: "light" | "moderate" | "heavy";
+    /** Intended role of the template. */
+    purpose: "legacy-demo" | "validation" | "starter" | "reference" | "showcase";
+}
+export interface WebappTemplate {
+    id: string;
+    description: string;
+    entrypoint: string;
+    /**
+     * Machine-readable selection metadata so agents and humans pick templates
+     * by capability instead of guessing from the id (names mix rendering,
+     * stack, session and content axes on purpose-free ids).
+     */
+    meta?: TemplateMeta;
+    /** Deploy mode written into app.json; defaults to the template id (spa/api). */
+    mode?: AppMode;
+    /** Multi-file templates list every file to scaffold; paths may be nested. */
+    files?: string[];
+    /** mpa: the static HTML pages served by path. */
+    pages?: string[];
+    /** mpa: the static assets (css/js/images) served by path. */
+    assets?: string[];
+    /** webapp: prebuilt frontend artifact contract. */
+    frontend?: AppFrontend;
+    /** webapp: optional Deno/Hono backend contract. */
+    backend?: AppBackend | null;
+    /** webapp SSR (DX-2): publish-probe logical path; required when frontend.fallback==="worker". */
+    ssrProbePath?: string;
+    /**
+     * Machine-readable post-scaffold TODOs surfaced by `app new --json` (R2-11):
+     * e.g. database initialization for templates that ship db/schema.sql. The CLI
+     * never auto-runs DDL; these are reminders requiring explicit user action.
+     */
+    nextSteps?: string[];
+}
+export interface AppManifest {
+    schemaVersion?: 1 | 2;
+    name: string;
+    slug: string;
+    template: string;
+    entrypoint: string;
+    verifyJwt: boolean;
+    createdAt: string;
+    /** Legacy spa/api/mpa modes and the v2 webapp mode are both supported. */
+    mode?: AppMode;
+    /** mpa: static HTML pages that must exist and be served by path. */
+    pages?: string[];
+    /** mpa: static assets that must exist and be served by path. */
+    assets?: string[];
+    /** webapp: frontend staging layout. */
+    frontend?: AppFrontend;
+    /** webapp: backend runtime contract; null for static-only apps. */
+    backend?: AppBackend | null;
+    /** Optional SSR publish-probe path (DX-2): logical path returning the SSR page. */
+    ssrProbePath?: string;
+    /** Local deployment state used by lifecycle commands; ignored by the runtime. */
+    deployment?: {
+        mountId: string;
+        candidateFunctionSlug?: string;
+        generation: number;
+    };
+}
+/** Replaced with the exact capability version only in the uploaded candidate. */
+export declare const HONO_VERSION_PLACEHOLDER = "{{HONO_VERSION}}";
+export declare class TemplatesNotFoundError extends Error {
+    constructor(message: string);
+}
+/** Walk up to find the package root holding templates/webapp/manifest.json. */
+export declare function resolveTemplatesRoot(startDir?: string): string | null;
+export declare function resolveTemplatesDir(startDir?: string): string;
+export declare function listTemplates(startDir?: string): Promise<WebappTemplate[]>;
+/**
+ * Synchronous template-id list for CLI help text (command registration is sync).
+ * Returns [] when the bundled templates are unavailable (standalone binary), so
+ * callers can fall back to a generic hint instead of throwing at startup.
+ */
+export declare function listTemplateIdsSync(startDir?: string): string[];
+/** Read a template's entrypoint and substitute {{APP_NAME}} / {{SLUG}}. */
+export declare function renderTemplate(templateId: string, vars: {
+    appName: string;
+    slug: string;
+}, startDir?: string): Promise<{
+    entrypoint: string;
+    source: string;
+}>;
+/**
+ * Resolve a template definition and render every file it declares.
+ *
+ * Single-file templates (spa/api) render just the entrypoint; multi-file
+ * templates (mpa) render each entry in `files` (falling back to the entrypoint).
+ * Returns the template definition plus the rendered `{ name, source }` list.
+ */
+export declare function renderTemplateFiles(templateId: string, vars: {
+    appName: string;
+    slug: string;
+}, startDir?: string): Promise<{
+    template: WebappTemplate;
+    files: Array<{
+        name: string;
+        source: string;
+    }>;
+}>;
+/**
+ * Scaffold a new app under `<dir>/<name>/`: writes the rendered entrypoint and an
+ * `app.json` manifest. Refuses to overwrite an existing entrypoint unless forced.
+ */
+export declare function scaffoldApp(opts: {
+    name: string;
+    slug: string;
+    template: string;
+    dir: string;
+    force?: boolean;
+    startDir?: string;
+}): Promise<{
+    appDir: string;
+    files: string[];
+    manifest: AppManifest;
+    nextSteps: string[];
+}>;
+//# sourceMappingURL=templates.d.ts.map

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

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

package/dist/app/templates.js

@@ -0,0 +1,151 @@
+/**
+ * Webapp template resolution & scaffolding for `pxbaas app`.
+ *
+ * Templates ship as package files under `apps/baas/templates/webapp/` (route A,
+ * same as the bundled skill). We resolve the package root by walking up from this
+ * module until we find `templates/webapp/manifest.json`. The standalone single-file
+ * binary does not carry these assets; scaffolding then fails with a clear error.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/** Replaced with the exact capability version only in the uploaded candidate. */
+export const HONO_VERSION_PLACEHOLDER = "{{HONO_VERSION}}";
+export class TemplatesNotFoundError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "TemplatesNotFoundError";
+    }
+}
+function moduleDir() {
+    return dirname(fileURLToPath(import.meta.url));
+}
+/** Walk up to find the package root holding templates/webapp/manifest.json. */
+export function resolveTemplatesRoot(startDir = moduleDir()) {
+    let dir = startDir;
+    for (let i = 0; i < 8; i++) {
+        if (existsSync(join(dir, "templates", "webapp", "manifest.json")))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+export function resolveTemplatesDir(startDir = moduleDir()) {
+    const root = resolveTemplatesRoot(startDir);
+    if (!root) {
+        throw new TemplatesNotFoundError("Bundled webapp templates not found. `pxbaas app new` requires the npm or source install (the standalone single-file binary does not bundle templates).");
+    }
+    return join(root, "templates", "webapp");
+}
+export async function listTemplates(startDir) {
+    const dir = resolveTemplatesDir(startDir);
+    const manifest = JSON.parse(await readFile(join(dir, "manifest.json"), "utf8"));
+    return manifest.templates ?? [];
+}
+/**
+ * Synchronous template-id list for CLI help text (command registration is sync).
+ * Returns [] when the bundled templates are unavailable (standalone binary), so
+ * callers can fall back to a generic hint instead of throwing at startup.
+ */
+export function listTemplateIdsSync(startDir) {
+    try {
+        const dir = resolveTemplatesDir(startDir);
+        const manifest = JSON.parse(readFileSync(join(dir, "manifest.json"), "utf8"));
+        return (manifest.templates ?? []).map((t) => t.id);
+    }
+    catch {
+        return [];
+    }
+}
+/** Read a template's entrypoint and substitute {{APP_NAME}} / {{SLUG}}. */
+export async function renderTemplate(templateId, vars, startDir) {
+    const dir = resolveTemplatesDir(startDir);
+    const templates = await listTemplates(startDir);
+    const tpl = templates.find((t) => t.id === templateId);
+    if (!tpl) {
+        throw new Error(`Unknown template '${templateId}'. Available: ${templates.map((t) => t.id).join(", ")}.`);
+    }
+    const raw = await readFile(join(dir, templateId, tpl.entrypoint), "utf8");
+    const source = substitute(raw, vars);
+    return { entrypoint: tpl.entrypoint, source };
+}
+function substitute(raw, vars) {
+    return raw
+        .replace(/\{\{APP_NAME\}\}/g, vars.appName)
+        .replace(/\{\{SLUG\}\}/g, vars.slug);
+}
+/**
+ * Resolve a template definition and render every file it declares.
+ *
+ * Single-file templates (spa/api) render just the entrypoint; multi-file
+ * templates (mpa) render each entry in `files` (falling back to the entrypoint).
+ * Returns the template definition plus the rendered `{ name, source }` list.
+ */
+export async function renderTemplateFiles(templateId, vars, startDir) {
+    const dir = resolveTemplatesDir(startDir);
+    const templates = await listTemplates(startDir);
+    const tpl = templates.find((t) => t.id === templateId);
+    if (!tpl) {
+        throw new Error(`Unknown template '${templateId}'. Available: ${templates.map((t) => t.id).join(", ")}.`);
+    }
+    const names = tpl.files && tpl.files.length > 0 ? tpl.files : [tpl.entrypoint];
+    const files = [];
+    for (const name of names) {
+        const raw = await readFile(join(dir, templateId, name), "utf8");
+        files.push({ name, source: substitute(raw, vars) });
+    }
+    return { template: tpl, files };
+}
+/**
+ * Scaffold a new app under `<dir>/<name>/`: writes the rendered entrypoint and an
+ * `app.json` manifest. Refuses to overwrite an existing entrypoint unless forced.
+ */
+export async function scaffoldApp(opts) {
+    const appDir = join(opts.dir, opts.name);
+    const { template, files } = await renderTemplateFiles(opts.template, { appName: opts.name, slug: opts.slug }, opts.startDir);
+    const entrypoint = template.entrypoint;
+    const entryPath = join(appDir, entrypoint);
+    const manifestPath = join(appDir, "app.json");
+    if ((existsSync(entryPath) || existsSync(manifestPath)) && !opts.force) {
+        throw new Error(`${appDir} already exists and contains an app scaffold. Pass --force to overwrite.`);
+    }
+    await mkdir(appDir, { recursive: true });
+    const written = [];
+    for (const f of files) {
+        const target = join(appDir, f.name);
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(target, f.source, "utf8");
+        written.push(f.name);
+    }
+    const mode = template.mode ?? template.id;
+    const manifest = {
+        ...(mode === "webapp" ? { schemaVersion: 2 } : {}),
+        name: opts.name,
+        slug: opts.slug,
+        template: opts.template,
+        entrypoint,
+        verifyJwt: template.backend?.verifyJwt ?? false,
+        createdAt: new Date().toISOString(),
+        mode,
+    };
+    if (mode === "mpa") {
+        manifest.pages = template.pages ?? [];
+        manifest.assets = template.assets ?? [];
+    }
+    if (mode === "webapp") {
+        manifest.frontend = template.frontend;
+        manifest.backend = template.backend ?? null;
+        // Carry the SSR publish-probe path so fallback="worker" templates survive
+        // scaffold -> deploy (R2-01); spec-lint requires it and the platform probe
+        // contract depends on it.
+        if (template.ssrProbePath)
+            manifest.ssrProbePath = template.ssrProbePath;
+    }
+    await writeFile(manifestPath, JSON.stringify(manifest, null, 2) + "\n", "utf8");
+    return { appDir, files: [...written, "app.json"], manifest, nextSteps: template.nextSteps ?? [] };
+}
+//# sourceMappingURL=templates.js.map

package/dist/app/templates.js.map

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

package/dist/cli/help-guides.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Agent-facing best-practice guides appended to `--help` output.
+ *
+ * Purpose: a coding agent that only knows "install pxbaas and deploy an app"
+ * must be able to discover the full recommended workflow from the CLI itself.
+ * These strings are flow-level only (command names, ordering, safety lines);
+ * the authoritative runtime/spec details stay in the bundled skills so the
+ * help text cannot drift into a stale manual.
+ *
+ * Help printing never runs action hooks, so both guides are readable without
+ * a profile, credentials, or network access.
+ */
+/** Short pointer appended to the top-level `pxbaas --help`. */
+export declare const TOP_LEVEL_AGENT_GUIDE = "\nDevelop and deploy an app with pxbaas?\n  Run 'pxbaas guide' for the recommended end-to-end workflow\n  (skills, instance, capabilities, code, build, init, deploy, verify, share).\n";
+/** Full recommended workflow printed by `pxbaas guide`. */
+export declare const WORKFLOW_GUIDE = "\nRECOMMENDED WORKFLOW (humans and coding agents)\n\n1. Load the bundled skills\n   pxbaas skill install --host <agent-id>                  # user scope (default)\n   pxbaas skill install --host <agent-id> --scope project  # repo-local, travels with code\n   user ids: qoder|claude|cursor|qwen|hermes|codex|gemini|copilot|qwenworkcn|agents\n   project ids add: trae|codebuddy|cline; other hosts: --dir <skills-dir>\n   Read pxbaas-cli/SKILL.md and pxbaas-app-spec/SKILL.md. They define the command\n   surface, runtime contract, templates and deploy rules. Use <command> --help for\n   exact syntax; never invent flags.\n\n2. Bind an instance (agents must not run 'pxbaas login'; it needs a TTY)\n   pxbaas profile ls --json\n   pxbaas profile import <env-file> --name <profile> --json     # env file from the user\n   pxbaas provision --name <profile> --json                     # only with user approval\n   Multi-tenant instance: never deploy into the default or shared tenant and\n   never use global keys. With my explicit approval, read DASHBOARD_USERNAME /\n   DASHBOARD_PASSWORD only from my env file, pipe them via stdin (never echo),\n   and create one isolated tenant bound to a fresh profile:\n   printf '%s\\n%s\\n' \"$DASHBOARD_USERNAME\" \"$DASHBOARD_PASSWORD\" | \\\n     pxbaas tenant login --endpoint <endpoint> --user-stdin --password-stdin --json\n   pxbaas tenant create --generate-id --dry-run --json          # preview first\n   pxbaas tenant create --generate-id --yes --as-profile --json # after approval\n   Continue every later step with that new tenant profile. Without dashboard\n   credentials: ask the operator for a tenant access file; never reuse an\n   existing tenant or its keys.\n   pxbaas --profile <profile> doctor --json                     # require 0 fail first\n\n3. Check instance capabilities before writing code\n   pxbaas --profile <profile> app capabilities --json\n   Confirm schemaVersion 2 webapp delivery, Deno/Hono support and the SSR library\n   allow-list. Unsupported requirement: stop and report; do not downgrade silently.\n\n4. Scaffold and implement inside the spec\n   pxbaas app templates --json\n   Pick by each template's meta (delivery/render/frontend/backend/session/\n   hasDb/coldStart); spa|api|mpa are legacy workers, not webapps.\n   pxbaas app new <name> --template <id> --dir <apps-dir> --json\n   Follow pxbaas-app-spec: prebuilt frontend only, Deno backend, no outbound egress,\n   no credentials in code or artifacts. Build the frontend when the template needs it.\n\n5. Preview database changes, then get one scoped approval\n   pxbaas --profile <profile> app db-init <name> --dir <apps-dir> --dry-run --json\n   Table names are fixed by the template: a new app name does not isolate data. Stop\n   on unrelated existing tables. After approval:\n   pxbaas --profile <profile> app db-init <name> --dir <apps-dir> --yes --json\n\n6. Preflight, then deploy\n   pxbaas --profile <profile> app deploy <name> --dir <apps-dir> --dry-run --json\n   pxbaas --profile <profile> app deploy <name> --dir <apps-dir> --json\n\n7. Recover by stage, never by restarting everything\n   Upload ok but publish timed out (APP_SSR_PROBE_FAILED): retry the SAME candidate,\n   max 3 times, 10s apart: pxbaas app publish <name> --dir <apps-dir> --json\n   APP_MOUNT_CONFLICT: recover the real mount id from this run's output or local\n   state; adopt/destroy only with explicit approval. Never guess ids or generations.\n\n8. Verify and deliver\n   pxbaas --profile <profile> app verify <name> --dir <apps-dir> --json\n   pxbaas --profile <profile> app url <name> --dir <apps-dir> --json\n   Report the returned URL with its Public/Preview classification. A local HTTP 200\n   does not prove access from other networks.\n   The published URL and any share link (app share create) are gated by the instance\n   IP whitelist, so AFTER publishing or sharing PROACTIVELY ask the user whether the\n   recipient's egress IP must be allowed, then act by instance kind:\n   - Zero trial instance (profile source=zero): offer to append it now \u2014 preview with\n     'pxbaas instance whitelist get --json', then ON APPROVAL\n     'pxbaas instance whitelist add <recipient-ip-or-cidr> --json' (append-only; the\n     add itself must originate from an already-allowed IP).\n   - Purchased/production instance: the CLI cannot edit its whitelist (instance\n     whitelist is Zero-only); remind the user to add the recipient's egress IP via the\n     cloud console / control plane promptly, or the shared URL stays unreachable.\n\nCOMMON FAILURES AND THE ONLY SANCTIONED RESPONSES\n- No active profile or not logged in: bind an instance per step 2; never run\n  'pxbaas login' and never paste keys into chat.\n- doctor fail or expired key: stop and report; do not swap in other\n  credentials or hand-edit the env file.\n- TENANT_CREDENTIAL_GAP on import: the env lacks tenant-level keys; with my\n  approval use the Studio-credential tenant-create chain in step 2, or ask the\n  operator for a tenant access file; never use global keys or the default tenant.\n- 401/403 on data or management calls: wrong role or tenant for this profile;\n  re-check 'pxbaas whoami --json'; do not broaden privileges.\n- APP_CAPABILITY_UNSUPPORTED or a missing ssrLibs entry: this instance cannot\n  run the app shape; stop and report; do not downgrade template or mode.\n- spec-lint blocker: fix the code per the cited pxbaas-app-spec reference;\n  --skip-spec-check is never a fix.\n- Quota blocker, or 429/503 from Zero provisioning: stop; do not loop retries\n  and do not delete functions to free slots without approval.\n- db-init stops on the first error and never rolls back: report which\n  statements completed; do not re-run blindly or hand-write rollback SQL.\n- 409 'Candidate is already active': confirm it is this run's candidate, then\n  treat the publish as success.\n- APP_PUBLISH_CONFLICT (stale generation): stop and reconcile from server\n  state; never guess a generation.\n- 502/503 right after publish: sandbox cold start; retry the read request\n  only, up to 3 times; do not redeploy.\n- Endpoint unreachable or doctor connectivity fail: separate DNS/firewall\n  problems from intranet-only endpoints; re-check with 'pxbaas status --json';\n  import VPC-internal URLs with --intranet; do not hand-edit the endpoint.\n- Zero instance rejects this machine: the instance is IP-whitelisted to the\n  claiming egress IP; run pxbaas on the claiming machine or re-provision with\n  --whitelist-ip; do not treat it as an app defect.\n- Others cannot open the URL while you can: almost always the instance IP whitelist\n  (or Preview exposure). State the limitation; for a Zero instance offer\n  'pxbaas instance whitelist add <their-ip>', for a purchased instance tell the user\n  to add it via the cloud console / control plane. Do not promise public access.\n\nSafety: never print or embed credentials; never use --skip-spec-check; never delete\nor adopt resources to work around a blocker.\n";
+//# sourceMappingURL=help-guides.d.ts.map

package/dist/cli/help-guides.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help-guides.d.ts","sourceRoot":"","sources":["../../src/cli/help-guides.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,+DAA+D;AAC/D,eAAO,MAAM,qBAAqB,4LAIjC,CAAC;AAEF,2DAA2D;AAC3D,eAAO,MAAM,cAAc,m4NA+G1B,CAAC"}

package/dist/cli/help-guides.js

@@ -0,0 +1,132 @@
+/**
+ * Agent-facing best-practice guides appended to `--help` output.
+ *
+ * Purpose: a coding agent that only knows "install pxbaas and deploy an app"
+ * must be able to discover the full recommended workflow from the CLI itself.
+ * These strings are flow-level only (command names, ordering, safety lines);
+ * the authoritative runtime/spec details stay in the bundled skills so the
+ * help text cannot drift into a stale manual.
+ *
+ * Help printing never runs action hooks, so both guides are readable without
+ * a profile, credentials, or network access.
+ */
+/** Short pointer appended to the top-level `pxbaas --help`. */
+export const TOP_LEVEL_AGENT_GUIDE = `
+Develop and deploy an app with pxbaas?
+  Run 'pxbaas guide' for the recommended end-to-end workflow
+  (skills, instance, capabilities, code, build, init, deploy, verify, share).
+`;
+/** Full recommended workflow printed by `pxbaas guide`. */
+export const WORKFLOW_GUIDE = `
+RECOMMENDED WORKFLOW (humans and coding agents)
+
+1. Load the bundled skills
+   pxbaas skill install --host <agent-id>                  # user scope (default)
+   pxbaas skill install --host <agent-id> --scope project  # repo-local, travels with code
+   user ids: qoder|claude|cursor|qwen|hermes|codex|gemini|copilot|qwenworkcn|agents
+   project ids add: trae|codebuddy|cline; other hosts: --dir <skills-dir>
+   Read pxbaas-cli/SKILL.md and pxbaas-app-spec/SKILL.md. They define the command
+   surface, runtime contract, templates and deploy rules. Use <command> --help for
+   exact syntax; never invent flags.
+
+2. Bind an instance (agents must not run 'pxbaas login'; it needs a TTY)
+   pxbaas profile ls --json
+   pxbaas profile import <env-file> --name <profile> --json     # env file from the user
+   pxbaas provision --name <profile> --json                     # only with user approval
+   Multi-tenant instance: never deploy into the default or shared tenant and
+   never use global keys. With my explicit approval, read DASHBOARD_USERNAME /
+   DASHBOARD_PASSWORD only from my env file, pipe them via stdin (never echo),
+   and create one isolated tenant bound to a fresh profile:
+   printf '%s\\n%s\\n' "$DASHBOARD_USERNAME" "$DASHBOARD_PASSWORD" | \\
+     pxbaas tenant login --endpoint <endpoint> --user-stdin --password-stdin --json
+   pxbaas tenant create --generate-id --dry-run --json          # preview first
+   pxbaas tenant create --generate-id --yes --as-profile --json # after approval
+   Continue every later step with that new tenant profile. Without dashboard
+   credentials: ask the operator for a tenant access file; never reuse an
+   existing tenant or its keys.
+   pxbaas --profile <profile> doctor --json                     # require 0 fail first
+
+3. Check instance capabilities before writing code
+   pxbaas --profile <profile> app capabilities --json
+   Confirm schemaVersion 2 webapp delivery, Deno/Hono support and the SSR library
+   allow-list. Unsupported requirement: stop and report; do not downgrade silently.
+
+4. Scaffold and implement inside the spec
+   pxbaas app templates --json
+   Pick by each template's meta (delivery/render/frontend/backend/session/
+   hasDb/coldStart); spa|api|mpa are legacy workers, not webapps.
+   pxbaas app new <name> --template <id> --dir <apps-dir> --json
+   Follow pxbaas-app-spec: prebuilt frontend only, Deno backend, no outbound egress,
+   no credentials in code or artifacts. Build the frontend when the template needs it.
+
+5. Preview database changes, then get one scoped approval
+   pxbaas --profile <profile> app db-init <name> --dir <apps-dir> --dry-run --json
+   Table names are fixed by the template: a new app name does not isolate data. Stop
+   on unrelated existing tables. After approval:
+   pxbaas --profile <profile> app db-init <name> --dir <apps-dir> --yes --json
+
+6. Preflight, then deploy
+   pxbaas --profile <profile> app deploy <name> --dir <apps-dir> --dry-run --json
+   pxbaas --profile <profile> app deploy <name> --dir <apps-dir> --json
+
+7. Recover by stage, never by restarting everything
+   Upload ok but publish timed out (APP_SSR_PROBE_FAILED): retry the SAME candidate,
+   max 3 times, 10s apart: pxbaas app publish <name> --dir <apps-dir> --json
+   APP_MOUNT_CONFLICT: recover the real mount id from this run's output or local
+   state; adopt/destroy only with explicit approval. Never guess ids or generations.
+
+8. Verify and deliver
+   pxbaas --profile <profile> app verify <name> --dir <apps-dir> --json
+   pxbaas --profile <profile> app url <name> --dir <apps-dir> --json
+   Report the returned URL with its Public/Preview classification. A local HTTP 200
+   does not prove access from other networks.
+   The published URL and any share link (app share create) are gated by the instance
+   IP whitelist, so AFTER publishing or sharing PROACTIVELY ask the user whether the
+   recipient's egress IP must be allowed, then act by instance kind:
+   - Zero trial instance (profile source=zero): offer to append it now — preview with
+     'pxbaas instance whitelist get --json', then ON APPROVAL
+     'pxbaas instance whitelist add <recipient-ip-or-cidr> --json' (append-only; the
+     add itself must originate from an already-allowed IP).
+   - Purchased/production instance: the CLI cannot edit its whitelist (instance
+     whitelist is Zero-only); remind the user to add the recipient's egress IP via the
+     cloud console / control plane promptly, or the shared URL stays unreachable.
+
+COMMON FAILURES AND THE ONLY SANCTIONED RESPONSES
+- No active profile or not logged in: bind an instance per step 2; never run
+  'pxbaas login' and never paste keys into chat.
+- doctor fail or expired key: stop and report; do not swap in other
+  credentials or hand-edit the env file.
+- TENANT_CREDENTIAL_GAP on import: the env lacks tenant-level keys; with my
+  approval use the Studio-credential tenant-create chain in step 2, or ask the
+  operator for a tenant access file; never use global keys or the default tenant.
+- 401/403 on data or management calls: wrong role or tenant for this profile;
+  re-check 'pxbaas whoami --json'; do not broaden privileges.
+- APP_CAPABILITY_UNSUPPORTED or a missing ssrLibs entry: this instance cannot
+  run the app shape; stop and report; do not downgrade template or mode.
+- spec-lint blocker: fix the code per the cited pxbaas-app-spec reference;
+  --skip-spec-check is never a fix.
+- Quota blocker, or 429/503 from Zero provisioning: stop; do not loop retries
+  and do not delete functions to free slots without approval.
+- db-init stops on the first error and never rolls back: report which
+  statements completed; do not re-run blindly or hand-write rollback SQL.
+- 409 'Candidate is already active': confirm it is this run's candidate, then
+  treat the publish as success.
+- APP_PUBLISH_CONFLICT (stale generation): stop and reconcile from server
+  state; never guess a generation.
+- 502/503 right after publish: sandbox cold start; retry the read request
+  only, up to 3 times; do not redeploy.
+- Endpoint unreachable or doctor connectivity fail: separate DNS/firewall
+  problems from intranet-only endpoints; re-check with 'pxbaas status --json';
+  import VPC-internal URLs with --intranet; do not hand-edit the endpoint.
+- Zero instance rejects this machine: the instance is IP-whitelisted to the
+  claiming egress IP; run pxbaas on the claiming machine or re-provision with
+  --whitelist-ip; do not treat it as an app defect.
+- Others cannot open the URL while you can: almost always the instance IP whitelist
+  (or Preview exposure). State the limitation; for a Zero instance offer
+  'pxbaas instance whitelist add <their-ip>', for a purchased instance tell the user
+  to add it via the cloud console / control plane. Do not promise public access.
+
+Safety: never print or embed credentials; never use --skip-spec-check; never delete
+or adopt resources to work around a blocker.
+`;
+//# sourceMappingURL=help-guides.js.map

package/dist/cli/help-guides.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"help-guides.js","sourceRoot":"","sources":["../../src/cli/help-guides.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,+DAA+D;AAC/D,MAAM,CAAC,MAAM,qBAAqB,GAAG;;;;CAIpC,CAAC;AAEF,2DAA2D;AAC3D,MAAM,CAAC,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+G7B,CAAC"}

package/dist/cli/root.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function registerCommands(program: Command): void;
+//# sourceMappingURL=root.d.ts.map

package/dist/cli/root.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root.d.ts","sourceRoot":"","sources":["../../src/cli/root.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAmCpC,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAkDvD"}

package/dist/cli/root.js

@@ -0,0 +1,75 @@
+// Import command registrations
+import { registerLoginCommand } from '../commands/login/index.js';
+import { registerLogoutCommand } from '../commands/logout/index.js';
+import { registerWhoamiCommand } from '../commands/whoami/index.js';
+import { registerStatusCommand } from '../commands/status/index.js';
+import { registerDoctorCommand } from '../commands/doctor/index.js';
+import { registerProfileCommand } from '../commands/profile/index.js';
+import { registerDbCommands } from '../commands/db/index.js';
+import { registerGenCommands } from '../commands/gen/index.js';
+import { registerFunctionsCommands } from '../commands/functions/index.js';
+import { registerStorageCommands } from '../commands/storage/index.js';
+import { registerAuthCommands } from '../commands/auth/index.js';
+import { registerDataCommands } from '../commands/data/index.js';
+import { registerRestCommand } from '../commands/rest/index.js';
+import { registerCompletionCommand } from '../commands/completion/index.js';
+import { registerSkillCommands } from '../commands/skill/index.js';
+import { registerGuideCommand } from '../commands/guide/index.js';
+import { registerInstanceCommands } from '../commands/instance/index.js';
+import { registerAppCommands } from '../commands/app/index.js';
+import { registerTenantCommands } from '../commands/tenant/index.js';
+import { maybePrintSkillHint, maybePrintProvisionHint } from '../skill/hint.js';
+/** Build the invoked command path (e.g. "db query") from an action command. */
+function commandPath(program, actionCommand) {
+    const parts = [];
+    let c = actionCommand;
+    while (c && c !== program && c.name()) {
+        parts.unshift(c.name());
+        c = c.parent;
+    }
+    return parts.join(' ');
+}
+export function registerCommands(program) {
+    // First-run nudge: surface `pxbaas skill install` once when an Agent host is
+    // detected but the skill is not installed yet. Never blocks the command.
+    program.hook('preAction', async (_thisCommand, actionCommand) => {
+        try {
+            const path = commandPath(program, actionCommand);
+            const json = program.opts().json;
+            await maybePrintProvisionHint({ json, commandPath: path });
+            await maybePrintSkillHint({ json, commandPath: path });
+        }
+        catch {
+            // cosmetic only — ignore
+        }
+    });
+    // Phase 1 (M2): Onboarding & diagnostics
+    registerLoginCommand(program);
+    registerLogoutCommand(program);
+    registerWhoamiCommand(program);
+    registerStatusCommand(program);
+    registerDoctorCommand(program);
+    registerProfileCommand(program);
+    // Phase 1 (M3): Database & types
+    registerDbCommands(program);
+    registerGenCommands(program);
+    // Phase 2 (M4): Functions & storage
+    registerFunctionsCommands(program);
+    registerStorageCommands(program);
+    registerCompletionCommand(program);
+    // Phase 3 (M5): Auth users, data ops, REST passthrough
+    registerAuthCommands(program);
+    registerDataCommands(program);
+    registerRestCommand(program);
+    // Tooling: install the bundled Agent Skill into supported hosts (offline)
+    registerSkillCommands(program);
+    // Best practice: printable end-to-end develop/deploy/verify/share workflow
+    registerGuideCommand(program);
+    // Onboarding: claim/manage disposable Zero BaaS instances
+    registerInstanceCommands(program);
+    // Webapp demos: scaffold/deploy/verify on edge functions
+    registerAppCommands(program);
+    // Platform-operator tenant management + dashboard credentials (multi-tenant)
+    registerTenantCommands(program);
+}
+//# sourceMappingURL=root.js.map

package/dist/cli/root.js.map

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

package/dist/commands/app/index.d.ts

@@ -0,0 +1,8 @@
+import { Command } from "commander";
+/**
+ * `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 declare function registerAppCommands(program: Command): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/commands/app/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/app/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAuDpC;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAqQ1D"}