@layers/amba 1.0.1 → 1.1.0

package/dist/project-config.d.ts

@@ -14,3 +14,14 @@ export interface ProjectConfig {
     apiUrl: string;
 }
 export declare function loadProjectConfig(cwd?: string): Promise<ProjectConfig>;
+/**
+ * Parse a `.env`-style file body into a flat string map.
+ *
+ * Lines are trimmed; blank lines and `#`-comments are skipped; lines
+ * without an `=` are skipped. Values may be wrapped in matching single
+ * or double quotes which are stripped on read. Bug fixes should land
+ * here once — both `project-config.ts` (resolves `AMBA_PROJECT_ID`)
+ * and `commands/functions.ts` (loads `.env.local` for the local dev
+ * server) call this.
+ */
+export declare function parseEnv(content: string): Record<string, string>;

package/dist/sandbox.d.ts

@@ -0,0 +1,311 @@
+/**
+ * Headless agentic sandbox bootstrap.
+ *
+ * Implements `amba init --sandbox`: the zero-question, no-browser path
+ * an AI coding agent runs when a developer pastes the homepage prompt:
+ *
+ *     Run `npx @layers/amba init --sandbox` and follow the
+ *     instructions it prints.
+ *
+ * The CLI does everything: synthesize an anonymous email + password,
+ * sign the developer up via the public `/v1/auth/developer/signup`
+ * endpoint (no Bearer needed), pluck the returned PAT + project
+ * credentials, and write them into:
+ *
+ *   - `~/.amba/credentials.json`     (chmod 0600)
+ *   - `<cwd>/.env.local`             (.gitignored — SDK reads it)
+ *   - `<cwd>/AMBA.md`                (markdown context for the agent)
+ *   - every detected MCP client config (`~/.claude.json`,
+ *     `~/.cursor/mcp.json`, `~/.codeium/windsurf/mcp_config.json`,
+ *     plus their project-local equivalents WHEN already present —
+ *     never created from scratch, to avoid cluttering repos)
+ *
+ * The MCP-config merge is non-destructive: an existing `mcpServers.amba`
+ * entry is replaced with the new PAT, but the prior file is copied
+ * aside to `<path>.bak-<unix-ms>` first so a developer who had a real
+ * production PAT wired in can recover. Every other server entry is
+ * preserved. JSON files that already exist but lack an `mcpServers`
+ * key gain one; missing files for the global locations get scaffolded
+ * with a minimal `{ "mcpServers": { "amba": … }}`.
+ *
+ * Similarly, a pre-existing `~/.amba/credentials.json` whose `source`
+ * is not `'sandbox-init'` is backed up to `credentials.json.bak-<ms>`
+ * before the sandbox PAT replaces it. Idempotent re-runs from our own
+ * sandbox session do NOT trigger a backup.
+ *
+ * Provisioning polling: deliberately skipped. The server returns the
+ * project row with `provisioning_status: 'provisioning'` immediately and
+ * the workflow flips it to `'active'` within ~5s. The agent's next SDK
+ * call may briefly retry — fine. Blocking the CLI here would just hide
+ * the same wait behind a different progress indicator.
+ */
+export interface SandboxSignupRequest {
+    email: string;
+    password: string;
+    name?: string;
+}
+/**
+ * Shape returned by `POST /v1/auth/developer/signup`. Only the fields the
+ * sandbox flow actually consumes are typed — the response body has more
+ * (developer row, token expiry, etc.) but we don't need them here.
+ */
+export interface SandboxSignupResponse {
+    pat: string;
+    project_id: string;
+    client_key: string;
+    server_key?: string;
+    api_url: string;
+    /** `'provisioning'` immediately after signup; flips to `'active'` once the workflow finishes. */
+    provisioning_status?: string;
+    /** Email-verification URL — surfaced by the API so we can echo it for upgrade. */
+    verify_url?: string;
+    /** The actual email we used (may be the auto-generated one). */
+    email: string;
+}
+export interface McpClientConfigTarget {
+    /** Display name for logging. */
+    label: string;
+    /** Absolute path on disk. */
+    path: string;
+    /** Whether to create the file if it doesn't exist. Global configs: yes. Project-local: no. */
+    scaffoldIfMissing: boolean;
+}
+export interface SandboxResult {
+    email: string;
+    projectId: string;
+    pat: string;
+    patPreview: string;
+    clientKey: string;
+    /** The exact API URL the signup POST hit. Source of truth for callers. */
+    apiUrl: string;
+    credentialsPath: string;
+    /** Backup of a pre-existing non-sandbox `~/.amba/credentials.json`, or null. */
+    credentialsBackedUpTo: string | null;
+    envLocalPath: string;
+    ambaMdPath: string;
+    /** One record per MCP client config we touched; includes per-file backup info. */
+    mcpConfigsWritten: McpConfigPathResult[];
+    /** Best-guess SDK package for the framework detected in CWD. */
+    sdkPackage: string;
+    framework: string;
+    verifyUrl: string | null;
+    provisioningStatus: string;
+    /**
+     * Absolute path of the `.claude/skills/amba-build/SKILL.md` we wrote
+     * during the sandbox init, or `null` if the skill install was skipped
+     * (e.g. `--no-skills`).
+     */
+    skillPath: string | null;
+}
+/**
+ * Generate a deterministic-looking but globally-unique sandbox email.
+ *
+ * Pattern: `sandbox-<epoch>-<6char>@layers.com`.
+ *
+ * The control DB's `developers` table has a UNIQUE(email) constraint and
+ * a 5-per-minute / 50-per-day per-IP rate limit on signup. Embedding the
+ * epoch + a 6-char nonce keeps the collision probability negligible even
+ * across a herd of CI agents all running `amba init --sandbox` from the
+ * same VPC.
+ *
+ * We use `@layers.com` (not the customer's own domain) because the
+ * sandbox tier is pre-verification — the developer never receives or
+ * actions a verification email for this address. When they want to
+ * upgrade, the CLI prints the verify URL the API returned so they can
+ * claim a real email in the console.
+ */
+export declare function generateSandboxEmail(): string;
+/**
+ * Random URL-safe password. 24 raw bytes → 32 base64url chars; well over
+ * the 8-char minimum the API enforces, with ~192 bits of entropy.
+ *
+ * The password is never shown to the developer or written anywhere — the
+ * PAT is what gets stored. We generate it solely because `POST /signup`
+ * requires it (and demands a non-empty value); a future API change could
+ * accept "agent signup" with no password and we'd drop this entirely.
+ */
+export declare function generateSandboxPassword(): string;
+/**
+ * POST the synthesized credentials at the public signup endpoint.
+ *
+ * No Bearer auth — this is the bootstrap call that mints one. We use
+ * `fetch` directly (not the api-client wrapper) because that wrapper
+ * always resolves a bearer token first, which is exactly what we don't
+ * have yet.
+ *
+ * Returns the unwrapped, flattened shape consumed by the rest of the
+ * sandbox flow. Throws with a human-readable message on any non-2xx so
+ * the CLI's `runAction` wrapper can surface it without crashing on a
+ * generic 'fetch failed'.
+ */
+export declare function performSandboxSignup(req: SandboxSignupRequest, options?: {
+    apiUrl?: string;
+    fetchImpl?: typeof fetch;
+}): Promise<SandboxSignupResponse>;
+/**
+ * Result of writing sandbox credentials. The optional `backedUpTo` lets
+ * the CLI surface a "we moved your existing creds aside" notice so a
+ * developer who accidentally ran `--sandbox` on top of a real OAuth
+ * session can recover.
+ */
+export interface WriteCredentialsResult {
+    path: string;
+    /** Absolute path of the backup file, or null if no backup was made. */
+    backedUpTo: string | null;
+}
+/**
+ * Write the PAT to `~/.amba/credentials.json` (chmod 0600) in a shape
+ * the existing `loadCredentials` reader recognises.
+ *
+ * `auth.ts` was built around browser-OAuth tokens (`access_token` +
+ * `refresh_token` + `expires_at`). PATs are long-lived and don't refresh
+ * — but the stored-creds reader only inspects `access_token`, so we
+ * write the PAT there and leave `refresh_token` empty + a far-future
+ * `expires_at` so the expiry guard never fires.
+ *
+ * Real-credential safety: if the file already exists AND its `source`
+ * is NOT `'sandbox-init'` AND `access_token` is non-empty, we treat it
+ * as a real OAuth/PAT session and back it up to
+ * `credentials.json.bak-<unix-ms>` before overwriting. The next
+ * `--sandbox` run reuses our own previous sandbox creds without
+ * back-up. This keeps the agentic flow idempotent while preventing a
+ * silent clobber of a developer's real account.
+ */
+export declare function writeSandboxCredentials(pat: string, options?: {
+    homeDir?: string;
+}): Promise<WriteCredentialsResult>;
+/**
+ * Write or update `<cwd>/.env.local` with the sandbox project's keys.
+ *
+ * Mirrors the `init` interactive flow exactly so the existing env-read
+ * conventions in the SDKs and CLI commands keep working. The merge
+ * logic: if the file already exists and contains an `AMBA_PROJECT_ID`
+ * line we replace the three Amba lines in place; otherwise we append a
+ * fresh stanza.
+ */
+export declare function writeSandboxEnvLocal(cwd: string, projectId: string, clientKey: string, apiUrl: string): Promise<string>;
+/**
+ * Write the AMBA.md sandbox-tier guide to `<cwd>/AMBA.md`.
+ *
+ * Always overwrites — the file is meant to be regenerated, and the
+ * interactive `init` flow's longer AMBA.md template is replaced here
+ * with a sandbox-specific shorter one (with upgrade instructions).
+ */
+export declare function writeSandboxAmbaMd(cwd: string, ctx: {
+    projectId: string;
+    email: string;
+    verifyUrl: string | null;
+    sdkPackage: string;
+    framework: string;
+    apiUrl: string;
+}): Promise<string>;
+/**
+ * The canonical Amba MCP entry. Used as the value of
+ * `mcpServers.amba` in every detected client config.
+ *
+ * Shape note: Claude Code, Cursor, and Windsurf all read the same
+ * `type` + `url` + `headers` triple. (Windsurf historically also
+ * accepted `serverUrl` — we emit `url` to match the modern shape it
+ * also accepts, and skip emitting the legacy alias to keep the JSON
+ * minimal.)
+ */
+export declare function buildAmbaMcpEntry(pat: string): Record<string, unknown>;
+/**
+ * Identifier for the MCP client family a config file belongs to.
+ * Used by the CLI's done-message to print per-client restart bullets
+ * — and only for clients whose config we actually wrote to.
+ */
+export type McpClientKind = 'claude-code' | 'cursor' | 'windsurf';
+/**
+ * Map an MCP config file path back to its client family. Returns null
+ * for paths that don't match any known config location — defensive
+ * against future additions to `mcpClientTargets`.
+ *
+ * The match is on path tail rather than full equality so the cwd /
+ * homedir-injected variants both classify correctly. We deliberately
+ * accept both global and project-local Claude Code paths
+ * (`.claude.json` and `.mcp.json`) as 'claude-code'.
+ */
+export declare function classifyMcpPath(path: string): McpClientKind | null;
+/**
+ * Reduce a list of written-config paths to the set of unique client
+ * families they belong to. Order: claude-code, cursor, windsurf (so
+ * the done-message renders consistently). Skips unclassified paths
+ * silently.
+ */
+export declare function clientKindsFromPaths(paths: string[]): McpClientKind[];
+/**
+ * The list of MCP client config files we probe. Order matters only for
+ * the printed report.
+ *
+ * Project-local entries are listed but only get touched when the file
+ * already exists in CWD — we don't want to scatter `.mcp.json` /
+ * `.cursor/mcp.json` files into random user repos that have never been
+ * MCP-configured.
+ */
+export declare function mcpClientTargets(cwd: string, options?: {
+    homeDir?: string;
+}): McpClientConfigTarget[];
+/**
+ * Per-target result of an MCP config merge.
+ *
+ * - `path: null` means the target file didn't exist and scaffolding was
+ *   not allowed (project-local targets in unconfigured repos).
+ * - `backedUpTo` is the absolute path of the backup file when an
+ *   existing `mcpServers.amba` entry was present (so a developer who
+ *   had a real PAT wired in can recover); `null` when no backup was
+ *   needed.
+ */
+export interface McpConfigWriteResult {
+    path: string | null;
+    backedUpTo: string | null;
+}
+/**
+ * Merge the `amba` entry into a single client config file.
+ *
+ * Strategy:
+ *   - If the file exists, load + JSON-parse. If parse fails, throw with
+ *     a clear "we won't clobber malformed JSON" error.
+ *   - If the file doesn't exist and scaffolding is allowed, create the
+ *     parent dir and write `{ "mcpServers": { "amba": ... } }`.
+ *   - In all cases, `mcpServers.amba` ends up set; every other
+ *     `mcpServers.*` entry is preserved.
+ *
+ * Real-credential safety: if the existing file ALREADY has a
+ * `mcpServers.amba` entry, we copy the whole file aside to
+ * `<path>.bak-<unix-ms>` BEFORE merging. This protects a developer who
+ * had a real production PAT wired in and then ran `amba init --sandbox`
+ * to "try" the flow. Idempotent re-runs from the same sandbox session
+ * still trigger a backup — cheap, and the developer can `rm *.bak-*`
+ * any time.
+ */
+export declare function mergeMcpConfigFile(target: McpClientConfigTarget, pat: string): Promise<McpConfigWriteResult>;
+/**
+ * Per-target result returned by `writeAllMcpConfigs`. Same shape as
+ * `McpConfigWriteResult` but always carries a non-null `path` (skipped
+ * targets aren't included in the list).
+ */
+export interface McpConfigPathResult {
+    path: string;
+    backedUpTo: string | null;
+}
+/**
+ * Probe every known MCP client location and merge our entry into the
+ * ones that exist (or that are flagged scaffoldIfMissing). Returns one
+ * record per touched file (skipped files are omitted).
+ *
+ * `warn` is invoked (instead of `console.warn`) for per-target errors
+ * so callers using `--json` can route those notices to stderr and keep
+ * stdout machine-parseable.
+ */
+export declare function writeAllMcpConfigs(cwd: string, pat: string, options?: {
+    homeDir?: string;
+    warn?: (msg: string) => void;
+}): Promise<McpConfigPathResult[]>;
+/**
+ * Render the canonical Amba MCP snippet for clients we can't auto-wire
+ * (anything outside the {Claude Code, Cursor, Windsurf} set). Printed by
+ * the CLI when no client configs are detected so the developer at least
+ * has a paste-ready JSON blob.
+ */
+export declare function formatManualMcpSnippet(pat: string): string;

package/dist/skills.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Claude Code skill installer for `amba init --sandbox`.
+ *
+ * Writes a project-local `.claude/skills/amba-build/SKILL.md` file
+ * containing the canonical "/goal" prompt for building a full Expo
+ * app with Amba as the only backend. Two behaviors:
+ *
+ *   1. **Live fetch first.** The skill's runtime instructions tell
+ *      Claude Code to `curl` the live MDX from
+ *      `https://docs.amba.dev/docs/prompts/expo-build.md`. So as long
+ *      as docs is reachable, the agent always uses the latest version.
+ *
+ *   2. **Inlined snapshot fallback.** The same SKILL.md file embeds a
+ *      verbatim copy of the prompt body — captured at CLI install
+ *      time from `@layers/amba-mcp/prompts`. Offline agents (or ones
+ *      whose curl 404s during the docs deploy gap) still get a
+ *      usable prompt.
+ *
+ * Out of scope (per DX-16): Cursor / Windsurf shortcut files. Those
+ * editors don't ingest Claude Code skills; their users paste the
+ * URL directly. The CLI's success line still surfaces the
+ * `/amba-build` command + the docs URL so both audiences are served.
+ *
+ * Project-local install is the default because skills written into
+ * `~/.claude/skills/` are user-global and would persist across
+ * unrelated projects (and accumulate stale copies of the inlined
+ * snapshot from old `amba init` runs). A project-scoped install
+ * disappears when the user `rm -rf`s the project.
+ */
+export interface WriteAmbaBuildSkillOptions {
+    /**
+     * Where to root the `.claude/skills/amba-build/` directory.
+     * Defaults to `cwd` — project-local. Override only in tests (the
+     * production caller never passes anything else).
+     */
+    baseDir?: string;
+}
+export interface WriteAmbaBuildSkillResult {
+    /** Absolute path of the SKILL.md we wrote. */
+    path: string;
+}
+/**
+ * Build the contents of `.claude/skills/amba-build/SKILL.md`.
+ *
+ * Exported as a pure function so the unit tests can assert structural
+ * properties (frontmatter, fetcher block, inlined snapshot fence)
+ * without round-tripping through the filesystem.
+ *
+ * Structure:
+ *   1. YAML frontmatter — `description` so Claude Code's skill
+ *      indexer picks it up.
+ *   2. Skill body — invocation instructions, fetcher one-liner,
+ *      fallback rule.
+ *   3. Inlined snapshot — fenced code block containing the
+ *      EXPO_BUILD_PROMPT_MD body verbatim. The snapshot is bounded
+ *      by a marker comment so a future `amba update-skills` command
+ *      can find and refresh just the inlined region without
+ *      clobbering user customizations above it.
+ */
+export declare function buildAmbaBuildSkillContent(): string;
+/**
+ * Write `.claude/skills/amba-build/SKILL.md` into the target project.
+ *
+ * Always overwrites — the skill file is meant to be regenerated each
+ * time `amba init --sandbox` runs (so the inlined snapshot stays
+ * fresh). Anything the user customized above the snapshot markers
+ * would be lost on a re-init; that's an accepted trade-off for the
+ * agentic single-command flow.
+ *
+ * If a future need for "preserve user edits across re-init" surfaces,
+ * the right shape is a separate `amba update-skills` command that
+ * surgically rewrites the inlined-snapshot region only — leaving the
+ * surrounding text untouched. Out of scope for DX-16.
+ */
+export declare function writeAmbaBuildSkill(options?: WriteAmbaBuildSkillOptions): Promise<WriteAmbaBuildSkillResult>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@layers/amba",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "amba — agent-native backend-as-a-service. Functions, collections, storage, AI, email, queues, sites — one CLI to spin up your project and ship to production. `npx @layers/amba init` to start.",
   "type": "module",
   "bin": {
@@ -46,12 +46,15 @@
   "devDependencies": {
     "@types/node": "^22.10.2",
     "tsdown": "^0.12.5",
-    "typescript": "^5.8.3"
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4",
+    "@layers/amba-mcp": "1.0.1"
   },
   "scripts": {
     "build": "tsdown && tsc --emitDeclarationOnly",
     "dev": "tsdown --watch",
     "typecheck": "tsc --noEmit",
+    "test": "vitest run",
     "clean": "rm -rf dist"
   }
 }