@maestro-js/cli 1.0.0-alpha.0

package/README.md

@@ -0,0 +1,252 @@
+# @maestro-js/cli
+
+CLI tool for the Maestro framework, built with [sade](https://github.com/lukeed/sade). Provides commands for database migrations, environment file encryption, Docker container creation, and AWS WireGuard client provisioning.
+
+Binary name: `maestro`. Installed via the `bin` field in package.json as `./dist/bin.js`.
+
+## Package Location
+
+- Source: `packages/maestro-cli/src/`
+- Entry point: `packages/maestro-cli/src/bin.ts`
+- Commands: `packages/maestro-cli/src/commands/`
+- Utilities: `packages/maestro-cli/src/utils/`
+- No tests directory exists for this package.
+
+## Available Commands
+
+| Command | Description |
+|---|---|
+| `maestro db:make-migration <name>` | Create a new database migration |
+| `maestro db:migrate` | Run pending database migrations |
+| `maestro db:rollback` | Rollback database migrations |
+| `maestro db:status` | Show database migration status |
+| `maestro db:make-container` | Create a Docker database container |
+| `maestro env:generate-key` | Generate an encryption key |
+| `maestro env:encrypt` | Encrypt a .env file |
+| `maestro env:decrypt` | Decrypt a .env.encrypted file |
+| `maestro aws:make-wireguard-client [id]` | Add a WireGuard client peer to a VPN server |
+
+## Command Details
+
+### db:make-migration
+
+Create a new migration in `infrastructure/db-migrations/` relative to cwd. Delegates to `DbMigrations.scaffold()` from `@maestro-js/db-migrate`.
+
+```
+maestro db:make-migration <name>
+```
+
+Generates three files: a `.ts` migration file, an `.up.sql` file, and a `.down.sql` file.
+
+### db:migrate
+
+Run pending database migrations. Connects to the database using resolved config (CLI flags > env vars > config file).
+
+```
+maestro db:migrate [options]
+  --host        Database host (env: DB_HOST)
+  --port        Database port (env: DB_PORT)
+  --user        Database user (env: DB_USER)
+  --password    Database password (env: DB_PASSWORD)
+  --database    Database name (env: DB_DATABASE)
+  --dry-run     Preview migrations without executing
+  --count       Number of migrations to run
+```
+
+### db:rollback
+
+Rollback database migrations. Default count is 1.
+
+```
+maestro db:rollback [options]
+  --host        Database host (env: DB_HOST)
+  --port        Database port (env: DB_PORT)
+  --user        Database user (env: DB_USER)
+  --password    Database password (env: DB_PASSWORD)
+  --database    Database name (env: DB_DATABASE)
+  --dry-run     Preview rollback without executing
+  --count       Number of migrations to rollback (default: 1)
+```
+
+### db:status
+
+Show which migrations have been applied and which are pending.
+
+```
+maestro db:status [options]
+  --host        Database host (env: DB_HOST)
+  --port        Database port (env: DB_PORT)
+  --user        Database user (env: DB_USER)
+  --password    Database password (env: DB_PASSWORD)
+  --database    Database name (env: DB_DATABASE)
+```
+
+### db:make-container
+
+Interactive command that prompts for database type (MySQL, PostgreSQL, Redis), container name, port, database name, and password. Pulls the Docker image and runs the container.
+
+```
+maestro db:make-container
+```
+
+Supported database images: `mysql:8`, `postgres:17`, `redis:7`.
+
+### env:generate-key
+
+Generate an encryption key via `Config.generateEncryptionKey()` from `@maestro-js/config`. Prints the key to stdout.
+
+```
+maestro env:generate-key
+```
+
+### env:encrypt
+
+Encrypt a `.env` file to `.env.encrypted`. Requires an encryption key via `--key` flag or `MAESTRO_ENV_ENCRYPTION_KEY` env var.
+
+```
+maestro env:encrypt [options]
+  --env    Environment name (e.g. production, creates .env.production.encrypted)
+  --key    Encryption key (env: MAESTRO_ENV_ENCRYPTION_KEY)
+```
+
+### env:decrypt
+
+Decrypt a `.env.encrypted` file back to `.env`. Requires an encryption key via `--key` flag or `MAESTRO_ENV_ENCRYPTION_KEY` env var.
+
+```
+maestro env:decrypt [options]
+  --env      Environment name (e.g. production)
+  --key      Encryption key (env: MAESTRO_ENV_ENCRYPTION_KEY)
+  --force    Overwrite existing .env file
+```
+
+### aws:make-wireguard-client
+
+Add a WireGuard client peer to an existing VPN server managed via AWS SSM Parameter Store. If no `[id]` argument is provided, lists available WireGuard configurations from SSM and prompts for selection.
+
+```
+maestro aws:make-wireguard-client [id] [options]
+  --region        AWS region (env: AWS_REGION)
+  --name          Label for the peer
+  --endpoint      Override auto-detected server IP
+  --dns           DNS for client config
+  --allowed-ips   Client AllowedIPs (default: "10.0.0.0/16, 10.100.0.0/24")
+```
+
+Generates a WireGuard client configuration, stores the peer in SSM, and applies it on the server via SSM Run Command.
+
+## Adding New Commands
+
+### 1. Create the command file
+
+Add a new file in `packages/maestro-cli/src/commands/`. Follow the existing pattern: export a single async function that receives parsed options.
+
+```ts
+// packages/maestro-cli/src/commands/my-command.ts
+interface Options {
+  flag?: string
+}
+
+export async function myCommand(opts: Options) {
+  // Implementation
+  console.log('Done.')
+}
+```
+
+### 2. Register in bin.ts
+
+Import the command function and register it with sade in `packages/maestro-cli/src/bin.ts`:
+
+```ts
+import { myCommand } from './commands/my-command.ts'
+
+prog
+  .command('namespace:my-command')
+  .describe('Short description of what it does')
+  .option('--flag', 'Description of the flag')
+  .action(myCommand)
+```
+
+### 3. Command naming convention
+
+Use colon-separated namespaces matching existing groups:
+- `db:*` for database-related commands
+- `env:*` for environment/config commands
+- `aws:*` for AWS infrastructure commands
+
+### 4. For database commands
+
+Use the shared utilities in `packages/maestro-cli/src/utils/db.ts`:
+
+```ts
+import { createDb, resolveDbConfig, type DbConnectionConfig } from '../utils/db.ts'
+
+export async function myDbCommand(opts: Partial<DbConnectionConfig>) {
+  const config = await resolveDbConfig(opts)
+  const db = await createDb(config)
+  try {
+    // Use db...
+  } finally {
+    await db.destroy()
+  }
+}
+```
+
+The `resolveDbConfig` function resolves database connection settings with this precedence: CLI flags > environment variables > config file (loaded via `@maestro-js/config` with config name `db-migrate`).
+
+## Common Patterns
+
+### Database config resolution
+
+All `db:*` commands (except `db:make-migration` and `db:make-container`) share the same connection options and resolution logic from `utils/db.ts`. The `resolveDbConfig` function reads from:
+1. CLI flags (`--host`, `--port`, `--user`, `--password`, `--database`)
+2. Environment variables (`DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`, `DB_DATABASE`)
+3. Config file via `@maestro-js/config` with config name `db-migrate`
+
+### Migration directory
+
+All migration commands expect migrations in `infrastructure/db-migrations/` relative to the current working directory.
+
+### Interactive prompts
+
+The `prompts` library is used for interactive input in `db:make-container` and `aws:make-wireguard-client`. All prompt flows call `process.exit(0)` on cancellation.
+
+### Error handling
+
+Commands print errors to stderr via `console.error()` and call `process.exit(1)` on failure. Database commands use `try/finally` to ensure `db.destroy()` is always called.
+
+## Cross-Package Integration
+
+| Dependency | Usage |
+|---|---|
+| `@maestro-js/config` | Env encryption/decryption (`Config.generateEncryptedEnvFile`, `Config.generateDecryptedEnvFile`, `Config.generateEncryptionKey`), config file loading for DB credentials |
+| `@maestro-js/db` | Database connection creation via `Db.Provider.create` with `Db.drivers.mysql` driver |
+| `@maestro-js/db-migrate` | Migration operations: `DbMigrations.scaffold`, `DbMigrations.migrate`, `DbMigrations.rollback`, `DbMigrations.status` |
+| `sade` | CLI argument parsing and command registration |
+| `prompts` | Interactive terminal prompts for `db:make-container` and `aws:make-wireguard-client` |
+| `@aws-sdk/client-ssm` | SSM parameter read/write and Run Command for WireGuard provisioning |
+| `@aws-sdk/client-sts` | Caller identity resolution for default peer naming |
+
+## Utility Modules
+
+### utils/db.ts
+
+Exports `resolveDbConfig`, `createDb`, and the `DbConnectionConfig` / `CliDb` interfaces. Central place for database connection setup across all db commands.
+
+### utils/migrations.ts
+
+Re-exports `DbMigrations` from `@maestro-js/db-migrate`.
+
+### utils/scaffolding.ts
+
+General-purpose file scaffolding utility (`Scaffolding.scaffold`, `Scaffolding.previewScaffold`, `Scaffolding.fromDirectory`). Supports token replacement with `{{token}}` syntax, skip-existing behavior, and reading directory trees into scaffolding objects. Not currently used by any CLI command but available for future scaffolding needs.
+
+## Build and Development
+
+```bash
+pnpm --filter @maestro-js/cli build        # Build with tsup
+pnpm --filter @maestro-js/cli typecheck     # Typecheck
+pnpm --filter @maestro-js/cli watch         # Watch mode
+```
+
+No tests exist for this package. When adding tests, use `beartest-js` with `expect` assertions consistent with the rest of the monorepo.

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/bin.js

@@ -0,0 +1,848 @@
+#!/usr/bin/env node
+
+// src/bin.ts
+import { createRequire } from "module";
+import sade from "sade";
+
+// src/commands/aws-make-wireguard-client.ts
+import { generateKeyPairSync } from "crypto";
+import {
+  SSMClient,
+  DescribeParametersCommand,
+  GetParameterCommand,
+  PutParameterCommand,
+  SendCommandCommand
+} from "@aws-sdk/client-ssm";
+import { STSClient, GetCallerIdentityCommand } from "@aws-sdk/client-sts";
+import prompts from "prompts";
+async function awsMakeWireguardClient(id, opts) {
+  const region = resolveRegion(opts.region);
+  const client = createSsmClient(region);
+  if (!id) {
+    const ids = await listWireguardIds(client);
+    if (ids.length === 0) {
+      console.error("Error: No WireGuard configurations found in SSM.");
+      process.exit(1);
+    }
+    id = await promptForId(ids);
+  }
+  const { privateKey, publicKey } = generateClientKeypair();
+  const serverPublicKey = await ssmGet(client, `/wireguard/${id}/public-key`);
+  const endpoint = opts.endpoint ?? await ssmGet(client, `/wireguard/${id}/endpoint`);
+  const instanceId = await ssmGet(client, `/wireguard/${id}/instance-id`);
+  const existingPeers = await ssmGetOrEmpty(client, `/wireguard/${id}/peers`);
+  const clientIp = allocateNextIp(existingPeers);
+  const name = opts.name ?? await getCallerName(region) ?? `client-${clientIp.split(".").pop()}`;
+  const allowedIps = opts["allowed-ips"] ?? "10.0.0.0/16, 10.100.0.0/24";
+  await appendPeerToSsm(client, `/wireguard/${id}/peers`, publicKey, clientIp, name, existingPeers);
+  await applyPeerOnServer(client, instanceId, id);
+  const dns = opts.dns ? `
+DNS = ${opts.dns}` : "";
+  const config = [
+    "[Interface]",
+    `PrivateKey = ${privateKey}`,
+    `Address = ${clientIp}/32${dns}`,
+    "",
+    "[Peer]",
+    `PublicKey = ${serverPublicKey}`,
+    `AllowedIPs = ${allowedIps}`,
+    `Endpoint = ${endpoint}:51820`,
+    "PersistentKeepalive = 25"
+  ].join("\n");
+  console.log(`
+${config}
+`);
+  console.log(`Peer "${name}" registered with IP ${clientIp}/32`);
+}
+function createSsmClient(region) {
+  return new SSMClient({ region });
+}
+async function listWireguardIds(client) {
+  try {
+    const response = await client.send(
+      new DescribeParametersCommand({
+        ParameterFilters: [{ Key: "Name", Option: "BeginsWith", Values: ["/wireguard/"] }]
+      })
+    );
+    const names = (response.Parameters ?? []).map((p) => p.Name).filter(Boolean);
+    const ids = /* @__PURE__ */ new Set();
+    for (const name of names) {
+      const match = name.match(/^\/wireguard\/([^/]+)\//);
+      if (match) ids.add(match[1]);
+    }
+    return [...ids].sort();
+  } catch {
+    console.error("Error: Failed to list WireGuard SSM parameters.");
+    process.exit(1);
+  }
+}
+async function promptForId(ids) {
+  const { id } = await prompts({
+    type: "select",
+    name: "id",
+    message: "Select a WireGuard configuration",
+    choices: ids.map((id2) => ({ title: id2, value: id2 }))
+  });
+  if (!id) {
+    process.exit(0);
+  }
+  return id;
+}
+function resolveRegion(flag) {
+  const region = flag ?? process.env.AWS_REGION ?? process.env.AWS_DEFAULT_REGION;
+  if (!region) {
+    console.error("Error: No AWS region specified. Use --region or set AWS_REGION.");
+    process.exit(1);
+  }
+  return region;
+}
+function generateClientKeypair() {
+  const { privateKey, publicKey } = generateKeyPairSync("x25519", {
+    privateKeyEncoding: { type: "pkcs8", format: "der" },
+    publicKeyEncoding: { type: "spki", format: "der" }
+  });
+  return {
+    privateKey: privateKey.subarray(-32).toString("base64"),
+    publicKey: publicKey.subarray(-32).toString("base64")
+  };
+}
+async function ssmGet(client, name) {
+  try {
+    const response = await client.send(new GetParameterCommand({ Name: name, WithDecryption: true }));
+    return response.Parameter.Value;
+  } catch {
+    console.error(`Error: Failed to read SSM parameter "${name}". Is the WireGuard stack deployed?`);
+    process.exit(1);
+  }
+}
+async function ssmGetOrEmpty(client, name) {
+  try {
+    const response = await client.send(new GetParameterCommand({ Name: name, WithDecryption: true }));
+    return response.Parameter.Value;
+  } catch {
+    return "";
+  }
+}
+async function getCallerName(region) {
+  try {
+    const sts = new STSClient({ region });
+    const { Arn } = await sts.send(new GetCallerIdentityCommand({}));
+    if (!Arn) return void 0;
+    const resource = Arn.split(":").pop();
+    const name = resource.includes("/") ? resource.split("/")[1] : resource;
+    return name;
+  } catch {
+    return void 0;
+  }
+}
+function allocateNextIp(existingPeers) {
+  const usedOctets = /* @__PURE__ */ new Set([1]);
+  const re = /AllowedIPs\s*=\s*10\.100\.0\.(\d+)/g;
+  let match;
+  while ((match = re.exec(existingPeers)) !== null) {
+    usedOctets.add(Number(match[1]));
+  }
+  for (let i = 2; i <= 254; i++) {
+    if (!usedOctets.has(i)) return `10.100.0.${i}`;
+  }
+  console.error("Error: No available IPs in 10.100.0.0/24 subnet.");
+  process.exit(1);
+}
+async function appendPeerToSsm(client, name, publicKey, clientIp, peerName, existingPeers) {
+  const newPeer = [`[Peer]`, `# ${peerName}`, `PublicKey = ${publicKey}`, `AllowedIPs = ${clientIp}/32`].join("\n");
+  const updated = existingPeers ? `${existingPeers}
+
+${newPeer}` : newPeer;
+  await client.send(
+    new PutParameterCommand({
+      Name: name,
+      Type: "SecureString",
+      Value: updated,
+      Overwrite: true
+    })
+  );
+}
+async function applyPeerOnServer(client, instanceId, wireguardId) {
+  const script = [
+    'TOKEN=$(curl -s -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600")',
+    'REGION=$(curl -s -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/placement/region)',
+    "sed -i '/^\\[Peer\\]/,$d' /etc/wireguard/wg0.conf",
+    `aws ssm get-parameter --name "/wireguard/${wireguardId}/peers" --with-decryption --region $REGION --query "Parameter.Value" --output text >> /etc/wireguard/wg0.conf`,
+    "systemctl restart wg-quick@wg0"
+  ];
+  try {
+    await client.send(
+      new SendCommandCommand({
+        InstanceIds: [instanceId],
+        DocumentName: "AWS-RunShellScript",
+        Parameters: { commands: script }
+      })
+    );
+  } catch {
+    console.error("Warning: Failed to apply peers via SSM Run Command. The peers are saved but may need a server restart.");
+  }
+}
+
+// src/commands/db-make-container.ts
+import { execSync } from "child_process";
+import prompts2 from "prompts";
+async function createDockerDb() {
+  assertDockerAvailable();
+  const config = await promptForConfig();
+  const db = DATABASE_CONFIGS[config.dbType];
+  pull(db.image);
+  run(config, db);
+  printSummary(config, db);
+}
+var DATABASE_CONFIGS = {
+  mysql: {
+    image: "mysql:8",
+    defaultPort: 3306,
+    envFlags: (dbName, password) => ["-e", `MYSQL_ROOT_PASSWORD=${password}`, "-e", `MYSQL_DATABASE=${dbName}`]
+  },
+  postgres: {
+    image: "postgres:17",
+    defaultPort: 5432,
+    envFlags: (dbName, password) => ["-e", `POSTGRES_PASSWORD=${password}`, "-e", `POSTGRES_DB=${dbName}`]
+  },
+  redis: {
+    image: "redis:7",
+    defaultPort: 6379,
+    envFlags: () => []
+  }
+};
+var onCancel = () => process.exit(0);
+async function promptForConfig() {
+  const { dbType } = await prompts2(
+    {
+      type: "select",
+      name: "dbType",
+      message: "Which database?",
+      choices: [
+        { title: "MySQL", value: "mysql" },
+        { title: "PostgreSQL", value: "postgres" },
+        { title: "Redis", value: "redis" }
+      ]
+    },
+    { onCancel }
+  );
+  const isRedis = dbType === "redis";
+  const defaultPort = DATABASE_CONFIGS[dbType].defaultPort;
+  const answers = await prompts2(
+    [
+      {
+        type: "text",
+        name: "containerName",
+        message: "Container name",
+        initial: `maestro-${dbType}`,
+        validate: (v) => /^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/.test(v) ? true : "Alphanumeric, hyphens, dots, underscores only"
+      },
+      {
+        type: "number",
+        name: "port",
+        message: "Host port",
+        initial: defaultPort
+      },
+      {
+        type: isRedis ? null : "text",
+        name: "dbName",
+        message: "Database name",
+        initial: "maestro"
+      },
+      {
+        type: isRedis ? null : "password",
+        name: "password",
+        message: "Root password",
+        initial: "maestro"
+      }
+    ],
+    { onCancel }
+  );
+  return {
+    dbType,
+    containerName: answers.containerName,
+    port: answers.port,
+    dbName: answers.dbName ?? "",
+    password: answers.password ?? ""
+  };
+}
+function assertDockerAvailable() {
+  try {
+    execSync("docker info", { stdio: "ignore" });
+  } catch {
+    console.error("Error: Docker is not running. Please start Docker and try again.");
+    process.exit(1);
+  }
+}
+function pull(image) {
+  console.log(`
+Pulling ${image}...`);
+  try {
+    execSync(`docker pull ${image}`, { stdio: "inherit" });
+  } catch {
+    console.error(`
+Failed to pull image ${image}.`);
+    process.exit(1);
+  }
+}
+function run(config, db) {
+  const args = [
+    "docker",
+    "run",
+    "-d",
+    "--name",
+    config.containerName,
+    "-p",
+    `${config.port}:${db.defaultPort}`,
+    ...db.envFlags(config.dbName, config.password),
+    db.image
+  ];
+  try {
+    execSync(args.join(" "), { stdio: "pipe" });
+  } catch (e) {
+    const stderr = e instanceof Error && "stderr" in e ? e.stderr?.toString() : "";
+    console.error(`
+Failed to start container:
+${stderr}`);
+    process.exit(1);
+  }
+}
+function printSummary(config, db) {
+  console.log(`
+Container "${config.containerName}" is running.`);
+  console.log(`  Image:  ${db.image}`);
+  console.log(`  Port:   ${config.port}`);
+  if (config.dbName) console.log(`  DB:     ${config.dbName}`);
+  if (config.password) console.log(`  Pass:   ${config.password}`);
+}
+
+// src/commands/agent.ts
+import { execSync as execSync2 } from "child_process";
+import { AgentContainer } from "@maestro-js/agent-container";
+import prompts3 from "prompts";
+
+// src/utils/agent.ts
+import { Config } from "@maestro-js/config";
+async function resolveAgentConfig(opts) {
+  const config = await Config.getConfig({
+    rootDir: process.cwd(),
+    configName: "agent-container",
+    envName: null,
+    encryptionKey: null
+  });
+  return {
+    memory: opts.memory ?? process.env.AGENT_MEMORY ?? config.AGENT_MEMORY,
+    cpus: opts.cpus ?? (process.env.AGENT_CPUS ?? config.AGENT_CPUS ? Number(process.env.AGENT_CPUS ?? config.AGENT_CPUS) : void 0),
+    workDir: process.env.AGENT_WORK_DIR ?? config.AGENT_WORK_DIR,
+    dockerfile: config.AGENT_DOCKERFILE
+  };
+}
+
+// src/commands/agent.ts
+async function agentMake(name, opts) {
+  const repoPath = opts.repo ?? findGitRoot();
+  const env = parseEnv(opts.env);
+  const agentConfig = await resolveAgentConfig(opts);
+  const container = await AgentContainer.create({ name, repoPath, env, ...agentConfig });
+  console.log(`Make container: ${container.id}`);
+}
+async function agentKill(name) {
+  const target = name ?? await selectContainer("Select a container to kill");
+  if (!target) return;
+  await AgentContainer.kill(target);
+  console.log(`Killed container: ${target}`);
+}
+async function agentShell(name) {
+  const target = name ?? await selectContainer("Select a container to shell into");
+  if (!target) return;
+  await AgentContainer.shell(target);
+}
+async function agentOpen(name) {
+  const target = name ?? await selectContainer("Select a container to open in VS Code");
+  if (!target) return;
+  await AgentContainer.open(target);
+}
+async function agentPull(name, opts) {
+  const target = name ?? await selectContainer("Select a container to pull from");
+  if (!target) return;
+  const repoPath = opts.repo ?? findGitRoot();
+  const result = await AgentContainer.pull(target, repoPath);
+  if (result.applied) {
+    console.log(`Pulled changes from container ${target} \u2192 host`);
+  } else {
+    console.log(`No changes to pull from container ${target}`);
+  }
+}
+async function selectContainer(message) {
+  const containers = await AgentContainer.list();
+  if (containers.length === 0) {
+    console.log("No running agent containers.");
+    return;
+  }
+  const onCancel3 = () => process.exit(0);
+  const { name } = await prompts3(
+    {
+      type: "select",
+      name: "name",
+      message,
+      choices: containers.map((c) => ({ title: `${c.name.replace("maestro-agent-", "")}  (${c.status})`, value: c.name }))
+    },
+    { onCancel: onCancel3 }
+  );
+  return name;
+}
+function findGitRoot() {
+  try {
+    return execSync2("git rev-parse --show-toplevel", { encoding: "utf8" }).trim();
+  } catch {
+    return process.cwd();
+  }
+}
+function parseEnv(env) {
+  if (!env) return {};
+  const entries = Array.isArray(env) ? env : [env];
+  return Object.fromEntries(
+    entries.map((e) => {
+      const i = e.indexOf("=");
+      return [e.slice(0, i), e.slice(i + 1)];
+    })
+  );
+}
+
+// src/commands/db-migrations.ts
+import { join } from "path";
+import { DbMigrations } from "@maestro-js/db-migrate";
+
+// src/utils/db.ts
+import { Config as Config2 } from "@maestro-js/config";
+import { Db } from "@maestro-js/db";
+async function resolveDbConfig(opts) {
+  const config = await Config2.getConfig({
+    rootDir: process.cwd(),
+    configName: "db-migrate",
+    envName: null,
+    encryptionKey: null
+  });
+  const database = opts.database ?? process.env.DB_DATABASE ?? config.DB_DATABASE;
+  const host = opts.host ?? process.env.DB_HOST ?? config.DB_HOST ?? "localhost";
+  const port = opts.port ?? (process.env.DB_PORT ?? config.DB_PORT ? Number(process.env.DB_PORT ?? config.DB_PORT) : 3306);
+  const user = opts.user ?? process.env.DB_USER ?? config.DB_USER ?? "root";
+  const password = opts.password ?? process.env.DB_PASSWORD ?? config.DB_PASSWORD ?? "err";
+  if (!database) {
+    console.error("Error: --database flag or DB_DATABASE env var is required.");
+    process.exit(1);
+  }
+  const resolved = {
+    host,
+    port,
+    user,
+    password,
+    database
+  };
+  console.log(resolved);
+  return resolved;
+}
+async function createDb(config) {
+  return Db.Provider.create({
+    driver: Db.drivers.mysql({
+      host: config.host,
+      port: config.port,
+      user: config.user,
+      password: config.password,
+      database: config.database,
+      multipleStatements: true
+    })
+  });
+}
+
+// src/commands/db-migrations.ts
+async function dbMakeMigration(name) {
+  const dir = join(process.cwd(), "infrastructure", "db-migrations");
+  const files = await DbMigrations.scaffold({ name, dir });
+  const cwd = process.cwd();
+  console.log(`Created migration:`);
+  console.log(`  ${files.ts.replace(cwd + "/", "")}`);
+  console.log(`  ${files.upSql.replace(cwd + "/", "")}`);
+  console.log(`  ${files.downSql.replace(cwd + "/", "")}`);
+}
+async function dbMigrate(opts) {
+  const config = await resolveDbConfig(opts);
+  const db = await createDb(config);
+  try {
+    const dir = join(process.cwd(), "infrastructure", "db-migrations");
+    const results = await DbMigrations.migrate(db, dir, {
+      dryRun: opts["dry-run"],
+      count: opts.count
+    });
+    if (!results.length) {
+      console.log("No pending migrations.");
+      return;
+    }
+    const prefix = opts["dry-run"] ? "[dry-run] " : "";
+    for (const r of results) {
+      console.log(`${prefix}Migrated: ${r.filename} (${r.durationMs}ms)`);
+    }
+  } finally {
+    await db.destroy();
+  }
+}
+async function dbRollback(opts) {
+  const config = await resolveDbConfig(opts);
+  const db = await createDb(config);
+  try {
+    const dir = join(process.cwd(), "infrastructure", "db-migrations");
+    const results = await DbMigrations.rollback(db, dir, {
+      dryRun: opts["dry-run"],
+      count: opts.count ?? 1
+    });
+    if (!results.length) {
+      console.log("Nothing to rollback.");
+      return;
+    }
+    const prefix = opts["dry-run"] ? "[dry-run] " : "";
+    for (const r of results) {
+      console.log(`${prefix}Rolled back: ${r.filename} (${r.durationMs}ms)`);
+    }
+  } finally {
+    await db.destroy();
+  }
+}
+async function dbStatus(opts) {
+  const config = await resolveDbConfig(opts);
+  const db = await createDb(config);
+  try {
+    const dir = join(process.cwd(), "infrastructure", "db-migrations");
+    const statuses = await DbMigrations.status(db, dir);
+    if (!statuses.length) {
+      console.log("No migrations found.");
+      return;
+    }
+    for (const s of statuses) {
+      if (s.applied) {
+        console.log(`[x] ${s.filename} (applied ${s.run_on})`);
+      } else {
+        console.log(`[ ] ${s.filename} (pending)`);
+      }
+    }
+  } finally {
+    await db.destroy();
+  }
+}
+
+// src/commands/env.ts
+import { Config as Config3 } from "@maestro-js/config";
+function envGenKey() {
+  const key = Config3.generateEncryptionKey();
+  console.log(key);
+}
+function envEncrypt(opts) {
+  const encryptionKey = opts.key || process.env.MAESTRO_ENV_ENCRYPTION_KEY;
+  if (!encryptionKey) {
+    console.error("Encryption key is required. Use --key or set MAESTRO_ENV_ENCRYPTION_KEY.");
+    process.exit(1);
+  }
+  const envName = opts.env || null;
+  Config3.generateEncryptedEnvFile({
+    rootDir: process.cwd(),
+    envName,
+    encryptionKey
+  });
+  const base = envName ? `.env.${envName}` : ".env";
+  console.log(`Encrypted ${base} \u2192 ${base}.encrypted`);
+}
+function envDecrypt(opts) {
+  const encryptionKey = opts.key || process.env.MAESTRO_ENV_ENCRYPTION_KEY;
+  if (!encryptionKey) {
+    console.error("Encryption key is required. Use --key or set MAESTRO_ENV_ENCRYPTION_KEY.");
+    process.exit(1);
+  }
+  const envName = opts.env || null;
+  Config3.generateDecryptedEnvFile({
+    rootDir: process.cwd(),
+    envName,
+    encryptionKey,
+    force: opts.force
+  });
+  const base = envName ? `.env.${envName}` : ".env";
+  console.log(`Decrypted ${base}.encrypted \u2192 ${base}`);
+}
+
+// src/commands/crypt.ts
+import crypto from "crypto";
+function cryptMakeKey() {
+  const key = crypto.randomBytes(32).toString("base64");
+  console.log(key);
+}
+
+// src/commands/hash.ts
+import crypto2 from "crypto";
+function hashMakeKey() {
+  const key = crypto2.randomBytes(32).toString("base64");
+  console.log(key);
+}
+
+// src/commands/config.ts
+import { execSync as execSync3 } from "child_process";
+import { Config as Config4 } from "@maestro-js/config";
+async function configRun(opts) {
+  const configName = opts.config;
+  if (!configName) {
+    console.error("Missing required --config <name> option");
+    process.exit(1);
+  }
+  const rootDir = opts.root ?? process.cwd();
+  const envName = opts.env ?? null;
+  const encryptionKey = opts.key ?? process.env["MAESTRO_ENV_ENCRYPTION_KEY"] ?? null;
+  const config = await Config4.getConfig({ rootDir, configName, envName, encryptionKey });
+  const command = opts._.join(" ");
+  if (!command) {
+    console.error("No command provided. Usage: maestro config:run --config <name> [options] -- <command>");
+    process.exit(1);
+  }
+  execSync3(command, {
+    stdio: "inherit",
+    env: { ...process.env, ...config }
+  });
+}
+
+// src/commands/components.ts
+import { Components } from "@maestro-js/components";
+async function componentsList() {
+  const names = await Components.list();
+  for (const name of names) {
+    console.log(name);
+  }
+}
+async function componentsAdd(name, opts) {
+  const components = opts.all ? await Components.list() : [name, ...opts._ || []];
+  const directory = opts.directory || process.cwd();
+  const written = await Components.add({ components, directory, overwrite: opts.overwrite });
+  for (const file of written) {
+    console.log(file);
+  }
+}
+
+// src/commands/upgrade.ts
+import { execSync as execSync4 } from "child_process";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import prompts4 from "prompts";
+var onCancel2 = () => process.exit(0);
+async function upgrade() {
+  const current = getCurrentVersion();
+  console.log(`Current @maestro-js version: ${current}`);
+  const versions = fetchAvailableVersions();
+  const newer = filterNewerVersions(versions, current);
+  if (newer.length === 0) {
+    console.log("Already on the latest version.");
+    return;
+  }
+  const choices = buildVersionChoices(newer, current);
+  const target = await promptForVersion(choices);
+  const updated = findAndUpdatePackageJsonFiles(target);
+  if (updated === 0) {
+    console.log("No @maestro-js/* dependencies found in any package.json.");
+    return;
+  }
+  console.log(`
+Updated ${updated} package.json file${updated === 1 ? "" : "s"}.`);
+  await runInstall();
+}
+function getCurrentVersion() {
+  const dir = path.dirname(fileURLToPath(import.meta.url));
+  const raw = fs.readFileSync(path.join(dir, "../package.json"), "utf-8");
+  const pkg = JSON.parse(raw);
+  return pkg.version;
+}
+function fetchAvailableVersions() {
+  try {
+    const raw = execSync4("npm view @maestro-js/cli versions --json", { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
+    const parsed = JSON.parse(raw);
+    if (typeof parsed === "string") return [parsed];
+    if (Array.isArray(parsed)) return parsed;
+    return [];
+  } catch {
+    console.error("Failed to fetch available versions from npm registry.");
+    process.exit(1);
+  }
+}
+function filterNewerVersions(versions, current) {
+  return versions.filter((v) => compareSemver(v, current) > 0);
+}
+function buildVersionChoices(versions, current) {
+  const currentMajor = parseSemver(current).major;
+  const byMajor = /* @__PURE__ */ new Map();
+  for (const v of versions) {
+    const { major } = parseSemver(v);
+    const existing = byMajor.get(major);
+    if (existing) {
+      existing.push(v);
+    } else {
+      byMajor.set(major, [v]);
+    }
+  }
+  const choices = [];
+  for (const [major, group] of [...byMajor.entries()].sort((a, b) => a[0] - b[0])) {
+    const latest = group.sort(compareSemver).at(-1);
+    const label = major > currentMajor ? `${latest} [major upgrade]` : latest;
+    choices.push({ title: label, value: latest });
+  }
+  return choices.reverse();
+}
+async function promptForVersion(choices) {
+  const { version: version2 } = await prompts4(
+    {
+      type: "select",
+      name: "version",
+      message: "Which version?",
+      choices
+    },
+    { onCancel: onCancel2 }
+  );
+  return version2;
+}
+function findAndUpdatePackageJsonFiles(targetVersion) {
+  const root = process.cwd();
+  const files = findPackageJsonFiles(root);
+  let updated = 0;
+  for (const filePath of files) {
+    if (updateMaestroDependencies(filePath, targetVersion)) {
+      updated++;
+    }
+  }
+  return updated;
+}
+function findPackageJsonFiles(dir) {
+  const results = [];
+  const skipDirs = /* @__PURE__ */ new Set(["node_modules", ".git", "dist", ".next", ".nuxt"]);
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (!skipDirs.has(entry.name)) {
+        results.push(...findPackageJsonFiles(path.join(dir, entry.name)));
+      }
+    } else if (entry.name === "package.json") {
+      results.push(path.join(dir, entry.name));
+    }
+  }
+  return results;
+}
+function updateMaestroDependencies(filePath, targetVersion) {
+  const raw = fs.readFileSync(filePath, "utf-8");
+  const pkg = JSON.parse(raw);
+  let changed = false;
+  for (const depKey of ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"]) {
+    const deps = pkg[depKey];
+    if (!deps || typeof deps !== "object") continue;
+    for (const [name, value] of Object.entries(deps)) {
+      if (!name.startsWith("@maestro-js/")) continue;
+      if (value.startsWith("workspace:")) continue;
+      const prefix = value.match(/^([^\d]*)/)?.[1] ?? "";
+      const newValue = `${prefix}${targetVersion}`;
+      if (value !== newValue) {
+        ;
+        deps[name] = newValue;
+        changed = true;
+      }
+    }
+  }
+  if (changed) {
+    const indent = detectIndent(raw);
+    const trailingNewline = raw.endsWith("\n");
+    let output = JSON.stringify(pkg, null, indent);
+    if (trailingNewline) output += "\n";
+    fs.writeFileSync(filePath, output, "utf-8");
+    console.log(`  Updated ${path.relative(process.cwd(), filePath)}`);
+  }
+  return changed;
+}
+async function runInstall() {
+  const pm = detectPackageManager();
+  console.log(`
+Running ${pm} install...`);
+  try {
+    execSync4(`${pm} install`, { stdio: "inherit", cwd: process.cwd() });
+    console.log("Done.");
+  } catch {
+    console.warn(`
+${pm} install failed. package.json files have been updated \u2014 run install manually.`);
+  }
+}
+function detectPackageManager() {
+  const root = process.cwd();
+  try {
+    const raw = fs.readFileSync(path.join(root, "package.json"), "utf-8");
+    const pkg = JSON.parse(raw);
+    if (pkg.packageManager) {
+      const name = pkg.packageManager.split("@")[0];
+      if (["pnpm", "yarn", "npm"].includes(name)) return name;
+    }
+  } catch {
+  }
+  if (fs.existsSync(path.join(root, "pnpm-lock.yaml"))) return "pnpm";
+  if (fs.existsSync(path.join(root, "yarn.lock"))) return "yarn";
+  return "npm";
+}
+function detectIndent(json) {
+  const match = json.match(/^[\t ]*(?=")/m);
+  return match?.[0]?.length ?? 2;
+}
+function parseSemver(version2) {
+  const idx = version2.indexOf("-");
+  const core = idx === -1 ? version2 : version2.slice(0, idx);
+  const pre = idx === -1 ? "" : version2.slice(idx + 1);
+  const [major = 0, minor = 0, patch = 0] = core.split(".").map(Number);
+  return { major, minor, patch, prerelease: pre ? pre.split(/[.-]/) : [] };
+}
+var PRE_ORDER = { alpha: 0, beta: 1, rc: 2 };
+function compareSemver(a, b) {
+  const sa = parseSemver(a);
+  const sb = parseSemver(b);
+  const d = sa.major - sb.major || sa.minor - sb.minor || sa.patch - sb.patch;
+  if (d !== 0) return d;
+  if (sa.prerelease.length === 0 && sb.prerelease.length === 0) return 0;
+  if (sa.prerelease.length === 0) return 1;
+  if (sb.prerelease.length === 0) return -1;
+  const maxLen = Math.max(sa.prerelease.length, sb.prerelease.length);
+  for (let i = 0; i < maxLen; i++) {
+    const pa = sa.prerelease[i];
+    const pb = sb.prerelease[i];
+    if (pa === void 0) return -1;
+    if (pb === void 0) return 1;
+    if (pa === pb) continue;
+    const na = PRE_ORDER[pa] ?? -1;
+    const nb = PRE_ORDER[pb] ?? -1;
+    if (na !== -1 || nb !== -1) return na - nb;
+    const numA = Number(pa);
+    const numB = Number(pb);
+    if (!Number.isNaN(numA) && !Number.isNaN(numB)) return numA - numB;
+    return pa < pb ? -1 : 1;
+  }
+  return 0;
+}
+
+// src/bin.ts
+var require2 = createRequire(import.meta.url);
+var { version } = require2("../package.json");
+var prog = sade("maestro").version(version);
+prog.command("aws:make-wireguard-client [id]").describe("Add a WireGuard client peer to an existing VPN server").option("--region", "AWS region (env: AWS_REGION)").option("--name", "Label for the peer").option("--endpoint", "Override auto-detected server IP").option("--dns", "DNS for client config").option("--allowed-ips", "Client AllowedIPs", "10.0.0.0/16, 10.100.0.0/24").action(awsMakeWireguardClient);
+prog.command("db:make-migration <name>").describe("Create a new database migration").action(dbMakeMigration);
+prog.command("db:make-container").describe("Create a Docker database container").action(createDockerDb);
+prog.command("db:migrate").describe("Run pending database migrations").option("--host", "Database host (env: DB_HOST)").option("--port", "Database port (env: DB_PORT)").option("--user", "Database user (env: DB_USER)").option("--password", "Database password (env: DB_PASSWORD)").option("--database", "Database name (env: DB_DATABASE)").option("--dry-run", "Preview migrations without executing").option("--count", "Number of migrations to run").action(dbMigrate);
+prog.command("db:rollback").describe("Rollback database migrations").option("--host", "Database host (env: DB_HOST)").option("--port", "Database port (env: DB_PORT)").option("--user", "Database user (env: DB_USER)").option("--password", "Database password (env: DB_PASSWORD)").option("--database", "Database name (env: DB_DATABASE)").option("--dry-run", "Preview rollback without executing").option("--count", "Number of migrations to rollback", 1).action(dbRollback);
+prog.command("db:status").describe("Show database migration status").option("--host", "Database host (env: DB_HOST)").option("--port", "Database port (env: DB_PORT)").option("--user", "Database user (env: DB_USER)").option("--password", "Database password (env: DB_PASSWORD)").option("--database", "Database name (env: DB_DATABASE)").action(dbStatus);
+prog.command("env:generate-key").describe("Generate an encryption key").action(envGenKey);
+prog.command("crypt:make-key").describe("Generate an encryption key for use with @maestro-js/crypt").action(cryptMakeKey);
+prog.command("hash:make-key").describe("Generate a signing key for use with @maestro-js/hash").action(hashMakeKey);
+prog.command("env:encrypt").describe("Encrypt a .env file").option("--env", "Environment name (e.g. production)").option("--key", "Encryption key (env: MAESTRO_ENV_ENCRYPTION_KEY)").action(envEncrypt);
+prog.command("env:decrypt").describe("Decrypt a .env.encrypted file").option("--env", "Environment name (e.g. production)").option("--key", "Encryption key (env: MAESTRO_ENV_ENCRYPTION_KEY)").option("--force", "Overwrite existing .env file").action(envDecrypt);
+prog.command("components:list").describe("List available components").action(componentsList);
+prog.command("components:add [name]").describe("Add components to the current project").option("--directory", "Target directory (default: cwd)").option("--overwrite", "Overwrite existing files").option("--all", "Add all available components").action(componentsAdd);
+prog.command("config:run").describe("Resolve config and run a command with the config values as environment variables").option("--config", "Config name (required)").option("--root", "Project root directory (default: cwd)").option("--env", "Environment name (e.g. production)").option("--key", "Encryption key (env: MAESTRO_ENV_ENCRYPTION_KEY)").action(configRun);
+prog.command("upgrade").describe("Upgrade @maestro-js/* packages to a newer version").action(upgrade);
+prog.command("agent:make [name]").describe("Launch an interactive shell in an isolated Docker agent container").option("--repo", "Path to the repository (default: cwd)").option("--env", "Environment variable as KEY=VALUE (repeatable)").option("--memory", "Memory limit (env: AGENT_MEMORY)").option("--cpus", "Number of CPUs (env: AGENT_CPUS)").action(agentMake);
+prog.command("agent:kill [name]").describe("Kill an agent container (prompts if no name given)").action(agentKill);
+prog.command("agent:shell [name]").describe("Shell into an agent container (prompts if no name given)").action(agentShell);
+prog.command("agent:pull [name]").describe("Pull container changes onto the host working tree (prompts if no name given)").option("--repo", "Path to the repository (default: cwd git root)").action(agentPull);
+prog.command("agent:open [name]").describe("Open an agent container in VS Code (prompts if no name given)").action(agentOpen);
+prog.parse(process.argv);

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@maestro-js/cli",
+  "description": "Skill for the @maestro-js/cli package, the command-line interface for the Maestro framework. Use when working with @maestro-js/cli or the maestro-cli package directory. Key capabilities: database migrations (create, run, rollback, status), environment encryption/decryption, Docker database container creation, and AWS WireGuard VPN client provisioning. Trigger when adding CLI commands, modifying migration workflows, working with env encryption, or integrating new Maestro packages into the CLI.",
+  "type": "module",
+  "bin": {
+    "maestro": "./dist/bin.js"
+  },
+  "exports": {},
+  "dependencies": {
+    "@aws-sdk/client-ssm": "^3.750.0",
+    "@aws-sdk/client-sts": "^3.993.0",
+    "prompts": "^2.4.2",
+    "sade": "^1.8.1",
+    "@maestro-js/components": "1.0.0-alpha.0",
+    "@maestro-js/config": "1.0.0-alpha.0",
+    "@maestro-js/db-migrate": "1.0.0-alpha.0",
+    "@maestro-js/agent-container": "1.0.0-alpha.0",
+    "@maestro-js/db": "1.0.0-alpha.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.11",
+    "@types/prompts": "^2.4.9"
+  },
+  "version": "1.0.0-alpha.0",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "repository": "https://github.com/Marcato-Partners/maestro-js",
+  "scripts": {
+    "build": "tsup",
+    "watch": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "format": "prettier --write src/",
+    "lint": "prettier --check src/"
+  }
+}