@gotillit/tllt 0.3.0

package/lib/auth.js

@@ -0,0 +1,123 @@
+import fs from 'fs';
+import path from 'path';
+import got from 'got';
+
+import {TILLIT_DIR} from './config.js';
+import {getApi} from './apis.js';
+
+const TOKEN_CACHE_PATH = path.join(TILLIT_DIR, 'tokens.json');
+// Refresh a little before the real expiry to avoid edge-of-validity failures.
+const EXPIRY_SKEW_MS = 60 * 1000;
+
+/**
+ * Resolve the auth + tenant headers for a profile against a given API.
+ *
+ * @param {object} profile  resolved profile (see lib/config.js)
+ * @param {string} apiId    'do' | 'scheduler'
+ * @returns {Promise<Record<string,string>>} headers to attach to every request
+ */
+export async function authHeaders(profile, apiId) {
+  getApi(apiId); // validate the API id
+  const method = profile.auth?.method;
+  const headers = {};
+
+  switch (method) {
+    case 'basic': {
+      const {username, password} = profile.auth;
+      const creds = `${username}@${profile.tenant}.tillit.cloud:${password}`;
+      headers.Authorization = 'Basic ' + Buffer.from(creds).toString('base64');
+      headers['tillit-tenant'] = profile.tenant;
+      break;
+    }
+    case 'basic-token': {
+      // Legacy .env profiles already store the base64 basic blob.
+      headers.Authorization = 'Basic ' + profile.auth.basicToken;
+      headers['tillit-tenant'] = profile.tenant;
+      break;
+    }
+    case 'apikey': {
+      const token = await getBearerToken(profile);
+      headers.Authorization = 'Bearer ' + token;
+      headers['tillit-tenant'] = profile.tenant;
+      break;
+    }
+    default:
+      throw new Error(`Profile "${profile.name}" has no usable auth method (got "${method}").`);
+  }
+
+  return headers;
+}
+
+/**
+ * Obtain a Cognito access token via the OAuth2 client_credentials flow,
+ * caching it on disk (keyed by profile + token URL) until shortly before it
+ * expires. The api key is the Cognito app-client id; the secret is its secret.
+ */
+export async function getBearerToken(profile) {
+  const {apiKey, apiSecret, tokenUrl, scopes} = profile.auth;
+  if (!tokenUrl) {
+    throw new Error(
+      `Profile "${profile.name}" is missing auth.tokenUrl (the Cognito OAuth2 token endpoint).`
+    );
+  }
+
+  const cacheKey = `${profile.name}|${tokenUrl}`;
+  const cached = readTokenCache()[cacheKey];
+  if (cached && cached.expiresAt - EXPIRY_SKEW_MS > absoluteNow()) {
+    return cached.accessToken;
+  }
+
+  const body = new URLSearchParams({grant_type: 'client_credentials'});
+  if (scopes && scopes.length) {
+    body.set('scope', scopes.join(' '));
+  }
+
+  let response;
+  try {
+    response = await got
+      .post(tokenUrl, {
+        headers: {
+          Authorization: 'Basic ' + Buffer.from(`${apiKey}:${apiSecret}`).toString('base64'),
+          'Content-Type': 'application/x-www-form-urlencoded',
+        },
+        body: body.toString(),
+      })
+      .json();
+  } catch (err) {
+    const detail = err.response?.body ? ` — ${err.response.body}` : '';
+    throw new Error(`Cognito token request failed (${err.message})${detail}`);
+  }
+
+  if (!response.access_token) {
+    throw new Error('Cognito token response did not contain an access_token.');
+  }
+
+  const expiresInMs = (response.expires_in ?? 3600) * 1000;
+  writeTokenCacheEntry(cacheKey, {
+    accessToken: response.access_token,
+    expiresAt: absoluteNow() + expiresInMs,
+  });
+
+  return response.access_token;
+}
+
+function absoluteNow() {
+  // new Date() is intentionally avoided in workflow scripts but is fine here in
+  // a normal CLI process. Kept in one place so caching logic is easy to follow.
+  return new Date().getTime();
+}
+
+function readTokenCache() {
+  if (!fs.existsSync(TOKEN_CACHE_PATH)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(TOKEN_CACHE_PATH, 'utf8') || '{}');
+  } catch {
+    return {};
+  }
+}
+
+function writeTokenCacheEntry(key, value) {
+  const cache = readTokenCache();
+  cache[key] = value;
+  fs.writeFileSync(TOKEN_CACHE_PATH, JSON.stringify(cache, null, 2) + '\n', {mode: 0o600});
+}

package/lib/client.js

@@ -0,0 +1,52 @@
+import got from 'got';
+
+import {authHeaders} from './auth.js';
+import {getApi} from './apis.js';
+
+/**
+ * Build a `got` instance bound to a profile + API surface. The returned client
+ * has `prefixUrl` set to https://{tenant}.tillit.cloud{prefix} and the resolved
+ * auth + tenant headers attached, so callers issue relative paths:
+ *
+ *   const api = await apiClient(profile, 'do');
+ *   await api.get('core/assets').json();
+ *
+ *   const sched = await apiClient(profile, 'scheduler');
+ *   await sched.get('equipment').json();
+ */
+export async function apiClient(profile, apiId) {
+  const api = getApi(apiId);
+  const headers = await authHeaders(profile, apiId);
+  const baseUrl = (profile.baseUrl || `https://${profile.tenant}.tillit.cloud`).replace(/\/+$/, '');
+
+  return got.extend({
+    prefixUrl: `${baseUrl}${api.prefix}`,
+    headers,
+    responseType: 'json',
+    retry: {limit: 1},
+    hooks: {
+      beforeError: [
+        (error) => {
+          const {response} = error;
+          if (response && response.body) {
+            const body =
+              typeof response.body === 'string' ? response.body : JSON.stringify(response.body);
+            error.message = `${error.message}: ${body}`;
+          }
+          return error;
+        },
+      ],
+    },
+  });
+}
+
+/**
+ * Raw GET against the tenant base URL (no API prefix) using the profile's auth.
+ * Used to fetch published asset files such as entity schemas.
+ */
+export async function fetchAsset(profile, apiId, assetPath) {
+  const headers = await authHeaders(profile, apiId);
+  const baseUrl = (profile.baseUrl || `https://${profile.tenant}.tillit.cloud`).replace(/\/+$/, '');
+  const url = `${baseUrl}${assetPath.startsWith('/') ? '' : '/'}${assetPath}`;
+  return got.get(url, {headers, responseType: 'json'}).json();
+}

package/lib/config.js

@@ -0,0 +1,209 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+/**
+ * Configuration store for the TilliT CLI.
+ *
+ * Profiles live in ~/.tillit/config.json and look like:
+ *
+ *   {
+ *     "defaultProfile": "client1-prod",
+ *     "profiles": {
+ *       "client1-prod": {
+ *         "tenant": "client1",
+ *         "environment": "prod",
+ *         "baseUrl": "https://client1.tillit.cloud",
+ *         "auth": {
+ *           "method": "basic",
+ *           "username": "alice",
+ *           "password": "..."
+ *         }
+ *       },
+ *       "acme-stage": {
+ *         "tenant": "acme",
+ *         "environment": "stage",
+ *         "baseUrl": "https://acme.tillit-stage.cloud",
+ *         "auth": {
+ *           "method": "apikey",
+ *           "apiKey": "<cognito client id>",
+ *           "apiSecret": "<cognito client secret>",
+ *           "tokenUrl": "https://....amazoncognito.com/oauth2/token",
+ *           "scopes": ["api/*.read", "api/*.write"]
+ *         }
+ *       }
+ *     }
+ *   }
+ *
+ * Legacy ~/.tillit/.env files written by older CLI versions are still read so
+ * existing setups keep working.
+ */
+
+export const TILLIT_DIR = path.join(os.homedir(), '.tillit');
+export const CONFIG_PATH = path.join(TILLIT_DIR, 'config.json');
+export const LEGACY_ENV_PATH = path.join(TILLIT_DIR, '.env');
+
+function ensureDir() {
+  if (!fs.existsSync(TILLIT_DIR)) {
+    fs.mkdirSync(TILLIT_DIR, {recursive: true});
+  }
+}
+
+export const ENVIRONMENTS = ['prod', 'stage', 'sandbox', 'dev', 'enterprise'];
+
+// Tiers an enterprise (dedicated) environment can sit on.
+export const ENTERPRISE_TIERS = ['prod', 'stage', 'dev'];
+const DEFAULT_TIER = 'stage';
+
+/**
+ * Per-environment domain templates. A connection lives on a per-tenant
+ * subdomain whose root domain depends on the environment, e.g.
+ *   prod  -> https://{tenant}.tillit.cloud
+ *   stage -> https://{tenant}.tillit-stage.cloud
+ *   dev   -> https://{tenant}.tillit-dev.cloud
+ *
+ * `enterprise` environments are dedicated deployments outside the shared
+ * cluster: the enterprise name becomes an extra subdomain segment on the chosen
+ * tier, e.g. tenant `client1` on the `acme` enterprise (stage tier) ->
+ * https://client1.acme.tillit-stage.cloud
+ *
+ * Override per profile with an explicit `baseUrl` if a tenant differs.
+ */
+const ENV_DOMAINS = {
+  prod: 'tillit.cloud',
+  stage: 'tillit-stage.cloud',
+  sandbox: 'tillit-sandbox.cloud',
+  dev: 'tillit-dev.cloud',
+};
+
+/**
+ * Default base URL for a tenant in a given environment. For `enterprise`
+ * environments pass `{enterprise, tier}` (tier defaults to stage).
+ */
+export function defaultBaseUrl(tenant, environment = 'prod', {enterprise, tier} = {}) {
+  if (environment === 'enterprise') {
+    if (!enterprise) throw new Error('An enterprise environment requires an enterprise name.');
+    const domain = ENV_DOMAINS[tier ?? DEFAULT_TIER] ?? ENV_DOMAINS[DEFAULT_TIER];
+    return `https://${tenant}.${enterprise}.${domain}`;
+  }
+  const domain = ENV_DOMAINS[environment] ?? ENV_DOMAINS.prod;
+  return `https://${tenant}.${domain}`;
+}
+
+/**
+ * Canonical profile name for a connection. A connection is uniquely identified
+ * by environment + tenant, so the profile name is `{tenant}-{environment}`
+ * (e.g. client1 on prod -> "client1-prod"). Enterprise environments include the
+ * enterprise + tier, e.g. client1 on acme/stage -> "client1-acme-stage".
+ */
+export function profileName(tenant, environment, {enterprise, tier} = {}) {
+  if (environment === 'enterprise') {
+    return `${tenant}-${enterprise}-${tier ?? DEFAULT_TIER}`;
+  }
+  return `${tenant}-${environment}`;
+}
+
+export function loadConfig() {
+  if (!fs.existsSync(CONFIG_PATH)) {
+    return {defaultProfile: null, profiles: {}};
+  }
+  try {
+    const raw = fs.readFileSync(CONFIG_PATH, 'utf8');
+    const parsed = JSON.parse(raw || '{}');
+    return {
+      defaultProfile: parsed.defaultProfile ?? null,
+      profiles: parsed.profiles ?? {},
+    };
+  } catch (err) {
+    throw new Error(`Could not parse ${CONFIG_PATH}: ${err.message}`);
+  }
+}
+
+export function saveConfig(config) {
+  ensureDir();
+  fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + '\n', {mode: 0o600});
+}
+
+/** Create or overwrite a named profile and persist it. */
+export function saveProfile(name, profile, {makeDefault = false} = {}) {
+  const config = loadConfig();
+  config.profiles[name] = profile;
+  if (makeDefault || !config.defaultProfile) {
+    config.defaultProfile = name;
+  }
+  saveConfig(config);
+  return config;
+}
+
+export function listProfiles() {
+  const config = loadConfig();
+  return Object.entries(config.profiles).map(([name, profile]) => ({
+    name,
+    tenant: profile.tenant,
+    baseUrl: profile.baseUrl,
+    method: profile.auth?.method,
+    isDefault: name === config.defaultProfile,
+  }));
+}
+
+/**
+ * Resolve a profile by name, falling back to the default profile, and finally
+ * to a legacy .env entry (keyed ENV_TENANT, e.g. PROD_BOTTLING). Returns the
+ * profile object augmented with its resolved `name`.
+ */
+export function resolveProfile(name) {
+  const config = loadConfig();
+  const profileName = name || config.defaultProfile;
+
+  if (profileName && config.profiles[profileName]) {
+    return {name: profileName, ...config.profiles[profileName]};
+  }
+
+  // Back-compat: allow "<env> <tenant>" or "<env>_<tenant>" against legacy .env.
+  const legacy = loadLegacyProfile(profileName);
+  if (legacy) return legacy;
+
+  if (!profileName) {
+    throw new Error('No profile specified and no default profile configured. Run `tllt configure`.');
+  }
+  throw new Error(`Profile "${profileName}" not found. Run \`tllt configure\` or \`tllt profiles\`.`);
+}
+
+/**
+ * Read a legacy ~/.tillit/.env profile of the shape
+ *   {ENV}_{TENANT}_AUTH=<base64 basic creds>
+ *   {ENV}_{TENANT}_REGION=<region>
+ * Accepts a key like "prod_bottling" / "PROD_BOTTLING".
+ */
+function loadLegacyProfile(key) {
+  if (!key || !fs.existsSync(LEGACY_ENV_PATH)) return null;
+  const env = parseEnvFile(LEGACY_ENV_PATH);
+  const prefix = key.toUpperCase().replace(/[\s/]+/g, '_');
+  const auth = env[`${prefix}_AUTH`];
+  if (!auth) return null;
+  // The legacy AUTH value is base64(username@tenant.tillit.cloud:password).
+  // Legacy keys are {ENV}_{TENANT}_AUTH, so the first segment is the environment.
+  const parts = prefix.split('_');
+  const environment = parts[0].toLowerCase();
+  const tenant = parts.slice(1).join('-').toLowerCase() || key;
+  return {
+    name: key,
+    tenant,
+    environment,
+    baseUrl: defaultBaseUrl(tenant, environment),
+    legacy: true,
+    auth: {method: 'basic-token', basicToken: auth},
+  };
+}
+
+function parseEnvFile(file) {
+  const out = {};
+  for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const idx = trimmed.indexOf('=');
+    if (idx === -1) continue;
+    out[trimmed.slice(0, idx).trim()] = trimmed.slice(idx + 1).trim();
+  }
+  return out;
+}

package/lib/output.js

@@ -0,0 +1,51 @@
+/**
+ * Output helpers that keep the CLI friendly for both humans and AI agents.
+ *
+ * When `--json` is set (or TILLIT_JSON=1), structured results go to stdout as
+ * JSON and nothing else is printed there, so an agent can parse stdout cleanly.
+ * Human-readable progress always goes to stderr. Errors are emitted as
+ * structured JSON on stderr in JSON mode.
+ */
+let jsonMode = false;
+
+export function setJsonMode(value) {
+  jsonMode = Boolean(value) || process.env.TILLIT_JSON === '1';
+}
+
+export function isJsonMode() {
+  return jsonMode;
+}
+
+/** Progress / status lines for humans — never pollute stdout in JSON mode. */
+export function info(message) {
+  if (!jsonMode) process.stderr.write(message + '\n');
+}
+
+/** The command's primary result. In JSON mode this is the only stdout output. */
+export function result(humanMessage, data) {
+  if (jsonMode) {
+    process.stdout.write(JSON.stringify(data ?? {}, null, 2) + '\n');
+  } else if (humanMessage) {
+    process.stdout.write(humanMessage + '\n');
+  }
+}
+
+/** Report a failure and exit non-zero. */
+export function fail(error, code = 1) {
+  const message = error instanceof Error ? error.message : String(error);
+  if (jsonMode) {
+    process.stderr.write(JSON.stringify({ok: false, error: message}, null, 2) + '\n');
+  } else {
+    process.stderr.write(`Error: ${message}\n`);
+  }
+  process.exitCode = code;
+}
+
+/** Wrap an async command action with uniform error handling + exit codes. */
+export function run(action) {
+  return (...args) => {
+    Promise.resolve()
+      .then(() => action(...args))
+      .catch((err) => fail(err));
+  };
+}