@lemonadecms/client 0.0.0-stage → 0.1.1

package/bin/cli/config.mjs

@@ -0,0 +1,309 @@
+import { access } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { parseEnv } from 'node:util';
+import { readText, parseJSON } from './io.mjs';
+import { fail } from './errors.mjs';
+import { languages } from '../codegen/definitions.mjs';
+export const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export const record = (value) =>
+  value !== null && typeof value === 'object' && !Array.isArray(value);
+const environmentKey = /^[a-z][a-z0-9_-]{0,31}$/;
+const envName = /^[A-Z][A-Z0-9_]{0,127}$/;
+const options = [
+  'config',
+  'target',
+  'url',
+  'workspace',
+  'environment',
+  'credential-env',
+  'file',
+  'out',
+  'plan',
+  'confirm',
+  'before',
+  'language',
+  'baseline',
+  'status',
+  'id',
+];
+const flags = ['json', 'check', 'help', 'version'];
+export function parseArgs(args) {
+  const opts = {},
+    words = [];
+  for (let i = 0; i < args.length; i++) {
+    const word = args[i];
+    if (!word.startsWith('-')) {
+      words.push(word);
+      continue;
+    }
+    const key = word.slice(2);
+    if (
+      !word.startsWith('--') ||
+      (!options.includes(key) && !flags.includes(key)) ||
+      Object.hasOwn(opts, key)
+    )
+      fail(2, 'Unknown or repeated option. Use lemonade --help.');
+    if (flags.includes(key)) opts[key] = true;
+    else {
+      const value = args[++i];
+      if (!value || value.startsWith('--')) fail(2, 'An option value is missing.');
+      opts[key] = value;
+    }
+  }
+  const command = words.join(' ');
+  const allowed = {
+    check: [],
+    'schema inspect': [],
+    'schema pull': ['out'],
+    'schema export': ['out'],
+    'schema validate': ['file'],
+    'schema diff': ['file'],
+    'types generate': ['file', 'out', 'check', 'language'],
+    'schema migrate status': ['before'],
+    'schema migrate create': ['file', 'baseline', 'status', 'id', 'out'],
+    'schema migrate plan': ['file', 'out'],
+    'schema migrate apply': ['file', 'plan', 'confirm'],
+  };
+  if (opts.help || opts.version) {
+    if (
+      words.length ||
+      Object.keys(opts).some((key) => !['help', 'version', 'json'].includes(key)) ||
+      (opts.help && opts.version)
+    )
+      fail(2, 'Use lemonade --help or lemonade --version on its own.');
+  } else {
+    if (!Object.hasOwn(allowed, command))
+      fail(2, 'Unknown command. Use lemonade --help.');
+    for (const key of [
+      'file',
+      'out',
+      'check',
+      'plan',
+      'confirm',
+      'before',
+      'language',
+      'baseline',
+      'status',
+      'id',
+    ])
+      if (Object.hasOwn(opts, key) && !allowed[command].includes(key))
+        fail(2, 'Option is not supported by this command.');
+    if (opts.language && !languages.includes(opts.language))
+      fail(2, 'Choose typescript, csharp or python as the output language.');
+    if (
+      (command === 'schema validate' ||
+        command === 'schema migrate create' ||
+        (command === 'types generate' && opts.file)) &&
+      ['config', 'target', 'url', 'workspace', 'environment', 'credential-env'].some(
+        (key) => Object.hasOwn(opts, key),
+      )
+    )
+      fail(2, 'Offline file commands do not accept connection options.');
+    if (
+      [
+        'schema pull',
+        'schema export',
+        'schema migrate plan',
+        'schema migrate create',
+      ].includes(command) &&
+      !opts.out
+    )
+      fail(2, '--out is required.');
+    if (command === 'types generate' && !opts.out)
+      opts.out = `src/types/${
+        {
+          typescript: 'cms-models.ts',
+          csharp: 'cms-models.cs',
+          python: 'cms_models.py',
+        }[opts.language || 'typescript']
+      }`;
+    if (
+      [
+        'schema validate',
+        'schema diff',
+        'schema migrate plan',
+        'schema migrate apply',
+        'schema migrate create',
+      ].includes(command) &&
+      !opts.file
+    )
+      fail(2, '--file is required.');
+    if (
+      command === 'schema migrate create' &&
+      (!opts.baseline ||
+        !opts.status ||
+        !/^[0-9]{14}_[a-z][a-z0-9_]{0,63}$/.test(opts.id || ''))
+    )
+      fail(
+        2,
+        'Creating requires --baseline, --status, --id YYYYMMDDHHMMSS_description, --file and --out.',
+      );
+  }
+  if (
+    command === 'schema migrate apply' &&
+    (!opts.plan || !/^[a-f0-9]{64}$/.test(opts.confirm || ''))
+  )
+    fail(2, 'Applying requires --file, --plan and --confirm REVIEWED_CHECKSUM.');
+  return { command, opts };
+}
+export async function typeGenerationEnv(env, cwd) {
+  const path = resolve(cwd, '.env');
+  try {
+    await access(path);
+  } catch (error) {
+    if (error.code === 'ENOENT') return { ...env };
+    fail(2, 'Could not open project .env. Check file access.');
+  }
+  try {
+    // Parse data only: never source shell code or change process.env/startup settings.
+    return { ...parseEnv(await readText(path, 65536)), ...env };
+  } catch {
+    fail(
+      2,
+      'Could not read project .env. Use a UTF-8 regular file no larger than 64 KiB.',
+    );
+  }
+}
+
+export async function readConfiguration(opts, cwd) {
+  const configPath = resolve(cwd, opts.config || 'lemonade.config.json');
+  let config = {};
+  let found = true;
+  try {
+    await access(configPath);
+  } catch (error) {
+    if (error.code !== 'ENOENT' || opts.config)
+      fail(2, 'Could not open project configuration.');
+    found = false;
+  }
+  if (found) {
+    try {
+      config = parseJSON(await readText(configPath, 65536));
+    } catch {
+      fail(2, 'Could not read valid project configuration.');
+    }
+    if (
+      !record(config) ||
+      config.version !== 1 ||
+      !record(config.targets) ||
+      Object.keys(config).some((key) => !['version', 'targets'].includes(key)) ||
+      Object.keys(config.targets).length > 20
+    )
+      fail(2, 'Invalid project configuration.');
+    for (const [name, target] of Object.entries(config.targets)) {
+      if (
+        !environmentKey.test(name) ||
+        !record(target) ||
+        Object.keys(target).some(
+          (key) => !['url', 'workspace', 'environment', 'credentialEnv'].includes(key),
+        ) ||
+        Object.values(target).some((value) => typeof value !== 'string') ||
+        !uuid.test(target.workspace || '') ||
+        !(
+          uuid.test(target.environment || '') ||
+          environmentKey.test(target.environment || '')
+        ) ||
+        (target.credentialEnv !== undefined && !envName.test(target.credentialEnv))
+      )
+        fail(
+          2,
+          'Invalid target configuration; keep credentials in environment variables.',
+        );
+      safeURL(target.url);
+    }
+  }
+  return { configPath, targets: config.targets || {} };
+}
+
+export async function connection(
+  opts,
+  env,
+  cwd,
+  management = false,
+  defaults = {},
+  configuration,
+) {
+  const { configPath, targets } = configuration || (await readConfiguration(opts, cwd));
+  const name = opts.target || env.LEMONADE_TARGET;
+  if (name && !Object.hasOwn(targets, name))
+    fail(2, 'Selected target is not configured.');
+  const target = name ? targets[name] : {};
+  const selected = {
+    url: opts.url || target.url || env.LEMONADE_URL || 'https://lemonadecms.com',
+    workspace:
+      opts.workspace ||
+      target.workspace ||
+      env.LEMONADE_WORKSPACE ||
+      defaults.workspace,
+    environment:
+      opts.environment ||
+      target.environment ||
+      env.LEMONADE_ENVIRONMENT ||
+      defaults.environment,
+    credentialEnv:
+      opts['credential-env'] ||
+      target.credentialEnv ||
+      (management
+        ? 'LEMONADE_MANAGEMENT_TOKEN'
+        : defaults.credentialEnv || 'LEMONADE_TOKEN'),
+    configPath,
+  };
+  if (defaults.credentialEnv && !selected.workspace)
+    fail(
+      2,
+      'Set CMS_PROJECT_ID in .env or the process environment, or pass --workspace UUID.',
+    );
+  if (
+    !uuid.test(selected.workspace || '') ||
+    !(
+      uuid.test(selected.environment || '') ||
+      environmentKey.test(selected.environment || '')
+    ) ||
+    !envName.test(selected.credentialEnv)
+  )
+    fail(
+      2,
+      'Set an explicit workspace UUID, environment key/UUID and credential environment-variable name.',
+    );
+  if (management && !uuid.test(selected.environment || ''))
+    fail(2, 'Schema management requires an explicit environment UUID.');
+  const url = safeURL(selected.url);
+  const key = env[selected.credentialEnv];
+  if (
+    typeof key !== 'string' ||
+    !(
+      management
+        ? /^lmd_mgmt_[0-9a-f-]{36}\.[A-Za-z0-9_-]{43}$/
+        : /^(?:(?:pk|sk)_[A-Za-z0-9_-]{43}|lmd_(?:pk|sk)_[0-9a-f-]{36}\.[A-Za-z0-9_-]{43})$/
+    ).test(key)
+  )
+    fail(
+      2,
+      'Set a valid command-specific credential in the configured environment variable.',
+    );
+  selected.url = url.href.replace(/\/+$/, '');
+  return { ...selected, key };
+}
+
+function safeURL(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    fail(2, 'Set a valid CMS URL.');
+  }
+  const loopback = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+  if (
+    !['https:', 'http:'].includes(url.protocol) ||
+    (url.protocol === 'http:' && !loopback) ||
+    url.username ||
+    url.password ||
+    url.search ||
+    url.hash
+  )
+    fail(
+      2,
+      'Use HTTPS (HTTP only on loopback), without URL credentials, query or fragment.',
+    );
+  return url;
+}

package/bin/cli/create-migration.mjs

@@ -0,0 +1,157 @@
+import { resolve } from 'node:path';
+import { validateSchema, canonical } from './schema.mjs';
+import { parseJSON, readText, writeOutput } from './io.mjs';
+import { record } from './config.mjs';
+import { fail } from './errors.mjs';
+
+const equal = (a, b) => JSON.stringify(canonical(a)) === JSON.stringify(canonical(b));
+const rejected = () =>
+  fail(
+    5,
+    'Only new models and appended optional fields are supported. Existing definitions, languages and remote bindings must remain unchanged.',
+  );
+function migrationFields(fields, adding = false) {
+  for (const field of fields) {
+    if (
+      ['component', 'components', 'blocks'].includes(field.type) ||
+      Object.hasOwn(field, 'default') ||
+      Object.hasOwn(field, 'seo') ||
+      (adding && field.required)
+    )
+      rejected();
+  }
+}
+
+function orderedOperations(operations, existingKeys) {
+  const sorted = [...operations].sort((a, b) =>
+    a.key < b.key ? -1 : a.key > b.key ? 1 : 0,
+  );
+  const pending = sorted.filter((operation) => operation.op === 'create_model');
+  const available = new Set(existingKeys);
+  const ordered = [];
+  while (pending.length) {
+    const index = pending.findIndex((operation) =>
+      operation.fields.every((field) => {
+        const targets = ['reference', 'references'].includes(field.type)
+          ? [field.target]
+          : field.type === 'rich_text'
+            ? field.targets || []
+            : [];
+        return targets.every(
+          (target) => target === operation.key || available.has(target),
+        );
+      }),
+    );
+    if (index < 0)
+      fail(
+        5,
+        'New-model reference cycles require separate reviewed additions. No output was written.',
+      );
+    const [next] = pending.splice(index, 1);
+    ordered.push(next);
+    available.add(next.key);
+  }
+  return [...ordered, ...sorted.filter((operation) => operation.op === 'add_fields')];
+}
+
+export async function createMigration(opts, cwd) {
+  const paths = [opts.baseline, opts.file, opts.status].map((name) =>
+    resolve(cwd, name),
+  );
+  const baseline = validateSchema(parseJSON(await readText(paths[0])));
+  const desired = validateSchema(parseJSON(await readText(paths[1])));
+  const status = parseJSON(await readText(paths[2]));
+  const environment = baseline.environment?.id || baseline.project_id;
+  const modelSummary = (schema) =>
+    schema.models
+      .map((model) => ({
+        key: model.key,
+        ...(model.singleton ? { singleton: true } : {}),
+        fields: model.fields.map(({ key, type }) => ({ key, type })),
+      }))
+      .sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+  if (
+    !record(status) ||
+    status.ok !== true ||
+    status.workspace !== baseline.project_id ||
+    status.environment !== environment ||
+    status.revision !== baseline.schema_revision ||
+    !/^[a-f0-9]{64}$/.test(status.schema_hash || '') ||
+    !(
+      status.latest === null ||
+      /^[0-9]{14}_[a-z][a-z0-9_]{0,63}$/.test(status.latest || '')
+    ) ||
+    (status.latest !== null && opts.id <= status.latest) ||
+    !Array.isArray(status.models) ||
+    !equal(
+      [...status.models].sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0)),
+      modelSummary(baseline),
+    )
+  )
+    fail(
+      5,
+      'Status and baseline identity, revision or model summary do not match. Capture fresh inputs.',
+    );
+  // Require an exact portable editing baseline. Never turn unsupported edits into
+  // omissions, removals, or a blind desired-state replacement.
+  const withoutModels = ({ models, ...rest }) => rest;
+  if (!equal(withoutModels(baseline), withoutModels(desired))) rejected();
+  const operations = [];
+  const prior = new Map(baseline.models.map((model) => [model.key, model]));
+  for (const model of desired.models) {
+    const before = prior.get(model.key);
+    if (!before) {
+      if (model.remote) rejected();
+      migrationFields(model.fields);
+      operations.push({
+        op: 'create_model',
+        ...(model.singleton ? { singleton: true } : {}),
+        key: model.key,
+        name: model.name,
+        fields: model.fields,
+      });
+    } else {
+      if (
+        !equal({ ...before, fields: [] }, { ...model, fields: [] }) ||
+        model.fields.length < before.fields.length ||
+        !equal(before.fields, model.fields.slice(0, before.fields.length))
+      )
+        rejected();
+      const added = model.fields.slice(before.fields.length);
+      if (added.length) {
+        if (model.remote) rejected();
+        migrationFields(added, true);
+        operations.push({ op: 'add_fields', key: model.key, fields: added });
+      }
+      prior.delete(model.key);
+    }
+  }
+  if (prior.size) rejected();
+  if (!operations.length || operations.length > 16)
+    fail(5, 'Create between 1 and 16 supported model operations per migration.');
+  const migration = {
+    format_version: 1,
+    id: opts.id,
+    previous: status.latest,
+    from: status.schema_hash,
+    operations: orderedOperations(
+      operations,
+      baseline.models.map((model) => model.key),
+    ),
+  };
+  const text = JSON.stringify(migration, null, 2) + '\n';
+  if (Buffer.byteLength(text) > 262144)
+    fail(5, 'Migration exceeds the supported size.');
+  await writeOutput(resolve(cwd, opts.out), text, [
+    ...paths,
+    resolve(cwd, 'lemonade.config.json'),
+  ]);
+  return {
+    ok: true,
+    command: 'schema migrate create',
+    written: true,
+    operations: operations.length,
+    publication: 'unchanged',
+    requiresReview: true,
+  };
+}

package/bin/cli/errors.mjs

@@ -0,0 +1,9 @@
+export class CLIError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+export function fail(code, message) {
+  throw new CLIError(code, message);
+}

package/bin/cli/io.mjs

@@ -0,0 +1,70 @@
+import { open, mkdir, rename, unlink, realpath } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { fail } from './errors.mjs';
+
+export const MAX_SCHEMA_BYTES = 8 * 1024 * 1024;
+export async function readText(path, max = MAX_SCHEMA_BYTES) {
+  let file;
+  try {
+    file = await open(path, constants.O_RDONLY | constants.O_NONBLOCK);
+    const stat = await file.stat();
+    if (!stat.isFile() || stat.size > max)
+      fail(5, 'Input must be a bounded regular file.');
+    const buffer = Buffer.alloc(max + 1);
+    let size = 0;
+    while (size < buffer.length) {
+      const { bytesRead } = await file.read(buffer, size, buffer.length - size, null);
+      if (!bytesRead) break;
+      size += bytesRead;
+    }
+    if (size > max) fail(5, 'Input exceeds the supported size.');
+    return new TextDecoder('utf-8', { fatal: true }).decode(buffer.subarray(0, size));
+  } catch (error) {
+    if (error.code === 5) throw error;
+    fail(5, 'Could not read the input file.');
+  } finally {
+    await file?.close();
+  }
+}
+export function parseJSON(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    fail(5, 'Input is not valid JSON.');
+  }
+}
+export async function writeOutput(path, text, protectedPaths = []) {
+  const destination = resolve(path);
+  const existingDestination = await realpath(destination).catch(() => destination);
+  const existingProtected = await Promise.all(
+    protectedPaths
+      .filter(Boolean)
+      .map((value) => realpath(resolve(value)).catch(() => resolve(value))),
+  );
+  if (
+    existingProtected.includes(existingDestination) ||
+    protectedPaths.some((value) => value && resolve(value) === destination) ||
+    /^(?:\.env(?:\..*)?|lemonade\.config\.json)$/i.test(
+      destination.split(/[\\/]/).pop(),
+    )
+  ) {
+    fail(2, 'Output must not replace configuration, credentials or the input schema.');
+  }
+  const temp = `${destination}.${randomUUID()}.tmp`;
+  try {
+    await mkdir(dirname(destination), { recursive: true });
+    const file = await open(temp, 'wx', 0o600);
+    try {
+      await file.writeFile(text);
+    } finally {
+      await file.close();
+    }
+    await rename(temp, destination);
+  } catch {
+    fail(6, 'Could not write the output file.');
+  } finally {
+    await unlink(temp).catch(() => {});
+  }
+}

package/bin/cli/migrate.mjs

@@ -0,0 +1,109 @@
+import { resolve } from 'node:path';
+import { createHash } from 'node:crypto';
+import { canonical } from './schema.mjs';
+import { connection, record } from './config.mjs';
+import { readText, parseJSON, writeOutput } from './io.mjs';
+import { requestJSON } from './network.mjs';
+import { fail } from './errors.mjs';
+const digest = (value) =>
+  createHash('sha256')
+    .update(JSON.stringify(canonical(value)))
+    .digest('hex');
+export async function migrate(command, opts, { cwd, env, fetcher, setKey }) {
+  const target = await connection(opts, env, cwd, true);
+  setKey(target.key);
+  const path = `/api/v1/management/projects/${target.workspace}/environments/${target.environment}/schema`;
+  if (command === 'schema migrate status') {
+    const result = await requestJSON(
+      target,
+      `${path}/status${opts.before ? '?before=' + encodeURIComponent(opts.before) : ''}`,
+      {},
+      fetcher,
+    );
+    context(result, target);
+    return { result, human: JSON.stringify(result, null, 2) };
+  }
+  const filePath = resolve(cwd, opts.file);
+  const migration = parseJSON(await readText(filePath, 262144));
+  if (
+    !record(migration) ||
+    ![1, 2].includes(migration.format_version) ||
+    !Array.isArray(migration.operations)
+  )
+    fail(5, 'Invalid migration file.');
+  let result;
+  if (command === 'schema migrate plan') {
+    result = await requestJSON(
+      target,
+      `${path}/plan`,
+      { method: 'POST', body: { migration } },
+      fetcher,
+    );
+    context(result, target);
+    if (result.already_applied === true) {
+      if (
+        result.receipt?.checksum !== digest(migration) ||
+        result.receipt?.migration_id !== migration.id
+      )
+        fail(5, 'Mismatched migration receipt.');
+      return { result, human: 'Migration already applied with the same checksum.' };
+    }
+    if (
+      result.checksum !== digest(migration) ||
+      typeof result.plan !== 'string' ||
+      result.plan.length > 8192
+    )
+      fail(5, 'Invalid or mismatched migration plan.');
+    // Local review artifact; never overwrite a migration/configuration file.
+    await writeOutput(resolve(cwd, opts.out), JSON.stringify(result, null, 2) + '\n', [
+      filePath,
+      target.configPath,
+    ]);
+    const { plan, ...safe } = result;
+    return {
+      result: { ...safe, written: true },
+      human: `Plan saved. Review its impact before applying. Confirm checksum: ${result.checksum}`,
+    };
+  }
+  const saved = parseJSON(await readText(resolve(cwd, opts.plan), 262144));
+  context(saved, target);
+  if (
+    saved.checksum !== digest(migration) ||
+    opts.confirm !== saved.checksum ||
+    typeof saved.plan !== 'string'
+  )
+    fail(5, 'File, reviewed plan and confirmation checksum must match.');
+  result = await requestJSON(
+    target,
+    `${path}/apply`,
+    { method: 'POST', body: { migration, plan: saved.plan } },
+    fetcher,
+  );
+  context(result, target);
+  if (
+    !record(result.receipt) ||
+    result.receipt.checksum !== saved.checksum ||
+    result.receipt.migration_id !== migration.id
+  )
+    fail(
+      5,
+      'CMS returned a mismatched migration receipt; inspect status before retrying.',
+    );
+  return {
+    result,
+    human: result.already_applied
+      ? 'Migration already applied; original receipt returned.'
+      : migration.format_version === 2
+        ? 'Reviewed draft backfill applied atomically. Published content is unchanged.'
+        : 'Schema migration applied atomically. Content publication is unchanged.',
+  };
+}
+function context(value, target) {
+  if (
+    !record(value) ||
+    value.ok !== true ||
+    value.workspace !== target.workspace ||
+    value.environment !== target.environment
+  )
+    fail(4, 'Management response does not match the selected workspace/environment.');
+}