@occam-scaly/scaly-cli 0.1.0

package/bin/scaly.js

@@ -0,0 +1,3083 @@
+#!/usr/bin/env node
+'use strict';
+
+const { spawnSync } = require('child_process');
+const path = require('path');
+
+function run(cmd, args, opts = {}) {
+  const res = spawnSync(cmd, args, { stdio: 'inherit', shell: false, ...opts });
+  if (res.error) throw res.error;
+  return res.status || 0;
+}
+
+function inVault() {
+  return (
+    Boolean(process.env.AWS_VAULT) || Boolean(process.env.AWS_ACCESS_KEY_ID)
+  );
+}
+
+function withVault(args) {
+  // Default to scaly-dev unless AWS_VAULT already active
+  if (inVault()) return args;
+  const profile = process.env.SCALY_PROFILE || 'scaly-dev';
+  return ['aws-vault', 'exec', profile, '--', ...args];
+}
+
+function shellQuote(arg) {
+  if (/^[A-Za-z0-9_/:.=+-]+$/.test(arg)) {
+    return arg;
+  }
+  return `'${arg.replace(/'/g, "'\\''")}'`;
+}
+
+function normalizeCommand(cmd) {
+  if (Array.isArray(cmd)) {
+    return cmd.map(shellQuote).join(' ');
+  }
+  return cmd;
+}
+
+function isProbablyJwt(token) {
+  // Fast heuristic: three dot-separated base64url-ish segments.
+  // This is intentionally loose; we just want to distinguish JWTs from API keys.
+  return typeof token === 'string' && token.split('.').length === 3;
+}
+
+function withDeployerEnv(inner) {
+  // Load deployer env if present so helpers can reach API without extra flags
+  const command = normalizeCommand(inner);
+  const pre = [
+    'bash',
+    '-lc',
+    `set -a && [ -f .env.dev.scaly-deployer.local ] && source .env.dev.scaly-deployer.local || true && set +a && ${command}`
+  ];
+  return inVault() ? pre : withVault(pre);
+}
+
+function printHelp() {
+  console.log(`
+Scaly CLI (preview)
+
+Usage:
+  scaly init [--force]
+  scaly plan  [--env dev|prod] [--app <name>] [--json]
+  scaly apply [--env dev|prod] [--app <name>] --plan-hash <sha256:...> [--auto-approve] [--json]
+  scaly pull  [--force] [--stack <id>] [--app <id>] [--json]
+
+  scaly auth login  [--stage prod|dev|qa] [--no-open]
+  scaly auth status [--json]
+  scaly auth logout [--json]
+
+  scaly secrets list --app <appId> [--json]
+  scaly secrets set  --app <appId> --name <KEY> [--from-env ENV] [--stdin] [--json]
+  scaly secrets delete --app <appId> (--name <KEY> | --id <secretId>) [--yes] [--json]
+  scaly secrets sync --app <appId> [--config-app <name>] [--env dev|prod] [--dry-run] [--apply] [--json]
+
+  scaly login --token <api-bearer> [--endpoint https://api.<stage>.scalyapps.io/graphql] | --clear
+  scaly db connect --addon <addOnId> [--ttl-minutes 60] [--local-port 5432] [--host 127.0.0.1] [--copy] [--show] [--json]
+  scaly db shell  --addon <addOnId> [--ttl-minutes 60] [--local-port 5432] [--host 127.0.0.1]
+  scaly db schema dump --addon <addOnId> [--out .scaly/schema.sql] [--ttl-minutes 60]
+  scaly db migrate <sql-file> --addon <addOnId> [--ttl-minutes 60] [--yes]
+  scaly deploy --app <appId> [--watch] [--strategy auto|git|restart] [--json]
+  scaly logs --follow --app <appId> [--since 10m] [--level error|warn|info|debug|all] [--q <str>] [--duration-seconds N] [--max-lines N] [--json]
+  scaly accounts create --email <email> [--name <org>] [--region EU|US|CANADA|ASIA_PACIFIC]
+  scaly stacks create --account <id> --name <stackName> [--size Eco|Basic|...] [--min-idle N]
+  scaly apps create   --account <id> [--stack <id>] --name <appName> [--template <tpl>]
+  scaly logs stack   --id <stackId> [--since 30m] [--limit 300] [--json]
+  scaly logs account --id <accountId> [--since 30m] [--limit 300] [--json]
+  scaly logs tail stack <stackId>
+  scaly logs tail app   <appId>
+  scaly e2e eu-smoke --template fastapi-hello|flask-hello|streamlit-hello
+  scaly insights diagnose-app --account <acctId> --stack <stackId> --app <name> [--json]
+
+Notes:
+  - Wraps existing npm QA helpers and auto-loads .env.dev.scaly-deployer.local
+  - If no AWS creds in env, runs under 'aws-vault exec scaly-dev'
+  - DB tunnel requires a short-lived Scaly session token. Run: scaly auth login
+`);
+}
+
+function main(argv) {
+  const [_node, _bin, cmd, sub, ...rest] = argv;
+  const args = sub ? [sub, ...rest] : rest;
+
+  const parseFlags = (arr) => {
+    const out = {};
+    for (let i = 0; i < arr.length; i++) {
+      const a = arr[i];
+      if (a.startsWith('--')) {
+        const key = a.slice(2);
+        const val =
+          arr[i + 1] && !arr[i + 1].startsWith('--') ? arr[++i] : 'true';
+        out[key] = val;
+      } else if (!out._) {
+        out._ = [a];
+      } else {
+        out._.push(a);
+      }
+    }
+    return out;
+  };
+
+  if (!cmd || cmd === '-h' || cmd === '--help') return printHelp();
+
+  if (cmd === 'login') {
+    return runLogin(sub, rest).then((code) => process.exit(code));
+  }
+
+  if (cmd === 'auth') {
+    const flags = parseFlags(args);
+    const { runAuth } = require('../lib/scaly-auth');
+    return runAuth(sub, flags).then((code) => process.exit(code));
+  }
+
+  if (cmd === 'secrets') {
+    return runSecrets(sub, rest).then((code) => process.exit(code));
+  }
+
+  if (cmd === 'deploy') {
+    return runDeploy([sub, ...rest].filter(Boolean)).then((code) =>
+      process.exit(code)
+    );
+  }
+
+  if (cmd === 'init') {
+    return runProjectInit(args).then((code) => process.exit(code));
+  }
+
+  if (cmd === 'plan') {
+    return runProjectPlan(args).then((code) => process.exit(code));
+  }
+
+  if (cmd === 'apply') {
+    return runProjectApply(args).then((code) => process.exit(code));
+  }
+
+  if (cmd === 'pull') {
+    return runProjectPull(args).then((code) => process.exit(code));
+  }
+
+  if (cmd === 'db' && sub === 'connect') {
+    return runDbConnect(rest).then((code) => process.exit(code));
+  }
+  if (cmd === 'db' && sub === 'shell') {
+    return runDbShell(rest).then((code) => process.exit(code));
+  }
+  if (cmd === 'db' && sub === 'schema' && rest[0] === 'dump') {
+    return runDbSchemaDump(rest.slice(1)).then((code) => process.exit(code));
+  }
+  if (cmd === 'db' && sub === 'migrate') {
+    return runDbMigrate(rest).then((code) => process.exit(code));
+  }
+
+  if (cmd === 'accounts' && sub === 'create') {
+    const f = parseFlags(rest);
+    if (!f.email) {
+      console.error('--email is required');
+      process.exit(2);
+    }
+    const regionArg = f.region ? ['--region', f.region] : [];
+    const nameArg = f.name ? ['--name', f.name] : [];
+    const args = withDeployerEnv([
+      'npm',
+      'run',
+      'qa:create-account',
+      '--',
+      '--email',
+      f.email,
+      ...nameArg,
+      ...regionArg
+    ]);
+    process.exit(run(args[0], args.slice(1)));
+  }
+
+  if (cmd === 'apps' && sub === 'update') {
+    return runAppsUpdate(rest).then((code) => process.exit(code));
+  }
+
+  if (cmd === 'apps' && sub === 'delete') {
+    return runAppsDelete(rest).then((code) => process.exit(code));
+  }
+
+  if (cmd === 'apps' && sub === 'delete-by-prefix') {
+    return runAppsDeleteByPrefix(rest).then((code) => process.exit(code));
+  }
+
+  if (cmd === 'stacks' && sub === 'create') {
+    const f = parseFlags(rest);
+    if (!f.account) {
+      console.error('--account is required');
+      process.exit(2);
+    }
+    const nameArg = f.name ? ['--name', f.name] : [];
+    const sizeArg = f.size ? ['--size', f.size] : [];
+    const minIdleArg = f['min-idle'] ? ['--min-idle', f['min-idle']] : [];
+    const args = withDeployerEnv([
+      'npm',
+      'run',
+      'qa:create-stack',
+      '--',
+      '--account',
+      f.account,
+      ...nameArg,
+      ...sizeArg,
+      ...minIdleArg
+    ]);
+    process.exit(run(args[0], args.slice(1)));
+  }
+
+  if (cmd === 'stacks' && sub === 'update') {
+    return runStacksUpdate(rest).then((code) => process.exit(code));
+  }
+
+  if (cmd === 'stacks' && sub === 'delete') {
+    return runStacksDelete(rest).then((code) => process.exit(code));
+  }
+
+  if (cmd === 'stacks' && sub === 'delete-by-prefix') {
+    return runStacksDeleteByPrefix(rest).then((code) => process.exit(code));
+  }
+
+  if (cmd === 'cleanup' && sub === 'purge') {
+    return runCleanupPurge(rest).then((code) => process.exit(code));
+  }
+
+  if (cmd === 'apps' && sub === 'create') {
+    const f = parseFlags(rest);
+    if (!f.account) {
+      console.error('--account is required');
+      process.exit(2);
+    }
+    const stackArg = f.stack ? ['--stack', f.stack] : [];
+    const nameArg = f.name ? ['--name', f.name] : [];
+    const tplArg = f.template ? ['--template', f.template] : [];
+    const args = withDeployerEnv([
+      'npm',
+      'run',
+      'qa:create-app',
+      '--',
+      '--account',
+      f.account,
+      ...stackArg,
+      ...nameArg,
+      ...tplArg
+    ]);
+    process.exit(run(args[0], args.slice(1)));
+  }
+
+  if (cmd === 'logs' && sub === 'tail') {
+    const kind = rest[0];
+    const id = rest[1];
+    if (!kind || !id) {
+      console.error('Usage: scaly logs tail <stack|app> <id>');
+      process.exit(2);
+    }
+    const script = kind === 'stack' ? 'qa:tail-stack' : 'qa:tail-app';
+    const args = withDeployerEnv(['npm', 'run', script, '--', id]);
+    process.exit(run(args[0], args.slice(1)));
+  }
+
+  if (
+    cmd === 'logs' &&
+    (sub === 'follow' || sub === '--follow' || rest.includes('--follow'))
+  ) {
+    const combined = sub && sub.startsWith('--') ? [sub, ...rest] : rest;
+    return runLogsFollow(combined).then((code) => process.exit(code));
+  }
+
+  if (cmd === 'logs' && sub === 'stack') {
+    return runLogsGql('stack', rest).then((code) => process.exit(code));
+  }
+  if (cmd === 'logs' && sub === 'account') {
+    return runLogsGql('account', rest).then((code) => process.exit(code));
+  }
+
+  if (
+    cmd === 'e2e' &&
+    (sub === 'eu-smoke' || sub === 'eu-smoke-node' || sub === 'eu-smoke-r')
+  ) {
+    return runEuSmokeFromArgs(sub, rest).then((code) => process.exit(code));
+  }
+
+  if (cmd === 'insights' && sub === 'diagnose-app') {
+    return runDiagnoseApp(rest).then((code) => process.exit(code));
+  }
+
+  if (cmd === 'auth' && sub === 'aws') {
+    return runAuthAws(rest).then((code) => process.exit(code));
+  }
+
+  if (cmd === 'templates' && sub === 'matrix') {
+    return runTemplatesMatrix(rest).then((code) => process.exit(code));
+  }
+
+  printHelp();
+}
+
+async function runEuSmokeFromArgs(which, rest) {
+  const f = (function parseFlags(arr) {
+    const out = {};
+    for (let i = 0; i < arr.length; i++) {
+      const a = arr[i];
+      if (a.startsWith('--')) {
+        const key = a.slice(2);
+        const val =
+          arr[i + 1] && !arr[i + 1].startsWith('--') ? arr[++i] : 'true';
+        out[key] = val;
+      } else if (!out._) {
+        out._ = [a];
+      } else {
+        out._.push(a);
+      }
+    }
+    return out;
+  })(rest);
+
+  // Ensure we run under aws-vault if creds not present
+  if (!inVault()) {
+    const repl = withVault(['node', __filename, 'e2e', which, ...rest]);
+    return run(repl[0], repl.slice(1));
+  }
+
+  // Default template per variant
+  if (!f.template) {
+    if (which === 'eu-smoke-node') f.template = 'react-nest-hello';
+    else if (which === 'eu-smoke-r') f.template = 'shiny-r-hello';
+    else f.template = 'fastapi-hello';
+  }
+  return runEuSmoke(f);
+}
+
+async function runEuSmoke(f) {
+  const template = f.template || 'fastapi-hello';
+  const name = f.name || `qa-${template}-${Date.now().toString(36)}`;
+  const accountId = f.account;
+  const stackId = f.stack;
+  if (!accountId || !stackId) {
+    console.error('--account and --stack are required for e2e eu-smoke');
+    return 2;
+  }
+
+  // Load deployer env if present
+  await sourceLocalEnv();
+
+  const { getToken, apiPost, deriveDomain, regionToAws } =
+    await importHelpers();
+  try {
+    const token = await getToken();
+
+    // 1) Create app and queue template deploy
+    const createRes = await apiPost(token, CREATE_APP_MUTATION, {
+      data: {
+        account: { connect: { id: accountId } },
+        name,
+        minIdle: 0,
+        stack: { connect: { id: stackId } }
+      }
+    });
+    const app = createRes?.createApp;
+    if (!app?.id) throw new Error('createApp did not return id');
+
+    console.log(`[smoke] created app ${app.name} (${app.id})`);
+    await apiPost(token, DEPLOY_TEMPLATE_APP_MUTATION, {
+      appId: app.id,
+      templateId: template
+    });
+
+    // 2) Wait for deployment to complete
+    const depList = await apiPost(token, LIST_DEPLOYMENTS_QUERY, {
+      appId: app.id
+    });
+    let deploymentId = depList?.listDeployments?.[0]?.id;
+    if (!deploymentId)
+      throw new Error('no deployment id after queuing template');
+
+    const deadline =
+      Date.now() + (Number(f['timeout-minutes']) || 20) * 60 * 1000;
+    const pollMs = (Number(f['poll-seconds']) || 10) * 1000;
+    let status = '';
+    while (Date.now() < deadline) {
+      const dep = await apiPost(token, GET_DEPLOYMENT_QUERY, {
+        id: deploymentId
+      });
+      const d = dep?.getDeployment;
+      if (d && d.status !== status) {
+        status = d.status;
+        console.log(
+          `[smoke] deployment ${deploymentId} status=${status} step=${d.step || 'n/a'}`
+        );
+      }
+      if (d && ['Successful', 'Failed', 'Cancelled'].includes(d.status)) break;
+      await wait(pollMs);
+    }
+    const finished = await apiPost(token, GET_DEPLOYMENT_QUERY, {
+      id: deploymentId
+    });
+    const finalDep = finished?.getDeployment;
+    if (!finalDep || finalDep.status !== 'Successful') {
+      console.error(
+        '[smoke] deployment did not succeed',
+        JSON.stringify(finalDep || {}, null, 2)
+      );
+      return 1;
+    }
+
+    // 3) Resolve URL
+    const stackRes = await apiPost(token, GET_STACK_QUERY, {
+      where: { id: stackId }
+    });
+    const stack = stackRes?.getStack;
+    if (!stack?.name) throw new Error('could not resolve stack name');
+    const domain = deriveDomain();
+    const accountPrefix = String(accountId).split('-')[0];
+    const url = `https://${accountPrefix}-${stack.name}.${domain}/${name}/`;
+
+    // 4) HTTP 200 check with backoff
+    const tries = Number(f.tries) > 0 ? Number(f.tries) : 12;
+    const delayMs = Number(f['delay-ms']) > 0 ? Number(f['delay-ms']) : 5000;
+    const httpOk = await checkHttp200(url, { tries, delayMs });
+
+    // 5) CloudWatch logs check in EU region (or account region if available)
+    const regionEnum = stack?.account?.region || 'EU';
+    const logRegion = regionToAws(regionEnum) || 'eu-west-1';
+    const logs = await checkCloudwatchLogs(accountId, app.id, logRegion);
+
+    const summary = {
+      ok: Boolean(httpOk) && logs.found,
+      url,
+      http: httpOk,
+      logs,
+      app: { id: app.id, name: app.name },
+      stack: { id: stackId, name: stack.name },
+      accountId
+    };
+    if (f.json && String(f.json).toLowerCase() !== 'false') {
+      console.log(JSON.stringify(summary));
+    } else {
+      console.log('SMOKE_RESULT:', JSON.stringify(summary, null, 2));
+    }
+    return summary.ok ? 0 : 1;
+  } catch (err) {
+    console.error('[smoke] error', (err && err.stack) || err);
+    return 1;
+  }
+}
+
+async function sourceLocalEnv() {
+  const fs = require('fs');
+  const p = '.env.dev.scaly-deployer.local';
+  if (!fs.existsSync(p)) return;
+  const text = fs.readFileSync(p, 'utf8');
+  for (const line of text.split(/\r?\n/)) {
+    if (!line || line.trim().startsWith('#')) continue;
+    const m = line.match(/^([A-Za-z0-9_]+)=(.*)$/);
+    if (!m) continue;
+    const key = m[1];
+    let val = m[2];
+    // Strip surrounding quotes if present
+    if (
+      (val.startsWith('"') && val.endsWith('"')) ||
+      (val.startsWith("'") && val.endsWith("'"))
+    ) {
+      val = val.slice(1, -1);
+    }
+    if (!(key in process.env)) process.env[key] = val;
+  }
+}
+
+async function importHelpers() {
+  const {
+    SecretsManagerClient,
+    GetSecretValueCommand
+  } = require('@aws-sdk/client-secrets-manager');
+  const {
+    CloudWatchLogsClient,
+    DescribeLogStreamsCommand
+  } = require('@aws-sdk/client-cloudwatch-logs');
+  const {
+    ECSClient,
+    ListClustersCommand,
+    ListServicesCommand,
+    DescribeServicesCommand,
+    ListTasksCommand,
+    DescribeTasksCommand
+  } = require('@aws-sdk/client-ecs');
+  const {
+    ElasticLoadBalancingV2Client,
+    DescribeTargetGroupsCommand,
+    DescribeTargetHealthCommand
+  } = require('@aws-sdk/client-elastic-load-balancing-v2');
+  const axios = require('axios');
+
+  const API = () => process.env.API_ENDPOINT;
+  const deriveDomain = () => {
+    try {
+      const u = new URL(API());
+      return u.host.replace(/^api\./, '');
+    } catch {
+      return process.env.SCALY_DOMAIN || 'dev.scalyapps.io';
+    }
+  };
+  const regionToAws = (r) =>
+    ({
+      CANADA: 'ca-central-1',
+      US: 'us-east-1',
+      EU: 'eu-west-1',
+      ASIA_PACIFIC: 'ap-southeast-1'
+    })[String(r || '').toUpperCase()] || null;
+
+  async function getToken() {
+    // Prefer stored bearer token or env override to avoid aws-vault
+    const t = getStoredBearer();
+    if (t) return t;
+    if (process.env.SCALY_API_BEARER) return process.env.SCALY_API_BEARER;
+    if (!process.env.COGNITO_SECRET) throw new Error('COGNITO_SECRET not set');
+    const region = process.env.COGNITO_SECRET_REGION || 'ca-central-1';
+    const sm = new SecretsManagerClient({ region });
+    const res = await sm.send(
+      new GetSecretValueCommand({ SecretId: process.env.COGNITO_SECRET })
+    );
+    const sec = JSON.parse(res.SecretString || '{}');
+    const resp = await axios.post(
+      `${sec.cognitoBaseUrl}/oauth2/token`,
+      new URLSearchParams({
+        grant_type: 'client_credentials',
+        client_id: sec.cognitoClientId,
+        client_secret: sec.cognitoClientSecret
+      }).toString(),
+      { headers: { 'content-type': 'application/x-www-form-urlencoded' } }
+    );
+    return resp.data.access_token;
+  }
+
+  async function apiPost(token, query, variables) {
+    const resp = await axios.post(
+      API(),
+      { query, variables },
+      { headers: { authorization: `Bearer ${token}` } }
+    );
+    if (resp.data && resp.data.errors)
+      throw new Error(JSON.stringify(resp.data.errors));
+    return resp.data.data;
+  }
+
+  function makeCreds(c) {
+    return {
+      accessKeyId: c.accessKeyId,
+      secretAccessKey: c.secretAccessKey,
+      sessionToken: c.sessionToken
+    };
+  }
+
+  function elbClient(region, creds) {
+    return new ElasticLoadBalancingV2Client({ region, credentials: creds });
+  }
+  function ecsClient(region, creds) {
+    return new ECSClient({ region, credentials: creds });
+  }
+
+  async function checkHttp200(url, { tries = 10, delayMs = 3000 } = {}) {
+    const axios = require('axios');
+    for (let i = 0; i < tries; i++) {
+      try {
+        const r = await axios.get(url, {
+          timeout: 5000,
+          validateStatus: () => true
+        });
+        if (r.status === 200) return { status: r.status };
+        console.log(
+          `[smoke] HTTP ${r.status} at attempt ${i + 1}; retrying in ${Math.round(delayMs / 1000)}s`
+        );
+      } catch (e) {
+        console.log(`[smoke] request failed at attempt ${i + 1}; retrying…`);
+      }
+      await wait(delayMs);
+    }
+    return null;
+  }
+
+  async function checkCloudwatchLogs(accountId, appId, region) {
+    try {
+      const cwl = new CloudWatchLogsClient({ region });
+      const group = `/scaly/account/${accountId}`;
+      const cmd = new DescribeLogStreamsCommand({
+        logGroupName: group,
+        logStreamNamePrefix: `${appId}-`,
+        orderBy: 'LastEventTime',
+        descending: true,
+        limit: 5
+      });
+      const res = await cwl.send(cmd);
+      const streams = res.logStreams || [];
+      const top = streams[0];
+      return {
+        region,
+        group,
+        found: streams.length > 0,
+        latestStream: top ? top.logStreamName : null,
+        lastEventTs: top ? top.lastEventTimestamp : null
+      };
+    } catch (e) {
+      return {
+        region,
+        group: `/scaly/account/${accountId}`,
+        found: false,
+        error: String(e)
+      };
+    }
+  }
+
+  return {
+    getToken,
+    apiPost,
+    deriveDomain,
+    regionToAws,
+    checkHttp200,
+    makeCreds,
+    elbClient,
+    ecsClient
+  };
+}
+
+function wait(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+// GraphQL used by smoke
+const CREATE_APP_MUTATION = `
+  mutation CreateApp($data: AppCreateInput!) {
+    createApp(data: $data) { id name account { id } stackId }
+  }
+`;
+const DEPLOY_TEMPLATE_APP_MUTATION = `
+  mutation DeployTemplateApp($appId: String!, $templateId: String!) {
+    deployTemplateApp(input: { appId: $appId, templateId: $templateId }) { appId templateId }
+  }
+`;
+const LIST_DEPLOYMENTS_QUERY = `
+  query AppDeployments($appId: String!) { listDeployments(where: { appId: { equals: $appId } }, orderBy: { createdAt: DESC }, take: 3) { id status step } }
+`;
+const GET_DEPLOYMENT_QUERY = `
+  query GetDeployment($id: String!) { getDeployment(where: { id: $id }) { id status step } }
+`;
+const GET_STACK_QUERY = `
+  query GetStack($where: StackWhereUniqueInput!) { getStack(where: $where) { id name account { id region } } }
+`;
+
+// --- Logs over GraphQL ---
+const GET_SCALY_STACK_LOGS = `
+  query GetScalyStackLogs($where: StackLogsWhereInput!) {
+    getScalyStackLogs(where: $where) {
+      events { id timestamp message logStreamName }
+      truncated
+    }
+  }
+`;
+const GET_SCALY_ACCOUNT_LOGS = `
+  query GetScalyAccountLogs($where: StackLogsWhereInput!) {
+    getScalyAccountLogs(where: $where) {
+      events { id timestamp message logStreamName }
+      truncated
+    }
+  }
+`;
+
+// --- STS Broker ---
+const ISSUE_AWS_CREDENTIALS_MUTATION = `
+  mutation IssueAwsCredentials($input: IssueAwsCredentialsInput!) {
+    issueAwsCredentials(input: $input) {
+      accessKeyId
+      secretAccessKey
+      sessionToken
+      expiration
+      region
+      assumedRoleArn
+      requestId
+    }
+  }
+`;
+
+// --- DB local access ---
+const CREATE_DATABASE_PROXY_TOKEN_MUTATION = `
+  mutation CreateDatabaseProxyToken($addOnId: String!, $ttlMinutes: Int) {
+    createDatabaseProxyToken(where: { id: $addOnId }, ttlMinutes: $ttlMinutes) {
+      token
+      expiresAt
+      host
+      port
+      database
+      username
+      ttlMinutes
+    }
+  }
+`;
+
+// --- Apps update/delete helpers ---
+const UPDATE_APP_MUTATION = `
+  mutation UpdateApp($where: AppWhereUniqueInput!, $data: AppUpdateInput) {
+    updateApp(where: $where, data: $data) { id name minIdle stackId }
+  }
+`;
+const DELETE_APP_MUTATION = `
+  mutation DeleteApp($where: AppWhereUniqueInput!) {
+    deleteApp(where: $where) { id name }
+  }
+`;
+const LIST_APPS_QUERY = `
+  query ListApps($where: AppWhereInput) {
+    listApps(where: $where) { id name accountId }
+  }
+`;
+
+// --- Stacks update/delete helpers ---
+const UPDATE_STACK_MUTATION = `
+  mutation UpdateStack($where: StackWhereUniqueInput!, $data: StackUpdateInput) {
+    updateStack(where: $where, data: $data) { id name minIdle size }
+  }
+`;
+const DELETE_STACK_MUTATION = `
+  mutation DeleteStack($where: StackWhereUniqueInput!) {
+    deleteStack(where: $where) { id name }
+  }
+`;
+const LIST_STACKS_QUERY = `
+  query ListStacks($where: StackWhereInput) {
+    listStacks(where: $where) { id name accountId }
+  }
+`;
+
+async function runAppsUpdate(rest) {
+  if (!inVault()) {
+    const repl = withVault(['node', __filename, 'apps', 'update', ...rest]);
+    return run(repl[0], repl.slice(1));
+  }
+  const f = parseKv(rest);
+  if (!f.id && !(f.name && f.account)) {
+    console.error('apps update requires --id OR (--name and --account)');
+    return 2;
+  }
+  await sourceLocalEnv();
+  const { getToken, apiPost } = await importHelpers();
+  const token = await getToken();
+  let id = f.id;
+  if (!id) {
+    // resolve by account + name
+    const res = await apiPost(token, LIST_APPS_QUERY, {
+      where: { accountId: { equals: f.account }, name: { equals: f.name } }
+    });
+    const apps = (res && res.listApps) || [];
+    if (apps.length !== 1) {
+      console.error(
+        `[apps update] expected exactly 1 match, found ${apps.length}`
+      );
+      return 1;
+    }
+    id = apps[0].id;
+  }
+  const data = {};
+  if (f['min-idle']) data.minIdle = Number(f['min-idle']);
+  if (f.name && f.id) data.name = f.name; // allow rename only with explicit id
+  if (Object.keys(data).length === 0) {
+    console.error('nothing to update; pass --min-idle or --name');
+    return 2;
+  }
+  const out = await apiPost(token, UPDATE_APP_MUTATION, {
+    where: { id },
+    data
+  });
+  console.log('apps.update:', JSON.stringify(out, null, 2));
+  return 0;
+}
+
+async function runAppsDelete(rest) {
+  if (!inVault()) {
+    const repl = withVault(['node', __filename, 'apps', 'delete', ...rest]);
+    return run(repl[0], repl.slice(1));
+  }
+  const f = parseKv(rest);
+  if (!f.id && !(f.name && f.account)) {
+    console.error('apps delete requires --id OR (--name and --account)');
+    return 2;
+  }
+  await sourceLocalEnv();
+  const { getToken, apiPost } = await importHelpers();
+  const token = await getToken();
+  let id = f.id;
+  if (!id) {
+    const res = await apiPost(token, LIST_APPS_QUERY, {
+      where: { accountId: { equals: f.account }, name: { equals: f.name } }
+    });
+    const apps = (res && res.listApps) || [];
+    if (apps.length !== 1) {
+      console.error(
+        `[apps delete] expected exactly 1 match, found ${apps.length}`
+      );
+      return 1;
+    }
+    id = apps[0].id;
+  }
+  const out = await apiPost(token, DELETE_APP_MUTATION, { where: { id } });
+  console.log('apps.delete:', JSON.stringify(out, null, 2));
+  return 0;
+}
+
+async function runAppsDeleteByPrefix(rest) {
+  if (!inVault()) {
+    const repl = withVault([
+      'node',
+      __filename,
+      'apps',
+      'delete-by-prefix',
+      ...rest
+    ]);
+    return run(repl[0], repl.slice(1));
+  }
+  const f = parseKv(rest);
+  if (!f.account || !f.prefix) {
+    console.error('apps delete-by-prefix requires --account and --prefix');
+    return 2;
+  }
+  await sourceLocalEnv();
+  const { getToken, apiPost } = await importHelpers();
+  const token = await getToken();
+  const res = await apiPost(token, LIST_APPS_QUERY, {
+    where: { accountId: { equals: f.account }, name: { startsWith: f.prefix } }
+  });
+  const apps = (res && res.listApps) || [];
+  if (apps.length === 0) {
+    console.log('apps.delete-by-prefix: no matches');
+    return 0;
+  }
+  console.log(`[apps delete-by-prefix] deleting ${apps.length} apps…`);
+  for (const a of apps) {
+    await apiPost(token, DELETE_APP_MUTATION, { where: { id: a.id } });
+    console.log(`  deleted ${a.name} (${a.id})`);
+  }
+  return 0;
+}
+
+async function runStacksUpdate(rest) {
+  if (!inVault()) {
+    const repl = withVault(['node', __filename, 'stacks', 'update', ...rest]);
+    return run(repl[0], repl.slice(1));
+  }
+  const f = parseKv(rest);
+  if (!f.id && !(f.name && f.account)) {
+    console.error('stacks update requires --id OR (--name and --account)');
+    return 2;
+  }
+  await sourceLocalEnv();
+  const { getToken, apiPost } = await importHelpers();
+  const token = await getToken();
+  let id = f.id;
+  if (!id) {
+    const res = await apiPost(token, LIST_STACKS_QUERY, {
+      where: { accountId: { equals: f.account }, name: { equals: f.name } }
+    });
+    const stacks = (res && res.listStacks) || [];
+    if (stacks.length !== 1) {
+      console.error(
+        `[stacks update] expected exactly 1 match, found ${stacks.length}`
+      );
+      return 1;
+    }
+    id = stacks[0].id;
+  }
+  const data = {};
+  if (f['min-idle']) data.minIdle = Number(f['min-idle']);
+  if (f.size) data.size = f.size;
+  if (f.name && f.id) data.name = f.name;
+  if (Object.keys(data).length === 0) {
+    console.error('nothing to update; pass --min-idle, --size or --name');
+    return 2;
+  }
+  const out = await apiPost(token, UPDATE_STACK_MUTATION, {
+    where: { id },
+    data
+  });
+  console.log('stacks.update:', JSON.stringify(out, null, 2));
+  return 0;
+}
+
+async function runStacksDelete(rest) {
+  if (!inVault()) {
+    const repl = withVault(['node', __filename, 'stacks', 'delete', ...rest]);
+    return run(repl[0], repl.slice(1));
+  }
+  const f = parseKv(rest);
+  if (!f.id && !(f.name && f.account)) {
+    console.error('stacks delete requires --id OR (--name and --account)');
+    return 2;
+  }
+  await sourceLocalEnv();
+  const { getToken, apiPost } = await importHelpers();
+  const token = await getToken();
+  let id = f.id;
+  if (!id) {
+    const res = await apiPost(token, LIST_STACKS_QUERY, {
+      where: { accountId: { equals: f.account }, name: { equals: f.name } }
+    });
+    const stacks = (res && res.listStacks) || [];
+    if (stacks.length !== 1) {
+      console.error(
+        `[stacks delete] expected exactly 1 match, found ${stacks.length}`
+      );
+      return 1;
+    }
+    id = stacks[0].id;
+  }
+  const out = await apiPost(token, DELETE_STACK_MUTATION, { where: { id } });
+  console.log('stacks.delete:', JSON.stringify(out, null, 2));
+  return 0;
+}
+
+async function runStacksDeleteByPrefix(rest) {
+  if (!inVault()) {
+    const repl = withVault([
+      'node',
+      __filename,
+      'stacks',
+      'delete-by-prefix',
+      ...rest
+    ]);
+    return run(repl[0], repl.slice(1));
+  }
+  const f = parseKv(rest);
+  if (!f.account || !f.prefix) {
+    console.error('stacks delete-by-prefix requires --account and --prefix');
+    return 2;
+  }
+  await sourceLocalEnv();
+  const { getToken, apiPost } = await importHelpers();
+  const token = await getToken();
+  const res = await apiPost(token, LIST_STACKS_QUERY, {
+    where: { accountId: { equals: f.account }, name: { startsWith: f.prefix } }
+  });
+  const stacks = (res && res.listStacks) || [];
+  if (stacks.length === 0) {
+    console.log('stacks.delete-by-prefix: no matches');
+    return 0;
+  }
+  console.log(`[stacks delete-by-prefix] deleting ${stacks.length} stacks…`);
+  for (const s of stacks) {
+    await apiPost(token, DELETE_STACK_MUTATION, { where: { id: s.id } });
+    console.log(`  deleted ${s.name} (${s.id})`);
+  }
+  return 0;
+}
+
+async function runCleanupPurge(rest) {
+  if (!inVault()) {
+    const repl = withVault(['node', __filename, 'cleanup', 'purge', ...rest]);
+    return run(repl[0], repl.slice(1));
+  }
+  const f = parseKv(rest);
+  const account = f.account;
+  if (!account) {
+    console.error('cleanup purge requires --account <id>');
+    return 2;
+  }
+  const prefixesArg = f.prefixes || f.prefix || '';
+  const prefixes = String(prefixesArg)
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+  const dry = !!(
+    f['dry-run'] && String(f['dry-run']).toLowerCase() !== 'false'
+  );
+  const scaleAll = !!(
+    f['scale-all-stacks'] &&
+    String(f['scale-all-stacks']).toLowerCase() !== 'false'
+  );
+  const stackId = f.stack;
+  const stackName = f['stack-name'];
+
+  await sourceLocalEnv();
+  const { getToken, apiPost } = await importHelpers();
+  const token = await getToken();
+
+  // Collect apps by prefix
+  let appsToDelete = [];
+  if (prefixes.length > 0) {
+    const where = { accountId: { equals: account } };
+    if (prefixes.length === 1) where.name = { startsWith: prefixes[0] };
+    else where.OR = prefixes.map((p) => ({ name: { startsWith: p } }));
+    const res = await apiPost(token, LIST_APPS_QUERY, { where });
+    appsToDelete = (res && res.listApps) || [];
+  }
+
+  // Collect stacks to scale
+  let stacksToScale = [];
+  if (scaleAll) {
+    const res = await apiPost(token, LIST_STACKS_QUERY, {
+      where: { accountId: { equals: account } }
+    });
+    stacksToScale = (res && res.listStacks) || [];
+  } else if (stackId || stackName) {
+    if (stackId) stacksToScale = [{ id: stackId }];
+    else {
+      const res = await apiPost(token, LIST_STACKS_QUERY, {
+        where: { accountId: { equals: account }, name: { equals: stackName } }
+      });
+      const stacks = (res && res.listStacks) || [];
+      if (stacks.length !== 1) {
+        console.error(
+          `[cleanup purge] expected exactly 1 stack named ${stackName}, found ${stacks.length}`
+        );
+        return 1;
+      }
+      stacksToScale = [stacks[0]];
+    }
+  }
+
+  console.log(`[cleanup purge] account=${account}`);
+  if (prefixes.length) console.log(`  app prefixes: ${prefixes.join(', ')}`);
+  console.log(`  apps matched: ${appsToDelete.length}`);
+  console.log(`  stacks to scale: ${stacksToScale.length}`);
+
+  if (dry) {
+    for (const a of appsToDelete)
+      console.log(`  [dry-run] would delete app ${a.name} (${a.id})`);
+    for (const s of stacksToScale)
+      console.log(`  [dry-run] would scale stack ${s.id} to minIdle=0`);
+    return 0;
+  }
+
+  for (const a of appsToDelete) {
+    await apiPost(token, DELETE_APP_MUTATION, { where: { id: a.id } });
+    console.log(`  deleted app ${a.name} (${a.id})`);
+  }
+
+  for (const s of stacksToScale) {
+    await apiPost(token, UPDATE_STACK_MUTATION, {
+      where: { id: s.id },
+      data: { minIdle: 0 }
+    });
+    console.log(`  scaled stack ${s.id} to minIdle=0`);
+  }
+
+  console.log(
+    `[cleanup purge] done. deleted=${appsToDelete.length}, scaled=${stacksToScale.length}`
+  );
+  return 0;
+}
+
+function parseKv(arr) {
+  const out = {};
+  for (let i = 0; i < arr.length; i++) {
+    const a = arr[i];
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const val =
+        arr[i + 1] && !arr[i + 1].startsWith('--') ? arr[++i] : 'true';
+      out[key] = val;
+    } else if (!out._) {
+      out._ = [a];
+    } else {
+      out._.push(a);
+    }
+  }
+  return out;
+}
+
+// -------------------------
+// Templates matrix runner
+// -------------------------
+async function runTemplatesMatrix(rest) {
+  const f = parseKv(rest);
+  await sourceLocalEnv();
+  const { getToken, apiPost, deriveDomain, regionToAws, checkHttp200 } =
+    await importHelpers();
+
+  const token = await getToken();
+  const accountId = f.account || process.env.SCALY_ACCOUNT_ID;
+  const stackId = f.stack || process.env.SCALY_STACK_ID;
+  if (!accountId || !stackId) {
+    console.error(
+      'templates matrix requires --account <id> and --stack <id> (or set SCALY_ACCOUNT_ID/SCALY_STACK_ID)'
+    );
+    return 2;
+  }
+
+  const tplArg = f.templates || f.template || 'all';
+  const ALL_TEMPLATES = [
+    'fastapi-hello',
+    'flask-hello',
+    'streamlit-hello',
+    'dash-hello',
+    'gradio-hello',
+    'shiny-r-hello',
+    'shiny-python-hello',
+    'react-nest-hello',
+    'mkdocs-hello',
+    'docusaurus-hello'
+  ];
+  const templates =
+    tplArg === 'all'
+      ? ALL_TEMPLATES
+      : String(tplArg)
+          .split(',')
+          .map((s) => s.trim())
+          .filter(Boolean);
+  const keep = !!(f.keep && String(f.keep).toLowerCase() !== 'false');
+  const autoFix = !!(
+    f['auto-fix'] && String(f['auto-fix']).toLowerCase() !== 'false'
+  );
+  const tries = Number(f.tries) || 8;
+  const delayMs = Number(f['delay-ms']) || 5000;
+
+  const stackRes = await apiPost(token, GET_STACK_QUERY, {
+    where: { id: stackId }
+  });
+  const stack = stackRes?.getStack;
+  if (!stack?.name) {
+    console.error('Could not resolve stack by id');
+    return 1;
+  }
+  const domain = deriveDomain();
+  const accountPrefix = String(accountId).split('-')[0];
+
+  const results = [];
+  for (const templateId of templates) {
+    const name = `${templateId.replace(/[^a-z0-9-]/gi, '-')}-${Date.now().toString(36).slice(-5)}`;
+    const url = `https://${accountPrefix}-${stack.name}.${domain}/${name}/`;
+    const startedAt = new Date().toISOString();
+    let appId = null;
+    let deploymentId = null;
+    let status = 'Unknown';
+    let http = null;
+    let attempts = 0;
+    let notes = [];
+    let autoFixApplied = false;
+
+    try {
+      // Create app
+      const createRes = await apiPost(token, CREATE_APP_MUTATION, {
+        data: {
+          account: { connect: { id: accountId } },
+          name,
+          minIdle: 0,
+          stack: { connect: { id: stackId } }
+        }
+      });
+      appId = createRes?.createApp?.id;
+      if (!appId) throw new Error('createApp returned no id');
+
+      // Deploy template
+      await apiPost(token, DEPLOY_TEMPLATE_APP_MUTATION, { appId, templateId });
+      const dl = await apiPost(token, LIST_DEPLOYMENTS_QUERY, { appId });
+      deploymentId = dl?.listDeployments?.[0]?.id;
+
+      // Wait terminal
+      const deadline =
+        Date.now() + (Number(f['timeout-minutes']) || 20) * 60 * 1000;
+      let last = '';
+      while (Date.now() < deadline) {
+        const d = await apiPost(token, GET_DEPLOYMENT_QUERY, {
+          id: deploymentId
+        });
+        const dep = d?.getDeployment;
+        if (dep && dep.status !== last) {
+          last = dep.status;
+        }
+        if (dep && ['Successful', 'Failed', 'Cancelled'].includes(dep.status)) {
+          status = dep.status;
+          break;
+        }
+        await wait(
+          Number(f['poll-seconds']) ? Number(f['poll-seconds']) * 1000 : 10000
+        );
+      }
+
+      // HTTP probe
+      attempts++;
+      http = await checkHttp200(url, { tries, delayMs });
+      if (!http && autoFix) {
+        // Try a one-time redeploy of the template
+        autoFixApplied = true;
+        notes.push('Auto-fix: redeploy template once');
+        await apiPost(token, DEPLOY_TEMPLATE_APP_MUTATION, {
+          appId,
+          templateId
+        });
+        await wait(10000);
+        attempts++;
+        http = await checkHttp200(url, { tries, delayMs });
+      }
+    } catch (e) {
+      notes.push(String((e && e.message) || e));
+    } finally {
+      const finishedAt = new Date().toISOString();
+      results.push({
+        templateId,
+        appId,
+        deploymentId,
+        name,
+        url,
+        status,
+        http,
+        attempts,
+        autoFixApplied,
+        notes,
+        startedAt,
+        finishedAt
+      });
+      if (!keep && appId) {
+        try {
+          await apiPost(token, DELETE_APP_MUTATION, { where: { id: appId } });
+        } catch {}
+      }
+    }
+  }
+
+  const summary = {
+    accountId,
+    stackId,
+    stackName: stack.name,
+    domain,
+    total: results.length,
+    passed: results.filter((r) => r.http && r.http.status === 200).length,
+    failed: results.filter((r) => !(r.http && r.http.status === 200)).length,
+    results
+  };
+
+  if (f.json && String(f.json).toLowerCase() !== 'false') {
+    console.log(JSON.stringify(summary));
+  } else {
+    console.log('MATRIX_RESULT:', JSON.stringify(summary, null, 2));
+  }
+  return summary.failed ? 1 : 0;
+}
+
+// -------------------------
+// Login (store/clear bearer)
+// -------------------------
+async function runLogin(sub, rest) {
+  const f = parseKv(rest);
+  if (f.clear) {
+    clearStoredBearer();
+    console.log('Cleared stored bearer token');
+    return 0;
+  }
+  const token = f.token || (f._ && f._[0]);
+  const endpoint = f.endpoint || process.env.API_ENDPOINT;
+  if (!token) {
+    console.error('login requires --token <api-bearer>');
+    return 2;
+  }
+  if (!endpoint) {
+    console.error(
+      'login requires --endpoint <https://api...> (or set API_ENDPOINT)'
+    );
+    return 2;
+  }
+  saveStoredBearer({ token, endpoint });
+  console.log(`Saved API bearer for ${endpoint}`);
+  return 0;
+}
+
+function getConfigPath() {
+  const os = require('os');
+  const fs = require('fs');
+  const path = require('path');
+  const base =
+    process.env.SCALY_CONFIG_DIR ||
+    process.env.XDG_CONFIG_HOME ||
+    path.join(os.homedir(), '.config');
+  const dir = path.join(base, 'scaly');
+  const file = path.join(dir, 'credentials.json');
+  return { dir, file, fs, path };
+}
+
+function saveStoredBearer({ token, endpoint }) {
+  const { dir, file, fs } = getConfigPath();
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+  } catch {}
+  const data = { token, endpoint, savedAt: new Date().toISOString() };
+  fs.writeFileSync(file, JSON.stringify(data, null, 2));
+}
+
+function clearStoredBearer() {
+  const { file, fs } = getConfigPath();
+  try {
+    fs.unlinkSync(file);
+  } catch {}
+}
+
+function loadStoredBearer() {
+  const { file, fs } = getConfigPath();
+  try {
+    const text = fs.readFileSync(file, 'utf8');
+    const obj = JSON.parse(text);
+    return obj && obj.token && obj.endpoint ? obj : null;
+  } catch {
+    return null;
+  }
+}
+
+function getStoredBearer() {
+  const obj = loadStoredBearer();
+  if (obj) process.env.API_ENDPOINT = process.env.API_ENDPOINT || obj.endpoint;
+  return obj ? obj.token : null;
+}
+
+function parseBool(v, defaultValue = false) {
+  if (v === undefined || v === null) return defaultValue;
+  const s = String(v).trim().toLowerCase();
+  if (s === '') return defaultValue;
+  if (['1', 'true', 'yes', 'y', 'on'].includes(s)) return true;
+  if (['0', 'false', 'no', 'n', 'off'].includes(s)) return false;
+  return defaultValue;
+}
+
+function promptYesNo(question) {
+  const readline = require('readline');
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(/^y(es)?$/i.test(String(answer || '').trim()));
+    });
+  });
+}
+
+function promptHidden(question) {
+  const readline = require('readline');
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: true
+  });
+  // Mask input with '*' while typing.
+  // eslint-disable-next-line no-underscore-dangle
+  rl._writeToOutput = function _writeToOutput(stringToWrite) {
+    if (rl.stdoutMuted) rl.output.write('*');
+    else rl.output.write(stringToWrite);
+  };
+  rl.stdoutMuted = true;
+  return new Promise((resolve) => {
+    rl.question(question, (value) => {
+      rl.stdoutMuted = false;
+      rl.output.write('\n');
+      rl.close();
+      resolve(String(value || ''));
+    });
+  });
+}
+
+function readStdinAll() {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => (data += chunk));
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', reject);
+  });
+}
+
+function copyToClipboard(text) {
+  const { spawnSync } = require('child_process');
+  const plat = process.platform;
+
+  const tryCmd = (cmd, args = []) => {
+    const res = spawnSync(cmd, args, {
+      input: text,
+      stdio: ['pipe', 'ignore', 'ignore'],
+      shell: false
+    });
+    return res && res.status === 0;
+  };
+
+  if (plat === 'darwin') {
+    if (tryCmd('pbcopy')) return true;
+  } else if (plat === 'win32') {
+    if (tryCmd('clip')) return true;
+  } else {
+    if (tryCmd('wl-copy')) return true;
+    if (tryCmd('xclip', ['-selection', 'clipboard'])) return true;
+    if (tryCmd('xsel', ['--clipboard', '--input'])) return true;
+  }
+
+  return false;
+}
+
+// -------------------------
+// GraphQL Logs
+// -------------------------
+async function runLogsGql(kind, rest) {
+  const f = parseKv(rest);
+  const id = f.id || (f._ && f._[0]);
+  if (!id) {
+    console.error(
+      `logs ${kind} requires --id <${kind === 'stack' ? 'stackId' : 'accountId'}>`
+    );
+    return 2;
+  }
+  const since = f.since || '30m';
+  const limit = Number(f.limit) > 0 ? Number(f.limit) : 300;
+  await sourceLocalEnv();
+  const { getToken, apiPost } = await importHelpers();
+  const token = await getToken();
+  const startTime = sinceToIso(since);
+  const where = { id, startTime };
+  const query =
+    kind === 'stack' ? GET_SCALY_STACK_LOGS : GET_SCALY_ACCOUNT_LOGS;
+  const res = await apiPost(token, query, { where });
+  const data =
+    kind === 'stack' ? res.getScalyStackLogs : res.getScalyAccountLogs;
+  const events = data && data.events ? data.events.slice(-limit) : [];
+  if (f.json && String(f.json).toLowerCase() !== 'false') {
+    console.log(
+      JSON.stringify({
+        id,
+        kind,
+        count: events.length,
+        truncated: !!data?.truncated,
+        events
+      })
+    );
+    return 0;
+  }
+  for (const e of events) {
+    console.log(`${e.timestamp} ${e.logStreamName || ''} ${e.message}`);
+  }
+  if (data?.truncated) console.log('[truncated]');
+  return 0;
+}
+
+function sinceToIso(s) {
+  const now = Date.now();
+  const m = String(s).match(/^(\d+)([smhd])$/i);
+  let ms = 30 * 60 * 1000; // default 30m
+  if (m) {
+    const n = Number(m[1]);
+    const u = m[2].toLowerCase();
+    if (u === 's') ms = n * 1000;
+    if (u === 'm') ms = n * 60 * 1000;
+    if (u === 'h') ms = n * 60 * 60 * 1000;
+    if (u === 'd') ms = n * 24 * 60 * 60 * 1000;
+  }
+  return new Date(now - ms).toISOString();
+}
+
+// -------------------------
+// .scaly project config (Phase 3)
+// -------------------------
+async function runProjectInit(rest) {
+  const fs = require('fs');
+  const path = require('path');
+  const { writeYamlFile } = require('../lib/scaly-project');
+
+  const f = parseKv(rest);
+  const force = String(f.force || '').toLowerCase() === 'true';
+
+  const root = process.cwd();
+  const project = path.basename(root).replace(/[^a-zA-Z0-9-_]/g, '') || 'app';
+  const scalyDir = path.join(root, '.scaly');
+  const configPath = path.join(scalyDir, 'config.yaml');
+
+  if (fs.existsSync(configPath) && !force) {
+    console.error(
+      `Refusing to overwrite existing ${configPath}. Re-run with --force to replace.`
+    );
+    return 2;
+  }
+
+  const baseConfig = {
+    version: '1',
+    account: { slug: 'mycompany' },
+    stack: {
+      name: `${project}-stack`,
+      size: 'Eco',
+      region: 'CANADA',
+      minIdle: 0
+    },
+    app: {
+      name: project,
+      framework: 'fastapi',
+      env: { LOG_LEVEL: 'info' },
+      secrets: []
+    },
+    addons: [],
+    domains: [],
+    jobs: []
+  };
+
+  writeYamlFile(configPath, baseConfig);
+
+  const schemaPath = path.join(scalyDir, 'schema.sql');
+  fs.writeFileSync(schemaPath, '', 'utf8');
+
+  const migrationsDir = path.join(scalyDir, 'migrations');
+  fs.mkdirSync(migrationsDir, { recursive: true });
+  const keep = path.join(migrationsDir, '.gitkeep');
+  fs.writeFileSync(keep, '', 'utf8');
+
+  console.log(`Created ${configPath}`);
+  console.log(`Created ${schemaPath} (empty)`);
+  console.log(`Created ${migrationsDir}/`);
+  return 0;
+}
+
+async function runProjectPlan(rest) {
+  const f = parseKv(rest);
+  const env = f.env || null;
+  const appName = f.app || null;
+  const json = String(f.json || '').toLowerCase() === 'true';
+
+  // Allow existing `scaly login` flow to set API_ENDPOINT.
+  try {
+    const t = getStoredBearer();
+    if (t && !process.env.SCALY_API_BEARER) process.env.SCALY_API_BEARER = t;
+  } catch {}
+
+  const {
+    loadScalyConfig,
+    computeConfigHash,
+    readLastApply
+  } = require('../lib/scaly-project');
+  const { buildPlan } = require('../lib/scaly-plan');
+
+  let loaded;
+  try {
+    loaded = loadScalyConfig({ cwd: process.cwd(), env });
+  } catch (err) {
+    console.error(String(err && err.message ? err.message : err));
+    return 2;
+  }
+
+  if (!loaded.validation.ok) {
+    console.error('Invalid .scaly/config.yaml:');
+    for (const e of loaded.validation.errors) console.error(`- ${e}`);
+    return 2;
+  }
+
+  const plan = await buildPlan({ config: loaded.config, env, appName });
+  const config_hash = computeConfigHash({
+    config: loaded.config,
+    env: plan.env,
+    appName
+  });
+  const lastApply = readLastApply(loaded.root);
+  const drift =
+    lastApply && lastApply.config_hash === config_hash
+      ? (plan.operations || [])
+          .filter((o) => o.action === 'create' || o.action === 'update')
+          .flatMap((op) => {
+            const diffs = Array.isArray(op.diff) ? op.diff : [];
+            return diffs.map((d) => ({
+              resource: op.kind,
+              id: op.resource?.id || null,
+              name: op.resource?.name || null,
+              field: d.field,
+              live: d.current ?? null,
+              config: d.desired ?? null
+            }));
+          })
+      : plan.drift || [];
+
+  const out = {
+    ok: true,
+    project_root: loaded.root,
+    config_path: loaded.basePath,
+    overlay_path: loaded.overlayPath,
+    plan_hash: plan.plan_hash,
+    env: plan.env,
+    summary: plan.summary,
+    drift,
+    warnings: plan.warnings,
+    operations: plan.operations
+  };
+
+  if (json) {
+    console.log(JSON.stringify(out));
+    return 0;
+  }
+
+  console.log(
+    `Plan: create=${plan.summary.create} update=${plan.summary.update} noop=${plan.summary.noop}`
+  );
+  for (const op of plan.operations) {
+    if (op.action === 'noop') continue;
+    const name = op.resource?.name || op.resource?.id || op.id;
+    console.log(`- ${op.action.toUpperCase()} ${op.kind} ${name}`);
+    for (const d of op.diff || []) {
+      console.log(
+        `    - ${d.field}: ${JSON.stringify(d.current)} → ${JSON.stringify(d.desired)}`
+      );
+    }
+  }
+  for (const w of plan.warnings || []) console.log(`[warn] ${w}`);
+  console.log('');
+  console.log(`plan_hash: ${plan.plan_hash}`);
+  console.log(
+    `Run: scaly apply --plan-hash ${plan.plan_hash}${env ? ` --env ${env}` : ''}${appName ? ` --app ${appName}` : ''}`
+  );
+  return 0;
+}
+
+async function runProjectApply(rest) {
+  const readline = require('readline');
+
+  const f = parseKv(rest);
+  const env = f.env || null;
+  const appName = f.app || null;
+  const json = String(f.json || '').toLowerCase() === 'true';
+  const autoApprove = String(f['auto-approve'] || '').toLowerCase() === 'true';
+  const planHash = f['plan-hash'] || f.plan_hash || f.planHash;
+  if (!planHash) {
+    console.error(
+      'apply requires --plan-hash <sha256:...> (run `scaly plan` first).'
+    );
+    return 2;
+  }
+
+  try {
+    const t = getStoredBearer();
+    if (t && !process.env.SCALY_API_BEARER) process.env.SCALY_API_BEARER = t;
+  } catch {}
+
+  const {
+    loadScalyConfig,
+    computeConfigHash,
+    writeLastApply
+  } = require('../lib/scaly-project');
+  const { buildPlan } = require('../lib/scaly-plan');
+  const { applyPlan } = require('../lib/scaly-apply');
+
+  let loaded;
+  try {
+    loaded = loadScalyConfig({ cwd: process.cwd(), env });
+  } catch (err) {
+    console.error(String(err && err.message ? err.message : err));
+    return 2;
+  }
+  if (!loaded.validation.ok) {
+    console.error('Invalid .scaly/config.yaml:');
+    for (const e of loaded.validation.errors) console.error(`- ${e}`);
+    return 2;
+  }
+
+  const plan = await buildPlan({ config: loaded.config, env, appName });
+  if (plan.plan_hash !== planHash) {
+    console.error('Plan hash mismatch.');
+    console.error(`Expected: ${plan.plan_hash}`);
+    console.error(`Provided: ${planHash}`);
+    console.error('Re-run `scaly plan` and use the printed hash.');
+    return 2;
+  }
+
+  const actionable = (plan.operations || []).filter(
+    (o) => o.action === 'create' || o.action === 'update'
+  );
+  if (actionable.length === 0) {
+    if (json)
+      console.log(
+        JSON.stringify({
+          ok: true,
+          plan_hash: plan.plan_hash,
+          applied: 0,
+          results: []
+        })
+      );
+    else console.log('No changes to apply.');
+    return 0;
+  }
+
+  if (!autoApprove) {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+    const answer = await new Promise((resolve) =>
+      rl.question(`Apply ${actionable.length} changes? (y/N) `, resolve)
+    );
+    rl.close();
+    if (!/^y(es)?$/i.test(String(answer || '').trim())) {
+      console.error('Aborted.');
+      return 1;
+    }
+  }
+
+  let res;
+  try {
+    res = await applyPlan({ config: loaded.config, plan, autoApprove });
+  } catch (err) {
+    const msg = String(err && err.message ? err.message : err);
+    if (json)
+      console.log(
+        JSON.stringify({
+          ok: false,
+          plan_hash: plan.plan_hash,
+          error: { message: msg }
+        })
+      );
+    else console.error(msg);
+    return 1;
+  }
+  const out = { ...res, plan_hash: plan.plan_hash };
+
+  if (res.ok) {
+    const config_hash = computeConfigHash({
+      config: loaded.config,
+      env: plan.env,
+      appName
+    });
+    writeLastApply(loaded.root, {
+      version: 1,
+      applied_at: new Date().toISOString(),
+      env: plan.env || null,
+      app: appName || null,
+      plan_hash: plan.plan_hash,
+      config_hash,
+      applied: out.applied
+    });
+  }
+
+  if (json) {
+    console.log(JSON.stringify(out));
+    return res.ok ? 0 : 1;
+  }
+
+  console.log(`Applied ${out.applied} changes.`);
+  for (const r of out.results || []) {
+    if (r.ok) console.log(`- OK ${r.op_id}`);
+    else
+      console.log(`- FAIL ${r.op_id}: ${r.error?.message || 'unknown error'}`);
+  }
+  return res.ok ? 0 : 1;
+}
+
+async function runProjectPull(rest) {
+  const fs = require('fs');
+  const path = require('path');
+  const api = require('../lib/scaly-api');
+  const { writeYamlFile } = require('../lib/scaly-project');
+
+  const f = parseKv(rest);
+  const json = String(f.json || '').toLowerCase() === 'true';
+  const force = String(f.force || '').toLowerCase() === 'true';
+  const stackId = f.stack || null;
+  const appId = f.app || null;
+
+  try {
+    const t = getStoredBearer();
+    if (t && !process.env.SCALY_API_BEARER) process.env.SCALY_API_BEARER = t;
+  } catch {}
+
+  const root = process.cwd();
+  const scalyDir = path.join(root, '.scaly');
+  const configPath = path.join(scalyDir, 'config.yaml');
+
+  if (fs.existsSync(configPath) && !force) {
+    console.error(
+      `Refusing to overwrite existing ${configPath}. Re-run with --force to replace.`
+    );
+    return 2;
+  }
+
+  const stacks = await api.listStacks({ take: 50 });
+  const chosenStack = stackId
+    ? stacks.find((s) => s.id === stackId)
+    : stacks.length === 1
+      ? stacks[0]
+      : null;
+  if (!chosenStack) {
+    console.error(
+      stackId
+        ? `Stack not found: ${stackId}`
+        : `Multiple stacks found (${stacks.length}). Re-run with --stack <id>.`
+    );
+    return 2;
+  }
+
+  const apps = await api.listApps({ take: 200 });
+  const appsInStack = apps.filter((a) => a.stackId === chosenStack.id);
+  const chosenApp = appId
+    ? apps.find((a) => a.id === appId)
+    : appsInStack.length === 1
+      ? appsInStack[0]
+      : null;
+  if (!chosenApp) {
+    console.error(
+      appId
+        ? `App not found: ${appId}`
+        : `Multiple apps found in stack (${appsInStack.length}). Re-run with --app <id>.`
+    );
+    return 2;
+  }
+
+  const config = {
+    version: '1',
+    account: { id: chosenStack.accountId },
+    stack: {
+      name: chosenStack.name,
+      size: chosenStack.size,
+      minIdle: chosenStack.minIdle
+    },
+    app: {
+      name: chosenApp.name,
+      framework: 'unknown'
+    },
+    addons: [],
+    domains: [],
+    jobs: []
+  };
+
+  writeYamlFile(configPath, config);
+  fs.mkdirSync(path.join(scalyDir, 'migrations'), { recursive: true });
+  const schemaPath = path.join(scalyDir, 'schema.sql');
+  if (!fs.existsSync(schemaPath)) fs.writeFileSync(schemaPath, '', 'utf8');
+
+  const out = {
+    ok: true,
+    wrote: configPath,
+    stack: chosenStack,
+    app: chosenApp
+  };
+
+  if (json) console.log(JSON.stringify(out));
+  else console.log(`Wrote ${configPath}`);
+  return 0;
+}
+
+// -------------------------
+// Deploy
+// -------------------------
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function runDeploy(rest) {
+  const f = parseKv(rest);
+  const json = parseBool(f.json, false);
+  const watch = f.watch !== undefined ? parseBool(f.watch, true) : false;
+  const strategy = String(f.strategy || 'auto').toLowerCase(); // auto|git|restart
+  const pollSeconds = Number(f['poll-seconds'] || 5);
+  const timeoutMinutes = Number(f['timeout-minutes'] || 20);
+
+  const appId = f.app || f['app-id'] || (f._ && f._[0]);
+  if (!appId) {
+    const msg = '--app <appId> is required';
+    if (json)
+      console.log(JSON.stringify({ ok: false, error: { message: msg } }));
+    else console.error(msg);
+    return 2;
+  }
+
+  try {
+    const t = getStoredBearer();
+    if (t && !process.env.SCALY_API_BEARER) process.env.SCALY_API_BEARER = t;
+  } catch {}
+
+  const deploy = require('../lib/scaly-deploy');
+
+  const app = await deploy.getAppBasic(appId);
+  if (!app) {
+    const msg = `App not found: ${appId}`;
+    if (json)
+      console.log(JSON.stringify({ ok: false, error: { message: msg } }));
+    else console.error(msg);
+    return 2;
+  }
+  if (!app.stackId) {
+    const msg = `App has no stackId: ${appId}`;
+    if (json)
+      console.log(JSON.stringify({ ok: false, error: { message: msg } }));
+    else console.error(msg);
+    return 2;
+  }
+
+  let chosen = strategy;
+  let gitSource = null;
+  if (strategy === 'auto') {
+    gitSource = await deploy.getAppGitSource(appId);
+    chosen = gitSource ? 'git' : 'restart';
+  } else if (strategy === 'git') {
+    gitSource = await deploy.getAppGitSource(appId);
+  }
+
+  if (chosen === 'git') {
+    const trigger = await deploy.triggerGitDeploy(appId);
+    if (!trigger?.id) {
+      const msg = 'Failed to trigger git deploy';
+      if (json)
+        console.log(JSON.stringify({ ok: false, error: { message: msg } }));
+      else console.error(msg);
+      return 1;
+    }
+
+    if (!watch) {
+      const out = { ok: true, strategy: 'git', git_deploy: trigger, app };
+      if (json) console.log(JSON.stringify(out));
+      else
+        console.log(
+          `[deploy] triggered git deploy ${trigger.id} status=${trigger.status}`
+        );
+      return 0;
+    }
+
+    const deadline = Date.now() + timeoutMinutes * 60_000;
+    let lastStatus = null;
+    let matched = null;
+    while (Date.now() < deadline) {
+      const items = await deploy.listGitDeployments(appId, 20);
+      matched = items.find((d) => d.id === trigger.id) || null;
+      if (matched && matched.status !== lastStatus) {
+        lastStatus = matched.status;
+        if (!json)
+          console.log(
+            `[deploy] git status=${matched.status} deploymentId=${matched.deploymentId || 'n/a'}`
+          );
+      }
+      if (
+        matched &&
+        ['successful', 'failed', 'cancelled'].includes(
+          String(matched.status || '').toLowerCase()
+        )
+      )
+        break;
+      await sleep(pollSeconds * 1000);
+    }
+
+    const final = matched || trigger;
+    const finalStatus = String(final?.status || '').toLowerCase();
+    const ok = finalStatus === 'successful';
+    if (!['successful', 'failed', 'cancelled'].includes(finalStatus)) {
+      const out = {
+        ok: false,
+        strategy: 'git',
+        git_deploy: final,
+        app,
+        error: { message: 'Timed out waiting for git deployment' }
+      };
+      if (json) console.log(JSON.stringify(out));
+      else console.error('[deploy] timed out waiting for git deployment');
+      return 1;
+    }
+    const out = { ok, strategy: 'git', git_deploy: final, app };
+    if (json) console.log(JSON.stringify(out));
+    return ok ? 0 : 1;
+  }
+
+  // restart strategy
+  const dep = await deploy.restartStackServices(app.stackId);
+  if (!dep?.id) {
+    const msg =
+      'Failed to start deployment (restartStackServices returned no id)';
+    if (json)
+      console.log(JSON.stringify({ ok: false, error: { message: msg } }));
+    else console.error(msg);
+    return 1;
+  }
+
+  if (!watch) {
+    const out = { ok: true, strategy: 'restart', deployment: dep, app };
+    if (json) console.log(JSON.stringify(out));
+    else
+      console.log(`[deploy] started deployment ${dep.id} status=${dep.status}`);
+    return 0;
+  }
+
+  const deadline = Date.now() + timeoutMinutes * 60_000;
+  let last = null;
+  while (Date.now() < deadline) {
+    const current = await deploy.getDeployment(dep.id);
+    if (
+      current &&
+      (current.status !== last?.status ||
+        current.step !== last?.step ||
+        current.progressPct !== last?.progressPct)
+    ) {
+      last = current;
+      if (!json) {
+        console.log(
+          `[deploy] ${current.id} status=${current.status} step=${current.step} progress=${current.progressPct}%`
+        );
+      }
+    }
+    const status = String(current?.status || '').toLowerCase();
+    if (current && ['successful', 'failed', 'cancelled'].includes(status)) {
+      const out = {
+        ok: status === 'successful',
+        strategy: 'restart',
+        deployment: current,
+        app
+      };
+      if (json) console.log(JSON.stringify(out));
+      return out.ok ? 0 : 1;
+    }
+    await sleep(pollSeconds * 1000);
+  }
+
+  const out = {
+    ok: false,
+    error: { message: 'Timed out waiting for deployment' },
+    deployment_id: dep.id
+  };
+  if (json) console.log(JSON.stringify(out));
+  else console.error(out.error.message);
+  return 1;
+}
+
+// -------------------------
+// Logs follow (Unified Logs)
+// -------------------------
+async function runLogsFollow(rest) {
+  const f = parseKv(rest);
+  const appId = f.app || f['app-id'] || (f._ && f._[0]);
+  const since = f.since || '10m';
+  const level = f.level || 'all';
+  const q = f.q || null;
+  const pollMs = Number(f['poll-ms'] || 2000);
+  const durationSeconds =
+    f['duration-seconds'] !== undefined ? Number(f['duration-seconds']) : null;
+  const maxLines = f['max-lines'] !== undefined ? Number(f['max-lines']) : null;
+  const json = parseBool(f.json, false);
+
+  if (!appId) {
+    console.error('--app <appId> is required');
+    return 2;
+  }
+
+  try {
+    const t = getStoredBearer();
+    if (t && !process.env.SCALY_API_BEARER) process.env.SCALY_API_BEARER = t;
+  } catch {}
+
+  const logs = require('../lib/scaly-logs');
+  const app = await logs.getAppBasic(appId);
+  if (!app) {
+    console.error(`App not found: ${appId}`);
+    return 2;
+  }
+
+  const lookbackHours = logs.parseTimeRangeToLookbackHours(since);
+  if (!lookbackHours) {
+    console.error('Invalid --since; expected like 15m, 1h, 1d');
+    return 2;
+  }
+
+  const deadline =
+    durationSeconds && Number.isFinite(durationSeconds) && durationSeconds > 0
+      ? Date.now() + durationSeconds * 1000
+      : null;
+  const shouldStopByLines =
+    maxLines && Number.isFinite(maxLines) && maxLines > 0 ? maxLines : null;
+  let printed = 0;
+
+  let liveFromTs = null;
+  // Initial batch
+  const first = await logs.getUnifiedLogs({
+    accountId: app.accountId,
+    appIds: [appId],
+    lookbackHours,
+    liveFromTs: undefined,
+    limit: 200,
+    q,
+    level,
+    pageToken: undefined
+  });
+  const seen = new Set();
+  const seenQueue = [];
+  const maxSeen = 5000;
+  const remember = (id) => {
+    if (seen.has(id)) return false;
+    seen.add(id);
+    seenQueue.push(id);
+    while (seenQueue.length > maxSeen) {
+      const old = seenQueue.shift();
+      if (old) seen.delete(old);
+    }
+    return true;
+  };
+  if (first && Array.isArray(first.events)) {
+    for (const e of first.events) {
+      if (!remember(e.id)) continue;
+      if (json) console.log(JSON.stringify(e));
+      else console.log(`${e.ts} ${e.level || 'Unknown'} ${e.message}`);
+      printed++;
+      if (!liveFromTs || e.ts > liveFromTs) liveFromTs = e.ts;
+      if (shouldStopByLines && printed >= shouldStopByLines) return 0;
+    }
+  }
+  if (!liveFromTs) liveFromTs = new Date().toISOString();
+
+  // Tail loop
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    if (deadline && Date.now() >= deadline) return 0;
+    const res = await logs.getUnifiedLogs({
+      accountId: app.accountId,
+      appIds: [appId],
+      lookbackHours: undefined,
+      liveFromTs,
+      limit: 200,
+      q,
+      level,
+      pageToken: undefined
+    });
+    if (res && Array.isArray(res.events) && res.events.length) {
+      for (const e of res.events) {
+        if (!remember(e.id)) continue;
+        if (json) console.log(JSON.stringify(e));
+        else console.log(`${e.ts} ${e.level || 'Unknown'} ${e.message}`);
+        printed++;
+        if (e.ts > liveFromTs) liveFromTs = e.ts;
+        if (shouldStopByLines && printed >= shouldStopByLines) return 0;
+      }
+    }
+    await sleep(pollMs);
+  }
+}
+
+// -------------------------
+// Secrets (App Build Secrets)
+// -------------------------
+async function runSecrets(sub, rest) {
+  const f = parseKv(rest);
+  const json = parseBool(f.json, false);
+
+  // OIDC-only for build secrets.
+  try {
+    const t = getStoredBearer();
+    if (t && !process.env.SCALY_API_BEARER) process.env.SCALY_API_BEARER = t;
+  } catch {}
+
+  const bearer =
+    process.env.SCALY_API_BEARER ||
+    process.env.API_BEARER_TOKEN ||
+    process.env.API_BEARER;
+  if (!bearer || !isProbablyJwt(bearer)) {
+    const msg =
+      'secrets commands require a Cognito OIDC access token (JWT). ' +
+      'Run `scaly login --token <access_token_jwt>` first.';
+    if (json)
+      console.log(JSON.stringify({ ok: false, error: { message: msg } }));
+    else console.error(msg);
+    return 2;
+  }
+
+  const appId = f.app || f['app-id'] || (f._ && f._[0]);
+  if (!appId) {
+    const msg = '--app <appId> is required';
+    if (json)
+      console.log(JSON.stringify({ ok: false, error: { message: msg } }));
+    else console.error(msg);
+    return 2;
+  }
+
+  const secrets = require('../lib/scaly-secrets');
+  const { loadScalyConfig } = require('../lib/scaly-project');
+
+  if (sub === 'list') {
+    const items = await secrets.listBuildSecrets(appId);
+    const out = {
+      ok: true,
+      app_id: appId,
+      secrets: items,
+      count: items.length
+    };
+    if (json) console.log(JSON.stringify(out));
+    else {
+      for (const s of items) console.log(`${s.name}\t${s.id}`);
+    }
+    return 0;
+  }
+
+  if (sub === 'set') {
+    const name = f.name;
+    const fromEnv = f['from-env'] || f.from_env;
+    const stdin = parseBool(f.stdin, false);
+    if (!name) {
+      const msg = '--name <KEY> is required';
+      if (json)
+        console.log(JSON.stringify({ ok: false, error: { message: msg } }));
+      else console.error(msg);
+      return 2;
+    }
+
+    let value = null;
+    if (fromEnv) {
+      value = process.env[String(fromEnv)] ?? null;
+      if (value === null) {
+        const msg = `Environment variable not set: ${fromEnv}`;
+        if (json)
+          console.log(JSON.stringify({ ok: false, error: { message: msg } }));
+        else console.error(msg);
+        return 2;
+      }
+    } else if (stdin) {
+      value = String(await readStdinAll()).replace(/\r?\n$/, '');
+    } else {
+      value = await promptHidden(`Value for ${name}: `);
+    }
+
+    const res = await secrets.setBuildSecret({ appId, name, value });
+    const out = {
+      ok: true,
+      app_id: appId,
+      action: res.action,
+      name,
+      id: res.secret?.id || null
+    };
+    if (json) console.log(JSON.stringify(out));
+    else console.log(`[secrets] ${res.action} ${name}`);
+    return 0;
+  }
+
+  if (sub === 'delete') {
+    const id = f.id || null;
+    const name = f.name || null;
+    const yes = parseBool(f.yes, false);
+    if (!id && !name) {
+      const msg = 'delete requires --id <secretId> or --name <KEY>';
+      if (json)
+        console.log(JSON.stringify({ ok: false, error: { message: msg } }));
+      else console.error(msg);
+      return 2;
+    }
+
+    let secretId = id;
+    if (!secretId) {
+      const items = await secrets.listBuildSecrets(appId);
+      const match = items.find((s) => s.name === name);
+      if (!match) {
+        const msg = `Secret not found: ${name}`;
+        if (json)
+          console.log(JSON.stringify({ ok: false, error: { message: msg } }));
+        else console.error(msg);
+        return 2;
+      }
+      secretId = match.id;
+    }
+
+    const proceed = yes
+      ? true
+      : await promptYesNo(`Delete secret ${name || secretId}? (y/N) `);
+    if (!proceed) {
+      const out = { ok: false, aborted: true };
+      if (json) console.log(JSON.stringify(out));
+      else console.error('Aborted.');
+      return 1;
+    }
+
+    await secrets.deleteBuildSecret({ id: secretId });
+    const out = { ok: true, deleted: true, id: secretId };
+    if (json) console.log(JSON.stringify(out));
+    else console.log('[secrets] deleted');
+    return 0;
+  }
+
+  if (sub === 'sync') {
+    const env = f.env || null;
+    const apply = parseBool(f.apply, false);
+    const dryRun =
+      f['dry-run'] !== undefined ? parseBool(f['dry-run'], true) : !apply;
+    const configAppName =
+      f['config-app'] || f.config_app || f['app-name'] || f.app_name || null;
+
+    let loaded;
+    try {
+      loaded = loadScalyConfig({ cwd: process.cwd(), env });
+    } catch (err) {
+      const msg = String(err && err.message ? err.message : err);
+      if (json)
+        console.log(JSON.stringify({ ok: false, error: { message: msg } }));
+      else console.error(msg);
+      return 2;
+    }
+    if (!loaded.validation.ok) {
+      const msg = 'Invalid .scaly/config.yaml';
+      if (json)
+        console.log(
+          JSON.stringify({
+            ok: false,
+            error: { message: msg },
+            details: loaded.validation.errors
+          })
+        );
+      else {
+        console.error(msg);
+        for (const e of loaded.validation.errors) console.error(`- ${e}`);
+      }
+      return 2;
+    }
+
+    const apps = loaded.config.apps || [];
+    const appsWithSecrets = apps.filter(
+      (a) =>
+        a &&
+        typeof a === 'object' &&
+        Array.isArray(a.secrets) &&
+        a.secrets.length
+    );
+
+    let selectedApp = null;
+    if (configAppName) {
+      selectedApp = apps.find((a) => a && a.name === configAppName) || null;
+      if (!selectedApp) {
+        const available = apps
+          .map((a) => a && a.name)
+          .filter(Boolean)
+          .join(', ');
+        const msg = `Unknown --config-app ${configAppName}. Available: ${available || '(none)'}`;
+        if (json)
+          console.log(JSON.stringify({ ok: false, error: { message: msg } }));
+        else console.error(msg);
+        return 2;
+      }
+    } else if (apps.length === 1) {
+      selectedApp = apps[0];
+    } else if (apps.some((a) => a && a.name === appId)) {
+      // Convenience: if user passed an app name (not id) to --app, treat it as config app selector.
+      selectedApp = apps.find((a) => a && a.name === appId) || null;
+    } else if (appsWithSecrets.length === 1) {
+      selectedApp = appsWithSecrets[0];
+    } else {
+      const available = apps
+        .map((a) => a && a.name)
+        .filter(Boolean)
+        .join(', ');
+      const msg =
+        `Multiple apps in .scaly/config.yaml. Use --config-app <name> to select which app's secrets to sync ` +
+        `to --app ${appId}. Available: ${available || '(none)'}`;
+      if (json)
+        console.log(JSON.stringify({ ok: false, error: { message: msg } }));
+      else console.error(msg);
+      return 2;
+    }
+
+    const wantedSecrets = [];
+    if (selectedApp && Array.isArray(selectedApp.secrets)) {
+      for (const s of selectedApp.secrets) {
+        if (!s || typeof s !== 'object') continue;
+        if (!s.name) continue;
+        wantedSecrets.push({ name: s.name, source_env: s.source_env || null });
+      }
+    }
+
+    const actions = [];
+    for (const s of wantedSecrets) {
+      const source = s.source_env;
+      const present = source
+        ? Object.prototype.hasOwnProperty.call(process.env, source)
+        : false;
+      actions.push({
+        name: s.name,
+        source_env: source,
+        present,
+        action: present ? (dryRun ? 'would_set' : 'set') : 'skipped'
+      });
+    }
+
+    if (!dryRun) {
+      for (const a of actions) {
+        if (a.action !== 'set') continue;
+        const value = process.env[a.source_env];
+        await secrets.setBuildSecret({ appId, name: a.name, value });
+      }
+    }
+
+    const out = {
+      ok: true,
+      app_id: appId,
+      config_app: selectedApp ? selectedApp.name : null,
+      dry_run: dryRun,
+      actions
+    };
+    if (json) console.log(JSON.stringify(out));
+    else {
+      for (const a of actions) {
+        const tag =
+          a.action === 'skipped' ? 'MISSING_ENV' : a.action.toUpperCase();
+        console.log(
+          `[secrets] ${tag} ${a.name}${a.source_env ? ` (${a.source_env})` : ''}`
+        );
+      }
+      if (dryRun)
+        console.log('[secrets] dry-run only. Re-run with --apply to write.');
+    }
+    return 0;
+  }
+
+  console.error('Usage: scaly secrets <list|set|delete|sync> ...');
+  return 2;
+}
+
+// -------------------------
+// DB tunnel: localhost port-forward via WSS
+// -------------------------
+async function mintDbProxyInfo(rest) {
+  const f = parseKv(rest);
+  const addOnId = f.addon || f['add-on'] || (f._ && f._[0]);
+  if (!addOnId) {
+    const e = new Error('db requires --addon <addOnId>');
+    e.code = 'SCALY_DB_ADDON_REQUIRED';
+    throw e;
+  }
+
+  const { getToken, apiPost, deriveDomain } = await importHelpers();
+  const bearer = await getToken();
+  if (!isProbablyJwt(bearer)) {
+    const e = new Error(
+      'db commands require a Cognito OIDC access token (JWT) in Authorization: Bearer.'
+    );
+    e.code = 'SCALY_DB_JWT_REQUIRED';
+    throw e;
+  }
+
+  const ttlMinutes =
+    f['ttl-minutes'] !== undefined ? Number(f['ttl-minutes']) : undefined;
+  const tokenRes = await apiPost(bearer, CREATE_DATABASE_PROXY_TOKEN_MUTATION, {
+    addOnId,
+    ttlMinutes
+  });
+  const info = tokenRes?.createDatabaseProxyToken;
+  if (!info?.token) {
+    const e = new Error('Could not mint database proxy token for add-on');
+    e.code = 'SCALY_DB_TOKEN_FAILED';
+    throw e;
+  }
+
+  const domain = deriveDomain();
+  const tunnelUrl = `wss://dbt.${domain}`;
+
+  return { f, addOnId, bearer, info, tunnelUrl };
+}
+
+async function startDbTunnelServer({ bearer, tunnelUrl, host, localPort }) {
+  const net = require('net');
+  const { WebSocket, createWebSocketStream } = require('ws');
+  const { pipeline } = require('stream');
+
+  const server = net.createServer((socket) => {
+    socket.setNoDelay(true);
+
+    const ws = new WebSocket(tunnelUrl, {
+      headers: {
+        authorization: `Bearer ${bearer}`
+      }
+    });
+
+    let closed = false;
+    const closeAll = () => {
+      if (closed) return;
+      closed = true;
+      try {
+        socket.destroy();
+      } catch {}
+      try {
+        ws.terminate();
+      } catch {}
+    };
+
+    const done = () => closeAll();
+    const wsStream = createWebSocketStream(ws);
+    pipeline(socket, wsStream, done);
+    pipeline(wsStream, socket, done);
+
+    ws.on('close', done);
+    ws.on('error', done);
+    socket.on('close', done);
+    socket.on('error', done);
+  });
+
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(localPort, host, resolve);
+  });
+
+  return server;
+}
+
+async function runDbConnect(rest) {
+  const f = parseKv(rest);
+  const json = parseBool(f.json, false);
+  const show = parseBool(f.show, false);
+  const copy = f.copy !== undefined ? parseBool(f.copy, true) : !show;
+
+  let minted;
+  try {
+    minted = await mintDbProxyInfo(rest);
+  } catch (e) {
+    const msg = String(e && e.message ? e.message : e);
+    if (json)
+      console.log(JSON.stringify({ ok: false, error: { message: msg } }));
+    else console.error(msg);
+    return 2;
+  }
+  const { addOnId, bearer, info, tunnelUrl } = minted;
+
+  const host = f.host || '127.0.0.1';
+  const localPort = Number(f['local-port'] || info.port || 5432);
+
+  const server = await startDbTunnelServer({
+    bearer,
+    tunnelUrl,
+    host,
+    localPort
+  });
+
+  const psqlCmd = `PGSSLMODE=require PGPASSWORD='${info.token}' psql -h ${host} -p ${localPort} -U ${info.username} -d ${info.database}`;
+  let copied = false;
+  if (copy && !show) {
+    copied = copyToClipboard(psqlCmd);
+  }
+
+  if (json) {
+    console.log(
+      JSON.stringify({
+        ok: true,
+        addon_id: addOnId,
+        host,
+        local_port: localPort,
+        username: info.username,
+        database: info.database,
+        expires_at: info.expiresAt,
+        copied,
+        show_supported: true
+      })
+    );
+  } else {
+    console.log(`[db connect] addOn=${addOnId}`);
+    console.log(
+      `[db connect] tunnel=${tunnelUrl} -> localhost ${host}:${localPort}`
+    );
+    console.log(`[db connect] token expiresAt=${info.expiresAt}`);
+    console.log('');
+    if (show) {
+      console.log(psqlCmd);
+      console.log('');
+    } else if (copy) {
+      console.log(
+        copied
+          ? '[db connect] copied psql command to clipboard (use --show to print)'
+          : '[db connect] could not copy to clipboard; re-run with --show to print'
+      );
+      console.log('');
+    }
+  }
+
+  if (!json) {
+    console.log(
+      `[db connect] listening on ${host}:${localPort} (Ctrl-C to stop)`
+    );
+  }
+
+  const closeServer = () => {
+    try {
+      server.close(() => process.exit(0));
+    } catch {
+      process.exit(0);
+    }
+  };
+  process.once('SIGINT', closeServer);
+  process.once('SIGTERM', closeServer);
+  await new Promise(() => {});
+}
+
+async function runDbShell(rest) {
+  const { spawnSync } = require('child_process');
+  const f = parseKv(rest);
+  let minted;
+  try {
+    minted = await mintDbProxyInfo(rest);
+  } catch (e) {
+    console.error(String(e && e.message ? e.message : e));
+    return 2;
+  }
+  const { addOnId, bearer, info, tunnelUrl } = minted;
+  const host = f.host || '127.0.0.1';
+  const localPort = Number(f['local-port'] || info.port || 5432);
+  const server = await startDbTunnelServer({
+    bearer,
+    tunnelUrl,
+    host,
+    localPort
+  });
+
+  const env = {
+    ...process.env,
+    PGPASSWORD: info.token,
+    PGSSLMODE: 'require'
+  };
+
+  console.log(`[db shell] addOn=${addOnId} on ${host}:${localPort}`);
+  const res = spawnSync(
+    'psql',
+    [
+      '-h',
+      host,
+      '-p',
+      String(localPort),
+      '-U',
+      info.username,
+      '-d',
+      info.database
+    ],
+    {
+      stdio: 'inherit',
+      env
+    }
+  );
+
+  try {
+    server.close();
+  } catch {}
+  return typeof res.status === 'number' ? res.status : 1;
+}
+
+async function runDbSchemaDump(rest) {
+  const { spawnSync } = require('child_process');
+  const fs = require('fs');
+  const path = require('path');
+  const f = parseKv(rest);
+
+  const outPath = f.out || path.join('.scaly', 'schema.sql');
+
+  let minted;
+  try {
+    minted = await mintDbProxyInfo(rest);
+  } catch (e) {
+    console.error(String(e && e.message ? e.message : e));
+    return 2;
+  }
+  const { addOnId, bearer, info, tunnelUrl } = minted;
+  const host = f.host || '127.0.0.1';
+  const localPort = Number(f['local-port'] || info.port || 5432);
+  const server = await startDbTunnelServer({
+    bearer,
+    tunnelUrl,
+    host,
+    localPort
+  });
+
+  const env = {
+    ...process.env,
+    PGPASSWORD: info.token,
+    PGSSLMODE: 'require'
+  };
+
+  console.log(`[db schema dump] addOn=${addOnId} -> ${outPath}`);
+
+  const res = spawnSync(
+    'pg_dump',
+    [
+      '--schema-only',
+      '--no-owner',
+      '--no-privileges',
+      '-h',
+      host,
+      '-p',
+      String(localPort),
+      '-U',
+      info.username,
+      '-d',
+      info.database
+    ],
+    { encoding: 'utf8', env }
+  );
+
+  try {
+    server.close();
+  } catch {}
+
+  if (res.status !== 0) {
+    console.error(res.stderr || '[db schema dump] pg_dump failed');
+    return res.status || 1;
+  }
+
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  fs.writeFileSync(outPath, res.stdout, 'utf8');
+  console.log(`[db schema dump] wrote ${outPath}`);
+  return 0;
+}
+
+async function runDbMigrate(rest) {
+  const { spawnSync } = require('child_process');
+  const fs = require('fs');
+  const path = require('path');
+  const f = parseKv(rest);
+  const file = (f._ && f._[0]) || null;
+  if (!file) {
+    console.error(
+      'Usage: scaly db migrate <sql-file> --addon <addOnId> [--yes]'
+    );
+    return 2;
+  }
+  const yes = parseBool(f.yes, false);
+
+  const abs = path.resolve(file);
+  if (!fs.existsSync(abs)) {
+    console.error(`Migration file not found: ${abs}`);
+    return 2;
+  }
+  if (!yes) {
+    const ok = await promptYesNo(`Apply migration ${abs}? (y/N) `);
+    if (!ok) {
+      console.error('Aborted.');
+      return 1;
+    }
+  }
+
+  let minted;
+  try {
+    minted = await mintDbProxyInfo(rest);
+  } catch (e) {
+    console.error(String(e && e.message ? e.message : e));
+    return 2;
+  }
+  const { addOnId, bearer, info, tunnelUrl } = minted;
+  const host = f.host || '127.0.0.1';
+  const localPort = Number(f['local-port'] || info.port || 5432);
+  const server = await startDbTunnelServer({
+    bearer,
+    tunnelUrl,
+    host,
+    localPort
+  });
+
+  const env = {
+    ...process.env,
+    PGPASSWORD: info.token,
+    PGSSLMODE: 'require'
+  };
+
+  console.log(`[db migrate] addOn=${addOnId} file=${abs}`);
+  const res = spawnSync(
+    'psql',
+    [
+      '-v',
+      'ON_ERROR_STOP=1',
+      '-h',
+      host,
+      '-p',
+      String(localPort),
+      '-U',
+      info.username,
+      '-d',
+      info.database,
+      '-f',
+      abs
+    ],
+    { stdio: 'inherit', env }
+  );
+
+  try {
+    server.close();
+  } catch {}
+
+  return typeof res.status === 'number' ? res.status : 1;
+}
+
+// -------------------------
+// Insights: diagnose-app
+// -------------------------
+async function runDiagnoseApp(rest) {
+  const f = parseKv(rest);
+  const accountId = f.account;
+  const stackId = f.stack;
+  const appName = f.app || (f._ && f._[0]);
+  if (!accountId || !stackId || !appName) {
+    console.error(
+      'diagnose-app requires --account <id> --stack <id> --app <name>'
+    );
+    return 2;
+  }
+  await sourceLocalEnv();
+  const {
+    getToken,
+    apiPost,
+    deriveDomain,
+    regionToAws,
+    checkHttp200,
+    makeCreds,
+    elbClient,
+    ecsClient
+  } = await importHelpers();
+  const token = await getToken();
+
+  const stackRes = await apiPost(token, GET_STACK_QUERY, {
+    where: { id: stackId }
+  });
+  const stack = stackRes?.getStack;
+  const domain = deriveDomain();
+  const accountPrefix = String(accountId).split('-')[0];
+  const url = `https://${accountPrefix}-${stack?.name}.${domain}/${appName}/`;
+
+  // Probe URL
+  const http = await checkHttp200(url, {
+    tries: Number(f.tries) || 6,
+    delayMs: Number(f['delay-ms']) || 5000
+  });
+
+  // Pull stack logs for last N (default 30m)
+  const lookback = f.since || '30m';
+  const logsRes = await apiPost(token, GET_SCALY_STACK_LOGS, {
+    where: { id: stackId, startTime: sinceToIso(lookback) }
+  });
+  const events = (logsRes?.getScalyStackLogs?.events || []).slice(-400);
+
+  const findings = [];
+  const text = events.map((e) => e.message || '').join('\n');
+  if (/fork\/exec\s+venv\/bin\/python: no such file/i.test(text)) {
+    findings.push({
+      code: 'APP_VENV_MISSING',
+      severity: 'high',
+      hint: 'Replicator/unpacker missing venv. Confirm rootfs contains venv and python shim.'
+    });
+  }
+  if (
+    /http:\s+proxy error: dial tcp 127\.0\.0\.1/i.test(text) ||
+    /connection refused/i.test(text)
+  ) {
+    findings.push({
+      code: 'APP_PORT_REFUSED',
+      severity: 'high',
+      hint: 'App process not listening. Check start command and runtime.'
+    });
+  }
+  if (/Unable to determine type of app/i.test(text)) {
+    findings.push({
+      code: 'APP_TYPE_UNKNOWN',
+      severity: 'medium',
+      hint: 'Server could not infer app type; ensure template sets it or requirements specify.'
+    });
+  }
+  if (/User pool .* does not exist/i.test(text)) {
+    findings.push({
+      code: 'COGNITO_POOL_MISSING',
+      severity: 'medium',
+      hint: 'Identity add-on misconfigured; verify user pool id/region.'
+    });
+  }
+  if (/ResourceAlreadyExistsException/i.test(text)) {
+    findings.push({
+      code: 'RESOURCE_EXISTS',
+      severity: 'low',
+      hint: 'Installer attempted to create a resource owned by the stack. Remove ad-hoc creation.'
+    });
+  }
+  // Node runtime signals
+  if (/MODULE_NOT_FOUND|Cannot find module/i.test(text)) {
+    findings.push({
+      code: 'NODE_MODULE_NOT_FOUND',
+      severity: 'high',
+      hint: 'node_modules missing or build incomplete. Ensure deps bundled or installed server-side.'
+    });
+  }
+  if (/npm ERR!/i.test(text)) {
+    findings.push({
+      code: 'NPM_ERROR',
+      severity: 'medium',
+      hint: 'NPM failed during build/start. Inspect logs for first error.'
+    });
+  }
+  if (/EADDRINUSE|address already in use/i.test(text)) {
+    findings.push({
+      code: 'PORT_IN_USE',
+      severity: 'medium',
+      hint: 'App bound to a busy port. Ensure it binds to the provided port.'
+    });
+  }
+  // R runtime signals
+  if (
+    /there is no package called/i.test(text) ||
+    /package or namespace load failed/i.test(text)
+  ) {
+    findings.push({
+      code: 'R_PACKAGE_MISSING',
+      severity: 'high',
+      hint: 'renv restore likely incomplete. Verify renv.lock and cache installer finished.'
+    });
+  }
+  if (/cannot open shared object file/i.test(text)) {
+    findings.push({
+      code: 'R_SHARED_LIB_MISSING',
+      severity: 'medium',
+      hint: 'System library missing. Consider adding runtime shim with required libs.'
+    });
+  }
+
+  // Infra checks (ALB target health + ECS tasks) using brokered creds
+  let infra = {};
+  try {
+    const region = regionToAws(stack?.account?.region || 'EU') || 'eu-west-1';
+    const credsRes = await apiPost(token, ISSUE_AWS_CREDENTIALS_MUTATION, {
+      input: {
+        accountId,
+        regionAws: region,
+        scopes: ['ELBV2_READ', 'ECS_READ'],
+        durationSeconds: 900
+      }
+    });
+    const c = credsRes?.issueAwsCredentials;
+    if (c?.accessKeyId) {
+      const creds = makeCreds(c);
+      // Target group heuristic: scaly-<first8-of-stackId>
+      const shortId = String(stackId).split('-')[0];
+      const elb = elbClient(region, creds);
+      const tgResp = await elb.send(new DescribeTargetGroupsCommand({}));
+      const tgs = (tgResp?.TargetGroups || []).filter((t) =>
+        (t.TargetGroupName || '').includes(shortId)
+      );
+      let targetHealth = null;
+      if (tgs.length > 0 && tgs[0].TargetGroupArn) {
+        const th = await elb.send(
+          new DescribeTargetHealthCommand({
+            TargetGroupArn: tgs[0].TargetGroupArn
+          })
+        );
+        targetHealth = (th?.TargetHealthDescriptions || []).map((d) => ({
+          id: d.Target?.Id,
+          port: d.Target?.Port,
+          state: d.TargetHealth?.State,
+          reason: d.TargetHealth?.Reason
+        }));
+      }
+
+      const ecs = ecsClient(region, creds);
+      const clusters = await ecs.send(new ListClustersCommand({}));
+      const clusterArns = (clusters?.clusterArns || []).filter((a) =>
+        /scaly-/.test(a)
+      );
+      let services = [];
+      for (const cluster of clusterArns) {
+        const ls = await ecs.send(new ListServicesCommand({ cluster }));
+        const svcArns = (ls?.serviceArns || []).filter((a) =>
+          a.includes(shortId)
+        );
+        if (svcArns.length) {
+          const ds = await ecs.send(
+            new DescribeServicesCommand({ cluster, services: svcArns })
+          );
+          for (const s of ds?.services || []) {
+            const lt = await ecs.send(
+              new ListTasksCommand({ cluster, serviceName: s.serviceName })
+            );
+            let tasks = [];
+            if ((lt?.taskArns || []).length) {
+              const dt = await ecs.send(
+                new DescribeTasksCommand({ cluster, tasks: lt.taskArns })
+              );
+              tasks = (dt?.tasks || []).map((t) => ({
+                taskArn: t.taskArn,
+                lastStatus: t.lastStatus,
+                desiredStatus: t.desiredStatus
+              }));
+            }
+            services.push({
+              cluster,
+              serviceName: s.serviceName,
+              desired: s.desiredCount,
+              running: s.runningCount,
+              tasks
+            });
+          }
+        }
+      }
+      infra = { region, targetGroupCount: tgs.length, targetHealth, services };
+    }
+  } catch (e) {
+    infra = { error: String((e && e.message) || e) };
+  }
+
+  const ok = !!http;
+  const summary = {
+    ok,
+    url,
+    http: http || null,
+    findings,
+    sample: events.slice(-10),
+    infra
+  };
+  if (f.json && String(f.json).toLowerCase() !== 'false') {
+    console.log(JSON.stringify(summary));
+  } else {
+    console.log('DIAG_RESULT:', JSON.stringify(summary, null, 2));
+  }
+  return ok ? 0 : 1;
+}
+
+// -------------------------
+// Auth: AWS via STS broker
+// -------------------------
+async function runAuthAws(rest) {
+  const f = parseKv(rest);
+  const regionArg = f.region || f.r;
+  const scopesArg = f.scopes || f.s;
+  const duration = Number(f.duration) || 1800;
+  if (!regionArg || !scopesArg) {
+    console.error(
+      'auth aws requires --region <eu-west-1|EU|US|...> and --scopes <logs:read,ecs:read,...>'
+    );
+    return 2;
+  }
+  await sourceLocalEnv();
+  const { getToken, apiPost, regionToAws } = await importHelpers();
+  const token = await getToken();
+  const region = regionArg.includes('-')
+    ? regionArg
+    : regionToAws(regionArg) || regionArg;
+  const scopes = String(scopesArg)
+    .split(',')
+    .map((s) =>
+      s
+        .trim()
+        .toUpperCase()
+        .replace(/[^A-Z_]/g, '_')
+    )
+    .filter(Boolean);
+  const accountId = f.account || process.env.SCALY_ACCOUNT_ID || '';
+  if (!accountId) {
+    console.error(
+      '--account <id> is recommended for proper scoping (or set SCALY_ACCOUNT_ID)'
+    );
+  }
+  try {
+    const res = await apiPost(token, ISSUE_AWS_CREDENTIALS_MUTATION, {
+      input: {
+        accountId: accountId || 'UNKNOWN',
+        regionAws: region,
+        scopes,
+        durationSeconds: duration
+      }
+    });
+    const c = res && res.issueAwsCredentials;
+    if (!c || !c.accessKeyId)
+      throw new Error(
+        'Broker did not return credentials (API not yet enabled?)'
+      );
+    if (f.export && String(f.export).toLowerCase() !== 'false') {
+      console.log(
+        `# region=${c.region} role=${c.assumedRoleArn} exp=${c.expiration}`
+      );
+      console.log(`export AWS_ACCESS_KEY_ID='${c.accessKeyId}'`);
+      console.log(`export AWS_SECRET_ACCESS_KEY='${c.secretAccessKey}'`);
+      console.log(`export AWS_SESSION_TOKEN='${c.sessionToken}'`);
+      return 0;
+    }
+    // Default: JSON for programmatic/agent use
+    console.log(JSON.stringify(c));
+    return 0;
+  } catch (e) {
+    console.error(
+      'auth aws failed:',
+      (e && e.response && e.response.data) || String(e)
+    );
+    // Provide an inline fallback template
+    if (!(f.json && String(f.json).toLowerCase() !== 'false')) {
+      console.log(
+        `# Broker not available yet. Once enabled, rerun this command.`
+      );
+    }
+    return 1;
+  }
+}
+
+main(process.argv);