@layers/amba 1.0.0 → 1.1.0

package/README.md

@@ -1,13 +1,11 @@
-# `@layers/amba` — the amba CLI
+# @layers/amba
 
-amba is an agent-native backend-as-a-service for mobile apps: functions,
-collections, storage, AI gateway, queues, and static sites — one CLI,
-per-tenant Postgres + edge runtime.
+Amba is the agent-native backend-as-a-service for mobile and web apps. This package is the `amba` command-line interface.
 
 ## Install
 
 ```bash
-npm install -g @layers/amba
+npm install -g @layers/amba@1.0.1
 ```
 
 …or run on demand:
@@ -16,40 +14,65 @@ npm install -g @layers/amba
 npx @layers/amba init
 ```
 
-## Quick start
+Requires Node.js 22 or newer.
+
+## Agent mode (recommended)
+
+For AI coding agents (Claude Code, Cursor, Windsurf): one command, no
+browser, no prompts.
 
 ```bash
-amba init                  # mint a personal dev project and scaffold context
-amba login                 # authenticate (browser flow)
-amba projects list         # list projects you own
-amba projects create --name my-app
+npx @layers/amba init --sandbox
+```
+
+This signs up an agent-mode developer account, provisions a project,
+writes `.env.local` + `AMBA.md`, auto-wires `mcpServers.amba` into
+every MCP client config it finds on disk, and installs the
+`/amba-build` Claude Code skill at `.claude/skills/amba-build/SKILL.md`.
+
+After restarting your MCP client, paste:
+
+```
+/amba-build <design-url-or-description>
+```
+
+…to scaffold a full Expo app with Amba as the only backend. The skill
+fetches the canonical prompt from
+<https://docs.amba.dev/docs/prompts/expo-build> at invocation time and
+falls back to an inlined snapshot when offline. Use `--no-skills` to
+skip the skill install.
+
+## Configure + first call
+
+```bash
+amba init              # mint a personal project and write .amba/ config
+amba login             # browser-based auth (skip with --token / AMBA_PAT)
+amba projects list
+```
+
+Track your first event from the CLI:
+
+```bash
+amba events track app_opened --prop source=cli
 ```
 
 ## Common commands
 
 ```bash
 amba functions deploy ./functions/hello.ts
-amba functions list
-amba functions schedule hello "0 * * * *" --tz UTC
-
 amba collections create messages --field user_id:uuid --field body:text
-amba collections list
-amba types generate                # emit .amba/types.d.ts
-
+amba types generate                       # emits .amba/types.d.ts
 amba secrets set OPENAI_KEY --function hello --from-stdin
-
 amba sites deploy ./out --name marketing
-amba sites domain add marketing.example.com --site marketing
 ```
 
 ## Headless / CI
 
-Pass a personal access token via `--token <pat>` or the `AMBA_PAT` env
-var to skip the browser-based login flow.
+Pass a Personal Access Token via `--token <pat>` or `AMBA_PAT` to skip the browser login.
 
-## Requirements
+## Docs
 
-- Node.js 22+
+Full reference: <https://docs.amba.dev/cli>.
 
 ## License
 

package/dist/api-client.d.ts

@@ -245,16 +245,16 @@ export interface FunctionDeploymentRow {
     project_id: string;
     name: string;
     version: number;
-    cf_script_name: string;
-    cf_dispatch_namespace: string;
+    runtime_script_name: string;
+    runtime_namespace: string;
     bundle_sha: string;
     status: 'active' | 'superseded' | 'disabled';
     created_at: string;
 }
 export declare function recordFunctionDeployment(projectId: string, input: {
     name: string;
-    cf_script_name: string;
-    cf_dispatch_namespace: string;
+    runtime_script_name: string;
+    runtime_namespace: string;
     bundle_sha: string;
     /**
      * Optional declarative rate-limit. The CLI passes a validated
@@ -298,13 +298,6 @@ export interface FunctionDeployContext {
      * step skips the storage binding in that case.
      */
     r2_bucket_name: string | null;
-    /**
-     * Cloudflare Hyperdrive config id. NULL until storage provisioning
-     * completes; deploy step skips the Hyperdrive binding when null and
-     * `ctx.collections` returns `tenant_unavailable` until the column is
-     * populated.
-     */
-    cf_hyperdrive_config_id: string | null;
 }
 export declare function getFunctionDispatchNamespace(projectId: string): Promise<ApiResponse<FunctionDeployContext>>;
 export interface InternalCredentialsResponse {
@@ -548,7 +541,7 @@ export interface SiteRow {
     id: string;
     project_id: string;
     name: string;
-    cf_pages_project_name: string;
+    slug: string;
     status: 'active' | 'disabled' | 'archived';
     created_at: string;
     updated_at: string;
@@ -557,7 +550,7 @@ export interface SiteDomainRow {
     id: string;
     site_id: string;
     hostname: string;
-    cf_hostname_id: string | null;
+    provider_hostname_id: string | null;
     cert_status: 'pending_validation' | 'pending_issuance' | 'pending_deployment' | 'active' | 'error';
     created_at: string;
     updated_at: string;
@@ -589,18 +582,18 @@ export declare function archiveSite(projectId: string, name: string, confirm: st
 /** Cascade summary returned by site/function delete proxies. */
 export interface DeleteCascadeSummary {
     domains_removed?: number;
-    cf_pages_project_deleted?: boolean;
-    cf_dispatch_script_deleted?: boolean;
+    site_runtime_removed?: boolean;
+    runtime_script_removed?: boolean;
     function_deployments_marked_disabled?: number;
 }
 /**
  * Add a custom domain to a site. The server-side proxy registers the
- * custom hostname, persists the resulting `cf_hostname_id`, and returns
+ * custom hostname, persists the resulting `provider_hostname_id`, and returns
  * the CNAME target the customer should point their DNS at.
  */
 export declare function addSiteDomainViaApi(projectId: string, siteName: string, hostname: string): Promise<ApiResponse<{
     hostname: string;
-    cf_hostname_id: string;
+    provider_hostname_id: string;
     cert_status: SiteDomainRow["cert_status"];
     dns_target: string;
     created_at: string;
@@ -615,10 +608,10 @@ export declare function removeSiteDomainViaApi(projectId: string, siteName: stri
     deleted: true;
 }>>;
 /**
- * Roll a live CF Pages deployment back to a prior `deployment_id`. CF's
- * rollback creates a NEW deployment that serves the prior bundle (git-
- * revert semantics, not git-reset), so the response shape mirrors
- * `DeploySiteResult` and the new `deployment_id` is what's now live.
+ * Roll a live deployment back to a prior `deployment_id`. Rollback creates
+ * a NEW deployment that serves the prior bundle (git-revert semantics,
+ * not git-reset), so the response shape mirrors `DeploySiteResult` and
+ * the new `deployment_id` is what's now live.
  */
 export declare function rollbackSiteViaApi(projectId: string, siteName: string, deploymentId: string): Promise<ApiResponse<DeploySiteResult>>;
 /**
@@ -650,12 +643,12 @@ export declare function deleteFunctionViaApi(projectId: string, functionName: st
 }>>;
 export declare function attachSiteDomain(projectId: string, siteName: string, input: {
     hostname: string;
-    cf_hostname_id?: string;
+    provider_hostname_id?: string;
 }): Promise<ApiResponse<SiteDomainRow>>;
 export declare function listSiteDomains(projectId: string, siteName: string): Promise<ApiListResponse<SiteDomainRow>>;
 export declare function updateSiteDomain(projectId: string, siteName: string, hostname: string, patch: {
     cert_status: SiteDomainRow['cert_status'];
-    cf_hostname_id?: string;
+    provider_hostname_id?: string;
 }): Promise<ApiResponse<SiteDomainRow>>;
 export declare function detachSiteDomain(projectId: string, siteName: string, hostname: string): Promise<ApiResponse<{
     deleted: boolean;

package/dist/commands/functions.d.ts

@@ -32,11 +32,36 @@ export declare function functionsDeleteCommand(name: string, options?: {
 export declare function functionsScheduleCommand(name: string, cron: string, options?: {
     tz?: string;
 }): Promise<void>;
+export interface DevOptions {
+    /** Local port. Default 8787 (overridable per project). */
+    port?: number;
+    /** Don't watch the file for changes. Default false. */
+    noWatch?: boolean;
+}
 /**
- * `amba functions dev` — not configured in this release. Use
- * `amba functions deploy <file>` to deploy via the platform API.
+ * `amba functions dev <file>` — run the function locally with file-change
+ * hot reload.
+ *
+ * Architecture: the CLI process owns the file watcher + bundler; the
+ * actual HTTP server lives in a child Node process that imports the
+ * bundle and binds to the user's port. On file change, the parent kills
+ * the child, writes a fresh bundle, and respawns. This bounds memory
+ * (each rebuild = fresh V8 heap) and isolates customer-handler crashes
+ * from the CLI. Brief downtime per rebuild (~100ms while the port is
+ * released and re-bound); incoming connections during the swap queue
+ * at the TCP listen backlog and complete once the new child is up.
+ *
+ * The bundler is the same esbuild pipeline `amba functions deploy` uses
+ * — externalization rules, size cap, and source-map handling are
+ * identical so dev → prod parity is automatic.
+ *
+ * Handler shape: `export default async function (req: Request): Promise<Response>`.
+ * `.env.local` values in the customer's working directory are passed
+ * through to the child process so the handler can read them via
+ * `process.env.MY_KEY`. Existing values in the parent's env take
+ * priority (so `MY_KEY=x amba functions dev …` wins).
  */
-export declare function functionsDevCommand(_entryPoint: string): Promise<void>;
+export declare function functionsDevCommand(entryPoint: string, options?: DevOptions): Promise<void>;
 /**
  * `amba functions consume <queue> <function>` — bind a function as the
  * consumer for a queue. Customers send to a queue with `ctx.queue.send`;

package/dist/commands/init.d.ts

@@ -1,3 +1,4 @@
+import { type SandboxResult } from '../sandbox.js';
 export interface InitOptions {
     withExample?: boolean;
     /**
@@ -8,5 +9,73 @@ export interface InitOptions {
      * minted via `amba projects create --env production` by automation).
      */
     env?: 'development' | 'production';
+    /**
+     * Headless agentic mode. Skips browser auth + interactive prompts:
+     * the CLI generates a sandbox email + password, posts to
+     * `/v1/auth/developer/signup`, writes credentials everywhere
+     * (`~/.amba/credentials.json` + `.env.local` + `AMBA.md`), and
+     * auto-wires the Amba MCP server into every detected MCP client
+     * config. Designed to be invoked unattended by an AI coding agent
+     * that pasted the homepage 3-line prompt.
+     */
+    sandbox?: boolean;
+    /** Override the auto-generated sandbox email. Only meaningful with `--sandbox`. */
+    sandboxEmail?: string;
+    /** Skip MCP-client-config writes. Mostly for testing. */
+    noMcpConfig?: boolean;
+    /**
+     * Skip installing the `/amba-build` Claude Code skill into
+     * `.claude/skills/amba-build/SKILL.md`. Default behavior (when
+     * `--sandbox` is on) is to install the skill — pass `--no-skills`
+     * to opt out (e.g. in a CI run that doesn't want stray files).
+     */
+    noSkills?: boolean;
+    /** Emit a machine-readable JSON summary instead of human-readable lines. */
+    json?: boolean;
+    /** Override `~/` resolution. Test seam — production code never sets this. */
+    homeDir?: string;
 }
 export declare function initCommand(options?: InitOptions): Promise<void>;
+export declare function runSandboxInit(cwd: string, options: {
+    sandboxEmail?: string;
+    noMcpConfig?: boolean;
+    /**
+     * Skip the project-local `/amba-build` Claude Code skill install.
+     * Default is to install (the skill is what makes the agentic
+     * "/amba-build <design>" invocation work). Set true in CI or
+     * during tests that don't want stray files written into the
+     * caller's CWD.
+     */
+    noSkills?: boolean;
+    json?: boolean;
+    /**
+     * Override `~/` resolution. The CLI itself never passes this — it's
+     * the seam tests use to avoid touching the developer's actual home
+     * directory. (vi.spyOn can't intercept `os.homedir` under ESM, so
+     * dependency injection is the cleanest substitute.)
+     */
+    homeDir?: string;
+}): Promise<SandboxResult>;
+/**
+ * Build the plaintext (no ANSI) success-output block printed at the
+ * end of `amba init --sandbox`. Pure function — exported only for the
+ * vitest cases that assert on per-line content. The CLI wraps each
+ * line with picocolors in `printSandboxNextSteps` below.
+ *
+ * Structure (in order):
+ *   1. Per-artifact checklist (`✓ ...` lines)
+ *   2. SDK install + configure hint
+ *   3. "Done." + per-client restart bullets — ONLY for clients we
+ *      actually wrote configs to. Never instruct the user to "restart
+ *      Cursor" if we only touched `~/.claude.json`. When no config
+ *      was written (manual-paste path), falls back to a generic
+ *      "quit + reopen" line.
+ *   4. Tail-line resume hint + sandbox limits + verify URL.
+ *
+ * We intentionally do NOT print any "kill -HUP / SIGHUP" advanced
+ * workaround. Telling the agent to surface a clean "restart your MCP
+ * client" instruction to the human is the whole optimization — adding
+ * an experimental fallback just dilutes the signal and risks the
+ * agent surfacing the workaround instead.
+ */
+export declare function buildSandboxNextStepsLines(r: SandboxResult): string[];