@occam-scaly/scaly-cli 0.2.7 → 0.2.9

package/bin/scaly.js

@@ -68,6 +68,15 @@ Usage:
   scaly auth status [--json]
   scaly auth logout [--json]
 
+  scaly doctor [--json] [--env-file .env] [--require KEY1,KEY2] [--db-host 127.0.0.1] [--db-port 5432] [--storage-addon <id>] [--storage-prefix <prefix>]
+
+  scaly user-groups list [--account <accountId>] [--json]
+  scaly user-groups members --name <group> [--account <accountId>] [--json]
+  scaly user-groups create --name <group> [--description <text>] [--account <accountId>] [--json]
+  scaly user-groups delete --name <group> [--yes] [--account <accountId>] [--json]
+  scaly user-groups add --name <group> <email...> [--emails a,b] [--account <accountId>] [--json]
+  scaly user-groups remove --name <group> <email...> [--emails a,b] [--account <accountId>] [--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]
@@ -132,6 +141,14 @@ function main(argv) {
     return runAuth(sub, flags).then((code) => process.exit(code));
   }
 
+  if (cmd === 'doctor') {
+    return runDoctor(args.slice(1)).then((code) => process.exit(code));
+  }
+
+  if (cmd === 'user-groups') {
+    return runUserGroups(sub, rest).then((code) => process.exit(code));
+  }
+
   if (cmd === 'secrets') {
     return runSecrets(sub, rest).then((code) => process.exit(code));
   }
@@ -487,28 +504,14 @@ async function sourceLocalEnv() {
 }
 
 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 { resolveApiEndpoint } = require('../lib/scaly-api');
+  const { normalizeStage, readAuthStore } = require('../lib/scaly-auth');
+
+  // Ensure API endpoint is set for common commands (db/secrets/etc).
+  if (!process.env.API_ENDPOINT && !process.env.SCALY_API_URL) {
+    process.env.API_ENDPOINT = resolveApiEndpoint();
+  }
 
   const API = () => process.env.API_ENDPOINT;
   const deriveDomain = () => {
@@ -528,12 +531,48 @@ async function importHelpers() {
     })[String(r || '').toUpperCase()] || null;
 
   async function getToken() {
-    // Prefer stored bearer token or env override to avoid aws-vault
+    // Prefer stored bearer token or env override.
     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');
+
+    // Prefer a Scaly session token from `scaly auth login`.
+    if (process.env.SCALY_OIDC_TOKEN) return process.env.SCALY_OIDC_TOKEN;
+    const found = readAuthStore();
+    if (found && found.session && found.session.access_token) {
+      const s = found.session;
+      const expMs = typeof s.expires_at === 'number' ? s.expires_at : null;
+      const stage = normalizeStage(
+        s.stage || process.env.SCALY_STAGE || 'prod'
+      );
+      if (!process.env.SCALY_STAGE) process.env.SCALY_STAGE = stage;
+      if (expMs && Date.now() >= expMs) {
+        const e = new Error(
+          `Your Scaly session token expired. Run: scaly auth login --stage ${stage}`
+        );
+        e.code = 'TOKEN_EXPIRED';
+        throw e;
+      }
+      return s.access_token;
+    }
+
+    // Internal-only fallback (dev tooling): Cognito client credentials via AWS Secrets Manager.
+    if (!process.env.COGNITO_SECRET) {
+      const stage = normalizeStage(process.env.SCALY_STAGE || 'prod');
+      const e = new Error(
+        `Not authenticated. Run: scaly auth login --stage ${stage}`
+      );
+      e.code = 'SCALY_AUTH_REQUIRED';
+      throw e;
+    }
     const region = process.env.COGNITO_SECRET_REGION || 'ca-central-1';
+    console.error(
+      '[warn] Using COGNITO_SECRET flow (internal dev only). Prefer: scaly auth login'
+    );
+    const {
+      SecretsManagerClient,
+      GetSecretValueCommand
+    } = require('@aws-sdk/client-secrets-manager');
     const sm = new SecretsManagerClient({ region });
     const res = await sm.send(
       new GetSecretValueCommand({ SecretId: process.env.COGNITO_SECRET })
@@ -571,9 +610,13 @@ async function importHelpers() {
   }
 
   function elbClient(region, creds) {
+    const {
+      ElasticLoadBalancingV2Client
+    } = require('@aws-sdk/client-elastic-load-balancing-v2');
     return new ElasticLoadBalancingV2Client({ region, credentials: creds });
   }
   function ecsClient(region, creds) {
+    const { ECSClient } = require('@aws-sdk/client-ecs');
     return new ECSClient({ region, credentials: creds });
   }
 
@@ -599,6 +642,10 @@ async function importHelpers() {
 
   async function checkCloudwatchLogs(accountId, appId, region) {
     try {
+      const {
+        CloudWatchLogsClient,
+        DescribeLogStreamsCommand
+      } = require('@aws-sdk/client-cloudwatch-logs');
       const cwl = new CloudWatchLogsClient({ region });
       const group = `/scaly/account/${accountId}`;
       const cmd = new DescribeLogStreamsCommand({
@@ -2284,6 +2331,36 @@ async function runSecrets(sub, rest) {
   const json = parseBool(f.json, false);
 
   // OIDC-only for build secrets.
+  try {
+    const { resolveApiEndpoint } = require('../lib/scaly-api');
+    const { normalizeStage, readAuthStore } = require('../lib/scaly-auth');
+    if (!process.env.API_ENDPOINT && !process.env.SCALY_API_URL) {
+      process.env.API_ENDPOINT = resolveApiEndpoint();
+    }
+
+    const found = readAuthStore();
+    if (
+      found &&
+      found.session &&
+      found.session.access_token &&
+      !process.env.SCALY_API_BEARER
+    ) {
+      const expMs =
+        typeof found.session.expires_at === 'number'
+          ? found.session.expires_at
+          : null;
+      const stage = normalizeStage(
+        found.session.stage || process.env.SCALY_STAGE || 'prod'
+      );
+      if (!process.env.SCALY_STAGE) process.env.SCALY_STAGE = stage;
+      if (expMs && Date.now() >= expMs) {
+        // Fall through to error message below.
+      } else {
+        process.env.SCALY_API_BEARER = found.session.access_token;
+      }
+    }
+  } catch {}
+
   try {
     const t = getStoredBearer();
     if (t && !process.env.SCALY_API_BEARER) process.env.SCALY_API_BEARER = t;
@@ -2295,8 +2372,8 @@ async function runSecrets(sub, rest) {
     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.';
+      'secrets commands require a Scaly session token (JWT). ' +
+      'Run `scaly auth login` first.';
     if (json)
       console.log(JSON.stringify({ ok: false, error: { message: msg } }));
     else console.error(msg);
@@ -2550,6 +2627,225 @@ async function runSecrets(sub, rest) {
   return 2;
 }
 
+// -------------------------
+// User Groups (account-scoped)
+// -------------------------
+async function runUserGroups(sub, rest) {
+  const action = String(sub || '')
+    .trim()
+    .toLowerCase();
+  const f = parseKv(rest);
+  const json = parseBool(f.json, false);
+
+  const accountId = await require('../lib/scaly-user-groups').resolveAccountId(
+    f.account || f['account-id'] || f.account_id
+  );
+  if (!accountId) {
+    const msg =
+      'Unable to infer account id. Pass --account <accountId> (or ensure you have accessible stacks).';
+    if (json)
+      console.log(JSON.stringify({ ok: false, error: { message: msg } }));
+    else console.error(msg);
+    return 2;
+  }
+
+  const groups = require('../lib/scaly-user-groups');
+
+  try {
+    if (!action || action === 'list') {
+      const res = await groups.listGroups({ accountId });
+      const out = {
+        ok: true,
+        account_id: accountId,
+        user_groups: { addon_id: res.pool.id, name: res.pool.name },
+        groups: (res.groups || []).map((g) => ({
+          name: g.name,
+          description: g.description || null
+        }))
+      };
+      if (json) console.log(JSON.stringify(out));
+      else out.groups.forEach((g) => console.log(g.name));
+      return 0;
+    }
+
+    if (action === 'members') {
+      const name = f.name || (f._ && f._[0]);
+      if (!name) {
+        const msg = '--name <group> is required';
+        if (json)
+          console.log(JSON.stringify({ ok: false, error: { message: msg } }));
+        else console.error(msg);
+        return 2;
+      }
+      const res = await groups.listGroupMembers({ accountId, name });
+      const out = {
+        ok: true,
+        account_id: accountId,
+        group: { name, description: res.group.description || null },
+        members: (res.members || []).map((u) => ({
+          email: u.email,
+          name: u.name,
+          status: u.status || null,
+          enabled: typeof u.enabled === 'boolean' ? u.enabled : null
+        }))
+      };
+      if (json) console.log(JSON.stringify(out));
+      else out.members.forEach((u) => console.log(u.email));
+      return 0;
+    }
+
+    if (action === 'create') {
+      const name = f.name || (f._ && f._[0]);
+      if (!name) {
+        const msg = '--name <group> is required';
+        if (json)
+          console.log(JSON.stringify({ ok: false, error: { message: msg } }));
+        else console.error(msg);
+        return 2;
+      }
+      const res = await groups.createGroup({
+        accountId,
+        name,
+        description: f.description || null
+      });
+      const out = {
+        ok: true,
+        account_id: accountId,
+        user_groups: { addon_id: res.pool.id, name: res.pool.name },
+        created: res.created
+      };
+      if (json) console.log(JSON.stringify(out));
+      else console.log(`Created group: ${name}`);
+      return 0;
+    }
+
+    if (action === 'delete') {
+      const name = f.name || (f._ && f._[0]);
+      const yes = parseBool(f.yes, false);
+      if (!name) {
+        const msg = '--name <group> is required';
+        if (json)
+          console.log(JSON.stringify({ ok: false, error: { message: msg } }));
+        else console.error(msg);
+        return 2;
+      }
+      if (!yes) {
+        const msg = 'Refusing to delete group without --yes';
+        if (json)
+          console.log(JSON.stringify({ ok: false, error: { message: msg } }));
+        else console.error(msg);
+        return 2;
+      }
+      const res = await groups.deleteGroup({ accountId, name });
+      const out = {
+        ok: true,
+        account_id: accountId,
+        deleted: true,
+        count: res.result ? res.result.count : null
+      };
+      if (json) console.log(JSON.stringify(out));
+      else console.log(`Deleted group: ${name}`);
+      return 0;
+    }
+
+    if (action === 'add' || action === 'remove') {
+      const name = f.name || (f._ && f._[0]);
+      if (!name) {
+        const msg = '--name <group> is required';
+        if (json)
+          console.log(JSON.stringify({ ok: false, error: { message: msg } }));
+        else console.error(msg);
+        return 2;
+      }
+      const rawEmails = []
+        .concat(f.emails ? String(f.emails).split(',') : [])
+        .concat(f.email ? [String(f.email)] : [])
+        .concat(Array.isArray(f._) ? f._.slice(1) : []);
+      const emails = rawEmails.map((e) => String(e).trim()).filter(Boolean);
+      if (!emails.length) {
+        const msg =
+          'At least one email is required (positional args or --emails a,b)';
+        if (json)
+          console.log(JSON.stringify({ ok: false, error: { message: msg } }));
+        else console.error(msg);
+        return 2;
+      }
+      const res =
+        action === 'add'
+          ? await groups.addUsers({ accountId, name, emails })
+          : await groups.removeUsers({ accountId, name, emails });
+      const out = {
+        ok: true,
+        account_id: accountId,
+        group: name,
+        emails,
+        count: res.result ? res.result.count : null
+      };
+      if (json) console.log(JSON.stringify(out));
+      else
+        console.log(
+          `${action === 'add' ? 'Added' : 'Removed'} ${emails.length} user(s).`
+        );
+      return 0;
+    }
+
+    const msg = `Unknown user-groups command: ${action}`;
+    if (json)
+      console.log(JSON.stringify({ ok: false, error: { message: msg } }));
+    else console.error(msg);
+    return 2;
+  } catch (e) {
+    const msg = String((e && e.message) || e);
+    if (json)
+      console.log(
+        JSON.stringify({
+          ok: false,
+          error: { message: msg, code: e && e.code ? e.code : null }
+        })
+      );
+    else console.error(msg);
+    return 2;
+  }
+}
+
+// -------------------------
+// Doctor (local checklist)
+// -------------------------
+async function runDoctor(rest) {
+  const f = parseKv(rest);
+  const json = parseBool(f.json, false);
+  const required =
+    f.require && typeof f.require === 'string'
+      ? f.require
+          .split(',')
+          .map((s) => s.trim())
+          .filter(Boolean)
+      : [];
+
+  const { runDoctor: doctor } = require('../lib/scaly-doctor');
+  const res = await doctor({
+    envFile: f['env-file'] || f.env_file || '.env',
+    requiredEnvVars: required,
+    dbHost: f['db-host'] || f.db_host || '127.0.0.1',
+    dbPort:
+      f['db-port'] !== undefined ? Number(f['db-port'] || f.db_port) : null,
+    storageAddonId: f['storage-addon'] || f.storage_addon || null,
+    storagePrefix: f['storage-prefix'] || f.storage_prefix || null
+  });
+
+  if (json) {
+    console.log(JSON.stringify(res));
+  } else {
+    for (const c of res.checks) {
+      const status = c.ok ? 'OK' : 'FAIL';
+      console.log(`[doctor] ${status} ${c.name}`);
+      if (c.hint) console.log(`         ${c.hint}`);
+    }
+  }
+
+  return res.ok ? 0 : 1;
+}
+
 // -------------------------
 // DB tunnel: localhost port-forward via WSS
 // -------------------------
@@ -2566,7 +2862,7 @@ async function mintDbProxyInfo(rest) {
   const bearer = await getToken();
   if (!isProbablyJwt(bearer)) {
     const e = new Error(
-      'db commands require a Cognito OIDC access token (JWT) in Authorization: Bearer.'
+      'db commands require a Scaly session token (JWT). Run `scaly auth login` first.'
     );
     e.code = 'SCALY_DB_JWT_REQUIRED';
     throw e;
@@ -3059,6 +3355,17 @@ async function runDiagnoseApp(rest) {
     });
     const c = credsRes?.issueAwsCredentials;
     if (c?.accessKeyId) {
+      const {
+        DescribeTargetGroupsCommand,
+        DescribeTargetHealthCommand
+      } = require('@aws-sdk/client-elastic-load-balancing-v2');
+      const {
+        ListClustersCommand,
+        ListServicesCommand,
+        DescribeServicesCommand,
+        ListTasksCommand,
+        DescribeTasksCommand
+      } = require('@aws-sdk/client-ecs');
       const creds = makeCreds(c);
       // Target group heuristic: scaly-<first8-of-stackId>
       const shortId = String(stackId).split('-')[0];

package/lib/scaly-api.js

@@ -140,7 +140,7 @@ function buildHeaders(auth) {
   };
 }
 
-async function graphqlRequest(query, variables) {
+async function graphqlRequest(query, variables, extraHeaders) {
   const endpoint = resolveApiEndpoint();
   const auth = resolveAuth();
   if (!auth) {
@@ -156,7 +156,10 @@ async function graphqlRequest(query, variables) {
     {
       headers: {
         'content-type': 'application/json',
-        ...buildHeaders(auth)
+        ...buildHeaders(auth),
+        ...(extraHeaders && typeof extraHeaders === 'object'
+          ? extraHeaders
+          : {})
       },
       timeout: 60_000
     }
@@ -304,6 +307,26 @@ const QUERIES = {
         minIdle
       }
     }
+  `,
+  listGroups: `
+    query ListGroups($where: AddOnWhereUniqueInput!) {
+      listGroups(where: $where) { name description }
+    }
+  `,
+  listGroupsWithUsers: `
+    query ListGroupsWithUsers($where: AddOnWhereUniqueInput!) {
+      listGroups(where: $where) { name description users { email name status enabled } }
+    }
+  `,
+  listBucketObjects: `
+    query ListBucketObjects($where: AddOnWhereUniqueInput!, $prefix: String, $pageSize: Int) {
+      listBucketObjects(where: $where, prefix: $prefix, pageSize: $pageSize) {
+        bucket
+        prefix
+        nextCursor
+        objects { key size lastModified }
+      }
+    }
   `
 };
 
@@ -332,6 +355,26 @@ const MUTATIONS = {
     mutation CreateAddOn($data: AddOnCreateInput!) {
       createAddOn(data: $data) { id name type accountId status }
     }
+  `,
+  createUserGroups: `
+    mutation CreateUserGroups($where: AddOnWhereUniqueInput!, $data: [CognitoUserGroupInput!]!) {
+      createUserGroups(where: $where, data: $data) { name description }
+    }
+  `,
+  deleteUserGroups: `
+    mutation DeleteUserGroups($where: AddOnWhereUniqueInput!, $groups: [String!]!) {
+      deleteUserGroups(where: $where, groups: $groups) { count }
+    }
+  `,
+  addUsersToGroups: `
+    mutation AddUsersToGroups($where: AddOnWhereUniqueInput!, $emails: [String!]!, $groups: [String!]!) {
+      addUsersToGroups(where: $where, emails: $emails, groups: $groups) { count }
+    }
+  `,
+  removeUsersFromGroups: `
+    mutation RemoveUsersFromGroups($where: AddOnWhereUniqueInput!, $emails: [String!]!, $groups: [String!]!) {
+      removeUsersFromGroups(where: $where, emails: $emails, groups: $groups) { count }
+    }
   `
 };
 
@@ -381,63 +424,162 @@ async function listAddOnsByType({ accountId, type, take = 10 }) {
   return data?.listAddOns || [];
 }
 
-async function createStack({ accountId, name, size, minIdle }) {
-  const data = await graphqlRequest(MUTATIONS.createStack, {
-    data: {
-      name,
-      size,
-      minIdle: typeof minIdle === 'number' ? minIdle : undefined,
-      account: { connect: { id: accountId } }
-    }
+async function listGroups({ addonId, includeUsers = false }) {
+  const data = await graphqlRequest(
+    includeUsers ? QUERIES.listGroupsWithUsers : QUERIES.listGroups,
+    { where: { id: addonId } }
+  );
+  return data?.listGroups || [];
+}
+
+async function createUserGroup({ addonId, name, description }) {
+  const data = await graphqlRequest(MUTATIONS.createUserGroups, {
+    where: { id: addonId },
+    data: [{ name, description: description || null }]
   });
-  return data?.createStack;
+  return (data?.createUserGroups || [])[0] || null;
 }
 
-async function updateStack({ id, name, size, minIdle }) {
-  const data = await graphqlRequest(MUTATIONS.updateStack, {
-    where: { id },
-    data: {
-      name: name || undefined,
-      size: size || undefined,
-      minIdle: typeof minIdle === 'number' ? minIdle : undefined
-    }
+async function deleteUserGroup({ addonId, name }) {
+  const data = await graphqlRequest(MUTATIONS.deleteUserGroups, {
+    where: { id: addonId },
+    groups: [name]
   });
-  return data?.updateStack;
+  return data?.deleteUserGroups || null;
 }
 
-async function createApp({ accountId, stackId, name, minIdle }) {
-  const data = await graphqlRequest(MUTATIONS.createApp, {
-    data: {
-      name,
-      minIdle: typeof minIdle === 'number' ? minIdle : undefined,
-      account: { connect: { id: accountId } },
-      stack: stackId ? { connect: { id: stackId } } : undefined
-    }
+async function addUsersToGroup({ addonId, name, emails }) {
+  const data = await graphqlRequest(MUTATIONS.addUsersToGroups, {
+    where: { id: addonId },
+    emails,
+    groups: [name]
   });
-  return data?.createApp;
+  return data?.addUsersToGroups || null;
 }
 
-async function updateApp({ id, stackId, name, minIdle }) {
-  const data = await graphqlRequest(MUTATIONS.updateApp, {
-    where: { id },
-    data: {
-      name: name || undefined,
-      minIdle: typeof minIdle === 'number' ? minIdle : undefined,
-      stack: stackId ? { connect: { id: stackId } } : undefined
-    }
+async function removeUsersFromGroup({ addonId, name, emails }) {
+  const data = await graphqlRequest(MUTATIONS.removeUsersFromGroups, {
+    where: { id: addonId },
+    emails,
+    groups: [name]
   });
-  return data?.updateApp;
+  return data?.removeUsersFromGroups || null;
 }
 
-async function createAddOn({ accountId, name, type, database }) {
-  const data = await graphqlRequest(MUTATIONS.createAddOn, {
-    data: {
-      name,
-      type,
-      account: { connect: { id: accountId } },
-      addOnDatabase: database ? { create: database } : undefined
-    }
+async function listBucketObjects({ addonId, prefix, pageSize = 1 }) {
+  const data = await graphqlRequest(QUERIES.listBucketObjects, {
+    where: { id: addonId },
+    prefix: prefix || null,
+    pageSize
   });
+  return data?.listBucketObjects || null;
+}
+
+async function createStack({
+  accountId,
+  name,
+  size,
+  minIdle,
+  executionGroupId
+}) {
+  const data = await graphqlRequest(
+    MUTATIONS.createStack,
+    {
+      data: {
+        name,
+        size,
+        minIdle: typeof minIdle === 'number' ? minIdle : undefined,
+        account: { connect: { id: accountId } }
+      }
+    },
+    executionGroupId
+      ? { 'x-scaly-execution-group-id': executionGroupId }
+      : undefined
+  );
+  return data?.createStack;
+}
+
+async function updateStack({ id, name, size, minIdle, executionGroupId }) {
+  const data = await graphqlRequest(
+    MUTATIONS.updateStack,
+    {
+      where: { id },
+      data: {
+        name: name || undefined,
+        size: size || undefined,
+        minIdle: typeof minIdle === 'number' ? minIdle : undefined
+      }
+    },
+    executionGroupId
+      ? { 'x-scaly-execution-group-id': executionGroupId }
+      : undefined
+  );
+  return data?.updateStack;
+}
+
+async function createApp({
+  accountId,
+  stackId,
+  name,
+  minIdle,
+  executionGroupId
+}) {
+  const data = await graphqlRequest(
+    MUTATIONS.createApp,
+    {
+      data: {
+        name,
+        minIdle: typeof minIdle === 'number' ? minIdle : undefined,
+        account: { connect: { id: accountId } },
+        stack: stackId ? { connect: { id: stackId } } : undefined
+      }
+    },
+    executionGroupId
+      ? { 'x-scaly-execution-group-id': executionGroupId }
+      : undefined
+  );
+  return data?.createApp;
+}
+
+async function updateApp({ id, stackId, name, minIdle, executionGroupId }) {
+  const data = await graphqlRequest(
+    MUTATIONS.updateApp,
+    {
+      where: { id },
+      data: {
+        name: name || undefined,
+        minIdle: typeof minIdle === 'number' ? minIdle : undefined,
+        stack: stackId ? { connect: { id: stackId } } : undefined
+      }
+    },
+    executionGroupId
+      ? { 'x-scaly-execution-group-id': executionGroupId }
+      : undefined
+  );
+  return data?.updateApp;
+}
+
+async function createAddOn({
+  accountId,
+  name,
+  type,
+  database,
+  executionGroupId
+}) {
+  const data = await graphqlRequest(
+    MUTATIONS.createAddOn,
+    {
+      data: {
+        name,
+        type,
+        account: { connect: { id: accountId } },
+        addOnDatabase: database ? { create: database } : undefined
+      }
+    },
+    executionGroupId
+      ? { 'x-scaly-execution-group-id': executionGroupId }
+      : undefined
+  );
   return data?.createAddOn;
 }
 
@@ -452,6 +594,12 @@ module.exports = {
   listAddOnsByType,
   listStacks,
   listApps,
+  listGroups,
+  createUserGroup,
+  deleteUserGroup,
+  addUsersToGroup,
+  removeUsersFromGroup,
+  listBucketObjects,
   createStack,
   updateStack,
   createApp,

package/lib/scaly-apply.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const api = require('./scaly-api');
+const { randomUUID } = require('crypto');
 
 async function applyPlan({ config, plan, autoApprove = false }) {
   const actionable = (plan.operations || []).filter(
@@ -8,6 +9,7 @@ async function applyPlan({ config, plan, autoApprove = false }) {
   );
 
   const results = [];
+  const executionGroupId = randomUUID();
 
   let createdStack = null;
   let stackId = null;
@@ -20,7 +22,8 @@ async function applyPlan({ config, plan, autoApprove = false }) {
         accountId: op.desired.accountId,
         name: op.desired.name,
         size: op.desired.size,
-        minIdle: op.desired.minIdle
+        minIdle: op.desired.minIdle,
+        executionGroupId
       });
       createdStack = res;
       stackId = res?.id || stackId;
@@ -33,7 +36,8 @@ async function applyPlan({ config, plan, autoApprove = false }) {
         id: op.resource.id,
         name: op.desired.name,
         size: op.desired.size,
-        minIdle: op.desired.minIdle
+        minIdle: op.desired.minIdle,
+        executionGroupId
       });
       stackId = res?.id || stackId;
       results.push({ op_id: op.id, ok: true, result: res });
@@ -48,7 +52,8 @@ async function applyPlan({ config, plan, autoApprove = false }) {
       const res = await api.createApp({
         accountId: op.desired.accountId,
         stackId,
-        name: op.desired.name
+        name: op.desired.name,
+        executionGroupId
       });
       results.push({ op_id: op.id, ok: true, result: res });
       continue;
@@ -59,7 +64,8 @@ async function applyPlan({ config, plan, autoApprove = false }) {
         accountId: op.desired.accountId,
         name: op.desired.name,
         type: op.desired.type,
-        database: op.desired.database || undefined
+        database: op.desired.database || undefined,
+        executionGroupId
       });
       results.push({ op_id: op.id, ok: true, result: res });
       continue;
@@ -76,6 +82,7 @@ async function applyPlan({ config, plan, autoApprove = false }) {
   return {
     ok,
     auto_approve: !!autoApprove,
+    execution_group_id: executionGroupId,
     applied: actionable.length,
     results,
     created_stack_id: createdStack?.id || null

package/lib/scaly-doctor.js

@@ -0,0 +1,211 @@
+'use strict';
+
+const fs = require('fs');
+const net = require('net');
+const path = require('path');
+
+const api = require('./scaly-api');
+const { normalizeStage, readAuthStore } = require('./scaly-auth');
+
+function parseEnvKeys(text) {
+  const out = new Set();
+  for (const rawLine of String(text || '').split('\n')) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) continue;
+    const idx = line.indexOf('=');
+    if (idx <= 0) continue;
+    out.add(line.slice(0, idx).trim());
+  }
+  return out;
+}
+
+function tcpCheck(host, port, timeoutMs = 1000) {
+  return new Promise((resolve) => {
+    const socket = net.createConnection({ host, port });
+    const done = (ok) => {
+      try {
+        socket.destroy();
+      } catch {}
+      resolve(ok);
+    };
+    socket.setTimeout(timeoutMs);
+    socket.once('connect', () => done(true));
+    socket.once('timeout', () => done(false));
+    socket.once('error', () => done(false));
+  });
+}
+
+async function runDoctor({
+  envFile = '.env',
+  requiredEnvVars = [],
+  dbHost = '127.0.0.1',
+  dbPort = null,
+  storageAddonId = null,
+  storagePrefix = null
+} = {}) {
+  const checks = [];
+
+  // Auth store / token
+  const found = readAuthStore();
+  const session = found && found.session ? found.session : null;
+  const stage = normalizeStage(
+    (session && session.stage) || process.env.SCALY_STAGE || 'prod'
+  );
+  const expMs =
+    session && typeof session.expires_at === 'number'
+      ? session.expires_at
+      : null;
+  const authenticated = Boolean(session && session.access_token);
+  const expired = Boolean(expMs && expMs <= Date.now());
+
+  checks.push({
+    name: 'auth',
+    ok: authenticated && !expired,
+    details: {
+      authenticated,
+      stage: session ? session.stage || stage : stage,
+      expires_in_seconds: expMs
+        ? Math.max(0, Math.floor((expMs - Date.now()) / 1000))
+        : null,
+      store_path: found ? found.path : null
+    },
+    hint: !authenticated
+      ? 'Run `scaly auth login`.'
+      : expired
+        ? `Run \`scaly auth login --stage ${stage}\`.`
+        : null
+  });
+
+  // API reachability
+  if (!process.env.SCALY_API_KEY) {
+    checks.push({
+      name: 'api',
+      ok: false,
+      details: { skipped: true },
+      hint: 'Set SCALY_API_KEY to verify API reachability.'
+    });
+  } else {
+    try {
+      const startedAt = Date.now();
+      await api.listStacks({ take: 1 });
+      checks.push({
+        name: 'api',
+        ok: true,
+        details: {
+          endpoint: api.resolveApiEndpoint(),
+          latency_ms: Date.now() - startedAt
+        }
+      });
+    } catch (e) {
+      checks.push({
+        name: 'api',
+        ok: false,
+        details: {
+          endpoint: api.resolveApiEndpoint(),
+          error: String((e && e.message) || e)
+        },
+        hint: 'Verify SCALY_API_KEY / SCALY_STAGE and confirm the API is reachable.'
+      });
+    }
+  }
+
+  // .env key checklist (optional)
+  if (Array.isArray(requiredEnvVars) && requiredEnvVars.length > 0) {
+    try {
+      const abs = path.resolve(envFile);
+      if (!fs.existsSync(abs)) {
+        checks.push({
+          name: 'env',
+          ok: false,
+          details: {
+            env_file: envFile,
+            missing_file: true,
+            required: requiredEnvVars
+          },
+          hint: `Create ${envFile} (or pass --env-file <path>).`
+        });
+      } else {
+        const keys = parseEnvKeys(fs.readFileSync(abs, 'utf8'));
+        const missing = requiredEnvVars.filter((k) => !keys.has(k));
+        checks.push({
+          name: 'env',
+          ok: missing.length === 0,
+          details: { env_file: envFile, required: requiredEnvVars, missing },
+          hint: missing.length
+            ? `Add missing keys to ${envFile} (values are not shown).`
+            : null
+        });
+      }
+    } catch (e) {
+      checks.push({
+        name: 'env',
+        ok: false,
+        details: { env_file: envFile, error: String((e && e.message) || e) }
+      });
+    }
+  }
+
+  // DB tunnel port check (optional)
+  if (typeof dbPort === 'number') {
+    const okTcp = await tcpCheck(dbHost, dbPort, 1000);
+    checks.push({
+      name: 'db_tunnel',
+      ok: okTcp,
+      details: { host: dbHost, port: dbPort },
+      hint: okTcp ? null : 'Start a DB tunnel (CLI or MCP) and retry.'
+    });
+  }
+
+  // Storage access check (optional)
+  if (storageAddonId) {
+    if (!process.env.SCALY_API_KEY) {
+      checks.push({
+        name: 'storage',
+        ok: false,
+        details: { addon_id: storageAddonId, skipped: true },
+        hint: 'Set SCALY_API_KEY and run `scaly auth login` to verify storage access.'
+      });
+    } else if (!authenticated || expired) {
+      checks.push({
+        name: 'storage',
+        ok: false,
+        details: { addon_id: storageAddonId, skipped: true },
+        hint: `Run \`scaly auth login --stage ${stage}\` to enable storage checks.`
+      });
+    } else {
+      try {
+        const startedAt = Date.now();
+        const res = await api.listBucketObjects({
+          addonId: storageAddonId,
+          prefix: storagePrefix,
+          pageSize: 1
+        });
+        checks.push({
+          name: 'storage',
+          ok: true,
+          details: {
+            addon_id: storageAddonId,
+            bucket: res ? res.bucket : null,
+            prefix: storagePrefix,
+            latency_ms: Date.now() - startedAt
+          }
+        });
+      } catch (e) {
+        checks.push({
+          name: 'storage',
+          ok: false,
+          details: {
+            addon_id: storageAddonId,
+            error: String((e && e.message) || e)
+          },
+          hint: 'Verify storage add-on id and that your session token is valid.'
+        });
+      }
+    }
+  }
+
+  const ok = checks.every((c) => c.ok !== false);
+  return { ok, checks };
+}
+
+module.exports = { runDoctor };

package/lib/scaly-user-groups.js

@@ -0,0 +1,97 @@
+'use strict';
+
+const api = require('./scaly-api');
+
+async function resolveAccountId(explicit) {
+  if (explicit) return explicit;
+  const stacks = await api.listStacks({ take: 1 });
+  return stacks && stacks[0] ? stacks[0].accountId : null;
+}
+
+async function getAccountUserGroupsAddOn(accountId) {
+  const pools = await api.listAddOnsByType({
+    accountId,
+    type: 'COGNITO',
+    take: 5
+  });
+  if (!pools || pools.length === 0) {
+    const e = new Error(
+      'User Groups is not provisioned for this account. Contact support to repair this account.'
+    );
+    e.code = 'COGNITO_POOL_MISSING';
+    throw e;
+  }
+  if (pools.length > 1) {
+    const e = new Error(
+      'Multiple User Groups pools exist in this account. Contact support to repair this account before continuing.'
+    );
+    e.code = 'COGNITO_POOL_DUPLICATE';
+    e.details = { pools };
+    throw e;
+  }
+  return pools[0];
+}
+
+async function listGroups({ accountId }) {
+  const pool = await getAccountUserGroupsAddOn(accountId);
+  const groups = await api.listGroups({
+    addonId: pool.id,
+    includeUsers: false
+  });
+  return { pool, groups };
+}
+
+async function listGroupMembers({ accountId, name }) {
+  const pool = await getAccountUserGroupsAddOn(accountId);
+  const groups = await api.listGroups({ addonId: pool.id, includeUsers: true });
+  const g = (groups || []).find((x) => x && x.name === name) || null;
+  if (!g) {
+    const e = new Error(`Group not found: ${name}`);
+    e.code = 'GROUP_NOT_FOUND';
+    throw e;
+  }
+  return { pool, group: g, members: g.users || [] };
+}
+
+async function createGroup({ accountId, name, description }) {
+  const pool = await getAccountUserGroupsAddOn(accountId);
+  const created = await api.createUserGroup({
+    addonId: pool.id,
+    name,
+    description
+  });
+  return { pool, created };
+}
+
+async function deleteGroup({ accountId, name }) {
+  const pool = await getAccountUserGroupsAddOn(accountId);
+  const res = await api.deleteUserGroup({ addonId: pool.id, name });
+  return { pool, result: res };
+}
+
+async function addUsers({ accountId, name, emails }) {
+  const pool = await getAccountUserGroupsAddOn(accountId);
+  const res = await api.addUsersToGroup({ addonId: pool.id, name, emails });
+  return { pool, result: res };
+}
+
+async function removeUsers({ accountId, name, emails }) {
+  const pool = await getAccountUserGroupsAddOn(accountId);
+  const res = await api.removeUsersFromGroup({
+    addonId: pool.id,
+    name,
+    emails
+  });
+  return { pool, result: res };
+}
+
+module.exports = {
+  resolveAccountId,
+  getAccountUserGroupsAddOn,
+  listGroups,
+  listGroupMembers,
+  createGroup,
+  deleteGroup,
+  addUsers,
+  removeUsers
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@occam-scaly/scaly-cli",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "description": "Scaly CLI (auth + project config helpers)",
   "bin": {
     "scaly": "./bin/scaly.js"