@layers/amba 4.0.4 → 4.1.1

package/dist/ship/config.d.ts

@@ -0,0 +1,98 @@
+/**
+ * `amba ship` config — the typed, hand-validated launch config.
+ *
+ * One file per repo (default `amba.ship.json`) describes how to take this Expo
+ * app from code-complete to live on the App Store and Google Play. It carries
+ * NON-SECRET identifiers and the NAME of the env var holding the Expo token —
+ * never secret values (the App Store Connect `.p8` and Play service-account
+ * JSON live in `eas.json`, owned by the app repo, exactly where the build runs).
+ *
+ * Validation is hand-rolled (the CLI deliberately ships no `zod` — see
+ * `_internal/shared.ts` for the same return-all-errors-at-once pattern). The
+ * field names are the canonical contract; `validateShipConfig` reports every
+ * problem in one pass and enforces the cross-field invariants.
+ *
+ * Monetization is NOT described here: the App Store / Play product catalog is
+ * Amba's monetization control plane (`amba monetization`, the durable Track H
+ * apply against the provider). `ship` only flips `monetization.enabled` to
+ * decide whether to verify that catalog is in sync before building.
+ */
+/** The ordered launch phases. `ship` runs them in this sequence. */
+export declare const SHIP_PHASES: readonly ["preflight", "monetization", "build", "submit", "metadata", "release"];
+export type Phase = (typeof SHIP_PHASES)[number];
+export declare const SHIP_PLATFORMS: readonly ["ios", "android"];
+export type Platform = (typeof SHIP_PLATFORMS)[number];
+/** Google Play release tracks `ship` can submit to. */
+export declare const PLAY_TRACKS: readonly ["internal", "alpha", "beta", "production"];
+export type PlayTrack = (typeof PLAY_TRACKS)[number];
+/** Default config filename when no `--config <path>` is passed. */
+export declare const DEFAULT_SHIP_CONFIG_FILE = "amba.ship.json";
+export interface ShipConfig {
+    /** Schema version of this config file (forward-compatible migrations). */
+    version: number;
+    app: {
+        /** Lowercase key used to scope the per-app launch state file. */
+        slug: string;
+        /** Human-facing app name (App Store / Play display). */
+        name: string;
+        /** Marketing version MAJOR.MINOR.PATCH. */
+        version: string;
+        /** iOS bundle identifier (reverse-DNS). */
+        bundleId: string;
+        /** Android application id (reverse-DNS); may equal bundleId. */
+        androidPackage: string;
+    };
+    build: {
+        /** EAS build profile (a `build.<profile>` key in eas.json), e.g. "production". */
+        profile: string;
+        /** Platforms to build/submit/release. At least one. */
+        platforms: Platform[];
+    };
+    ios: {
+        /**
+         * App Store Connect numeric app id. `null` until the app record exists.
+         * EAS Submit cannot create the record (and under --non-interactive cannot
+         * prompt for it, eas-cli #2418), so `ship` treats a null value as a manual
+         * gate on the submit phase.
+         */
+        ascAppId: string | null;
+    };
+    android: {
+        /** Track the submit phase lands on; release promotes it to production. */
+        track: PlayTrack;
+    };
+    monetization: {
+        /**
+         * When true, `ship` verifies the App Store / Play product catalog is in
+         * sync with the Amba monetization control plane before building, and gates
+         * if it has drifted (run `amba monetization apply`). When false (the
+         * default for apps that don't sell anything), the monetization phase is a
+         * no-op skip.
+         */
+        enabled: boolean;
+    };
+    secrets: {
+        /** NAME of the env var holding the Expo token for non-interactive EAS auth. */
+        expoTokenEnvVar: string;
+    };
+}
+export type ValidateResult = {
+    ok: true;
+    config: ShipConfig;
+} | {
+    ok: false;
+    errors: string[];
+};
+/**
+ * Validate an untrusted parsed JSON value into a typed `ShipConfig`,
+ * collecting EVERY problem (not just the first) so a misconfigured file
+ * surfaces all its issues in one run. Returns the typed config on success.
+ */
+export declare function validateShipConfig(raw: unknown): ValidateResult;
+/**
+ * A starter config written by `amba ship init`. Placeholders are intentionally
+ * obvious so the validator's invariants don't pass on an unedited file's IDs
+ * (the reverse-DNS / semver placeholders DO validate so `--phase preflight`
+ * works immediately; the operator swaps in their real values).
+ */
+export declare function shipConfigTemplate(slug: string): ShipConfig;

package/dist/ship/exec.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The external-command boundary for `amba ship`.
+ *
+ * Every shell-out (always `eas`) goes through an `Executor`, so the phase
+ * logic — which args get built, how `--json` output is parsed, which failures
+ * map to which manual gate — is unit-tested against a fake executor with NO
+ * live cloud, no EAS account, and no Apple/Google credentials. The default
+ * `createNodeExecutor()` is a thin, shell-free wrapper around
+ * `node:child_process.spawn` (mirrors the launch toolkit's `lib/exec`).
+ */
+export interface ExecRunOptions {
+    /** Extra environment variables merged over process.env. */
+    env?: NodeJS.ProcessEnv;
+    /** Working directory for the child. Defaults to process.cwd(). */
+    cwd?: string;
+    /** Hard timeout in ms. On expiry the child is SIGKILLed and the call rejects. */
+    timeoutMs?: number;
+    /** If true, stream child stdout/stderr live to this process. Default false. */
+    stream?: boolean;
+    /** If true, log the command and return a synthetic success WITHOUT running. */
+    dryRun?: boolean;
+}
+export interface ExecResult {
+    /** The redacted command line, for logging / state. */
+    command: string;
+    code: number;
+    stdout: string;
+    stderr: string;
+    /** True when the call was skipped because of dry-run. */
+    dryRun: boolean;
+}
+export interface Executor {
+    /** Run a command. Resolves on exit 0; REJECTS (with an actionable message) otherwise. */
+    run(cmd: string, args: string[], opts?: ExecRunOptions): Promise<ExecResult>;
+}
+/**
+ * Redact secret-shaped tokens from a string before it is logged. A backstop,
+ * not a license — `ship` never puts secret values on a command line (EAS reads
+ * its token from the env and its store creds from eas.json). Covers Expo /
+ * common access-token shapes and `Bearer`/`sk_` prefixes.
+ */
+export declare function redactSecrets(text: string): string;
+/** A backing executor over `node:child_process.spawn`. Never invokes a shell. */
+export declare function createNodeExecutor(globalDryRun?: boolean): Executor;
+/**
+ * Run a command and report success/failure WITHOUT throwing — for read-only
+ * "is this CLI installed/authed?" probes where a non-zero exit is data, not a
+ * fatal error.
+ */
+export declare function probe(exec: Executor, cmd: string, args: string[], opts?: ExecRunOptions): Promise<{
+    ok: boolean;
+    result?: ExecResult;
+}>;

package/dist/ship/orchestrator.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The `amba ship` orchestrator.
+ *
+ * Sequences the requested phases in canonical order, honoring per-app
+ * idempotency state (skip phases already `done` unless `--force`), propagating
+ * a global `--dry-run` to every phase, and stopping the chain at the first gate
+ * or failure (later phases depend on earlier ones — the "clear a gate → re-run"
+ * loop). It owns ALL state writes and the clock; the phase runners stay pure of
+ * both. Returns structured rows for the command layer to render.
+ */
+import type { Phase, Platform, ShipConfig } from './config.js';
+import type { Executor } from './exec.js';
+import { type PhaseRunner } from './phases.js';
+export type RowStatus = 'done' | 'skipped' | 'gate' | 'failed' | 'pending' | 'dry-run';
+export interface ShipRow {
+    phase: Phase;
+    status: RowStatus;
+    detail: string;
+    gates?: string[];
+}
+export interface ShipResult {
+    rows: ShipRow[];
+    /** A gate stopped the chain (human store action needed) — not an error. */
+    blocked: boolean;
+    /** A phase errored. */
+    failed: boolean;
+}
+export interface ShipRunOptions {
+    config: ShipConfig;
+    /** Which phases to run (any subset of SHIP_PHASES). */
+    phases: Phase[];
+    platforms: Platform[];
+    exec: Executor;
+    dryRun: boolean;
+    force: boolean;
+    stateBaseDir?: string;
+    env?: NodeJS.ProcessEnv;
+    now?: () => string;
+    log?: (line: string) => void;
+    sleep?: (ms: number) => Promise<void>;
+    /** Resolve the linked Amba project id (default: from .env.local). */
+    resolveProjectId?: () => Promise<string | null>;
+    /** Admin GET (default: the real api-client). Injected in tests. */
+    adminGet?: <T>(path: string) => Promise<{
+        data: T;
+    }>;
+    /** Phase runners (default: the real registry). Injected in tests. */
+    runners?: Record<Phase, PhaseRunner>;
+    releasePollMs?: number;
+    releaseMaxWaitMs?: number;
+}
+export declare function runShip(opts: ShipRunOptions): Promise<ShipResult>;

package/dist/ship/phases.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The six `amba ship` phases.
+ *
+ * Each runner receives a `ShipContext` (config + an injected `Executor` for
+ * `eas`, an injected admin-API `adminGet`, a project resolver, and state
+ * accessors) and returns a `PhaseOutcome`. The cloud-touching work is all
+ * behind those injection points, so the arg-building, `--json` parsing, and
+ * failure→manual-gate mapping below are unit-tested with no live cloud.
+ *
+ * Honest gates: several launch steps are NOT API-automatable (create the App
+ * Store Connect / Play app record, the Apple Paid-Apps agreement, screenshots,
+ * store review). A runner DETECTS such a step and returns `status: 'gate'` with
+ * the exact action + console URL, rather than pretending it is automated.
+ */
+import type { Executor } from './exec.js';
+import type { Phase, Platform, ShipConfig } from './config.js';
+import type { PhaseStatus } from './state.js';
+export interface ShipContext {
+    config: ShipConfig;
+    exec: Executor;
+    platforms: Platform[];
+    dryRun: boolean;
+    force: boolean;
+    env: NodeJS.ProcessEnv;
+    now: () => string;
+    log: (line: string) => void;
+    /** Read a phase's persisted note (a JSON string) or null. */
+    getNote: (phase: Phase) => string | null;
+    /** Checkpoint a phase's status + note mid-run. No-op under dryRun. */
+    checkpoint: (phase: Phase, status: PhaseStatus, note: string) => void;
+    /** Resolve the linked Amba project id, or null when no project is linked. */
+    resolveProjectId: () => Promise<string | null>;
+    /** GET an admin API path → `{ data }`. */
+    adminGet: <T>(path: string) => Promise<{
+        data: T;
+    }>;
+    /** Sleep helper (injected so release-polling is instant in tests). */
+    sleep: (ms: number) => Promise<void>;
+    /** Build-completion poll cadence (release phase). Small values in tests. */
+    releasePollMs: number;
+    releaseMaxWaitMs: number;
+}
+export interface PhaseOutcome {
+    status: 'done' | 'gate' | 'failed' | 'skipped';
+    detail: string;
+    /** Structured JSON note to persist (build/submit/release maps). */
+    note?: string;
+    /** Human-action items when status === 'gate' (printed prominently). */
+    gates?: string[];
+}
+export type PhaseRunner = (ctx: ShipContext) => Promise<PhaseOutcome>;
+export declare function easBuildArgs(platform: Platform, profile: string): string[];
+export declare function easSubmitArgs(input: {
+    platform: Platform;
+    profile: string;
+    buildId: string | null;
+    track?: string;
+}): string[];
+export declare function easBuildViewArgs(buildId: string): string[];
+export declare function easMetadataArgs(profile: string): string[];
+export interface EasBuild {
+    id: string;
+    status?: string;
+    platform?: string;
+    appVersion?: string;
+    artifacts?: {
+        applicationArchiveUrl?: string;
+        buildUrl?: string;
+    };
+    buildDetailsPageUrl?: string;
+}
+export interface EasSubmission {
+    id?: string;
+    status?: string;
+    platform?: string;
+    buildId?: string;
+    submissionDetailsPageUrl?: string;
+}
+/** Pull the build object for `platform` out of `eas build --json` stdout. */
+export declare function extractBuild(raw: string, platform: Platform): EasBuild;
+export declare function artifactUrlOf(b: EasBuild): string | null;
+/** Parse the submission object for `platform` out of `eas submit --json` stdout. */
+export declare function parseSubmission(raw: string, platform: Platform): EasSubmission;
+export declare function diagnoseBuildFailure(message: string): string;
+/** A submit failure that needs a human store action, or null for a plain error. */
+export declare function diagnoseSubmitGate(platform: Platform, message: string): string | null;
+export declare const PHASE_RUNNERS: Record<Phase, PhaseRunner>;

package/dist/ship/state.d.ts

@@ -0,0 +1,52 @@
+/**
+ * `amba ship` per-app idempotency state.
+ *
+ * Each app's launch progress is a JSON file at `.amba/ship-state/<slug>.json`
+ * recording, per phase, whether it is done / failed / blocked-by-a-human-gate /
+ * in-progress, when, and an optional structured `note` (e.g. the build ids a
+ * later phase reads back). The orchestrator uses it to skip already-done phases
+ * and to resume the "clear a gate → re-run" loop.
+ *
+ * PURITY RULE: this module NEVER reads the clock itself — callers pass an
+ * ISO-8601 timestamp into every mutation so it stays deterministically
+ * testable (the orchestrator owns the clock). The file is purely an
+ * optimization/audit log: deleting it is safe because every phase re-detects
+ * real cloud state before mutating.
+ */
+import type { Phase } from './config.js';
+export type PhaseStatus = 'pending' | 'in-progress' | 'done' | 'failed' | 'gate';
+export interface PhaseRecord {
+    status: PhaseStatus;
+    /** ISO timestamp of the last status change (supplied by the caller). */
+    updatedAt: string;
+    /** Free-form note: build ids, a short reason, etc. NEVER secrets. */
+    note?: string;
+}
+export interface ShipState {
+    slug: string;
+    /** Schema version of this state file (forward-compatible migrations). */
+    stateVersion: 1;
+    /**
+     * The app marketing version the recorded phases shipped. When it changes, the
+     * orchestrator invalidates the binary-scoped phases (build → release) so a
+     * version bump rebuilds instead of skipping a stale `done`.
+     */
+    appVersion?: string;
+    phases: Partial<Record<Phase, PhaseRecord>>;
+}
+/** Path to the state file for a slug, under `<baseDir>/.amba/ship-state/`. */
+export declare function shipStatePath(slug: string, baseDir?: string): string;
+/** Load state for a slug, or a fresh empty state if none exists. Pure read. */
+export declare function loadShipState(slug: string, baseDir?: string): ShipState;
+/** Write state atomically (write temp, then rename) to avoid partial files. */
+export declare function saveShipState(state: ShipState, baseDir?: string): void;
+/**
+ * Return a NEW state with one phase updated. Pure: does not touch disk and does
+ * not read the clock — the caller passes `timestamp`. Use `saveShipState` to
+ * persist.
+ */
+export declare function withPhase(state: ShipState, phase: Phase, status: PhaseStatus, timestamp: string, note?: string): ShipState;
+/** True if a phase is recorded as done. Used by the orchestrator for idempotency. */
+export declare function isPhaseDone(state: ShipState, phase: Phase): boolean;
+/** The record for a phase, or a synthetic pending record if never run. */
+export declare function phaseRecord(state: ShipState, phase: Phase): PhaseRecord;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@layers/amba",
-  "version": "4.0.4",
-  "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.",
+  "version": "4.1.1",
+  "description": "amba — agent-native backend-as-a-service. Functions, collections, storage, AI, email, queues, sites, and `amba ship` to take an Expo app live on the App Store + Google Play. `npx @layers/amba init` to start.",
   "type": "module",
   "bin": {
     "amba": "dist/index.js"

package/skill-bundle/SKILL.md

@@ -176,7 +176,7 @@ For each surface in the confirmed set, read the relevant reference file and exec
 - **gamification** (XP rules, achievements, streaks, leaderboards, challenges) → `references/gamification.md`
 - **economy** (currencies, catalog, stores, inventory) → `references/economy.md`
 - **social** (friends, groups, feeds, messaging, moderation, reviews) → `references/social.md`
-- **infrastructure** (collections / DB tables, functions, analytics, AI prompts) → `references/infrastructure.md`
+- **infrastructure** (collections / relational Postgres tables, functions, analytics, AI prompts) → `references/infrastructure.md`
 
 Each reference file has, in order:
 

package/skill-bundle/references/infrastructure.md

@@ -1,14 +1,14 @@
 # Infrastructure
 
-The plumbing that sits behind every other surface: custom database tables (Collections — schema-first, per-tenant), serverless functions (run server-side code without standing up a backend), analytics (events + sessions), AI prompts (managed LLM templates, callable from the SDK with per-tenant keys), secrets, runtime configs, feature flags, third-party integrations (RevenueCat / Superwall / Resend / Stripe / etc.), media (file storage + CDN), and sites (static asset hosting at `*.app.amba.host`).
+The plumbing that sits behind every other surface: relational Postgres tables (Collections — schema-first, per-tenant), serverless functions (run server-side code without standing up a backend), analytics (events + sessions), AI prompts (managed LLM templates, callable from the SDK with per-tenant keys), secrets, runtime configs, feature flags, third-party integrations (RevenueCat / Superwall / Resend / Stripe / etc.), media (file storage + CDN), and sites (static asset hosting at `*.app.amba.host`).
 
 If gamification, economy, and social are the playable surface, **infrastructure is what you build a custom product on top of**. Anything that doesn't fit the canned surfaces lands here.
 
 ## MCP tools
 
-### Collections (typed tables)
+### Collections (relational Postgres tables)
 
-A collection is a schema-first table inside the project's isolated tenant database. You describe the columns, the server creates the table and any indexes. Rows are scoped to the signed-in `app_user` automatically (server-enforced auto row-level isolation) for SDK clients — admin tools bypass this.
+A collection is a relational Postgres table inside the project's isolated tenant database — typed columns, foreign keys, transactions, unique indexes, and vector search. You describe the columns, the server creates the table and any indexes. Rows are scoped to the signed-in `app_user` automatically (server-enforced auto row-level isolation) for SDK clients — admin tools bypass this.
 
 | Tool | Purpose | Example args |
 | --- | --- | --- |