@occam-scaly/scaly-cli 0.1.0

package/lib/scaly-plan.js

@@ -0,0 +1,392 @@
+'use strict';
+
+const { stableStringify, sha256Prefixed } = require('./stable-json');
+const api = require('./scaly-api');
+
+function normalizeEnv(env) {
+  if (!env) return null;
+  const v = String(env).trim().toLowerCase();
+  if (!v) return null;
+  return v;
+}
+
+function pick(obj, keys) {
+  const out = {};
+  for (const k of keys) {
+    if (obj && typeof obj === 'object' && k in obj) out[k] = obj[k];
+  }
+  return out;
+}
+
+function stableOpSort(a, b) {
+  const kindOrder = { stack: 0, addon: 1, app: 2 };
+  const ao = kindOrder[a.kind] ?? 9;
+  const bo = kindOrder[b.kind] ?? 9;
+  if (ao !== bo) return ao - bo;
+  const ak = `${a.kind}:${a.resource?.name || ''}:${a.resource?.id || ''}`;
+  const bk = `${b.kind}:${b.resource?.name || ''}:${b.resource?.id || ''}`;
+  return ak.localeCompare(bk);
+}
+
+function mapAddOnType(type) {
+  const t = String(type || '').toLowerCase();
+  if (t === 'database') return 'DATABASE';
+  if (t === 'storage' || t === 'storage_s3' || t === 's3') return 'STORAGE_S3';
+  if (t === 'cognito' || t === 'userpool' || t === 'user_pool')
+    return 'COGNITO';
+  if (t === 'cname') return 'CNAME';
+  return null;
+}
+
+function mapDbEngine(engine) {
+  const e = String(engine || '').toUpperCase();
+  if (!e) return null;
+  if (e === 'POSTGRES_16') return 'POSTGRES_16';
+  if (e === 'POSTGRES_14') return 'POSTGRES_14';
+  if (e === 'MYSQL_80') return 'MYSQL_80';
+  return null;
+}
+
+async function resolveAccountId({ config }) {
+  const explicit = config?.account?.id;
+  if (explicit) return explicit;
+
+  const slug = config?.account?.slug;
+  if (slug && typeof api.findAccountBySlug === 'function') {
+    const acct = await api.findAccountBySlug(slug);
+    if (acct?.id) return acct.id;
+  }
+
+  const stacks = await api.listStacks({ take: 10 });
+  if (stacks?.[0]?.accountId) return stacks[0].accountId;
+
+  const e = new Error(
+    'Unable to infer account ID. Add `account: { id: ... }` to `.scaly/config.yaml` or ensure you have at least one stack in the account.'
+  );
+  e.code = 'SCALY_ACCOUNT_UNRESOLVED';
+  throw e;
+}
+
+function diffFields({ current, desired, fields }) {
+  const diffs = [];
+  for (const field of fields) {
+    const c = current ? current[field] : undefined;
+    const d = desired ? desired[field] : undefined;
+    if (typeof d === 'undefined') continue;
+    if (c !== d) diffs.push({ field, current: c ?? null, desired: d ?? null });
+  }
+  return diffs;
+}
+
+async function buildPlan({ config, env, appName }) {
+  const warnings = [];
+  const drift = [];
+  const ops = [];
+  const normalizedEnv = normalizeEnv(env);
+
+  if (config?.stack?.region) {
+    warnings.push(
+      'config.stack.region is currently informational only (Stack has no region field in the API).'
+    );
+  }
+
+  const desiredStack = {
+    name: config.stack.name,
+    size: config.stack.size,
+    minIdle:
+      typeof config.stack.minIdle === 'number'
+        ? config.stack.minIdle
+        : config.stack.minIdle != null
+          ? Number(config.stack.minIdle)
+          : undefined
+  };
+
+  const stacks = await api.findStackByName(desiredStack.name);
+  const currentStack = stacks?.[0] || null;
+  if (stacks.length > 1) {
+    warnings.push(
+      `Multiple stacks found named '${desiredStack.name}'. Using '${currentStack.id}'.`
+    );
+  }
+
+  let accountId = currentStack?.accountId || null;
+  if (!accountId) {
+    accountId = await resolveAccountId({ config });
+  }
+
+  let stackOpId = null;
+  if (!currentStack) {
+    stackOpId = 'op_stack_create';
+    ops.push({
+      id: stackOpId,
+      kind: 'stack',
+      action: 'create',
+      resource: { type: 'stack', name: desiredStack.name },
+      current: null,
+      desired: { ...desiredStack, accountId },
+      diff: [{ field: 'exists', current: false, desired: true }]
+    });
+  } else {
+    const diffs = diffFields({
+      current: currentStack,
+      desired: desiredStack,
+      fields: ['size', 'minIdle']
+    });
+    if (diffs.length) {
+      stackOpId = 'op_stack_update';
+      ops.push({
+        id: stackOpId,
+        kind: 'stack',
+        action: 'update',
+        resource: {
+          type: 'stack',
+          name: currentStack.name,
+          id: currentStack.id
+        },
+        current: pick(currentStack, [
+          'id',
+          'name',
+          'accountId',
+          'size',
+          'minIdle'
+        ]),
+        desired: { ...desiredStack, accountId },
+        diff: diffs
+      });
+    } else {
+      ops.push({
+        id: 'op_stack_noop',
+        kind: 'stack',
+        action: 'noop',
+        resource: {
+          type: 'stack',
+          name: currentStack.name,
+          id: currentStack.id
+        },
+        current: pick(currentStack, [
+          'id',
+          'name',
+          'accountId',
+          'size',
+          'minIdle'
+        ]),
+        desired: { ...desiredStack, accountId },
+        diff: []
+      });
+    }
+  }
+
+  const desiredApps = (config.apps || []).filter(Boolean);
+  const filteredApps = appName
+    ? desiredApps.filter((a) => a && a.name === appName)
+    : desiredApps;
+  if (appName && filteredApps.length === 0) {
+    const e = new Error(
+      `Unknown app '${appName}'. Available: ${(desiredApps || [])
+        .map((a) => a && a.name)
+        .filter(Boolean)
+        .join(', ')}`
+    );
+    e.code = 'SCALY_APP_NOT_FOUND_IN_CONFIG';
+    throw e;
+  }
+
+  if ((desiredApps || []).some((a) => a && a.path)) {
+    warnings.push(
+      'apps[].path is currently informational only (plan/apply does not inspect your source tree yet).'
+    );
+  }
+
+  for (const desiredApp of filteredApps) {
+    const apps = await api.findAppByName(desiredApp.name);
+    const currentApp = apps?.[0] || null;
+    if (apps.length > 1) {
+      warnings.push(
+        `Multiple apps found named '${desiredApp.name}'. Using '${currentApp.id}'.`
+      );
+    }
+
+    if (!currentApp) {
+      ops.push({
+        id: `op_app_create_${desiredApp.name}`,
+        kind: 'app',
+        action: 'create',
+        depends_on: stackOpId ? [stackOpId] : undefined,
+        resource: { type: 'app', name: desiredApp.name },
+        current: null,
+        desired: {
+          name: desiredApp.name,
+          framework: desiredApp.framework,
+          accountId,
+          stackName: desiredStack.name
+        },
+        diff: [{ field: 'exists', current: false, desired: true }]
+      });
+      continue;
+    }
+
+    // For now, we only ensure the app exists. Framework is informational (API source/runtime varies by deploy method).
+    ops.push({
+      id: `op_app_noop_${desiredApp.name}`,
+      kind: 'app',
+      action: 'noop',
+      resource: { type: 'app', name: currentApp.name, id: currentApp.id },
+      current: pick(currentApp, [
+        'id',
+        'name',
+        'accountId',
+        'stackId',
+        'minIdle'
+      ]),
+      desired: {
+        name: desiredApp.name,
+        framework: desiredApp.framework,
+        accountId,
+        stackName: desiredStack.name
+      },
+      diff: []
+    });
+  }
+
+  if (Array.isArray(config.addons) && config.addons.length) {
+    let addOnReadable = true;
+    for (const addOn of config.addons) {
+      if (!addOn || typeof addOn !== 'object') continue;
+      const apiType = mapAddOnType(addOn.type);
+      if (!apiType) {
+        warnings.push(
+          `Unknown addon type '${addOn.type}' for '${addOn.name}'.`
+        );
+        continue;
+      }
+      if (!addOn.name) {
+        warnings.push('addons[] entry is missing name.');
+        continue;
+      }
+
+      let currentAddOn = null;
+      try {
+        const list = await api.findAddOnByName(addOn.name);
+        currentAddOn = list?.[0] || null;
+        if (list.length > 1) {
+          warnings.push(
+            `Multiple add-ons found named '${addOn.name}'. Using '${currentAddOn.id}'.`
+          );
+        }
+      } catch (err) {
+        addOnReadable = false;
+        warnings.push(
+          'Unable to read add-ons from the API (auth/permissions). Add-on planning is skipped for now.'
+        );
+        break;
+      }
+
+      if (!currentAddOn) {
+        const desired = { name: addOn.name, type: apiType, accountId };
+        if (apiType === 'DATABASE') {
+          const dbType = mapDbEngine(addOn.engine);
+          const dbSize = addOn.size ? String(addOn.size) : null;
+          if (!dbType || !dbSize) {
+            warnings.push(
+              `Database add-on '${addOn.name}' missing engine/size (engine like POSTGRES_16, size like Small).`
+            );
+          } else {
+            desired.database = { size: dbSize, type: dbType };
+          }
+        }
+
+        ops.push({
+          id: `op_addon_create_${addOn.name}`,
+          kind: 'addon',
+          action: 'create',
+          resource: { type: 'addon', name: addOn.name },
+          current: null,
+          desired,
+          diff: [{ field: 'exists', current: false, desired: true }]
+        });
+      } else if (currentAddOn.type !== apiType) {
+        warnings.push(
+          `Add-on '${addOn.name}' exists with type '${currentAddOn.type}', but config wants '${apiType}'. Type changes are not supported.`
+        );
+      } else {
+        ops.push({
+          id: `op_addon_noop_${addOn.name}`,
+          kind: 'addon',
+          action: 'noop',
+          resource: {
+            type: 'addon',
+            name: currentAddOn.name,
+            id: currentAddOn.id
+          },
+          current: pick(currentAddOn, ['id', 'name', 'type', 'accountId']),
+          desired: { name: addOn.name, type: apiType, accountId },
+          diff: []
+        });
+      }
+    }
+
+    if (addOnReadable) {
+      warnings.push(
+        'Add-on updates (e.g., DB resize, Cognito policy) are not yet planned; only create/noop is supported.'
+      );
+    }
+  }
+  if (Array.isArray(config.domains) && config.domains.length) {
+    warnings.push(
+      'domains are parsed but not yet included in plan/apply (Phase 4: custom domains).'
+    );
+  }
+  if (Array.isArray(config.jobs) && config.jobs.length) {
+    warnings.push(
+      'jobs are parsed but not yet included in plan/apply (Phase 4: scheduled jobs).'
+    );
+  }
+  if (config.git) {
+    warnings.push(
+      'git integration is parsed but not yet included in plan/apply (Phase 4: link repo + auto-deploy).'
+    );
+  }
+
+  const sortedOps = ops.slice().sort(stableOpSort);
+  const planForHash = {
+    version: 1,
+    env: normalizedEnv,
+    desired: {
+      account: pick(config.account, ['id', 'slug']),
+      stack: pick(desiredStack, ['name', 'size', 'minIdle']),
+      apps: (filteredApps || []).map((a) =>
+        pick(a, ['name', 'framework', 'path'])
+      )
+    },
+    operations: sortedOps.map((o) =>
+      pick(o, [
+        'id',
+        'kind',
+        'action',
+        'resource',
+        'desired',
+        'diff',
+        'depends_on'
+      ])
+    )
+  };
+
+  const plan_hash = sha256Prefixed(stableStringify(planForHash));
+
+  const summary = {
+    create: sortedOps.filter((o) => o.action === 'create').length,
+    update: sortedOps.filter((o) => o.action === 'update').length,
+    noop: sortedOps.filter((o) => o.action === 'noop').length
+  };
+
+  return {
+    env: normalizedEnv,
+    plan_hash,
+    operations: sortedOps,
+    summary,
+    warnings,
+    drift
+  };
+}
+
+module.exports = { buildPlan };

package/lib/scaly-project.js

@@ -0,0 +1,303 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { stableStringify, sha256Prefixed } = require('./stable-json');
+
+function fileExists(p) {
+  try {
+    fs.accessSync(p, fs.constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function findProjectRoot(startDir) {
+  let current = path.resolve(startDir || process.cwd());
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    const candidate = path.join(current, '.scaly', 'config.yaml');
+    if (fileExists(candidate)) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+function requireYaml() {
+  try {
+    // eslint-disable-next-line global-require
+    return require('yaml');
+  } catch (err) {
+    const e = new Error(
+      "Missing dependency: 'yaml'. Install it with `npm i yaml` (repo) or add it to the CLI package."
+    );
+    e.cause = err;
+    throw e;
+  }
+}
+
+function readYamlFile(filePath) {
+  const YAML = requireYaml();
+  const text = fs.readFileSync(filePath, 'utf8');
+  const parsed = YAML.parse(text);
+  return parsed ?? {};
+}
+
+function writeYamlFile(filePath, data) {
+  const YAML = requireYaml();
+  const dir = path.dirname(filePath);
+  fs.mkdirSync(dir, { recursive: true });
+  const text = YAML.stringify(data);
+  fs.writeFileSync(filePath, text, 'utf8');
+}
+
+function asPlainObject(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  return value;
+}
+
+function mergeObjects(base, overlay) {
+  const b = asPlainObject(base) || {};
+  const o = asPlainObject(overlay) || {};
+  const out = { ...b };
+  for (const [key, value] of Object.entries(o)) {
+    if (value === null) {
+      out[key] = null;
+      continue;
+    }
+    const baseValue = out[key];
+    if (Array.isArray(value)) {
+      out[key] = value.slice();
+      continue;
+    }
+    if (asPlainObject(value) && asPlainObject(baseValue)) {
+      out[key] = mergeObjects(baseValue, value);
+      continue;
+    }
+    out[key] = value;
+  }
+  return out;
+}
+
+function mergeArrayByKey(baseArr, overlayArr, key) {
+  const base = Array.isArray(baseArr) ? baseArr : [];
+  const overlay = Array.isArray(overlayArr) ? overlayArr : [];
+
+  const out = [];
+  const seen = new Set();
+
+  const byKey = (item) => {
+    if (!item || typeof item !== 'object') return null;
+    const v = item[key];
+    return typeof v === 'string' && v.trim() ? v : null;
+  };
+
+  const overlayMap = new Map();
+  for (const item of overlay) {
+    const k = byKey(item);
+    if (!k) continue;
+    overlayMap.set(k, item);
+  }
+
+  for (const item of base) {
+    const k = byKey(item);
+    if (!k) continue;
+    const next = overlayMap.has(k)
+      ? mergeObjects(item, overlayMap.get(k))
+      : item;
+    out.push(next);
+    seen.add(k);
+  }
+
+  for (const item of overlay) {
+    const k = byKey(item);
+    if (!k) continue;
+    if (seen.has(k)) continue;
+    out.push(item);
+    seen.add(k);
+  }
+
+  return out;
+}
+
+function normalizeConfig(config) {
+  const c = asPlainObject(config) || {};
+
+  // Support app: sugar for apps: [app]
+  if (!c.apps && c.app) {
+    return { ...c, apps: [c.app], app: undefined };
+  }
+  return c;
+}
+
+function mergeScalyConfig(baseConfig, overlayConfig) {
+  const base = normalizeConfig(baseConfig);
+  const overlay = normalizeConfig(overlayConfig);
+
+  const merged = mergeObjects(base, overlay);
+
+  merged.addons = mergeArrayByKey(base.addons, overlay.addons, 'name');
+  merged.domains = mergeArrayByKey(base.domains, overlay.domains, 'hostname');
+  merged.jobs = mergeArrayByKey(base.jobs, overlay.jobs, 'name');
+  merged.apps = mergeArrayByKey(base.apps, overlay.apps, 'name');
+
+  // Secrets are names-only and frequently sourced from CI; treat overrides as replace.
+  if (overlay.app && overlay.app.secrets) merged.app = merged.app || {};
+  if (overlay.app && overlay.app.secrets)
+    merged.app.secrets = overlay.app.secrets;
+
+  if (Array.isArray(overlay.apps)) {
+    const overlayByName = new Map(
+      overlay.apps
+        .filter((a) => a && typeof a === 'object' && a.name)
+        .map((a) => [a.name, a])
+    );
+    merged.apps = (merged.apps || []).map((app) => {
+      if (!app || typeof app !== 'object' || !app.name) return app;
+      const o = overlayByName.get(app.name);
+      if (o && o.secrets) return { ...app, secrets: o.secrets };
+      return app;
+    });
+  }
+
+  return merged;
+}
+
+function validateConfig(config) {
+  const errors = [];
+  if (!config || typeof config !== 'object') {
+    return { ok: false, errors: ['Config must be a YAML object'] };
+  }
+
+  if (String(config.version || '') !== '1') {
+    errors.push("Missing/invalid 'version' (expected '1').");
+  }
+
+  if (!config.stack || typeof config.stack !== 'object') {
+    errors.push("Missing required 'stack' block.");
+  } else {
+    if (!config.stack.name) errors.push("Missing 'stack.name'.");
+    if (!config.stack.size) errors.push("Missing 'stack.size'.");
+  }
+
+  if (!Array.isArray(config.apps) || config.apps.length === 0) {
+    errors.push("Missing application definition: provide 'app:' or 'apps:'.");
+  } else {
+    for (const [idx, app] of config.apps.entries()) {
+      if (!app || typeof app !== 'object') {
+        errors.push(`apps[${idx}] must be an object.`);
+        continue;
+      }
+      if (!app.name) errors.push(`apps[${idx}].name is required.`);
+      if (!app.framework) errors.push(`apps[${idx}].framework is required.`);
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+function loadScalyConfig({ cwd = process.cwd(), env } = {}) {
+  const root = findProjectRoot(cwd);
+  if (!root) {
+    const e = new Error(
+      "No Scaly project found (missing '.scaly/config.yaml' in this or any parent directory). Run `scaly init`."
+    );
+    e.code = 'SCALY_NO_PROJECT';
+    throw e;
+  }
+
+  const basePath = path.join(root, '.scaly', 'config.yaml');
+  const overlayPath = env
+    ? path.join(root, '.scaly', `config.${env}.yaml`)
+    : null;
+
+  const base = readYamlFile(basePath);
+  const overlay =
+    overlayPath && fileExists(overlayPath) ? readYamlFile(overlayPath) : {};
+
+  const merged = mergeScalyConfig(base, overlay);
+  const normalized = normalizeConfig(merged);
+  const validation = validateConfig(normalized);
+
+  return {
+    root,
+    basePath,
+    overlayPath: overlayPath && fileExists(overlayPath) ? overlayPath : null,
+    config: normalized,
+    validation
+  };
+}
+
+function normalizeEnv(value) {
+  if (!value) return null;
+  const s = String(value).trim().toLowerCase();
+  return s || null;
+}
+
+function pick(obj, keys) {
+  const out = {};
+  for (const k of keys) {
+    if (obj && typeof obj === 'object' && k in obj) out[k] = obj[k];
+  }
+  return out;
+}
+
+function computeConfigHash({ config, env, appName }) {
+  const apps = Array.isArray(config?.apps) ? config.apps : [];
+  const filteredApps = appName
+    ? apps.filter((a) => a && a.name === appName)
+    : apps;
+  const addons = Array.isArray(config?.addons) ? config.addons : [];
+
+  const input = {
+    version: 1,
+    env: normalizeEnv(env),
+    desired: {
+      account: pick(config?.account, ['id', 'slug']),
+      stack: pick(config?.stack, ['name', 'size', 'minIdle']),
+      apps: (filteredApps || [])
+        .filter(Boolean)
+        .map((a) => pick(a, ['name', 'framework', 'path'])),
+      addons: (addons || [])
+        .filter(Boolean)
+        .map((a) => pick(a, ['name', 'type', 'engine', 'size']))
+    }
+  };
+
+  return sha256Prefixed(stableStringify(input));
+}
+
+function getLastApplyPath(root) {
+  return path.join(root, '.scaly', 'last_apply.json');
+}
+
+function readLastApply(root) {
+  const p = getLastApplyPath(root);
+  try {
+    const text = fs.readFileSync(p, 'utf8');
+    const obj = JSON.parse(text);
+    return obj && typeof obj === 'object' ? obj : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeLastApply(root, payload) {
+  const p = getLastApplyPath(root);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(payload, null, 2) + '\n', 'utf8');
+}
+
+module.exports = {
+  findProjectRoot,
+  readYamlFile,
+  writeYamlFile,
+  mergeScalyConfig,
+  loadScalyConfig,
+  normalizeEnv,
+  computeConfigHash,
+  readLastApply,
+  writeLastApply
+};