@alexkroman1/aai-cli 5.3.0 → 5.4.0

package/README.md

@@ -0,0 +1,51 @@
+# @alexkroman1/aai-cli
+
+The `aai` command — scaffold, run, test, and deploy aai voice agents.
+
+```sh
+npm i -g @alexkroman1/aai-cli   # or: npx @alexkroman1/aai-cli@latest
+```
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `aai init [dir]` | Scaffold a new agent project (`--template <name>`, `--yes`) |
+| `aai templates` | List the shipped project templates |
+| `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 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`) |
+
+Every command accepts `--json` for machine-readable output (auto-detected
+when stdout is not a TTY). `aai <command> --help` shows flags.
+
+## Typical flow
+
+```sh
+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
+```
+
+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.
+
+## Notes
+
+- A bare `aai` in a project directory offers to deploy (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.
+- The API key is stored `0600` in your user config dir (`AAI_CONFIG_DIR`
+  overrides the location).
+
+## Documentation
+
+SDK API reference: <https://alexkroman.github.io/agent/>

package/dist/{_bundler-DFS4xxqE.mjs → _bundler-Cjaxa2wi.mjs}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { u as validateAgentExport } from "./_utils-Ch0J4s6a.mjs";
-import { t as buildClient } from "./client-bundler-BWDkUeEP.mjs";
+import { t as buildClient } from "./client-bundler-yiWoXrgb.mjs";
 import { buildWorker } from "./worker-bundler.mjs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";

package/dist/{_dev-server-BBUWo0sb.mjs → _dev-server-cigzayJe.mjs}

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 import { n as log } from "./_ui-8kOEB-JH.mjs";
 import { a as errorMessage, r as errorCode } from "./_utils-Ch0J4s6a.mjs";
-import { n as fallbackHtmlPlugin } from "./client-bundler-BWDkUeEP.mjs";
+import { n as fallbackHtmlPlugin } from "./client-bundler-yiWoXrgb.mjs";
 import { buildWorker } from "./worker-bundler.mjs";
-import { n as createWorkerEvaluator } from "./_bundler-DFS4xxqE.mjs";
+import { n as createWorkerEvaluator } from "./_bundler-Cjaxa2wi.mjs";
 import { n as ensureApiKey } from "./_config-D3F9km8X.mjs";
 import { t as resolveServerEnv } from "./_server-common-CnaP_Urf.mjs";
 import { createRequire } from "node:module";

package/dist/{_init-DU-sXH6S.mjs → _init-_G8l4lh2.mjs}

@@ -1,62 +1,9 @@
 #!/usr/bin/env node
-import { a as errorMessage, c as readJson, d as writeJson, s as isEexist } from "./_utils-Ch0J4s6a.mjs";
+import { c as readJson, d as writeJson, s as isEexist } from "./_utils-Ch0J4s6a.mjs";
 import { r as isDevMode, t as getMonorepoRoot } from "./_agent-D8zBb3M5.mjs";
-import { existsSync } from "node:fs";
+import { REPO_URL, downloadAndMergeTemplate } from "./_templates-DW9CvuDN.mjs";
 import path from "node:path";
 import fs from "node:fs/promises";
-const REPO_URL = `https://github.com/alexkroman/agent`;
-/**
-* Templates as shipped inside the published tarball, copied into `dist/` by
-* `bundle-templates.mjs` at build time — so this resolves to `dist/` for a
-* published CLI and to the (template-less) package root when running source
-* in the monorepo, where the branch above wins.
-*
-* They used to be fetched at `init` time with giget from
-* `github:alexkroman/agent/packages/aai-templates#main`. That required a
-* network for every `init`, and pinned templates to `main` regardless of the
-* CLI version the user had installed, so a template written against a newer
-* SDK could land in a project resolving an older one. Bundling pins the two
-* together by construction. It also puts the templates inside the studio's
-* guest sandbox, which has the CLI in its baked toolchain but no way to fetch
-* anything from GitHub.
-*/
-function bundledTemplatesDir() {
-	return import.meta.dirname;
-}
-/** Resolve the templates root — env override, then monorepo, then bundled. */
-function resolveTemplatesDir() {
-	const override = process.env.AAI_TEMPLATES_DIR;
-	if (override) return override;
-	const monorepoRoot = getMonorepoRoot();
-	if (monorepoRoot) return path.join(monorepoRoot, "packages", "aai-templates");
-	return bundledTemplatesDir();
-}
-/**
-* Copy a template into targetDir, merging scaffold files underneath.
-*/
-async function downloadAndMergeTemplate(template, targetDir) {
-	const root = resolveTemplatesDir();
-	const templatesDir = path.join(root, "templates");
-	let available;
-	try {
-		available = await fs.readdir(templatesDir, { withFileTypes: true });
-	} catch (err) {
-		throw new Error(`Templates directory is missing or unreadable at ${templatesDir} (incomplete @alexkroman1/aai-cli install?): ${errorMessage(err)}`, { cause: err });
-	}
-	const names = available.filter((e) => e.isDirectory()).map((e) => e.name);
-	if (!names.includes(template)) throw new Error(`Unknown template "${template}". Available templates: ${names.join(", ")}`);
-	await fs.cp(path.join(templatesDir, 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
-	});
-}
-//#endregion
 //#region _init.ts
 function readmeContent(slug) {
 	return `# ${slug}

package/dist/_templates-DW9CvuDN.mjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+import { a as errorMessage } from "./_utils-Ch0J4s6a.mjs";
+import { t as getMonorepoRoot } from "./_agent-D8zBb3M5.mjs";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import fs from "node:fs/promises";
+const REPO_URL = `https://github.com/alexkroman/agent`;
+/**
+* Templates as shipped inside the published tarball, copied into `dist/` by
+* `bundle-templates.mjs` at build time — so this resolves to `dist/` for a
+* published CLI and to the (template-less) package root when running source
+* in the monorepo, where the branch above wins.
+*
+* They used to be fetched at `init` time with giget from
+* `github:alexkroman/agent/packages/aai-templates#main`. That required a
+* network for every `init`, and pinned templates to `main` regardless of the
+* CLI version the user had installed, so a template written against a newer
+* SDK could land in a project resolving an older one. Bundling pins the two
+* together by construction. It also puts the templates inside the studio's
+* guest sandbox, which has the CLI in its baked toolchain but no way to fetch
+* anything from GitHub.
+*/
+function bundledTemplatesDir() {
+	return import.meta.dirname;
+}
+/** Resolve the templates root — env override, then monorepo, then bundled. */
+function resolveTemplatesDir() {
+	const override = process.env.AAI_TEMPLATES_DIR;
+	if (override) return override;
+	const monorepoRoot = getMonorepoRoot();
+	if (monorepoRoot) return path.join(monorepoRoot, "packages", "aai-templates");
+	return bundledTemplatesDir();
+}
+/**
+* List the shipped template names (sorted). Backs `aai templates` and the
+* unknown-template error, so the discoverable list and the validated list
+* can never drift.
+*/
+async function listTemplates(root = resolveTemplatesDir()) {
+	const templatesDir = path.join(root, "templates");
+	let available;
+	try {
+		available = await fs.readdir(templatesDir, { withFileTypes: true });
+	} catch (err) {
+		throw new Error(`Templates directory is missing or unreadable at ${templatesDir} (incomplete @alexkroman1/aai-cli install?): ${errorMessage(err)}`, { cause: err });
+	}
+	return available.filter((e) => e.isDirectory()).map((e) => e.name).sort();
+}
+/**
+* Copy a template into targetDir, merging scaffold files underneath.
+*/
+async function downloadAndMergeTemplate(template, targetDir) {
+	const root = resolveTemplatesDir();
+	const templatesDir = path.join(root, "templates");
+	const names = await listTemplates(root);
+	if (!names.includes(template)) throw new Error(`Unknown template "${template}". Available templates: ${names.join(", ")}`);
+	await fs.cp(path.join(templatesDir, 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
+	});
+}
+//#endregion
+export { REPO_URL, downloadAndMergeTemplate, listTemplates };

package/dist/_templates.d.ts

@@ -15,6 +15,12 @@ export declare const REPO_URL = "https://github.com/alexkroman/agent";
  * anything from GitHub.
  */
 export declare function bundledTemplatesDir(): string;
+/**
+ * List the shipped template names (sorted). Backs `aai templates` and the
+ * unknown-template error, so the discoverable list and the validated list
+ * can never drift.
+ */
+export declare function listTemplates(root?: string): Promise<string[]>;
 /**
  * Copy a template into targetDir, merging scaffold files underneath.
  */

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

@@ -1,6 +1,6 @@
 #!/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-DFS4xxqE.mjs";
+import { r as evalWorkerBundle, t as buildAgentBundle } from "./_bundler-Cjaxa2wi.mjs";
 import { t as assertTypechecks } from "./_typecheck-gate-9IHWDnl1.mjs";
 import { classifyVitestError, runVitest } from "./test-3Gq4pqH_.mjs";
 //#region build.ts

package/dist/cli.mjs

@@ -68,7 +68,10 @@ async function runCommand(args, fn) {
 	} catch (err) {
 		const code = err instanceof CliError ? err.code : "command_failed";
 		const hint = err instanceof CliError ? err.hint : void 0;
-		if (mode === "human") log.error(errorMessage(err));
+		if (mode === "human") {
+			log.error(errorMessage(err));
+			if (hint) log.info(hint);
+		}
 		result = fail(code, errorMessage(err), hint);
 	}
 	if (mode === "json") await writeLine(`${JSON.stringify(result)}\n`);
@@ -93,7 +96,7 @@ const init = defineCommand({
 		template: {
 			type: "string",
 			alias: "t",
-			description: "Template to use (e.g. pizza-ordering)"
+			description: "Template to use (run `aai templates` for the list)"
 		},
 		server: sharedArgs.server,
 		yes: sharedArgs.yes,
@@ -105,7 +108,7 @@ const init = defineCommand({
 	},
 	async run({ args }) {
 		await runCommand(args, async (mode) => {
-			const { executeInit } = await import("./init-BjeK8crW.mjs");
+			const { executeInit } = await import("./init-BkW9BuZF.mjs");
 			return executeInit({
 				dir: args.dir,
 				force: args.force,
@@ -134,7 +137,7 @@ const dev = defineCommand({
 	async run({ args }) {
 		await runCommand(args, async () => {
 			const cwd = await setup({ agent: true });
-			const { executeDev } = await import("./dev-g7sGt8qX.mjs");
+			const { executeDev } = await import("./dev-2oUsvgRX.mjs");
 			return executeDev({
 				cwd,
 				port: args.port
@@ -175,7 +178,7 @@ const build = defineCommand({
 	async run({ args }) {
 		await runCommand(args, async () => {
 			const cwd = await setup({ agent: true });
-			const { executeBuild } = await import("./build-Xq1xxoSg.mjs");
+			const { executeBuild } = await import("./build-D_PgQOD4.mjs");
 			return executeBuild({
 				cwd,
 				skipTests: args.skipTests,
@@ -204,7 +207,7 @@ const deploy = defineCommand({
 	async run({ args }) {
 		await runCommand(args, async () => {
 			const cwd = await setup({ agent: true });
-			const { executeDeploy } = await import("./deploy-Ci0X1gp2.mjs");
+			const { executeDeploy } = await import("./deploy-C0VLnnJe.mjs");
 			return executeDeploy({
 				cwd,
 				server: args.server,
@@ -318,7 +321,7 @@ const storageDir = {
 const storage = defineCommand({
 	meta: {
 		name: "storage",
-		description: "Manage the agent's database (storage)"
+		description: "Manage the agent's app database"
 	},
 	subCommands: {
 		status: defineCommand({
@@ -341,7 +344,7 @@ const storage = defineCommand({
 		enable: defineCommand({
 			meta: {
 				name: "enable",
-				description: "Enable the agent's database (storage)"
+				description: "Enable the agent's app database"
 			},
 			args: {
 				dir: storageDir,
@@ -358,7 +361,7 @@ const storage = defineCommand({
 		disable: defineCommand({
 			meta: {
 				name: "disable",
-				description: "Disable storage (DROPS the database schema and all its data)"
+				description: "Disable storage and DROP the database schema with all its data"
 			},
 			args: {
 				dir: storageDir,
@@ -382,6 +385,27 @@ const storage = defineCommand({
 		})
 	}
 });
+const templates = defineCommand({
+	meta: {
+		name: "templates",
+		description: "List available project templates"
+	},
+	args: { json: sharedArgs.json },
+	async run({ args }) {
+		await runCommand(args, async (mode) => {
+			const { listTemplates } = await import("./_templates-DW9CvuDN.mjs");
+			const names = await listTemplates();
+			if (mode === "human") {
+				for (const name of names) log.message(name);
+				log.info("Scaffold one with `aai init --template <name>`.");
+			}
+			return {
+				ok: true,
+				data: { templates: names }
+			};
+		});
+	}
+});
 const mainCommand = defineCommand({
 	meta: {
 		name: "aai",
@@ -396,7 +420,8 @@ const mainCommand = defineCommand({
 		deploy,
 		delete: del,
 		secret,
-		storage
+		storage,
+		templates
 	}
 });
 if (process.env.VITEST !== "true") {

package/dist/{client-bundler-BWDkUeEP.mjs → client-bundler-yiWoXrgb.mjs}

@@ -95,6 +95,9 @@ const DEDUPED_PEERS = ["react", "react-dom"];
 * Build the client SPA with Vite if `client.tsx` exists.
 * Returns a map of relative file paths to string contents for deploy,
 * or `{}` when the project has no `client.tsx`.
+*
+* @internal — build hook for aai-server/the studio; not a supported public
+* API and not covered by semver.
 */
 async function buildClient(cwd, opts = {}) {
 	if (!await fileExists(path.join(cwd, "client.tsx"))) return {};

package/dist/client-bundler.d.ts

@@ -1,4 +1,10 @@
 import { type PluginOption } from "vite";
+/**
+ * Options for client SPA bundling.
+ *
+ * @internal — build hook for aai-server/the studio; not a supported public
+ * API and not covered by semver.
+ */
 export type BuildClientOptions = {
     /**
      * Plugins to inject instead of relying on the project's `vite.config.ts`
@@ -17,5 +23,8 @@ export type BuildClientOptions = {
  * Build the client SPA with Vite if `client.tsx` exists.
  * Returns a map of relative file paths to string contents for deploy,
  * or `{}` when the project has no `client.tsx`.
+ *
+ * @internal — build hook for aai-server/the studio; not a supported public
+ * API and not covered by semver.
  */
 export declare function buildClient(cwd: string, opts?: BuildClientOptions): Promise<Record<string, string>>;

package/dist/client-bundler.mjs

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-import { t as buildClient } from "./client-bundler-BWDkUeEP.mjs";
+import { t as buildClient } from "./client-bundler-yiWoXrgb.mjs";
 export { buildClient };

package/dist/{deploy-Ci0X1gp2.mjs → deploy-C0VLnnJe.mjs}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { n as log, t as fmtUrl, u as ok } from "./_ui-8kOEB-JH.mjs";
 import { a as errorMessage } from "./_utils-Ch0J4s6a.mjs";
-import { t as buildAgentBundle } from "./_bundler-DFS4xxqE.mjs";
+import { t as buildAgentBundle } from "./_bundler-Cjaxa2wi.mjs";
 import { o as writeProjectConfig } from "./_config-D3F9km8X.mjs";
 import { t as resolveServerEnv } from "./_server-common-CnaP_Urf.mjs";
 import { i as resolveDeployTarget } from "./_agent-D8zBb3M5.mjs";

package/dist/{dev-g7sGt8qX.mjs → dev-2oUsvgRX.mjs}

@@ -11,7 +11,7 @@ import { styleText } from "node:util";
 async function executeDev(opts) {
 	const port = parsePort(opts.port);
 	const agentName = path.basename(path.resolve(opts.cwd));
-	const { startDevServer } = await import("./_dev-server-BBUWo0sb.mjs");
+	const { startDevServer } = await import("./_dev-server-cigzayJe.mjs");
 	let cleanup;
 	let shuttingDown = false;
 	const onSignal = () => {

package/dist/{init-BjeK8crW.mjs → init-BkW9BuZF.mjs}

@@ -74,7 +74,7 @@ function resolveTargetDir(dir) {
 }
 /** Run deploy after init and return deploy metadata if successful. */
 async function tryDeploy(cwd, server) {
-	const { executeDeploy } = await import("./deploy-Ci0X1gp2.mjs");
+	const { executeDeploy } = await import("./deploy-C0VLnnJe.mjs");
 	try {
 		const result = await executeDeploy({
 			cwd,
@@ -92,7 +92,7 @@ async function tryDeploy(cwd, server) {
 }
 /** Scaffold the project, optionally showing a spinner. */
 async function scaffoldProject(dir, cwd, template, silent) {
-	const { runInit } = await import("./_init-DU-sXH6S.mjs");
+	const { runInit } = await import("./_init-_G8l4lh2.mjs");
 	const s = silent ? void 0 : p.spinner();
 	s?.start(`Creating ${dir}`);
 	await runInit({