@alexkroman1/aai-cli 5.5.1 → 5.6.0

package/README.md

@@ -1,6 +1,6 @@
 # @alexkroman1/aai-cli
 
-The `aai` command — scaffold, run, test, and deploy aai voice agents.
+The `aai` command — scaffold, run, test, and publish aai voice agents.
 
 ```sh
 npm i -g @alexkroman1/aai-cli   # or: npx @alexkroman1/aai-cli@latest
@@ -15,7 +15,10 @@ npm i -g @alexkroman1/aai-cli   # or: npx @alexkroman1/aai-cli@latest
 | `aai dev` | Local dev server: loads `agent.ts`, rebuilds on change, serves the browser client (`--port`) |
 | `aai test` | Run the project's vitest suite |
 | `aai build` | Bundle without deploying (type-checks first; `--skipTypecheck` opts out) |
-| `aai deploy` | Bundle and deploy to the platform (uploads `.env` as agent secrets) |
+| `aai list` | List your studio projects |
+| `aai pull <project>` | Pull a studio project into a local directory, ready for `aai dev` |
+| `aai push` | Sync this project's source to its studio workspace (fast-forward-checked; `--force` overwrites) |
+| `aai publish` | Push, then deploy to production — the studio's Publish button from the terminal (`.env` syncs as agent secrets) |
 | `aai delete` | Remove a deployed agent |
 | `aai secret put\|delete\|list` | Manage a deployed agent's secrets |
 | `aai storage status\|enable\|disable` | Manage the agent's opt-in SQL database (`ctx.db`) |
@@ -30,16 +33,22 @@ aai init my-agent --template pizza-ordering
 cd my-agent
 # put ASSEMBLYAI_API_KEY=... in .env
 aai dev            # talk to it at the printed URL
-aai deploy         # ship it; .env values become the agent's secrets
+aai publish        # ship it; .env values become the agent's secrets
 ```
 
-Deploys type-check the project, preflight required credentials (a missing
-provider key fails the deploy instead of the first call), and print the
-agent's public URL.
+Every published agent is also a **studio project**: publishing prints a
+studio link where the same source can be edited in the browser (with the
+coding agent), and `aai pull` brings those edits back to your machine.
+`push`/`pull` are fast-forward-only — an edit made in the studio since your
+last pull surfaces as a conflict instead of being overwritten.
+
+Publishes type-check the project locally, then build and deploy inside the
+project's sandbox — byte-for-byte the studio's Publish path — preflight
+required credentials, and print the agent's public URL.
 
 ## Notes
 
-- A bare `aai` in a project directory offers to deploy (TTY-confirmed);
+- A bare `aai` in a project directory offers to publish (TTY-confirmed);
   outside one it runs `init`.
 - `--server <url>` targets a self-hosted platform; the origin is remembered
   in your user config after explicit approval.

package/dist/{_agent-DMyOab9_.mjs → _agent-BB1ZaZsX.mjs}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as readProjectConfig, i as readGlobalConfig, n as ensureApiKey, o as serverOrigin, t as approveServer } from "./_config-5AEqhh-O.mjs";
+import { a as readProjectConfig, i as readGlobalConfig, n as ensureApiKey, o as serverOrigin, t as approveServer } from "./_config-PIC0nzRu.mjs";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -83,8 +83,8 @@ async function resolveDeployTarget(cwd, explicitServer) {
 /** Like resolveDeployTarget, but requires an existing deployment (project config). */
 async function getServerInfo(cwd, explicitServer) {
 	const { config, serverUrl, apiKey } = await resolveDeployTarget(cwd, explicitServer);
-	if (!config) throw new Error("No .aai/project.json found — run `aai deploy` first");
-	if (!VALID_SLUG_RE.test(config.slug)) throw new Error(`Invalid slug in .aai/project.json: ${JSON.stringify(config.slug)}\n  Expected lowercase letters, digits, \`-\`, \`_\` (2-64 chars). Fix the file or run \`aai deploy\` to create a fresh deployment.`);
+	if (!config?.slug) throw new Error("This project has no deployed agent — run `aai publish` first");
+	if (!VALID_SLUG_RE.test(config.slug)) throw new Error(`Invalid slug in .aai/project.json: ${JSON.stringify(config.slug)}\n  Expected lowercase letters, digits, \`-\`, \`_\` (2-64 chars). Fix the file or run \`aai publish\` to create a fresh deployment.`);
 	return {
 		serverUrl,
 		slug: config.slug,

package/dist/_agent.d.ts

@@ -25,8 +25,10 @@ export declare function resolveServerUrl(explicit?: string, configUrl?: string,
  */
 export declare function resolveDeployTarget(cwd: string, explicitServer?: string): Promise<{
     config: {
-        slug: string;
+        slug?: string | undefined;
         serverUrl: string;
+        studioProject?: string | undefined;
+        studioSourceHash?: string | undefined;
     } | null;
     serverUrl: string;
     apiKey: string;

package/dist/{_api-client-MenP4-O7.mjs → _api-client-B6_uvuLs.mjs}

@@ -30,6 +30,7 @@ async function apiRequest(url, opts) {
 			retryDelay: opts.retryDelay ?? 300
 		});
 	} catch (err) {
+		if (opts.allow404 && err instanceof FetchError && err.statusCode === 404) return null;
 		throw toApiError(err, url, opts);
 	}
 }

package/dist/_api-client.d.ts

@@ -28,6 +28,12 @@ export type ApiRequestOptions = {
     retryDelay?: number;
     /** Optional fetch implementation for testing. Defaults to globalThis.fetch. */
     fetch?: typeof globalThis.fetch;
+    /**
+     * Resolve `null` on a 404 instead of throwing — for existence probes
+     * ("is there a studio project with this name?") where absence is an
+     * answer, not a failure.
+     */
+    allow404?: boolean;
 };
 /**
  * Send an authenticated request to the platform API and return the parsed

package/dist/_cli-common.d.ts

@@ -0,0 +1,38 @@
+import { type CommandResult, type OutputMode } from "./_output.ts";
+/** Shared arg definitions for citty commands. */
+export declare const sharedArgs: {
+    readonly server: {
+        readonly type: "string";
+        readonly alias: "s";
+        readonly description: "Platform server URL";
+    };
+    readonly yes: {
+        readonly type: "boolean";
+        readonly alias: "y";
+        readonly description: "Accept defaults (no prompts)";
+    };
+    readonly json: {
+        readonly type: "boolean";
+        readonly description: "Output JSON (auto-detected in non-TTY)";
+    };
+};
+/** Shared command setup: resolve cwd, optionally require agent.ts. */
+export declare function setup(opts?: {
+    agent?: boolean;
+}): Promise<string>;
+/**
+ * Run a command body with standard output-mode resolution, error handling,
+ * and result emission.
+ *
+ * - API key acquisition is owned by `resolveDeployTarget`/`getServerInfo`
+ *   inside the commands that talk to the platform — after the server-trust
+ *   check, so an untrusted `serverUrl` is refused without prompting for a
+ *   key, and commands with no platform traffic never prompt at all.
+ *
+ * A thrown error and a returned `fail(...)` converge here on one emitter:
+ * human mode logs the message, JSON mode writes exactly one result line,
+ * and both exit 1.
+ */
+export declare function runCommand(args: {
+    json?: boolean | undefined;
+}, fn: (mode: OutputMode) => Promise<CommandResult<unknown>>): Promise<void>;

package/dist/{_config-5AEqhh-O.mjs → _config-PIC0nzRu.mjs}

@@ -18,8 +18,17 @@ import { z } from "zod";
 * that isn't an approved http(s) origin.
 */
 const ProjectConfigSchema = z.object({
-	slug: z.string(),
-	serverUrl: z.string()
+	/** Deployed agent slug — absent for a pulled project never published. */
+	slug: z.string().optional(),
+	serverUrl: z.string(),
+	/** Studio project this directory is linked to (`aai pull`/`aai push`). */
+	studioProject: z.string().optional(),
+	/**
+	* The workspace files hash at the last pull/push — `aai push` sends it
+	* back as the fast-forward token, so an edit made in the studio since
+	* then surfaces as a 409 instead of being silently overwritten.
+	*/
+	studioSourceHash: z.string().optional()
 });
 /**
 * Resolve the global config directory (the platform-conventional env-paths
@@ -53,6 +62,23 @@ async function writeProjectConfig(agentDir, data) {
 	await writeJson(path.join(agentDir, ".aai", "project.json"), data);
 }
 /**
+* Merge `patch` into the existing project config rather than replacing the
+* file — a publish recording its `slug` must not drop the studio link
+* fields a pull wrote, and vice versa.
+*/
+async function updateProjectConfig(agentDir, patch) {
+	let existing = null;
+	try {
+		existing = await readProjectConfig(agentDir);
+	} catch {}
+	const merged = {
+		...existing,
+		...patch
+	};
+	await writeProjectConfig(agentDir, merged);
+	return merged;
+}
+/**
 * Origin of `url`, or `null` when it is not an absolute http(s) URL.
 *
 * Non-HTTP schemes are rejected rather than returned: `new URL()` yields the
@@ -121,4 +147,4 @@ async function ensureApiKey(configDir) {
 	return apiKey;
 }
 //#endregion
-export { readProjectConfig as a, writeProjectConfig as c, readGlobalConfig as i, ensureApiKey as n, serverOrigin as o, getConfigDir as r, writeGlobalConfig as s, approveServer as t };
+export { readProjectConfig as a, writeGlobalConfig as c, readGlobalConfig as i, ensureApiKey as n, serverOrigin as o, getConfigDir as r, updateProjectConfig as s, approveServer as t };

package/dist/_config.d.ts

@@ -11,8 +11,10 @@ import { z } from "zod";
  * that isn't an approved http(s) origin.
  */
 declare const ProjectConfigSchema: z.ZodObject<{
-    slug: z.ZodString;
+    slug: z.ZodOptional<z.ZodString>;
     serverUrl: z.ZodString;
+    studioProject: z.ZodOptional<z.ZodString>;
+    studioSourceHash: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 /**
  * Resolve the global config directory (the platform-conventional env-paths
@@ -27,6 +29,12 @@ export declare function getConfigDir(): string;
 export type ProjectConfig = z.infer<typeof ProjectConfigSchema>;
 export declare function readProjectConfig(agentDir: string): Promise<ProjectConfig | null>;
 export declare function writeProjectConfig(agentDir: string, data: ProjectConfig): Promise<void>;
+/**
+ * Merge `patch` into the existing project config rather than replacing the
+ * file — a publish recording its `slug` must not drop the studio link
+ * fields a pull wrote, and vice versa.
+ */
+export declare function updateProjectConfig(agentDir: string, patch: Partial<ProjectConfig> & Pick<ProjectConfig, "serverUrl">): Promise<ProjectConfig>;
 export type GlobalConfig = {
     apiKey?: string;
     /**

package/dist/_deploy.d.ts

@@ -15,6 +15,13 @@ export type DeployOpts = {
      * panel needs a deployed slug to attach secrets to).
      */
     allowMissingSecrets?: boolean;
+    /**
+     * Ask the server to permit a `-preview`-suffixed slug (`aai deploy
+     * --allow-preview-slug`). That suffix is reserved for the studio's
+     * auto-preview deploys — the server rejects it otherwise — and this is set
+     * by the studio's own in-guest deploy, not by ordinary users.
+     */
+    allowPreviewSlug?: boolean;
     /** Retry delay override for tests (0 = no real sleeps on retry paths). */
     retryDelay?: number;
     /** Optional fetch implementation for testing. Defaults to globalThis.fetch. */

package/dist/{_dev-server-vV05Fnki.mjs → _dev-server-CGptLIAm.mjs}

@@ -4,7 +4,7 @@ import { a as errorMessage, r as errorCode } from "./_utils-Ch0J4s6a.mjs";
 import { n as fallbackHtmlPlugin } from "./client-bundler-yiWoXrgb.mjs";
 import { buildWorker } from "./worker-bundler.mjs";
 import { n as createWorkerEvaluator } from "./_bundler-Cjaxa2wi.mjs";
-import { n as ensureApiKey } from "./_config-5AEqhh-O.mjs";
+import { n as ensureApiKey } from "./_config-PIC0nzRu.mjs";
 import { t as resolveServerEnv } from "./_server-common-CnaP_Urf.mjs";
 import { createRequire } from "node:module";
 import { existsSync } from "node:fs";
@@ -44,7 +44,7 @@ function agentEnvWarnings(agentDef, env, shellEnv = process.env) {
 	const missing = required.filter((name) => !(env[name] || shellEnv[name]));
 	if (missing.length > 0) warnings.push(`Missing provider credential${s(missing)}: ${missing.join(", ")}. Set ${them(missing)} in .env or the environment.`);
 	const shellOnly = required.filter((name) => !env[name] && shellEnv[name]);
-	if (shellOnly.length > 0) warnings.push(`${shellOnly.join(", ")} resolved from your shell, not .env — deployed agents won't have ${them(shellOnly)}. Declare ${them(shellOnly)} in .env before \`aai deploy\`.`);
+	if (shellOnly.length > 0) warnings.push(`${shellOnly.join(", ")} resolved from your shell, not .env — deployed agents won't have ${them(shellOnly)}. Declare ${them(shellOnly)} in .env before \`aai publish\`.`);
 	const declared = (agentDef.requiredEnv ?? []).filter((name) => !env[name]);
 	if (declared.length > 0) warnings.push(`Missing requiredEnv key${s(declared)} declared by the agent: ${declared.join(", ")}. Set ${them(declared)} in .env — ctx.env will not contain ${them(declared)} otherwise.`);
 	return warnings;

package/dist/{_init-BZ9t_Kz-.mjs → _init-BPFM4uBH.mjs}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { c as readJson, d as writeJson, s as isEexist } from "./_utils-Ch0J4s6a.mjs";
-import { r as isDevMode, t as getMonorepoRoot } from "./_agent-DMyOab9_.mjs";
-import { REPO_URL, downloadAndMergeTemplate } from "./_templates-Bv8CR800.mjs";
+import { r as isDevMode, t as getMonorepoRoot } from "./_agent-BB1ZaZsX.mjs";
+import { REPO_URL, downloadAndMergeTemplate } from "./_templates-jmjgdgcd.mjs";
 import path from "node:path";
 import fs from "node:fs/promises";
 //#region _init.ts
@@ -15,7 +15,7 @@ A voice agent built with [aai](${REPO_URL}).
 \`\`\`sh
 npm install        # Install dependencies
 aai dev            # Run locally (opens browser)
-aai deploy         # Deploy to production
+aai publish        # Publish to production (and sync to the studio)
 \`\`\`
 
 ## Secrets

package/dist/{_slug-api-DaqQJHk8.mjs → _slug-api-dcaQ_Uho.mjs}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { n as getServerInfo } from "./_agent-DMyOab9_.mjs";
-import { n as apiRequest, t as HINT_NOT_DEPLOYED } from "./_api-client-MenP4-O7.mjs";
+import { n as getServerInfo } from "./_agent-BB1ZaZsX.mjs";
+import { n as apiRequest, t as HINT_NOT_DEPLOYED } from "./_api-client-B6_uvuLs.mjs";
 //#region _slug-api.ts
 /**
 * Authenticated request against a deployed agent's slug-scoped resource

package/dist/_studio-commands.d.ts

@@ -0,0 +1,73 @@
+export declare const list: import("citty").CommandDef<{
+    readonly server: {
+        readonly type: "string";
+        readonly alias: "s";
+        readonly description: "Platform server URL";
+    };
+    readonly json: {
+        readonly type: "boolean";
+        readonly description: "Output JSON (auto-detected in non-TTY)";
+    };
+}>;
+export declare const pull: import("citty").CommandDef<{
+    readonly project: {
+        readonly type: "positional";
+        readonly description: "Studio project name (see `aai list`)";
+        readonly required: true;
+    };
+    readonly dir: {
+        readonly type: "positional";
+        readonly description: "Target directory (default: the project name)";
+        readonly required: false;
+    };
+    readonly force: {
+        readonly type: "boolean";
+        readonly alias: "f";
+        readonly description: "Overwrite files in a non-empty directory";
+    };
+    readonly server: {
+        readonly type: "string";
+        readonly alias: "s";
+        readonly description: "Platform server URL";
+    };
+    readonly json: {
+        readonly type: "boolean";
+        readonly description: "Output JSON (auto-detected in non-TTY)";
+    };
+}>;
+export declare const push: import("citty").CommandDef<{
+    readonly force: {
+        readonly type: "boolean";
+        readonly alias: "f";
+        readonly description: "Overwrite studio-side changes instead of failing the fast-forward check";
+    };
+    readonly server: {
+        readonly type: "string";
+        readonly alias: "s";
+        readonly description: "Platform server URL";
+    };
+    readonly json: {
+        readonly type: "boolean";
+        readonly description: "Output JSON (auto-detected in non-TTY)";
+    };
+}>;
+export declare const publish: import("citty").CommandDef<{
+    readonly force: {
+        readonly type: "boolean";
+        readonly alias: "f";
+        readonly description: "Overwrite studio-side changes instead of failing the fast-forward check";
+    };
+    readonly server: {
+        readonly type: "string";
+        readonly alias: "s";
+        readonly description: "Platform server URL";
+    };
+    readonly json: {
+        readonly type: "boolean";
+        readonly description: "Output JSON (auto-detected in non-TTY)";
+    };
+    readonly skipTypecheck: {
+        readonly type: "boolean";
+        readonly description: "Skip type checking before publishing";
+    };
+}>;

package/dist/_studio.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Internals of the studio-workspace commands (`aai list/pull/push/publish`):
+ * the local source-file walk and the thin clients for the platform's
+ * `/studio/projects` routes. The workspace is the single source of truth —
+ * these helpers only move files between a local directory and the project's
+ * workspace row; production deploys happen exclusively through the studio's
+ * Publish route (which runs the deploy machinery in the project's sandbox).
+ */
+/**
+ * Mirrors of the studio workspace caps (`aai-studio-server/studio-limits.ts`)
+ * — by value, like `aai-guest/limits.ts`, since the CLI cannot depend on the
+ * private server package. The server re-validates every push; these exist so
+ * an oversized file is a named warning locally instead of a rejected upload.
+ */
+export declare const MAX_STUDIO_FILE_BYTES = 256000;
+export declare const MAX_STUDIO_FILES = 100;
+/**
+ * Walk a local project into the path→content record a workspace stores —
+ * the CLI-side twin of the guest's `snapshotWorkspace`: same ignored
+ * directories, same caps, oversized files skipped with a warning rather
+ * than failing the whole push.
+ */
+export declare function collectSourceFiles(dir: string): Promise<{
+    files: Record<string, string>;
+    warnings: string[];
+}>;
+/** A studio project name derived from a directory name, or null if unusable. */
+export declare function projectNameFromDir(dir: string): string | null;
+/** The shareable studio URL for a project — what every command prints. */
+export declare function studioProjectUrl(serverUrl: string, project: string): string;
+/** `GET /studio/projects/:project` — see `projectPayload` server-side. */
+export type StudioProject = {
+    files: Record<string, string>;
+    sourceHash: string;
+    deployedSlug?: string;
+    unpublished?: boolean;
+};
+export declare function listStudioProjects(serverUrl: string, apiKey: string): Promise<string[]>;
+/** Fetch a project, or null when it doesn't exist (the push existence probe). */
+export declare function fetchStudioProject(serverUrl: string, apiKey: string, project: string): Promise<StudioProject | null>;
+/** `PUT /studio/projects/:project/source` — the atomic whole-tree push. */
+export declare function pushStudioSource(serverUrl: string, apiKey: string, project: string, body: {
+    files: Record<string, string>;
+    baseHash?: string | undefined;
+}): Promise<{
+    sourceHash: string;
+    created: boolean;
+}>;
+/** `POST /studio/projects/:project/deploy` — Publish, in the project's sandbox. */
+export declare function publishStudioProject(serverUrl: string, apiKey: string, project: string): Promise<{
+    ok: true;
+    slug: string;
+    url: string;
+    output: string;
+}>;

package/dist/{_templates-Bv8CR800.mjs → _templates-jmjgdgcd.mjs}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { a as errorMessage } from "./_utils-Ch0J4s6a.mjs";
-import { t as getMonorepoRoot } from "./_agent-DMyOab9_.mjs";
+import { t as getMonorepoRoot } from "./_agent-BB1ZaZsX.mjs";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import fs from "node:fs/promises";
@@ -47,6 +47,22 @@ async function listTemplates(root = resolveTemplatesDir()) {
 	return available.filter((e) => e.isDirectory()).map((e) => e.name).sort();
 }
 /**
+* Layer the base scaffold (package.json, tsconfig, …) into targetDir
+* WITHOUT overwriting anything already there. Shared by `aai init`
+* (underneath a template) and `aai pull` (underneath the studio workspace
+* files — the workspace stores source, and the scaffold completes it into a
+* runnable project the same way the guest's `ensureProjectShape` does
+* before an in-sandbox build).
+*/
+async function layerScaffold(targetDir) {
+	const scaffoldDir = path.join(resolveTemplatesDir(), "scaffold");
+	if (existsSync(scaffoldDir)) await fs.cp(scaffoldDir, targetDir, {
+		recursive: true,
+		force: false,
+		errorOnExist: false
+	});
+}
+/**
 * Copy a template into targetDir, merging scaffold files underneath.
 */
 async function downloadAndMergeTemplate(template, targetDir) {
@@ -58,12 +74,7 @@ async function downloadAndMergeTemplate(template, targetDir) {
 		recursive: true,
 		force: true
 	});
-	const scaffoldDir = path.join(root, "scaffold");
-	if (existsSync(scaffoldDir)) await fs.cp(scaffoldDir, targetDir, {
-		recursive: true,
-		force: false,
-		errorOnExist: false
-	});
+	await layerScaffold(targetDir);
 }
 //#endregion
-export { REPO_URL, downloadAndMergeTemplate, listTemplates };
+export { REPO_URL, downloadAndMergeTemplate, layerScaffold, listTemplates };

package/dist/_templates.d.ts

@@ -21,6 +21,15 @@ export declare function bundledTemplatesDir(): string;
  * can never drift.
  */
 export declare function listTemplates(root?: string): Promise<string[]>;
+/**
+ * Layer the base scaffold (package.json, tsconfig, …) into targetDir
+ * WITHOUT overwriting anything already there. Shared by `aai init`
+ * (underneath a template) and `aai pull` (underneath the studio workspace
+ * files — the workspace stores source, and the scaffold completes it into a
+ * runnable project the same way the guest's `ensureProjectShape` does
+ * before an in-sandbox build).
+ */
+export declare function layerScaffold(targetDir: string): Promise<void>;
 /**
  * Copy a template into targetDir, merging scaffold files underneath.
  */

package/dist/{_typecheck-gate-9IHWDnl1.mjs → _typecheck-gate-DvE8S3aQ.mjs}

@@ -14,4 +14,4 @@ async function assertTypechecks(cwd) {
 	if (!result.ok) throw new CliError("typecheck_failed", result.output, "Fix the type errors, or pass --skipTypecheck to build anyway");
 }
 //#endregion
-export { assertTypechecks as t };
+export { assertTypechecks };

package/dist/{build-D_PgQOD4.mjs → build-BXwDB78d.mjs}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { n as log, o as CliError, u as ok } from "./_ui-8kOEB-JH.mjs";
 import { r as evalWorkerBundle, t as buildAgentBundle } from "./_bundler-Cjaxa2wi.mjs";
-import { t as assertTypechecks } from "./_typecheck-gate-9IHWDnl1.mjs";
+import { assertTypechecks } from "./_typecheck-gate-DvE8S3aQ.mjs";
 import { classifyVitestError, runVitest } from "./test-3Gq4pqH_.mjs";
 //#region build.ts
 /**