@stacksjs/buddy 0.70.59 → 0.70.61

package/dist/commands/migrate.js

@@ -0,0 +1,373 @@
+import { closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import process from "node:process";
+import { confirm, intro, log, onUnknownSubcommand, outro } from "@stacksjs/cli";
+import { Action } from "@stacksjs/enums";
+import { hasTTY, isCI } from "@stacksjs/env";
+import { appPath, frameworkPath, projectPath } from "@stacksjs/path";
+import { ExitCode } from "@stacksjs/types";
+let _runAction;
+async function runAction(...args) {
+  if (!_runAction)
+    _runAction = (await import("@stacksjs/actions")).runAction;
+  return _runAction(...args);
+}
+function acquireMigrationLock() {
+  const lockDir = projectPath(".stacks"), lockFile = `${lockDir}/migrations.lock`;
+  try {
+    if (!existsSync(lockDir))
+      mkdirSync(lockDir, { recursive: !0 });
+    const fd = openSync(lockFile, "wx");
+    try {
+      closeSync(fd);
+    } catch {}
+    return {
+      acquired: !0,
+      release: () => {
+        try {
+          rmSync(lockFile, { force: !0 });
+        } catch {}
+      }
+    };
+  } catch {
+    return {
+      acquired: !1,
+      release: () => {}
+    };
+  }
+}
+function readMigrateMarker() {
+  const file = projectPath(".stacks/last-migrate-result.json");
+  if (!existsSync(file))
+    return null;
+  try {
+    const raw = readFileSync(file, "utf8"), parsed = JSON.parse(raw), n = typeof parsed.appliedCount === "number" ? parsed.appliedCount : null;
+    if (n === null || !Number.isFinite(n))
+      return null;
+    return { appliedCount: Math.max(0, Math.floor(n)) };
+  } catch {
+    return null;
+  } finally {
+    try {
+      rmSync(file, { force: !0 });
+    } catch {}
+  }
+}
+function countModelFiles(dir) {
+  if (!existsSync(dir))
+    return 0;
+  let count = 0;
+  const entries = readdirSync(dir, { withFileTypes: !0 });
+  for (const entry of entries)
+    if (entry.isDirectory())
+      count += countModelFiles(`${dir}/${entry.name}`);
+    else if (entry.name.endsWith(".ts") && !entry.name.startsWith(".") && !entry.name.startsWith("index"))
+      count++;
+  return count;
+}
+function validateModelsExist() {
+  const userModelsPath = appPath("Models"), defaultModelsPath = frameworkPath("defaults/app/Models"), userModelCount = countModelFiles(userModelsPath), defaultModelCount = countModelFiles(defaultModelsPath);
+  if (userModelCount === 0 && defaultModelCount === 0)
+    return {
+      valid: !1,
+      error: "No models found. Please create models in app/Models or ensure framework defaults exist."
+    };
+  return { valid: !0 };
+}
+async function reportMissingForeignKeys() {
+  try {
+    const { auditForeignKeys } = await import("@stacksjs/database"), result = await auditForeignKeys();
+    if (result.missing.length === 0)
+      return;
+    const sample = result.missing.slice(0, 5).map((fk) => `  \u2022 ${fk.fromTable}.${fk.fromColumn} \u2192 ${fk.toTable}.${fk.toColumn} (${fk.model})`).join(`
+`), more = result.missing.length > 5 ? `
+  + ${result.missing.length - 5} more \u2014 run \`./buddy doctor\` for the full list.` : "";
+    log.warn(`${result.missing.length} of ${result.declared.length} declared foreign keys are missing from the live schema:
+${sample}${more}
+` + "If you just flipped DB_CONNECTION, the FK ALTER migrations may be sitting on disk but unapplied \u2014 run `./buddy migrate:fresh` against the new database (will reset data) or replay the alter-*.sql files manually.");
+  } catch (err) {
+    log.debug(`[migrate] FK integrity check skipped: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+function describeOp(op) {
+  switch (op.kind) {
+    case "drop_table":
+      return `drop table "${op.table}" (all rows lost)`;
+    case "drop_column":
+      return `drop column "${op.table}"."${op.column}" (column data lost)`;
+    case "modify_column":
+      return `change type of "${op.table}"."${op.column}" (possible data loss)`;
+    case "rebuild_table":
+      return `rebuild table "${op.table}" (type/constraint change)`;
+    case "rename_column":
+      return `rename "${op.table}"."${op.from}" \u2192 "${op.to}"`;
+    case "rename_table":
+      return `rename table "${op.from}" \u2192 "${op.to}"`;
+    default:
+      return `${op.kind} on "${op.table}"${op.column ? `."${op.column}"` : ""}`;
+  }
+}
+async function confirmDestructiveMigrations(opts) {
+  let operations = [];
+  try {
+    const { previewPendingMigrations } = await import("@stacksjs/database");
+    operations = await previewPendingMigrations({ fromDb: opts.fromDb, applyRenames: opts.applyRenames });
+  } catch (error) {
+    log.debug(`Migration preview unavailable: ${error instanceof Error ? error.message : String(error)}`);
+    return !0;
+  }
+  const renames = operations.filter((o) => o.kind === "rename_column" || o.kind === "rename_table");
+  for (const r of renames)
+    log.info(`Detected ${describeOp(r)} \u2014 applying as a rename (data preserved). Use --no-rename to drop + add instead.`);
+  const destructive = operations.filter((o) => o.destructive);
+  if (destructive.length === 0)
+    return !0;
+  log.warn(`This migration includes ${destructive.length} potentially destructive change${destructive.length === 1 ? "" : "s"}:`);
+  for (const op of destructive)
+    log.warn(`  \u2022 ${describeOp(op)}`);
+  if (opts.force)
+    return !0;
+  if (isCI || !hasTTY) {
+    log.error("Refusing to apply destructive changes in a non-interactive environment. Re-run with --force to proceed.");
+    return !1;
+  }
+  return confirm({ message: "Apply these destructive changes?", initial: !1 });
+}
+export function migrate(buddy) {
+  const descriptions = {
+    migrate: "Migrates your database",
+    project: "Target a specific project",
+    verbose: "Enable verbose output",
+    auth: "Also migrate auth tables (oauth_clients, oauth_access_tokens, oauth_refresh_tokens, password_resets)",
+    force: "Apply destructive changes (drop column/table, lossy type change) without confirmation",
+    fromDb: "Diff against the live database schema instead of the snapshot (self-heal drift)",
+    noRename: "Treat renamed columns as drop + add instead of a data-preserving rename"
+  };
+  buddy.command("migrate", descriptions.migrate).alias("db:migrate").option("-d, --diff", "Show the SQL that would be run", { default: !1 }).option("-p, --project [project]", descriptions.project, { default: !1 }).option("-a, --auth", descriptions.auth, { default: !0 }).option("--no-auth", "Skip auth/oauth table migrations").option("-f, --force", descriptions.force, { default: !1 }).option("--from-db", descriptions.fromDb, { default: !1 }).option("--no-rename", descriptions.noRename).option("--verbose", descriptions.verbose, { default: !1 }).action(async (options) => {
+    log.debug("Running `buddy migrate` ...", options);
+    const perf = await intro("buddy migrate"), validation = validateModelsExist();
+    if (!validation.valid) {
+      console.error(`
+\u274C Error: ${validation.error}
+`);
+      process.exit(ExitCode.FatalError);
+    }
+    const applyRenames = options.rename === !1 ? !1 : void 0;
+    if (options.fromDb)
+      process.env.STACKS_MIGRATE_FROM_DB = "1";
+    if (applyRenames === !1)
+      process.env.STACKS_MIGRATE_NO_RENAME = "1";
+    if (options.diff) {
+      try {
+        const { previewPendingMigrations } = await import("@stacksjs/database"), ops = await previewPendingMigrations({ fromDb: options.fromDb, applyRenames });
+        if (ops.length === 0)
+          log.info("No pending schema changes \u2014 your models match the database.");
+        else {
+          log.info(`${ops.length} pending change${ops.length === 1 ? "" : "s"}:`);
+          for (const op of ops)
+            log.info(`  \u2022 ${describeOp(op)}${op.destructive ? "  [destructive]" : ""}`);
+        }
+      } catch (error) {
+        log.error("Failed to preview migrations:", error);
+      }
+      await outro("Diff complete \u2014 no changes applied.", { startTime: perf, useSeconds: !0 });
+      process.exit(ExitCode.Success);
+    }
+    const lock = acquireMigrationLock();
+    if (!lock.acquired) {
+      log.error("Another migration is already running (.stacks/migrations.lock exists). Wait for it to finish, or remove the lockfile if it is stale.");
+      process.exit(ExitCode.FatalError);
+    }
+    if (!await confirmDestructiveMigrations({ force: options.force, fromDb: options.fromDb, applyRenames })) {
+      lock.release();
+      await outro("Migration cancelled \u2014 no changes applied.", { startTime: perf, useSeconds: !0 });
+      process.exit(ExitCode.Success);
+    }
+    if (options.auth !== !1) {
+      log.debug("Migrating auth tables...");
+      try {
+        const { migrateAuthTables, migrateNotificationTables, migrateRbacTables } = await import("@stacksjs/database"), authResult = await migrateAuthTables({ verbose: options.verbose });
+        if (!authResult.success)
+          log.error(`Failed to migrate auth tables: ${authResult.error}`);
+        const notifResult = await migrateNotificationTables({ verbose: options.verbose });
+        if (!notifResult.success)
+          log.error(`Failed to migrate notification tables: ${notifResult.error}`);
+        const rbacResult = await migrateRbacTables({ verbose: options.verbose });
+        if (!rbacResult.success)
+          log.error(`Failed to migrate RBAC tables: ${rbacResult.error}`);
+      } catch (error) {
+        log.error("Failed to migrate auth/notification/RBAC tables:", error);
+      }
+    }
+    const result = await runAction(Action.Migrate, options).finally(() => lock.release());
+    if (result.isErr)
+      log.error("Model migrations failed.");
+    if (result.isErr) {
+      await outro("While running the migrate command, there was an issue", { startTime: perf, useSeconds: !0 }, result.error);
+      process.exit(ExitCode.FatalError);
+    }
+    if (options.auth !== !1)
+      try {
+        const { ensureUsersAuthColumns, sqlHelpers } = await import("@stacksjs/database"), driver = process.env.DB_CONNECTION || "sqlite";
+        await ensureUsersAuthColumns(sqlHelpers(driver), { verbose: options.verbose });
+      } catch (error) {
+        log.error("Failed to ensure users auth columns post-migration:", error);
+      }
+    try {
+      const { ensureUuidColumns, sqlHelpers } = await import("@stacksjs/database"), driver = process.env.DB_CONNECTION || "sqlite";
+      await ensureUuidColumns(sqlHelpers(driver), { verbose: options.verbose });
+    } catch (error) {
+      log.error("Failed to ensure uuid columns post-migration:", error);
+    }
+    await reportMissingForeignKeys();
+    const APP_ENV = process.env.APP_ENV || "local", marker = readMigrateMarker(), authSuffix = options.auth !== !1 ? " (including auth tables)" : "", outroMessage = marker == null ? `Migrated your ${APP_ENV} database.${authSuffix}` : marker.appliedCount === 0 ? `Nothing to migrate \u2014 your ${APP_ENV} database is already up to date.${authSuffix}` : `Applied ${marker.appliedCount} migration${marker.appliedCount === 1 ? "" : "s"} to your ${APP_ENV} database.${authSuffix}`;
+    await outro(outroMessage, {
+      startTime: perf,
+      useSeconds: !0
+    });
+    process.exit(ExitCode.Success);
+  });
+  buddy.command("migrate:fresh", descriptions.migrate).alias("db:fresh").option("-d, --diff", "Show the SQL that would be run", { default: !1 }).option("-p, --project [project]", descriptions.project, { default: !1 }).option("-s, --seed", "Run database seeders after migration", { default: !1 }).option("-a, --auth", descriptions.auth, { default: !0 }).option("--no-auth", "Skip auth/oauth table migrations").option("--verbose", descriptions.verbose, { default: !1 }).action(async (options) => {
+    log.debug("Running `buddy migrate:fresh` ...", options);
+    const perf = await intro("buddy migrate:fresh"), validation = validateModelsExist();
+    if (!validation.valid) {
+      console.error(`
+\u274C Error: ${validation.error}
+`);
+      process.exit(ExitCode.FatalError);
+    }
+    const result = await runAction(Action.MigrateFresh, options);
+    if (result.isErr)
+      log.error("Model migrations failed \u2014 applying auth/notification/RBAC table guarantees before exiting.");
+    if (options.auth !== !1) {
+      log.debug("Migrating auth tables...");
+      try {
+        const { migrateAuthTables, migrateNotificationTables, migrateRbacTables } = await import("@stacksjs/database"), authResult = await migrateAuthTables({ verbose: options.verbose });
+        if (!authResult.success)
+          log.error(`Failed to migrate auth tables: ${authResult.error}`);
+        const notifResult = await migrateNotificationTables({ verbose: options.verbose });
+        if (!notifResult.success)
+          log.error(`Failed to migrate notification tables: ${notifResult.error}`);
+        const rbacResult = await migrateRbacTables({ verbose: options.verbose });
+        if (!rbacResult.success)
+          log.error(`Failed to migrate RBAC tables: ${rbacResult.error}`);
+      } catch (error) {
+        log.error("Failed to migrate auth/notification/RBAC tables:", error);
+      }
+    }
+    try {
+      const { ensureUuidColumns, sqlHelpers } = await import("@stacksjs/database"), driver = process.env.DB_CONNECTION || "sqlite";
+      await ensureUuidColumns(sqlHelpers(driver), { verbose: options.verbose });
+    } catch (error) {
+      log.error("Failed to ensure uuid columns post-migration:", error);
+    }
+    if (result.isErr) {
+      await outro("While running the migrate:fresh command, there was an issue", { startTime: perf, useSeconds: !0 }, result.error);
+      process.exit(ExitCode.FatalError);
+    }
+    await reportMissingForeignKeys();
+    if (options.seed) {
+      log.info("Running database seeders...");
+      try {
+        const { seed } = await import("@stacksjs/database"), seedResult = await seed({ verbose: options.verbose, fresh: !0 });
+        if (seedResult.failed > 0) {
+          log.warn(`Seeding completed with ${seedResult.failed} failure(s)`);
+          for (const r of seedResult.results)
+            if (!r.success)
+              log.error(`  - ${r.model}: ${r.error}`);
+        } else
+          log.success(`Seeded ${seedResult.successful} model(s)`);
+      } catch (error) {
+        log.error("Failed to run seeders:", error);
+      }
+    }
+    const parts = [];
+    if (options.auth !== !1)
+      parts.push("auth tables");
+    if (options.seed)
+      parts.push("seeded");
+    const suffix = parts.length > 0 ? ` & ${parts.join(" & ")}` : "", marker = readMigrateMarker(), countPhrase = marker == null ? "" : marker.appliedCount === 0 ? " (0 applied \u2014 no migration files found?)" : ` (${marker.appliedCount} migration${marker.appliedCount === 1 ? "" : "s"} applied)`;
+    await outro(`All tables dropped successfully & migrated successfully${countPhrase}${suffix}`, {
+      startTime: perf,
+      useSeconds: !0
+    });
+    process.exit(ExitCode.Success);
+  });
+  buddy.command("migrate:dns", descriptions.migrate).option("-p, --project [project]", descriptions.project, { default: !1 }).option("--verbose", descriptions.verbose, { default: !1 }).action(async (options) => {
+    log.debug("Running `buddy migrate:dns` ...", options);
+    const perf = await intro("buddy migrate:dns"), result = await runAction(Action.MigrateDns, { ...options });
+    if (result.isErr) {
+      await outro("While running the migrate:dns command, there was an issue", { startTime: perf, useSeconds: !0 }, result.error);
+      process.exit(ExitCode.FatalError);
+    }
+    const APP_URL = process.env.APP_URL || "undefined";
+    await outro(`Migrated your ${APP_URL} DNS.`, {
+      startTime: perf,
+      useSeconds: !0
+    });
+    process.exit(ExitCode.Success);
+  });
+  buddy.command("migrate:switch <driver>", "Pre-flight check + plan for switching DB_CONNECTION between sqlite / mysql / postgres").action(async (driver) => {
+    log.debug(`Running \`buddy migrate:switch ${driver}\` ...`);
+    const perf = await intro("buddy migrate:switch"), target = driver.toLowerCase();
+    if (!new Set(["sqlite", "mysql", "postgres"]).has(target)) {
+      console.log(`
+  Unknown target driver "${driver}". Allowed: sqlite, mysql, postgres.
+`);
+      await outro("Aborted.", { startTime: perf, useSeconds: !0 });
+      process.exit(ExitCode.FatalError);
+    }
+    const current = (process.env.DB_CONNECTION || "sqlite").toLowerCase();
+    if (current === target) {
+      console.log(`
+  DB_CONNECTION is already "${target}". Nothing to switch.
+`);
+      await outro("No-op.", { startTime: perf, useSeconds: !0 });
+      process.exit(ExitCode.Success);
+    }
+    const missingEnv = ({
+      sqlite: ["DB_DATABASE"],
+      mysql: ["DB_HOST", "DB_PORT", "DB_USERNAME", "DB_PASSWORD", "DB_DATABASE"],
+      postgres: ["DB_HOST", "DB_PORT", "DB_USERNAME", "DB_PASSWORD", "DB_DATABASE"]
+    }[target] ?? []).filter((k) => !process.env[k]);
+    let alterCount = 0, uniqueIdxCount = 0;
+    try {
+      const migrationsDir = projectPath("database/migrations");
+      if (existsSync(migrationsDir)) {
+        const files = readdirSync(migrationsDir).filter((f) => f.endsWith(".sql"));
+        for (const f of files) {
+          const content = readFileSync(`${migrationsDir}/${f}`, "utf-8").toLowerCase();
+          if (/alter\s+table[\s\S]*add\s+constraint/.test(content))
+            alterCount++;
+          if (/^\s*create\s+unique\s+index/m.test(content))
+            uniqueIdxCount++;
+        }
+      }
+    } catch {}
+    const sqliteFkNote = current === "sqlite" && alterCount > 0 ? `
+    (These were skipped on SQLite per stacksjs/stacks#1916 and survive on disk for replay.)` : "", boolNote = current === "sqlite" && (target === "postgres" || target === "mysql") ? `
+  \u2022 Booleans land as 0/1 on SQLite; ${target} stores them as ${target === "postgres" ? "true/false" : "0/1 (compatible)"}.` : "", tzNote = target === "postgres" ? `
+  \u2022 PostgreSQL uses timestamptz (with TZ) where SQLite/MySQL store plain TIMESTAMP. Existing rows do NOT auto-upgrade \u2014 they ride the column's stored type.` : "", envExtras = target !== "sqlite" ? ", plus DB_HOST / DB_PORT / DB_USERNAME / DB_PASSWORD / DB_DATABASE" : "", missingNote = missingEnv.length > 0 ? `
+  \u26A0 Missing env vars for ${target}: ${missingEnv.join(", ")}` : "";
+    console.log(`
+  Switch plan: ${current} \u2192 ${target}
+  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+  \u2022 ${alterCount} ALTER TABLE ADD CONSTRAINT migration(s) will be applied against ${target}.${sqliteFkNote}
+  \u2022 ${uniqueIdxCount} CREATE UNIQUE INDEX migration(s) will be applied against ${target}.
+  \u2022 Auth tables (oauth_clients, oauth_access_tokens, oauth_refresh_tokens, password_resets) will be CREATE TABLE IF NOT EXISTS \u2014 they re-create cleanly under the new dialect.${boolNote}${tzNote}
+  \u2022 Existing row data does NOT auto-migrate. Use \`mysqldump\` / \`pg_dump\` (or your own export) to move it.${missingNote}
+  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+
+  Next steps:
+    1. Update .env:  DB_CONNECTION=${target}${envExtras}
+    2. (Optional) Export data from the current ${current} database.
+    3. Run \`./buddy migrate\` (or \`migrate:fresh\` to start clean).
+    4. The post-migrate FK audit will report any constraints that didn't replay.
+`);
+    await outro("Plan rendered. Re-run after updating .env to actually switch.", {
+      startTime: perf,
+      useSeconds: !0
+    });
+    process.exit(ExitCode.Success);
+  });
+  onUnknownSubcommand(buddy, "migrate");
+}

package/dist/commands/outdated.js

@@ -0,0 +1,19 @@
+import { $ } from "bun";
+import process from "node:process";
+import { log } from "@stacksjs/logging";
+import { projectPath } from "@stacksjs/path";
+import { onUnknownSubcommand } from "@stacksjs/cli";
+export function outdated(buddy) {
+  const descriptions = {
+    outdated: "List all the outdated project dependencies",
+    project: "Target a specific project",
+    verbose: "Enable verbose output"
+  };
+  buddy.command("outdated", descriptions.outdated).option("-p, --project [project]", descriptions.project, { default: !1 }).option("--verbose", descriptions.verbose, { default: !1 }).action(async () => {
+    log.debug("Running `buddy outdated` ...");
+    $.cwd(projectPath());
+    const response = await $`bun outdated`.text();
+    console.log(response);
+  });
+  onUnknownSubcommand(buddy, "outdated");
+}

package/dist/commands/package.d.ts

@@ -0,0 +1,2 @@
+import type { CLI } from '@stacksjs/types';
+export declare function packageCommands(buddy: CLI): void;

package/dist/commands/package.js

@@ -0,0 +1,17 @@
+import process from "node:process";
+import { intro, log, onUnknownSubcommand, outro } from "@stacksjs/cli";
+import { ExitCode } from "@stacksjs/types";
+export function packageCommands(buddy) {
+  buddy.command("package:discover", "Discover Stacks-compatible packages from pantry").option("--verbose", "Enable verbose output", { default: !1 }).action(async () => {
+    const perf = await intro("buddy package:discover"), { discoverPackages } = await import("@stacksjs/actions"), manifest = await discoverPackages(), count = Object.keys(manifest.packages).length;
+    if (count > 0) {
+      log.success(`Discovered ${count} Stacks package${count === 1 ? "" : "s"}:`);
+      for (const name of Object.keys(manifest.packages))
+        log.info(`  - ${name}`);
+    } else
+      log.info("No Stacks-compatible packages found in pantry");
+    await outro("Package discovery complete", { startTime: perf, useSeconds: !0 });
+    process.exit(ExitCode.Success);
+  });
+  onUnknownSubcommand(buddy, "package");
+}

package/dist/commands/phone.js

@@ -0,0 +1,188 @@
+import { getErrorMessage } from "@stacksjs/utils";
+import { readFileSync, existsSync } from "node:fs";
+const TIMEOUT_MS = 30000;
+async function withTimeout(promise, ms = TIMEOUT_MS) {
+  let timeoutId;
+  const timeoutPromise = new Promise((_, reject) => {
+    timeoutId = setTimeout(() => reject(Error(`Operation timed out after ${ms}ms`)), ms);
+  });
+  try {
+    return await Promise.race([promise, timeoutPromise]);
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+function loadAwsCredentials() {
+  const envPath = ".env.production";
+  if (existsSync(envPath)) {
+    const content = readFileSync(envPath, "utf-8");
+    for (const line of content.split(`
+`)) {
+      const eq = line.indexOf("=");
+      if (eq > 0 && !line.startsWith("#"))
+        process.env[line.slice(0, eq).trim()] = line.slice(eq + 1).trim();
+    }
+  }
+}
+const descriptions = {
+  phone: "Phone/voice service management commands",
+  status: "Show phone service status",
+  numbers: "List phone numbers",
+  search: "Search available phone numbers",
+  setup: "Initialize phone infrastructure"
+};
+export function phone(buddy) {
+  buddy.command("phone", descriptions.phone).action(async () => {
+    console.log(`
+\uD83D\uDCDE Phone Service Commands
+`);
+    console.log("  buddy phone:status   - Show phone service status");
+    console.log("  buddy phone:numbers  - List phone numbers");
+    console.log("  buddy phone:search   - Search available phone numbers");
+    console.log("  buddy phone:setup    - Initialize phone infrastructure");
+    console.log("");
+    process.exit(0);
+  });
+  buddy.command("phone:status", descriptions.status).action(async () => {
+    console.log(`
+\uD83D\uDCDE Phone Service Status
+`);
+    loadAwsCredentials();
+    try {
+      const { ConnectClient } = await import("@stacksjs/ts-cloud"), connect = new ConnectClient(process.env.AWS_REGION || "us-east-1"), instanceAlias = `${(process.env.APP_NAME || "stacks").toLowerCase().replace(/[^a-z0-9-]/g, "-")}-phone`;
+      console.log(`Looking for Connect instance: ${instanceAlias}`);
+      const instance = (await withTimeout(connect.listInstances({ MaxResults: 100 }))).InstanceSummaryList?.find((i) => i.InstanceAlias === instanceAlias);
+      if (instance) {
+        console.log(`
+\u2705 Phone Service Active
+`);
+        console.log(`  Instance ID: ${instance.Id}`);
+        console.log(`  Alias: ${instance.InstanceAlias}`);
+        console.log(`  Status: ${instance.InstanceStatus}`);
+        console.log(`  Inbound Calls: ${instance.InboundCallsEnabled ? "Enabled" : "Disabled"}`);
+        console.log(`  Outbound Calls: ${instance.OutboundCallsEnabled ? "Enabled" : "Disabled"}`);
+        if (instance.Id)
+          try {
+            const numbers = await withTimeout(connect.listPhoneNumbers({ InstanceId: instance.Id }));
+            if (numbers.ListPhoneNumbersSummaryList && numbers.ListPhoneNumbersSummaryList.length > 0) {
+              console.log(`
+  Phone Numbers:`);
+              for (const num of numbers.ListPhoneNumbersSummaryList)
+                console.log(`    \uD83D\uDCF1 ${num.PhoneNumber} (${num.PhoneNumberType})`);
+            } else
+              console.log(`
+  No phone numbers claimed yet.`);
+          } catch {
+            console.log(`
+  Could not retrieve phone numbers.`);
+          }
+      } else {
+        console.log(`
+\u274C Phone service not deployed.`);
+        console.log(`
+\uD83D\uDCA1 To set up phone service:`);
+        console.log("   1. Enable phone in config/phone.ts");
+        console.log("   2. Run `buddy deploy`");
+      }
+    } catch (error) {
+      console.error("Error checking status:", getErrorMessage(error));
+    }
+    process.exit(0);
+  });
+  buddy.command("phone:numbers", descriptions.numbers).action(async () => {
+    console.log(`
+\uD83D\uDCDE Phone Numbers
+`);
+    loadAwsCredentials();
+    try {
+      const { ConnectClient } = await import("@stacksjs/ts-cloud"), connect = new ConnectClient(process.env.AWS_REGION || "us-east-1"), instanceAlias = `${(process.env.APP_NAME || "stacks").toLowerCase().replace(/[^a-z0-9-]/g, "-")}-phone`, instance = (await withTimeout(connect.listInstances({ MaxResults: 100 }))).InstanceSummaryList?.find((i) => i.InstanceAlias === instanceAlias);
+      if (!instance?.Id) {
+        console.log("Phone service not deployed. Run `buddy phone:setup` first.");
+        process.exit(0);
+        return;
+      }
+      const numbers = await withTimeout(connect.listPhoneNumbers({ InstanceId: instance.Id }));
+      if (!numbers.ListPhoneNumbersSummaryList || numbers.ListPhoneNumbersSummaryList.length === 0) {
+        console.log("No phone numbers claimed.");
+        console.log("\n\uD83D\uDCA1 Use `buddy phone:search` to find available numbers.");
+        process.exit(0);
+        return;
+      }
+      console.log(`Claimed Phone Numbers:
+`);
+      for (const num of numbers.ListPhoneNumbersSummaryList) {
+        console.log(`  \uD83D\uDCF1 ${num.PhoneNumber}`);
+        console.log(`     Type: ${num.PhoneNumberType}`);
+        console.log(`     Country: ${num.PhoneNumberCountryCode}`);
+        if (num.PhoneNumberDescription)
+          console.log(`     Description: ${num.PhoneNumberDescription}`);
+        console.log("");
+      }
+    } catch (error) {
+      console.error("Error listing numbers:", getErrorMessage(error));
+    }
+    process.exit(0);
+  });
+  buddy.command("phone:search [country]", descriptions.search).option("-t, --type <type>", "Phone number type (TOLL_FREE, DID)", { default: "TOLL_FREE" }).action(async (country, options) => {
+    const countryCode = country?.toUpperCase() || "US", phoneType = options.type?.toUpperCase() || "TOLL_FREE";
+    console.log(`
+\uD83D\uDCDE Searching for ${phoneType} numbers in ${countryCode}...
+`);
+    loadAwsCredentials();
+    try {
+      const { ConnectClient } = await import("@stacksjs/ts-cloud"), connect = new ConnectClient(process.env.AWS_REGION || "us-east-1"), instanceAlias = `${(process.env.APP_NAME || "stacks").toLowerCase().replace(/[^a-z0-9-]/g, "-")}-phone`, instance = (await withTimeout(connect.listInstances({ MaxResults: 100 }))).InstanceSummaryList?.find((i) => i.InstanceAlias === instanceAlias);
+      if (!instance?.Arn) {
+        console.log("Phone service not deployed. Run `buddy phone:setup` first.");
+        process.exit(0);
+        return;
+      }
+      const available = await withTimeout(connect.searchAvailablePhoneNumbers({
+        TargetArn: instance.Arn,
+        PhoneNumberCountryCode: countryCode,
+        PhoneNumberType: phoneType,
+        MaxResults: 10
+      }));
+      if (!available.AvailableNumbersList || available.AvailableNumbersList.length === 0) {
+        console.log(`No ${phoneType} numbers available in ${countryCode}.`);
+        console.log(`
+\uD83D\uDCA1 Try a different country or number type.`);
+        process.exit(0);
+        return;
+      }
+      console.log(`Available Phone Numbers:
+`);
+      for (const num of available.AvailableNumbersList)
+        console.log(`  \uD83D\uDCF1 ${num.PhoneNumber}`);
+      console.log("\n\uD83D\uDCA1 To claim a number, use `buddy phone:claim <number>`");
+    } catch (error) {
+      if (getErrorMessage(error).includes("not authorized")) {
+        console.log("Not authorized to search phone numbers.");
+        console.log("Make sure your AWS account has Amazon Connect permissions.");
+      } else
+        console.error("Error searching numbers:", getErrorMessage(error));
+    }
+    process.exit(0);
+  });
+  buddy.command("phone:setup", descriptions.setup).action(async () => {
+    console.log(`
+\uD83D\uDCDE Phone Service Setup
+`);
+    console.log("Amazon Connect setup requires manual configuration.");
+    console.log(`
+Steps to set up phone service:
+`);
+    console.log("1. Enable phone in config/phone.ts:");
+    console.log("   enabled: true");
+    console.log("");
+    console.log("2. Run `buddy deploy` to create the Connect instance");
+    console.log("");
+    console.log("3. Access the Connect console to:");
+    console.log("   - Claim phone numbers");
+    console.log("   - Configure contact flows");
+    console.log("   - Set up routing profiles");
+    console.log("");
+    console.log("4. Use `buddy phone:status` to verify setup");
+    console.log("");
+    process.exit(0);
+  });
+}