@layers/amba 1.0.1 → 4.0.2

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,309 @@
+/**
+ * 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
+ * (refresh 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;
+    /**
+     * Developer row returned in `data.developer`. Required for callers
+     * (e.g. `ensureDeveloperIdentity`) to populate the developer_id on
+     * the freshly-minted local credentials without a second round trip
+     * to `/developer/me`.
+     */
+    developer_id: string;
+    /** Developer name, if set on the row. */
+    developer_name?: 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;
+    /**
+     * Per-agent setup-guide fan-out result. One entry per writer that
+     * succeeded. Empty array when `--no-skills` was passed (the same flag
+     * gates both the build-task skill and the cross-agent fan-out — they
+     * write into the same project surfaces and there's no use-case for
+     * skipping one but not the other).
+     */
+    setupTargets: Array<{
+        target: string;
+        path: string;
+        mode: 'created' | 'refreshed';
+    }>;
+}
+/**
+ * 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>;
+/**
+ * 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 Amba lines in place; otherwise we append a
+ * fresh stanza.
+ *
+ * `serverKey` is optional — pass it on the new two-scope credential
+ * model where init mints both client+server. Pre-existing AMBA_SERVER_KEY
+ * lines are refreshed when a new value is provided and removed when
+ * serverKey is null AND no prior line existed (no-op on second case).
+ */
+export declare function writeSandboxEnvLocal(cwd: string, projectId: string, clientKey: string, apiUrl: string, serverKey?: string | null): 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.
+ * Kept around so callers can reason about which agent runtime a given
+ * config path targets — the CLI no longer prints per-client restart
+ * bullets (the new flow frames MCP wiring as "active next agent
+ * launch" rather than asking the developer to restart), but the
+ * classifier is still useful for callers that want to render per-
+ * client labels in their own UI.
+ */
+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/skill-installer.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Amba skill bundle installer.
+ *
+ * The bundled `skill-bundle/` directory contains `SKILL.md` plus a
+ * `references/` folder with one file per Amba surface area. The skill
+ * teaches the agent the classify → confirm → wire-up playbook for
+ * adding Amba primitives to a developer's codebase. See
+ * `packages/cli/skill-bundle/SKILL.md` for the source.
+ *
+ * Why ship a bundled skill (instead of `npx skills add layers/amba`):
+ * the CLI run is the same install step. Bundling avoids a second
+ * fetch, keeps the skill version locked to the CLI version, and means
+ * `amba init` produces a fully-wired agent on offline networks too.
+ *
+ * Cross-agent install — we drop the same body into every detected
+ * coding agent's skill directory. Agents read their own location:
+ *
+ *   - Claude Code:  `.claude/skills/amba/`
+ *   - Cursor:       `.cursor/skills/amba/`
+ *   - Codex CLI:    `.codex/skills/amba/`
+ *   - Windsurf:     `.windsurf/skills/amba/`
+ *
+ * We also write a project-root copy at `.agents/skills/amba/` which
+ * the `npx skills add ...` distribution tool reads from (and which any
+ * agent that pre-registers an `.agents/skills/` lookup picks up). Five
+ * locations, one body — same fan-out pattern `writeAllSetupTargets`
+ * already uses for the legacy setup guide.
+ *
+ * Idempotency: re-running `amba init` overwrites the bundled
+ * `SKILL.md` and `references/*.md` so every developer ends up on the
+ * latest playbook. We back up a pre-existing `SKILL.md` to a sibling
+ * `.bak-<unix-ms>` ONLY when its first frontmatter key (`name:`) is
+ * not `amba` — that's the signal it was hand-authored / unrelated and
+ * shouldn't be silently clobbered. Bundled Amba files are refreshed
+ * without backup.
+ */
+export type SkillInstallTargetKind = 'claude-code' | 'cursor' | 'codex' | 'windsurf' | 'generic-agents';
+export interface SkillInstallTarget {
+    kind: SkillInstallTargetKind;
+    /** Absolute path to the `amba/` directory inside the agent's skill root. */
+    path: string;
+}
+export interface SkillFileWritten {
+    /** Absolute path of the file written. */
+    path: string;
+    /** Backup path when an existing non-Amba SKILL.md was preserved; otherwise null. */
+    backedUpTo: string | null;
+}
+export interface SkillInstallResult {
+    /** Target directory the skill was installed under. */
+    target: SkillInstallTarget;
+    /** Files written this run. */
+    files: SkillFileWritten[];
+}
+/**
+ * Resolve the bundled skill source directory.
+ *
+ * The bundle lives at `<package-root>/skill-bundle/` in both the
+ * source tree and the published tarball (via `files[]` in
+ * `package.json`). From a built `dist/commands/init.js` the path is
+ * `../../skill-bundle/`. From the source tree
+ * (`src/skill-installer.ts`) the path is `../skill-bundle/`. We try
+ * both relative to `import.meta.url` and pick the one that exists.
+ */
+export declare function resolveBundleDir(): Promise<string>;
+/**
+ * List the five install targets the CLI fans out to. Project-local
+ * directories (`<cwd>/.claude/skills/amba/`, etc.) — the agent reads
+ * project-local skills with priority over global ones, so this is the
+ * canonical install location for a tool meant to wire up THIS project.
+ */
+export declare function skillInstallTargets(cwd: string): SkillInstallTarget[];
+/**
+ * Copy SKILL.md + every file under references/ into the target
+ * directory. Creates the directory tree if missing. Returns the list
+ * of files touched and any backup paths.
+ *
+ * Backup rule: a pre-existing `SKILL.md` is backed up to
+ * `SKILL.md.bak-<unix-ms>` ONLY when its first `name:` frontmatter
+ * line is NOT `name: amba`. That's the signal it was authored by the
+ * user for an unrelated purpose and shouldn't be silently overwritten.
+ * Amba-owned files get refreshed without backup so developers
+ * tracking the latest playbook don't accumulate junk.
+ */
+export declare function installSkillBundle(cwd: string, options?: {
+    bundleDir?: string;
+}): Promise<SkillInstallResult[]>;
+/**
+ * Convenience: returns the count of skill files written and the list
+ * of target kinds, for the CLI's done-message summary.
+ */
+export declare function summarizeSkillInstall(results: SkillInstallResult[]): {
+    totalFiles: number;
+    targetKinds: SkillInstallTargetKind[];
+};

package/dist/skills/presets.d.ts

@@ -0,0 +1,146 @@
+/**
+ * App-kind presets for the "Hey Claude, get amba.dev in my app" onboarding.
+ *
+ * The classifier picks one of 10 kinds (9 opinionated + `custom`); the
+ * wire-up engine reads the matching preset to know:
+ *
+ *   - which Amba surface areas to enable (used to scope the docs the
+ *     coding agent pulls into context),
+ *   - which follow-up questions to ask the developer when the preset has
+ *     genuine ambiguity (e.g. friends-vs-global leaderboard scope),
+ *   - the exact MCP tool calls to issue against `mcp.amba.dev` to create
+ *     the starter resources (currencies, achievements, streaks, …),
+ *   - the literal SDK init snippet to paste into the developer's project
+ *     for whichever of the six supported stacks they're on.
+ *
+ * The MCP tool names and argument shapes here MUST match the registered
+ * tools in `packages/mcp/src/tools/*`. The validation surface for that
+ * is the per-tool zod schema; this file is the single source of truth
+ * for "what does Amba install for a fitness app" and lives in the CLI
+ * because the CLI's classifier (Task #3) reads it directly. The MCP
+ * server doesn't import this — its job is to expose the underlying
+ * tools, not to know about preset choices.
+ *
+ * Naming discipline (see CLAUDE.md): no `cf_*` / `neon_*` / `temporal_*`
+ * field names; achievement icons reference customer-replaceable URLs on
+ * the Amba CDN; SDK snippets never name an underlying vendor.
+ */
+/**
+ * The closed set of app kinds the classifier returns. `custom` is the
+ * escape hatch — when the classifier can't confidently pick, the CLI
+ * presents the full surface-area picker instead of applying a preset.
+ */
+export type AppKind = 'fitness' | 'social' | 'marketplace' | 'productivity' | 'education' | 'game' | 'dating' | 'content_creator' | 'ai_chatbot' | 'custom';
+/**
+ * The surface areas (Amba primitives) a preset can opt into.
+ *
+ * `identity` is implicit in every preset — anonymous user provisioning is
+ * a precondition of every other surface — but listing it explicitly in
+ * `surfaces` makes the wire-up output self-describing.
+ */
+export type AmbaSurface = 'identity' | 'xp' | 'streaks' | 'achievements' | 'leaderboards' | 'currencies' | 'catalog' | 'stores' | 'inventory' | 'friendships' | 'groups' | 'feeds' | 'messaging' | 'moderation' | 'reviews' | 'push' | 'content' | 'referrals' | 'deeplinks' | 'segments' | 'onboarding' | 'ai_prompts';
+/** The 6 SDK stacks for which we emit a copy-pasteable init snippet. */
+export type SdkStack = 'expo' | 'reactNative' | 'web' | 'swift' | 'kotlin' | 'flutter';
+export interface FollowUpOption {
+    value: string;
+    label: string;
+    /**
+     * Marks the option the CLI selects by default if the developer accepts
+     * the recommended answer without interaction. Exactly zero or one
+     * option per question carries this flag.
+     */
+    recommended?: boolean;
+}
+export interface FollowUpQuestion {
+    /** The surface the answer mutates. Used by the wire-up engine to route. */
+    surface: AmbaSurface;
+    /**
+     * Stable identifier used to look up the answer in the wire-up engine.
+     * Tied to `WireUpAction.dependsOn` references.
+     */
+    id: string;
+    question: string;
+    options: FollowUpOption[];
+}
+/**
+ * A single MCP tool call the wire-up engine should issue.
+ *
+ * `args` mirrors the tool's zod input schema MINUS `project_id`, which
+ * the engine injects from the active project context — the developer
+ * never passes a project id at this layer.
+ *
+ * `dependsOn` is the id of a follow-up question whose answer mutates
+ * the action (e.g. leaderboard scope drives `metric` / `name`). The
+ * engine reads the answer, applies `whenAnswer` to transform `args`,
+ * and skips the action entirely if `whenAnswer` returns `null`.
+ */
+export interface WireUpAction {
+    tool: string;
+    args: Record<string, unknown>;
+    /**
+     * Optional follow-up dependency. The engine resolves the developer's
+     * answer to `dependsOn.id`, then calls `dependsOn.whenAnswer(value)`
+     * to produce the final args. Returning `null` means "skip this
+     * action for that answer."
+     */
+    dependsOn?: {
+        id: string;
+        whenAnswer: (answer: string) => Record<string, unknown> | null;
+    };
+}
+export interface SdkInitSnippets {
+    /** Expo (managed) — uses `@layers/amba-expo`. */
+    expo: string;
+    /** Bare React Native — uses `@layers/amba-react-native`. */
+    reactNative: string;
+    /** Browser / SSR — uses `@layers/amba-web`. */
+    web: string;
+    /** iOS / macOS / tvOS / watchOS — Swift Package Manager. */
+    swift: string;
+    /** Android — Maven Central artifact `com.layers.amba:amba-sdk-android`. */
+    kotlin: string;
+    /** Flutter / Dart — `amba` on pub.dev. */
+    flutter: string;
+}
+export interface AppKindPreset {
+    kind: AppKind;
+    label: string;
+    description: string;
+    /**
+     * Surfaces to enable. `identity` always appears first — every preset
+     * requires user identity. The order in the array is the order the
+     * wire-up engine renders to the developer (logical, not arbitrary).
+     */
+    surfaces: AmbaSurface[];
+    /**
+     * Genuinely ambiguous choices the developer needs to make. Decisions
+     * with a clear default (e.g. "should we install identity?" — yes,
+     * always) are NOT follow-ups; they're baked into `wireUp.actions`.
+     */
+    followUpQuestions: FollowUpQuestion[];
+    wireUp: {
+        actions: WireUpAction[];
+        sdkInit: SdkInitSnippets;
+    };
+}
+/**
+ * Canonical preset registry. Lookup is by `AppKind`; iteration order is
+ * the order the CLI presents to the developer when classification is
+ * ambiguous and we fall back to a manual menu (alphabetical-ish by
+ * common usage, with `custom` last).
+ */
+export declare const PRESETS: Record<AppKind, AppKindPreset>;
+/**
+ * Ordered list of the 9 non-custom presets. Useful when the CLI
+ * renders the "pick an app type" menu — `custom` is appended by the
+ * caller as the final escape-hatch option.
+ */
+export declare const PRESET_ORDER: readonly AppKind[];
+/**
+ * Type-narrowing helper for the classifier output. Returns the preset
+ * verbatim when the kind is known; the caller is expected to surface a
+ * helpful error if classification produced a value outside the closed
+ * set (the type system blocks that in TypeScript, but the boundary
+ * between classifier-JSON and this module is a runtime trust check).
+ */
+export declare function getPreset(kind: AppKind): AppKindPreset;