@lemonadecms/client 0.0.0-stage → 0.1.1

package/bin/cli/network.mjs

@@ -0,0 +1,134 @@
+import { MAX_SCHEMA_BYTES, parseJSON } from './io.mjs';
+import { fail, CLIError } from './errors.mjs';
+import { validateSchema, schemaIdentity } from './schema.mjs';
+
+// Bound caller completion even when a transport/body ignores native abort.
+export function withinSignal(signal, operation) {
+  if (signal.aborted) return Promise.reject(signal.reason);
+  return new Promise((resolve, reject) => {
+    const abort = () => {
+      signal.removeEventListener('abort', abort);
+      reject(signal.reason);
+    };
+    signal.addEventListener('abort', abort, { once: true });
+    Promise.resolve()
+      .then(() => {
+        if (signal.aborted) throw signal.reason;
+        return operation();
+      })
+      .then(
+        (value) => {
+          signal.removeEventListener('abort', abort);
+          if (signal.aborted) reject(signal.reason);
+          else resolve(value);
+        },
+        (error) => {
+          signal.removeEventListener('abort', abort);
+          reject(error);
+        },
+      );
+  });
+}
+export async function fetchSchema(target, fetcher = fetch) {
+  const schema = validateSchema(
+    await requestJSON(
+      target,
+      `/api/v1/projects/${target.workspace}/schema`,
+      {},
+      fetcher,
+    ),
+  );
+  const identity = schemaIdentity(schema);
+  if (
+    identity.workspace.toLowerCase() !== target.workspace.toLowerCase() ||
+    !(
+      identity.environment === target.environment ||
+      identity.environmentId.toLowerCase() === target.environment.toLowerCase()
+    )
+  )
+    fail(
+      4,
+      'Schema does not match the explicitly selected workspace/environment. No output was written.',
+    );
+  return schema;
+}
+
+export async function requestJSON(
+  target,
+  path,
+  { method = 'GET', body: requestBody } = {},
+  fetcher = fetch,
+) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 15000);
+  let reader;
+  try {
+    const response = await withinSignal(controller.signal, () =>
+      fetcher(`${target.url}${path}`, {
+        method,
+        headers: {
+          Accept: 'application/json',
+          Authorization: `Bearer ${target.key}`,
+          ...(requestBody ? { 'Content-Type': 'application/json' } : {}),
+        },
+        ...(requestBody ? { body: JSON.stringify(requestBody) } : {}),
+        redirect: 'error',
+        credentials: 'omit',
+        cache: 'no-store',
+        signal: controller.signal,
+      }),
+    );
+    if ([401, 403].includes(response.status))
+      fail(
+        4,
+        'Credential rejected, expired or revoked; check its workspace and scope.',
+      );
+    if (path.startsWith('/api/v1/management/') && [409, 422].includes(response.status))
+      fail(
+        3,
+        'Migration rejected: drift, stale plan, order, checksum, validation or capacity. Inspect status and create a fresh reviewed plan.',
+      );
+    if (!response.ok)
+      fail(4, 'CMS request failed. Check connection, server status and read access.');
+    if (
+      !/^application\/json(?:\s*;|$)/i.test(response.headers.get('content-type') || '')
+    )
+      fail(5, 'CMS did not return a JSON schema.');
+    const size = response.headers.get('content-length');
+    if (size !== null && (!/^\d+$/.test(size) || Number(size) > MAX_SCHEMA_BYTES))
+      fail(5, 'Schema response exceeds the supported size.');
+    reader = response.body?.getReader();
+    if (!reader) fail(5, 'CMS returned an empty response.');
+    const chunks = [];
+    let bytes = 0;
+    while (true) {
+      const { done, value } = await withinSignal(controller.signal, () =>
+        reader.read(),
+      );
+      if (done) break;
+      bytes += value.byteLength;
+      if (bytes > MAX_SCHEMA_BYTES)
+        fail(5, 'Schema response exceeds the supported size.');
+      chunks.push(value);
+    }
+    let body;
+    try {
+      body = new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks));
+    } catch {
+      fail(5, 'CMS returned invalid UTF-8 schema data.');
+    }
+    // Never persist or print a reflected credential, even on an otherwise valid server response.
+    if (body.includes(target.key)) fail(5, 'CMS returned unsafe schema metadata.');
+    return parseJSON(body);
+  } catch (error) {
+    if (error instanceof CLIError) throw error;
+    fail(4, 'Could not read CMS schema. Check network, TLS and server availability.');
+  } finally {
+    clearTimeout(timer);
+    controller.abort();
+    // Cancellation is best effort: a stalled cleanup must not extend the deadline.
+    try {
+      reader?.cancel().catch(() => {});
+    } catch {}
+  }
+}

package/bin/cli/picker.mjs

@@ -0,0 +1,118 @@
+import { emitKeypressEvents } from 'node:readline';
+import { CLIError } from './errors.mjs';
+
+export function canPickTarget(opts, env, { input, output, stdoutIsTTY }) {
+  return Boolean(
+    input.isTTY &&
+    output.isTTY &&
+    stdoutIsTTY &&
+    typeof input.setRawMode === 'function' &&
+    !env.CI &&
+    !opts.json &&
+    !opts.check &&
+    !['target', 'environment', 'url', 'workspace', 'credential-env'].some(
+      (key) => opts[key],
+    ) &&
+    !['LEMONADE_TARGET', 'LEMONADE_ENVIRONMENT', 'CMS_ENVIRONMENT'].some(
+      (key) => env[key],
+    ),
+  );
+}
+
+// Targets have already passed bounded configuration validation. Only safe target
+// names/environment identities reach the terminal, never URLs or credential data.
+export function pickTarget(targets, { input, output }) {
+  const production = (target) =>
+    target.environment === 'production' ||
+    target.environment.toLowerCase() === target.workspace.toLowerCase();
+  const choices = Object.entries(targets).sort(
+    ([a, left], [b, right]) =>
+      Number(production(right)) - Number(production(left)) ||
+      (a < b ? -1 : a > b ? 1 : 0),
+  );
+  return new Promise((resolve, reject) => {
+    let selected = 0,
+      settled = false,
+      renderedLines = 0;
+    const wasRaw = input.isRaw === true;
+    const wasFlowing = input.readableFlowing === true;
+    const cancelled = () =>
+      finish(
+        new CLIError(130, 'Environment selection cancelled. No output was written.'),
+      );
+    const failed = () =>
+      finish(
+        new CLIError(
+          2,
+          'Could not read the environment selection. No output was written.',
+        ),
+      );
+    const render = () => {
+      const width = Math.max(10, (output.columns || 80) - 1);
+      const visible = Math.min(choices.length, Math.max(1, (output.rows || 24) - 4));
+      const start = Math.min(
+        Math.max(0, selected - visible + 1),
+        choices.length - visible,
+      );
+      const lines = choices
+        .slice(start, start + visible)
+        .map(([name, target], index) => {
+          const label = `${index + start === selected ? '>' : ' '} ${name} (${target.environment})`;
+          return label.length > width ? label.slice(0, width - 3) + '...' : label;
+        });
+      if (renderedLines) output.write(`\x1b[${renderedLines}A\r`);
+      output.write(lines.map((line) => `\x1b[2K${line}\n`).join(''));
+      renderedLines = lines.length;
+    };
+    function finish(error) {
+      if (settled) return;
+      settled = true;
+      input.removeListener('keypress', onKey);
+      input.removeListener('end', cancelled);
+      input.removeListener('close', cancelled);
+      input.removeListener('error', failed);
+      output.removeListener('error', failed);
+      process.removeListener('SIGINT', cancelled);
+      try {
+        input.setRawMode(wasRaw);
+        if (!wasFlowing) input.pause();
+      } catch {
+        error ||= new CLIError(2, 'Could not restore terminal input.');
+      }
+      if (error) reject(error);
+      else resolve(choices[selected][0]);
+    }
+    function onKey(_, key = {}) {
+      if (settled) return;
+      if (key.name === 'escape' || (key.ctrl && ['c', 'd'].includes(key.name)))
+        return cancelled();
+      if (['return', 'enter'].includes(key.name)) return finish();
+      if (['up', 'down'].includes(key.name)) {
+        selected =
+          (selected + (key.name === 'up' ? -1 : 1) + choices.length) % choices.length;
+        try {
+          render();
+        } catch {
+          failed();
+        }
+      }
+    }
+    try {
+      if (input.destroyed || input.readableEnded) return cancelled();
+      if (output.destroyed || output.writableEnded) return failed();
+      emitKeypressEvents(input);
+      input.on('keypress', onKey);
+      input.once('end', cancelled);
+      input.once('close', cancelled);
+      input.once('error', failed);
+      output.once('error', failed);
+      process.once('SIGINT', cancelled);
+      input.setRawMode(true);
+      input.resume();
+      output.write('Select an environment (arrows, Enter; Esc/Ctrl+C to cancel):\n');
+      render();
+    } catch {
+      failed();
+    }
+  });
+}

package/bin/cli/run.mjs

@@ -0,0 +1,240 @@
+import { resolve } from 'node:path';
+import { createRequire } from 'node:module';
+const { version } = createRequire(import.meta.url)('../../package.json');
+import { access } from 'node:fs/promises';
+import {
+  parseArgs,
+  connection,
+  typeGenerationEnv,
+  readConfiguration,
+} from './config.mjs';
+import { canPickTarget, pickTarget } from './picker.mjs';
+import { CLIError, fail } from './errors.mjs';
+import { parseJSON, readText, writeOutput, MAX_SCHEMA_BYTES } from './io.mjs';
+import {
+  validateSchema,
+  schemaIdentity,
+  compareSchemas,
+  serialize,
+} from './schema.mjs';
+import { migrate } from './migrate.mjs';
+import { fetchSchema } from './network.mjs';
+import { generateLanguage } from '../codegen/languages.mjs';
+import { createMigration } from './create-migration.mjs';
+export const HELP = `Lemonade CMS — delivery CLI and explicit schema migrations
+
+lemonade check [connection options]
+lemonade schema inspect [connection options]
+lemonade schema pull --out schema.json [connection options]
+lemonade schema export --out schema.json [connection options]
+lemonade schema validate --file schema.json
+lemonade schema diff --file schema.json [connection options]
+lemonade types generate [--file schema.json | connection options] [--out FILE] [--language typescript|csharp|python] [--check]
+
+lemonade schema migrate status [--before MIGRATION_ID] [connection options]
+lemonade schema migrate create --baseline current.json --file desired.json --status status.json --id YYYYMMDDHHMMSS_description --out migration.json
+lemonade schema migrate plan --file migration.json --out review.json [connection options]
+lemonade schema migrate apply --file migration.json --plan review.json --confirm CHECKSUM [connection options]
+
+Migration commands require an environment UUID and a separate management credential
+(default LEMONADE_MANAGEMENT_TOKEN); delivery commands remain read-only.
+
+Connection: --config FILE --target NAME, or --url URL --workspace UUID --environment KEY_OR_UUID
+Credential: --credential-env ENV_NAME (default LEMONADE_TOKEN). Never pass a token value.
+Targets live in lemonade.config.json. URL/workspace/environment also accept LEMONADE_* environment variables.
+Types generate: loads cwd/.env (process values win); workspace falls back to CMS_PROJECT_ID,
+environment to CMS_ENVIRONMENT or production, credential to CMS_PUBLIC_KEY when LEMONADE_TOKEN is unset.
+Default output: src/types/cms-models.ts (csharp: cms-models.cs; python: cms_models.py).
+Explicit options, named targets and existing LEMONADE_* settings take precedence. --out is a file path.
+Offline generation and other commands do not load .env. Use the selected environment's credential.
+Interactive types generate offers configured targets (production first) when no connection selection is explicit.
+Use arrows/Enter to choose; Escape/Ctrl+C/EOF cancels without network or output-file writes.
+CI, --json, --check, piped input/output, --file and explicit connection/environment settings never prompt.
+All commands: --json. Informational: --help, --version.
+Exit codes: 0 success, 2 usage/config, 3 drift, 4 connection/auth/context, 5 invalid schema/input, 6 output failure, 130 selection cancelled.
+Only schema migrate apply writes compatible schema additions or reviewed missing-draft backfills. No content publication, automatic retries or credential persistence. Node.js 22+ required.
+`;
+export async function run(
+  args,
+  {
+    env = process.env,
+    cwd = process.cwd(),
+    fetcher = fetch,
+    stdout = (text) => process.stdout.write(text),
+    stderr = (text) => process.stderr.write(text),
+    terminal = {
+      input: process.stdin,
+      output: process.stderr,
+      stdoutIsTTY: process.stdout.isTTY,
+    },
+  } = {},
+) {
+  let opts = {},
+    key;
+  function emit(value, human, error = false) {
+    const text = opts.json ? JSON.stringify(value) + '\n' : human + '\n';
+    if (key && text.includes(key)) fail(5, 'Unsafe reflected credential was blocked.');
+    (opts.json || !error ? stdout : stderr)(text);
+  }
+  try {
+    // Preserve structured errors even when another option is invalid.
+    opts.json = args.includes('--json');
+    const parsed = parseArgs(args);
+    opts = parsed.opts;
+    if (opts.help) {
+      emit({ ok: true, help: HELP }, HELP.trimEnd());
+      return 0;
+    }
+    if (opts.version) {
+      emit({ ok: true, version }, version);
+      return 0;
+    }
+    const command = parsed.command;
+    if (command === 'schema migrate create') {
+      const result = await createMigration(opts, cwd);
+      emit(
+        result,
+        'Migration created locally. Review the file, then plan and explicitly apply it.',
+      );
+      return 0;
+    }
+    if (command.startsWith('schema migrate ')) {
+      const { result, human } = await migrate(command, opts, {
+        cwd,
+        env,
+        fetcher,
+        setKey: (value) => {
+          key = value;
+        },
+      });
+      emit(result, human);
+      return 0;
+    }
+    const inputPath = opts.file && resolve(cwd, opts.file);
+    const readSchema = async () => validateSchema(parseJSON(await readText(inputPath)));
+    const remote = async () => {
+      const generation = command === 'types generate';
+      const selectedEnv = generation ? await typeGenerationEnv(env, cwd) : env;
+      const defaults = generation
+        ? {
+            workspace: selectedEnv.CMS_PROJECT_ID,
+            environment: selectedEnv.CMS_ENVIRONMENT || 'production',
+            credentialEnv: Object.hasOwn(selectedEnv, 'LEMONADE_TOKEN')
+              ? 'LEMONADE_TOKEN'
+              : 'CMS_PUBLIC_KEY',
+          }
+        : {};
+      const configuration = await readConfiguration(opts, cwd);
+      let selected = opts;
+      if (
+        generation &&
+        canPickTarget(opts, selectedEnv, terminal) &&
+        Object.keys(configuration.targets).length
+      ) {
+        selected = {
+          ...opts,
+          target: await pickTarget(configuration.targets, terminal),
+        };
+      }
+      const target = await connection(
+        selected,
+        selectedEnv,
+        cwd,
+        false,
+        defaults,
+        configuration,
+      );
+      key = target.key;
+      return fetchSchema(target, fetcher);
+    };
+    const schema =
+      inputPath && ['schema validate', 'types generate'].includes(command)
+        ? await readSchema()
+        : await remote();
+    const identity = schemaIdentity(schema);
+    let result = { ok: true, command, ...identity };
+    let human = `Connected: ${identity.workspace} / ${identity.environment} — ${identity.models} models, ${identity.fields} fields, revision ${identity.revision}.`;
+    let code = 0;
+    if (command === 'schema inspect') {
+      result.models = schema.models.map((model) => ({
+        key: model.key,
+        fields: model.fields.map((field) => ({
+          key: field.key,
+          type: field.type,
+          required: field.required,
+        })),
+      }));
+      human +=
+        '\n' +
+        result.models
+          .map(
+            (model) =>
+              `  ${model.key}: ${model.fields.map((field) => `${field.key} (${field.type})`).join(', ')}`,
+          )
+          .join('\n');
+    } else if (['schema pull', 'schema export'].includes(command)) {
+      const targetPath = resolve(cwd, opts.out);
+      await writeOutput(targetPath, serialize(schema), [
+        resolve(cwd, opts.config || 'lemonade.config.json'),
+      ]);
+      result.written = true;
+      human = 'Schema exported successfully.';
+    } else if (command === 'schema diff') {
+      result.changes = compareSchemas(await readSchema(), schema);
+      result.drift = result.changes.length > 0;
+      code = result.drift ? 3 : 0;
+      result.ok = !result.drift;
+      human = result.drift
+        ? `Schema differs (${result.changes.length} changes):\n${result.changes.map((item) => `  ${item.change}: ${item.path}`).join('\n')}`
+        : 'Schema matches the baseline.';
+    } else if (command === 'schema validate') {
+      human = 'Schema is valid for read-only inspection and type generation.';
+    } else if (command === 'types generate') {
+      const language = opts.language || 'typescript';
+      const output = generateLanguage(schema, language);
+      if (Buffer.byteLength(output) > MAX_SCHEMA_BYTES)
+        fail(5, 'Generated output exceeds the supported 8 MiB limit.');
+      result.language = language;
+      if (key && output.includes(key))
+        fail(5, 'Unsafe reflected credential was blocked.');
+      const path = resolve(cwd, opts.out);
+      if (opts.check) {
+        let exists = true;
+        try {
+          await access(path);
+        } catch (error) {
+          if (error.code !== 'ENOENT') fail(5, 'Could not inspect generated output.');
+          exists = false;
+        }
+        result.drift = !exists || (await readText(path)) !== output;
+        result.ok = !result.drift;
+        code = result.drift ? 3 : 0;
+        human = result.drift
+          ? 'Generated types differ or are missing. Run types generate without --check.'
+          : 'Generated types are up to date.';
+      } else {
+        await writeOutput(path, output, [
+          inputPath,
+          resolve(cwd, opts.config || 'lemonade.config.json'),
+          resolve(cwd, '.env'),
+        ]);
+        result.written = true;
+        human = `Types generated successfully (${language}).`;
+      }
+    }
+    emit(result, human);
+    return code;
+  } catch (error) {
+    const safe =
+      error instanceof CLIError
+        ? error
+        : new CLIError(
+            5,
+            'Operation failed. Check configuration, schema and file access.',
+          );
+    const result = { ok: false, code: safe.code, error: safe.message };
+    // Fixed diagnostic messages never interpolate server responses, URLs or supplied arguments.
+    emit(result, safe.message, true);
+    return safe.code;
+  }
+}