@lemonadecms/client 0.0.0-stage → 0.1.0

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.');
+}

package/bin/cli/network.mjs

@@ -0,0 +1,99 @@
+import { MAX_SCHEMA_BYTES, parseJSON } from './io.mjs';
+import { fail, CLIError } from './errors.mjs';
+import { validateSchema, schemaIdentity } from './schema.mjs';
+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 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 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();
+    await reader?.cancel().catch(() => {});
+  }
+}

package/bin/cli/run.mjs

@@ -0,0 +1,190 @@
+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 } from './config.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.
+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.
+Only schema migrate apply writes compatible schema additions or reviewed missing-draft backfills. No content publication, prompts, 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),
+  } = {},
+) {
+  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 target = await connection(opts, env, cwd);
+      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'),
+        ]);
+        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;
+  }
+}