@maykonpaulo/maestro-cli 0.2.0

package/dist/chunk-CSDLIL7L.js

@@ -0,0 +1,1309 @@
+// src/commands/registry.ts
+var CommandRegistry = class {
+  commands = /* @__PURE__ */ new Map();
+  register(command) {
+    if (this.commands.has(command.name)) {
+      throw new Error(`Command '${command.name}' is already registered.`);
+    }
+    this.commands.set(command.name, command);
+  }
+  get(name) {
+    return this.commands.get(name);
+  }
+  list() {
+    return [...this.commands.values()];
+  }
+};
+
+// src/commands/planned.ts
+var PLANNED_COMMANDS = [];
+
+// src/parseArgs.ts
+function parseArgs(argv) {
+  const help = argv.includes("--help") || argv.includes("-h");
+  const version = argv.includes("--version") || argv.includes("-v");
+  const [first, ...rest] = argv;
+  const hasCommand = first !== void 0 && !first.startsWith("-");
+  return {
+    command: hasCommand ? first : void 0,
+    args: hasCommand ? rest : argv,
+    help,
+    version
+  };
+}
+
+// src/help.ts
+function formatHelp(registry) {
+  const lines = [
+    "maestro \u2014 Maestro CLI",
+    "",
+    "Command-line interface for the Maestro declarative engine.",
+    "",
+    "Usage:",
+    "  maestro <command> [options]",
+    "",
+    "Options:",
+    "  -h, --help       Show this help message",
+    "  -v, --version    Show the CLI version",
+    ""
+  ];
+  const available = registry.list();
+  if (available.length > 0) {
+    lines.push("Available commands:");
+    for (const command of available) {
+      lines.push(`  ${command.name.padEnd(12)} ${command.description}`);
+    }
+    lines.push("");
+  }
+  if (PLANNED_COMMANDS.length > 0) {
+    lines.push("Planned commands (not yet implemented):");
+    for (const planned of PLANNED_COMMANDS) {
+      lines.push(`  ${planned.name.padEnd(12)} ${planned.description}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+// src/version.ts
+import { createRequire } from "module";
+var require2 = createRequire(import.meta.url);
+function getCliVersion() {
+  const pkg = require2("../package.json");
+  return pkg.version;
+}
+
+// src/commands/generate/parseGenerateArgs.ts
+function parseFlags(argv) {
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (!arg.startsWith("--")) continue;
+    const eqIndex = arg.indexOf("=");
+    if (eqIndex !== -1) {
+      flags[arg.slice(2, eqIndex)] = arg.slice(eqIndex + 1);
+      continue;
+    }
+    const key = arg.slice(2);
+    const next = argv[i + 1];
+    if (next !== void 0 && !next.startsWith("--")) {
+      flags[key] = next;
+      i++;
+    } else {
+      flags[key] = "true";
+    }
+  }
+  return flags;
+}
+function parseGenerateArgs(argv) {
+  const flags = parseFlags(argv);
+  const input = flags["input"];
+  if (!input) {
+    return { ok: false, error: "Missing required flag --input <path>." };
+  }
+  const type = flags["type"];
+  if (type !== "metadata" && type !== "schema") {
+    return {
+      ok: false,
+      error: `Missing or invalid --type flag. Expected "metadata" or "schema"${type ? `, got "${type}"` : ""}.`
+    };
+  }
+  const format = flags["format"] ?? "json";
+  if (format !== "json" && format !== "yaml") {
+    return { ok: false, error: `Invalid --format flag. Expected "json" or "yaml", got "${format}".` };
+  }
+  return { ok: true, value: { input, type, format, out: flags["out"] } };
+}
+
+// src/commands/generate/GenerateCommand.ts
+import { readFileSync, writeFileSync } from "fs";
+import * as YAML from "yaml";
+import {
+  generateDeclarativeConfigFromMetadata,
+  generateDeclarativeConfigFromSchema,
+  serializeDeclarativeConfig
+} from "@maykonpaulo/maestro-core";
+var defaultDeps = {
+  readFile: (path) => readFileSync(path, "utf-8"),
+  writeFile: (path, content) => writeFileSync(path, content, "utf-8")
+};
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+var GENERATE_HELP_TEXT = `maestro generate \u2014 Generate a declarative config from a local metadata/schema JSON file
+
+Reads a local JSON file containing already-built EntityMetadata[] (--type metadata) or
+EntitySchema[] (--type schema) and generates a declarative config (EntityDeclaration[], plus an
+optional default consumer) using the core's Declarative Config Generator. The result is written to
+stdout, or to a file with --out.
+
+This command does NOT perform introspection, does NOT connect to any database or datasource, and
+does NOT create a Maestro engine \u2014 it only reads a file, transforms it, and writes text. The input
+must already be metadata/schema you produced some other way (e.g. via engine.getMetadata(), or a
+hand-written EntitySchema[]). Introspecting a live datasource is a separate, not-yet-implemented
+command ("maestro introspect").
+
+Usage:
+  maestro generate --input <path> --type <metadata|schema> [--format <json|yaml>] [--out <path>]
+
+Flags:
+  --input <path>              Required. Path to a local JSON file.
+  --type <metadata|schema>    Required. Whether --input holds EntityMetadata[] or EntitySchema[].
+  --format <json|yaml>        Optional. Output format. Default: json.
+  --out <path>                Optional. Write the result to this file instead of stdout.
+
+Examples:
+  maestro generate --input ./metadata.json --type metadata --format json
+  maestro generate --input ./metadata.json --type metadata --format yaml --out ./maestro.config.yaml
+  maestro generate --input ./schema.json --type schema --format json --out ./maestro.config.json
+
+Recommended flow:
+  1. Produce EntityMetadata[] or EntitySchema[] as JSON (e.g. JSON.stringify(engine.getMetadata().entities)).
+  2. maestro generate --input <that file> --type <metadata|schema> --out maestro.config.yaml
+  3. Load it back: loadDeclarativeConfigFromFile('./maestro.config.yaml', { yamlParser })
+  4. Pass the result to createMaestro({ declarations })`;
+function assertGeneratorInput(value, sourcePath) {
+  const isObject2 = typeof value === "object" && value !== null && !Array.isArray(value);
+  const hasEntities = isObject2 && Array.isArray(value["entities"]);
+  if (!hasEntities) {
+    throw new Error(`'${sourcePath}' must be a JSON object with an "entities" array.`);
+  }
+}
+function createGenerateCommand(deps = defaultDeps) {
+  return {
+    name: "generate",
+    description: "Generate a declarative config from a local metadata/schema JSON file",
+    helpText: GENERATE_HELP_TEXT,
+    run(context) {
+      const parsed = parseGenerateArgs(context.argv);
+      if (!parsed.ok) {
+        context.stderr(`maestro generate: ${parsed.error}`);
+        return 1;
+      }
+      const { input, type, format, out } = parsed.value;
+      let rawInput;
+      try {
+        rawInput = deps.readFile(input);
+      } catch (error) {
+        context.stderr(`maestro generate: could not read input file '${input}': ${errorMessage(error)}`);
+        return 1;
+      }
+      let parsedInput;
+      try {
+        parsedInput = JSON.parse(rawInput);
+      } catch (error) {
+        context.stderr(`maestro generate: '${input}' is not valid JSON: ${errorMessage(error)}`);
+        return 1;
+      }
+      let generated;
+      try {
+        assertGeneratorInput(parsedInput, input);
+        generated = type === "metadata" ? generateDeclarativeConfigFromMetadata(parsedInput) : generateDeclarativeConfigFromSchema(parsedInput);
+      } catch (error) {
+        context.stderr(`maestro generate: failed to generate declarative config: ${errorMessage(error)}`);
+        return 1;
+      }
+      let output;
+      try {
+        output = serializeDeclarativeConfig(generated, {
+          format,
+          yamlSerializer: format === "yaml" ? { stringify: (value) => YAML.stringify(value) } : void 0
+        });
+      } catch (error) {
+        context.stderr(`maestro generate: ${errorMessage(error)}`);
+        return 1;
+      }
+      if (out) {
+        try {
+          deps.writeFile(out, output);
+        } catch (error) {
+          context.stderr(`maestro generate: could not write output file '${out}': ${errorMessage(error)}`);
+          return 1;
+        }
+        context.stdout(`Declarative config written to ${out}`);
+      } else {
+        context.stdout(output);
+      }
+      return 0;
+    }
+  };
+}
+
+// src/commands/validate/parseValidateArgs.ts
+var ALIASES = { i: "input" };
+function parseFlags2(argv) {
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    const isLong = arg.startsWith("--");
+    const isShort = !isLong && arg.startsWith("-") && arg.length > 1;
+    if (!isLong && !isShort) continue;
+    const body = isLong ? arg.slice(2) : arg.slice(1);
+    const eqIndex = body.indexOf("=");
+    if (eqIndex !== -1) {
+      const key2 = body.slice(0, eqIndex);
+      flags[ALIASES[key2] ?? key2] = body.slice(eqIndex + 1);
+      continue;
+    }
+    const key = ALIASES[body] ?? body;
+    const next = argv[i + 1];
+    if (next !== void 0 && !next.startsWith("-")) {
+      flags[key] = next;
+      i++;
+    } else {
+      flags[key] = "true";
+    }
+  }
+  return flags;
+}
+function parseValidateArgs(argv) {
+  const flags = parseFlags2(argv);
+  const input = flags["input"];
+  if (!input || input === "true") {
+    return { ok: false, error: "Missing required flag --input <path> (or -i <path>)." };
+  }
+  const format = flags["format"];
+  if (format !== void 0 && format !== "json" && format !== "yaml") {
+    return { ok: false, error: `Invalid --format flag. Expected "json" or "yaml", got "${format}".` };
+  }
+  return { ok: true, value: { input, format } };
+}
+
+// src/commands/validate/ValidateCommand.ts
+import { readFileSync as readFileSync2 } from "fs";
+import { extname } from "path";
+import * as YAML2 from "yaml";
+import {
+  loadDeclarativeConfigFromString
+} from "@maykonpaulo/maestro-core";
+var defaultDeps2 = {
+  readFile: (path) => readFileSync2(path, "utf-8")
+};
+function errorMessage2(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+var VALIDATE_HELP_TEXT = `maestro validate \u2014 Validate a declarative config file (YAML or JSON)
+
+Loads a local declarative config file (maestro.config.yaml/.yml/.json) and validates its structure
+using the core's Declarative File Loader. Prints a readable summary on success and a readable error
+on failure.
+
+This command does NOT create a Maestro engine (no createMaestro()), does NOT connect to any database,
+datasource or provider, and does NOT require declared operations to have a real implementation.
+Structural validation of the declarative file is all it does; wiring operations to code and starting
+the runtime is what createMaestro() does separately.
+
+Usage:
+  maestro validate --input <path> [--format <json|yaml>]
+  maestro validate -i <path>
+
+Flags:
+  --input, -i <path>       Required. Path to a local declarative config file (.yaml, .yml or .json).
+  --format <json|yaml>     Optional. Overrides the format detected from the file extension.
+
+Accepted file formats:
+  .json          \u2192 parsed as JSON
+  .yaml, .yml    \u2192 parsed as YAML
+  (other)        \u2192 pass --format explicitly
+
+What is validated:
+  - The file parses as JSON/YAML.
+  - The top-level shape (optional "entities" and "consumers" arrays; no unknown keys).
+  - Each entity declaration (fields, types, capabilities, operations, relationships, enumOptions).
+  - Each consumer declaration against its referenced entity.
+
+What is NOT validated:
+  - Operation bindings (whether declared operations have a real handler) \u2014 that's createMaestro().
+  - Datasource/provider connectivity \u2014 no database or external system is contacted.
+
+Examples:
+  maestro validate --input ./maestro.config.yaml
+  maestro validate --input ./maestro.config.json
+  maestro validate -i ./maestro.config.yaml
+  maestro validate --input ./maestro.config --format yaml`;
+var yamlParser = { parse: (content) => YAML2.parse(content) };
+function resolveFormat(input, override) {
+  if (override) return { ok: true, format: override };
+  const ext = extname(input).toLowerCase();
+  if (ext === ".json") return { ok: true, format: "json" };
+  if (ext === ".yaml" || ext === ".yml") return { ok: true, format: "yaml" };
+  return {
+    ok: false,
+    error: `cannot detect format from file extension "${ext || "(none)"}" of '${input}'. Supported: .json, .yaml, .yml. Pass --format <json|yaml> to override.`
+  };
+}
+function createValidateCommand(deps = defaultDeps2) {
+  return {
+    name: "validate",
+    description: "Validate a declarative config file (YAML or JSON)",
+    helpText: VALIDATE_HELP_TEXT,
+    run(context) {
+      const parsed = parseValidateArgs(context.argv);
+      if (!parsed.ok) {
+        context.stderr(`maestro validate: ${parsed.error}`);
+        return 1;
+      }
+      const { input, format: formatOverride } = parsed.value;
+      const resolved = resolveFormat(input, formatOverride);
+      if (!resolved.ok) {
+        context.stderr(`maestro validate: ${resolved.error}`);
+        return 1;
+      }
+      const { format } = resolved;
+      let content;
+      try {
+        content = deps.readFile(input);
+      } catch (error) {
+        context.stderr(`maestro validate: could not read input file '${input}': ${errorMessage2(error)}`);
+        return 1;
+      }
+      let config;
+      try {
+        config = loadDeclarativeConfigFromString(content, {
+          format,
+          yamlParser: format === "yaml" ? yamlParser : void 0,
+          source: input
+        });
+      } catch (error) {
+        context.stderr(`maestro validate: ${errorMessage2(error)}`);
+        return 1;
+      }
+      context.stdout(`Valid declarative config: ${input}`);
+      context.stdout(`Entities: ${config.entities.length}`);
+      context.stdout(`Consumers: ${config.consumers?.length ?? 0}`);
+      return 0;
+    }
+  };
+}
+
+// src/commands/diff/parseDiffArgs.ts
+var ALIASES2 = { f: "from", t: "to" };
+function parseFlags3(argv) {
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    const isLong = arg.startsWith("--");
+    const isShort = !isLong && arg.startsWith("-") && arg.length > 1;
+    if (!isLong && !isShort) continue;
+    const body = isLong ? arg.slice(2) : arg.slice(1);
+    const eqIndex = body.indexOf("=");
+    if (eqIndex !== -1) {
+      const key2 = body.slice(0, eqIndex);
+      flags[ALIASES2[key2] ?? key2] = body.slice(eqIndex + 1);
+      continue;
+    }
+    const key = ALIASES2[body] ?? body;
+    const next = argv[i + 1];
+    if (next !== void 0 && !next.startsWith("-")) {
+      flags[key] = next;
+      i++;
+    } else {
+      flags[key] = "true";
+    }
+  }
+  return flags;
+}
+function validateFormat(value, flag) {
+  if (value === void 0) return { ok: true, value: void 0 };
+  if (value !== "json" && value !== "yaml") {
+    return { ok: false, error: `Invalid ${flag} flag. Expected "json" or "yaml", got "${value}".` };
+  }
+  return { ok: true, value };
+}
+function parseDiffArgs(argv) {
+  const flags = parseFlags3(argv);
+  const from = flags["from"];
+  if (!from || from === "true") {
+    return { ok: false, error: "Missing required flag --from <path> (or -f <path>)." };
+  }
+  const to = flags["to"];
+  if (!to || to === "true") {
+    return { ok: false, error: "Missing required flag --to <path> (or -t <path>)." };
+  }
+  const fromFormat = validateFormat(flags["from-format"], "--from-format");
+  if (!fromFormat.ok) return fromFormat;
+  const toFormat = validateFormat(flags["to-format"], "--to-format");
+  if (!toFormat.ok) return toFormat;
+  return { ok: true, value: { from, to, fromFormat: fromFormat.value, toFormat: toFormat.value } };
+}
+
+// src/commands/diff/diffDeclarativeConfigs.ts
+function canonicalize(value) {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (value !== null && typeof value === "object") {
+    const entries = Object.entries(value).filter(([, v]) => v !== void 0).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+    const out = {};
+    for (const [k, v] of entries) out[k] = canonicalize(v);
+    return out;
+  }
+  return value;
+}
+function canonicalString(value) {
+  return JSON.stringify(canonicalize(value)) ?? "undefined";
+}
+function deepEqual(a, b) {
+  return canonicalString(a) === canonicalString(b);
+}
+function sortedKeyUnion(...records) {
+  const keys = /* @__PURE__ */ new Set();
+  for (const record of records) {
+    if (record) for (const key of Object.keys(record)) keys.add(key);
+  }
+  return [...keys].sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
+}
+function leafChanges(a, b, keys) {
+  const paths = keys ?? sortedKeyUnion(a, b);
+  const changes = [];
+  for (const path of paths) {
+    if (!deepEqual(a[path], b[path])) {
+      changes.push({ path, from: a[path], to: b[path] });
+    }
+  }
+  return changes;
+}
+function diffRecord(from, to) {
+  const result = [];
+  for (const name of sortedKeyUnion(from, to)) {
+    const a = from?.[name];
+    const b = to?.[name];
+    if (a === void 0) {
+      result.push({ name, kind: "added" });
+    } else if (b === void 0) {
+      result.push({ name, kind: "removed" });
+    } else {
+      const changes = leafChanges(a, b);
+      if (changes.length > 0) result.push({ name, kind: "changed", leafChanges: changes });
+    }
+  }
+  return result;
+}
+function relationRecord(relationships) {
+  const record = {};
+  for (const relation of relationships ?? []) {
+    const key = relation.id ?? `${relation.fromField}->${relation.toEntity}.${relation.toField}`;
+    record[key] = relation;
+  }
+  return record;
+}
+var ENTITY_SCALAR_KEYS = ["label", "pluralLabel", "description", "capabilities"];
+var CONSUMER_KEYS = ["list", "detail", "forms", "actions"];
+function diffEntity(a, b) {
+  const leaf = leafChanges(
+    a,
+    b,
+    ENTITY_SCALAR_KEYS
+  );
+  const groups = [];
+  const fields = diffRecord(a.fields, b.fields);
+  if (fields.length > 0) groups.push({ title: "fields", members: fields });
+  const operations = diffRecord(a.operations, b.operations);
+  if (operations.length > 0) groups.push({ title: "operations", members: operations });
+  const relationships = diffRecord(relationRecord(a.relationships), relationRecord(b.relationships));
+  if (relationships.length > 0) groups.push({ title: "relationships", members: relationships });
+  if (leaf.length === 0 && groups.length === 0) return null;
+  return { name: a.entity, kind: "changed", leafChanges: leaf, groups };
+}
+function entityIndex(config) {
+  const index = {};
+  for (const entity of config.entities) index[entity.entity] = entity;
+  return index;
+}
+function consumerIndex(config) {
+  const index = {};
+  for (const consumer of config.consumers ?? []) {
+    index[`${consumer.consumer}:${consumer.entity}`] = consumer;
+  }
+  return index;
+}
+function diffEntities(from, to) {
+  const a = entityIndex(from);
+  const b = entityIndex(to);
+  const result = [];
+  for (const name of sortedKeyUnion(a, b)) {
+    if (a[name] === void 0) {
+      result.push({ name, kind: "added" });
+    } else if (b[name] === void 0) {
+      result.push({ name, kind: "removed" });
+    } else {
+      const changed = diffEntity(a[name], b[name]);
+      if (changed) result.push(changed);
+    }
+  }
+  return result;
+}
+function diffConsumers(from, to) {
+  const a = consumerIndex(from);
+  const b = consumerIndex(to);
+  const result = [];
+  for (const name of sortedKeyUnion(a, b)) {
+    if (a[name] === void 0) {
+      result.push({ name, kind: "added" });
+    } else if (b[name] === void 0) {
+      result.push({ name, kind: "removed" });
+    } else {
+      const changes = leafChanges(
+        a[name],
+        b[name],
+        CONSUMER_KEYS
+      );
+      if (changes.length > 0) result.push({ name, kind: "changed", leafChanges: changes });
+    }
+  }
+  return result;
+}
+function diffDeclarativeConfigs(from, to) {
+  const entities = diffEntities(from, to);
+  const consumers = diffConsumers(from, to);
+  return { entities, consumers, hasDifferences: entities.length > 0 || consumers.length > 0 };
+}
+var SYMBOL = { added: "+", removed: "-", changed: "~" };
+function renderValue(value) {
+  if (value === void 0) return "(unset)";
+  return canonicalString(value);
+}
+function renderLeafChange(change, indent) {
+  return `${indent}${change.path}: ${renderValue(change.from)} \u2192 ${renderValue(change.to)}`;
+}
+function renderMember(member, indent, lines) {
+  lines.push(`${indent}${SYMBOL[member.kind]} ${member.name}`);
+  const childIndent = `${indent}  `;
+  for (const change of member.leafChanges ?? []) {
+    lines.push(renderLeafChange(change, childIndent));
+  }
+  for (const group of member.groups ?? []) {
+    lines.push(`${childIndent}${group.title}:`);
+    for (const child of group.members) {
+      renderMember(child, `${childIndent}  `, lines);
+    }
+  }
+}
+function formatDeclarativeDiff(diff) {
+  if (!diff.hasDifferences) return "No differences found.";
+  const lines = ["Differences found."];
+  if (diff.entities.length > 0) {
+    lines.push("", "Entities:");
+    for (const member of diff.entities) renderMember(member, "  ", lines);
+  }
+  if (diff.consumers.length > 0) {
+    lines.push("", "Consumers:");
+    for (const member of diff.consumers) renderMember(member, "  ", lines);
+  }
+  return lines.join("\n");
+}
+
+// src/commands/diff/DiffCommand.ts
+import { readFileSync as readFileSync3 } from "fs";
+import { extname as extname2 } from "path";
+import * as YAML3 from "yaml";
+import {
+  loadDeclarativeConfigFromString as loadDeclarativeConfigFromString2
+} from "@maykonpaulo/maestro-core";
+var defaultDeps3 = {
+  readFile: (path) => readFileSync3(path, "utf-8")
+};
+var EXIT_DIFFERENCES = 1;
+var EXIT_ERROR = 2;
+function errorMessage3(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+var DIFF_HELP_TEXT = `maestro diff \u2014 Compare two declarative config files (YAML or JSON)
+
+Loads two local declarative config files (maestro.config.yaml/.yml/.json) with the core's Declarative
+File Loader, then compares their normalised structures and prints a readable, deterministic report of
+what changed. Useful before promoting, reviewing or versioning a config.
+
+This command does NOT create a Maestro engine (no createMaestro()), does NOT connect to any database,
+datasource or provider, does NOT execute operations, and does NOT require declared operations to have
+a real implementation. It is a read-only, local comparison of two declarative files.
+
+Usage:
+  maestro diff --from <path> --to <path> [--from-format <json|yaml>] [--to-format <json|yaml>]
+  maestro diff -f <path> -t <path>
+
+Flags:
+  --from, -f <path>          Required. Path to the baseline declarative config file.
+  --to, -t <path>            Required. Path to the changed declarative config file.
+  --from-format <json|yaml>  Optional. Overrides the format detected from the --from extension.
+  --to-format <json|yaml>    Optional. Overrides the format detected from the --to extension.
+
+Accepted file formats:
+  .json          \u2192 parsed as JSON
+  .yaml, .yml    \u2192 parsed as YAML
+  (other)        \u2192 pass --from-format / --to-format explicitly
+
+What is compared:
+  - Entities (added / removed / changed): label, pluralLabel, description, capabilities.
+  - Entity fields (added / removed / changed): type, label, required, readonly, description,
+    enumOptions, relationEntity and any other declarative field property.
+  - Entity operations (added / removed / changed) \u2014 no handler/implementation required.
+  - Entity relationships (added / removed / changed).
+  - Consumers (added / removed / changed): list, detail, forms and actions projections.
+
+What is NOT compared:
+  - Operation bindings or handlers \u2014 that's createMaestro(), not diff.
+  - Live database/introspection metadata \u2014 this diffs declarative files, not a real schema.
+
+Exit codes:
+  0   Both files are valid and there are no differences.
+  1   Both files are valid and there are differences.
+  2   Usage, file-read, parse or validation error.
+
+Examples:
+  maestro diff --from ./maestro.config.old.yaml --to ./maestro.config.new.yaml
+  maestro diff -f ./before.json -t ./after.json
+  maestro diff --from ./before.config --from-format yaml --to ./after.config --to-format yaml`;
+var yamlParser2 = { parse: (content) => YAML3.parse(content) };
+function resolveFormat2(path, override, flag) {
+  if (override) return { ok: true, format: override };
+  const ext = extname2(path).toLowerCase();
+  if (ext === ".json") return { ok: true, format: "json" };
+  if (ext === ".yaml" || ext === ".yml") return { ok: true, format: "yaml" };
+  return {
+    ok: false,
+    error: `cannot detect format from file extension "${ext || "(none)"}" of '${path}'. Supported: .json, .yaml, .yml. Pass ${flag} <json|yaml> to override.`
+  };
+}
+function loadConfig(deps, path, format) {
+  let content;
+  try {
+    content = deps.readFile(path);
+  } catch (error) {
+    return { ok: false, error: `could not read file '${path}': ${errorMessage3(error)}` };
+  }
+  try {
+    const config = loadDeclarativeConfigFromString2(content, {
+      format,
+      yamlParser: format === "yaml" ? yamlParser2 : void 0,
+      source: path
+    });
+    return { ok: true, config };
+  } catch (error) {
+    return { ok: false, error: errorMessage3(error) };
+  }
+}
+function createDiffCommand(deps = defaultDeps3) {
+  return {
+    name: "diff",
+    description: "Compare two declarative config files (YAML or JSON)",
+    helpText: DIFF_HELP_TEXT,
+    run(context) {
+      const parsed = parseDiffArgs(context.argv);
+      if (!parsed.ok) {
+        context.stderr(`maestro diff: ${parsed.error}`);
+        return EXIT_ERROR;
+      }
+      const { from, to, fromFormat, toFormat } = parsed.value;
+      const fromResolved = resolveFormat2(from, fromFormat, "--from-format");
+      if (!fromResolved.ok) {
+        context.stderr(`maestro diff: ${fromResolved.error}`);
+        return EXIT_ERROR;
+      }
+      const toResolved = resolveFormat2(to, toFormat, "--to-format");
+      if (!toResolved.ok) {
+        context.stderr(`maestro diff: ${toResolved.error}`);
+        return EXIT_ERROR;
+      }
+      const fromConfig = loadConfig(deps, from, fromResolved.format);
+      if (!fromConfig.ok) {
+        context.stderr(`maestro diff: ${fromConfig.error}`);
+        return EXIT_ERROR;
+      }
+      const toConfig = loadConfig(deps, to, toResolved.format);
+      if (!toConfig.ok) {
+        context.stderr(`maestro diff: ${toConfig.error}`);
+        return EXIT_ERROR;
+      }
+      const diff = diffDeclarativeConfigs(fromConfig.config, toConfig.config);
+      context.stdout(formatDeclarativeDiff(diff));
+      return diff.hasDifferences ? EXIT_DIFFERENCES : 0;
+    }
+  };
+}
+
+// src/commands/snapshot/parseSnapshotArgs.ts
+var ALIASES3 = { i: "input" };
+function parseFlags4(argv) {
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    const isLong = arg.startsWith("--");
+    const isShort = !isLong && arg.startsWith("-") && arg.length > 1;
+    if (!isLong && !isShort) continue;
+    const body = isLong ? arg.slice(2) : arg.slice(1);
+    const eqIndex = body.indexOf("=");
+    if (eqIndex !== -1) {
+      const key2 = body.slice(0, eqIndex);
+      flags[ALIASES3[key2] ?? key2] = body.slice(eqIndex + 1);
+      continue;
+    }
+    const key = ALIASES3[body] ?? body;
+    const next = argv[i + 1];
+    if (next !== void 0 && !next.startsWith("-")) {
+      flags[key] = next;
+      i++;
+    } else {
+      flags[key] = "true";
+    }
+  }
+  return flags;
+}
+function validateInputFormat(value) {
+  if (value === void 0) return { ok: true, value: void 0 };
+  if (value !== "json" && value !== "yaml") {
+    return {
+      ok: false,
+      error: `Invalid --input-format flag. Expected "json" or "yaml", got "${value}".`
+    };
+  }
+  return { ok: true, value };
+}
+function validateOutputFormat(value) {
+  if (value === void 0) return { ok: true, value: "json" };
+  if (value !== "json") {
+    return { ok: false, error: `Invalid --format flag. Expected "json", got "${value}".` };
+  }
+  return { ok: true, value };
+}
+function parseSnapshotArgs(argv) {
+  const flags = parseFlags4(argv);
+  const input = flags["input"];
+  if (!input || input === "true") {
+    return { ok: false, error: "Missing required flag --input <path> (or -i <path>)." };
+  }
+  const inputFormat = validateInputFormat(flags["input-format"]);
+  if (!inputFormat.ok) return inputFormat;
+  const format = validateOutputFormat(flags["format"]);
+  if (!format.ok) return format;
+  const out = flags["out"] && flags["out"] !== "true" ? flags["out"] : void 0;
+  return {
+    ok: true,
+    value: { input, inputFormat: inputFormat.value, out, format: format.value }
+  };
+}
+
+// src/commands/snapshot/buildDeclarativeSnapshot.ts
+var SNAPSHOT_SCHEMA_VERSION = 1;
+var SNAPSHOT_KIND = "maestro.declarative.snapshot";
+function relationId(fromEntity, relation) {
+  return relation.id ?? `${fromEntity}.${relation.toEntity}`;
+}
+function compareStrings(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+function buildDeclarativeSnapshot(config, source) {
+  const entities = [...config.entities].sort((a, b) => compareStrings(a.entity, b.entity)).map((entity) => canonicalizeEntity(entity));
+  const consumers = [...config.consumers ?? []].sort(
+    (a, b) => compareStrings(a.consumer, b.consumer)
+  );
+  const relations = entities.flatMap(
+    (entity) => (entity.relationships ?? []).map(
+      (relation) => ({ fromEntity: entity.entity, ...relation })
+    )
+  ).sort((a, b) => {
+    const byId = compareStrings(relationId(a.fromEntity, a), relationId(b.fromEntity, b));
+    return byId !== 0 ? byId : compareStrings(a.fromEntity, b.fromEntity);
+  });
+  return {
+    schemaVersion: SNAPSHOT_SCHEMA_VERSION,
+    kind: SNAPSHOT_KIND,
+    source,
+    summary: {
+      entities: entities.length,
+      consumers: consumers.length,
+      relations: relations.length
+    },
+    declarations: { entities, consumers, relations }
+  };
+}
+function canonicalizeEntity(entity) {
+  if (!entity.relationships || entity.relationships.length === 0) return entity;
+  const relationships = [...entity.relationships].sort(
+    (a, b) => compareStrings(relationId(entity.entity, a), relationId(entity.entity, b))
+  );
+  return { ...entity, relationships };
+}
+function sortKeys(value) {
+  if (Array.isArray(value)) return value.map(sortKeys);
+  if (value !== null && typeof value === "object") {
+    const sorted = {};
+    for (const key of Object.keys(value).sort()) {
+      sorted[key] = sortKeys(value[key]);
+    }
+    return sorted;
+  }
+  return value;
+}
+function serializeSnapshot(snapshot) {
+  return `${JSON.stringify(sortKeys(snapshot), null, 2)}
+`;
+}
+
+// src/commands/snapshot/SnapshotCommand.ts
+import { readFileSync as readFileSync4, writeFileSync as writeFileSync2 } from "fs";
+import { extname as extname3 } from "path";
+import * as YAML4 from "yaml";
+import {
+  loadDeclarativeConfigFromString as loadDeclarativeConfigFromString3
+} from "@maykonpaulo/maestro-core";
+var defaultDeps4 = {
+  readFile: (path) => readFileSync4(path, "utf-8"),
+  writeFile: (path, content) => writeFileSync2(path, content, "utf-8")
+};
+function errorMessage4(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+var SNAPSHOT_HELP_TEXT = `maestro snapshot \u2014 Produce a canonical, deterministic snapshot of a declarative config file
+
+Loads a local declarative config file (maestro.config.yaml/.yml/.json) with the core's Declarative
+File Loader, validates it, then emits a canonical JSON snapshot of its declarations. The snapshot is a
+stable, versionable artifact for auditing, PR review and future comparison \u2014 the same (semantically
+equivalent) input always produces byte-identical output.
+
+This command does NOT create a Maestro engine (no createMaestro()), does NOT connect to any database,
+datasource or provider, does NOT execute operations, and does NOT require declared operations to have
+a real implementation. It is a read-only, local, declarative snapshot \u2014 NOT a snapshot of a live
+database or of runtime introspection.
+
+Usage:
+  maestro snapshot --input <path> [--input-format <json|yaml>] [--format json] [--out <path>]
+  maestro snapshot -i <path>
+
+Flags:
+  --input, -i <path>         Required. Path to a local declarative config file (.yaml, .yml or .json).
+  --input-format <json|yaml> Optional. Overrides the format detected from the --input extension.
+  --format json              Optional. Snapshot output format. Only "json" is supported. Default: json.
+  --out <path>               Optional. Write the snapshot to this file instead of stdout.
+
+Accepted input formats:
+  .json          \u2192 parsed as JSON
+  .yaml, .yml    \u2192 parsed as YAML
+  (other)        \u2192 pass --input-format <json|yaml> explicitly
+
+Snapshot format (JSON):
+  {
+    "schemaVersion": 1,
+    "kind": "maestro.declarative.snapshot",
+    "source":   { "path": "<the --input value>", "format": "yaml" },
+    "summary":  { "entities": N, "consumers": N, "relations": N },
+    "declarations": { "entities": [...], "consumers": [...], "relations": [...] }
+  }
+
+What is included:
+  - Every declared entity (fields, capabilities, operations, relationships), consumer and relationship.
+  - A flattened "relations" index of all entity relationships, each tagged with its "fromEntity".
+  - Stable ordering (entities/consumers/relations sorted; object keys sorted) for deterministic output.
+
+What is NOT included:
+  - Timestamps, absolute paths, hashes or any value that varies between runs of the same input.
+  - Operation bindings/handlers, live database or runtime introspection data.
+
+Exit codes:
+  0   The file is valid and the snapshot was produced.
+  1   Usage, file-read, parse, validation or write error.
+
+Examples:
+  maestro snapshot --input ./maestro.config.yaml
+  maestro snapshot -i ./maestro.config.json
+  maestro snapshot --input ./maestro.config.yaml --out ./maestro.snapshot.json
+  maestro snapshot --input ./maestro.config --input-format yaml --out ./maestro.snapshot.json`;
+var yamlParser3 = { parse: (content) => YAML4.parse(content) };
+function resolveFormat3(input, override) {
+  if (override) return { ok: true, format: override };
+  const ext = extname3(input).toLowerCase();
+  if (ext === ".json") return { ok: true, format: "json" };
+  if (ext === ".yaml" || ext === ".yml") return { ok: true, format: "yaml" };
+  return {
+    ok: false,
+    error: `cannot detect format from file extension "${ext || "(none)"}" of '${input}'. Supported: .json, .yaml, .yml. Pass --input-format <json|yaml> to override.`
+  };
+}
+function createSnapshotCommand(deps = defaultDeps4) {
+  return {
+    name: "snapshot",
+    description: "Produce a canonical snapshot of a declarative config file (YAML or JSON)",
+    helpText: SNAPSHOT_HELP_TEXT,
+    run(context) {
+      const parsed = parseSnapshotArgs(context.argv);
+      if (!parsed.ok) {
+        context.stderr(`maestro snapshot: ${parsed.error}`);
+        return 1;
+      }
+      const { input, inputFormat, out } = parsed.value;
+      const resolved = resolveFormat3(input, inputFormat);
+      if (!resolved.ok) {
+        context.stderr(`maestro snapshot: ${resolved.error}`);
+        return 1;
+      }
+      const { format } = resolved;
+      let content;
+      try {
+        content = deps.readFile(input);
+      } catch (error) {
+        context.stderr(`maestro snapshot: could not read input file '${input}': ${errorMessage4(error)}`);
+        return 1;
+      }
+      let config;
+      try {
+        config = loadDeclarativeConfigFromString3(content, {
+          format,
+          yamlParser: format === "yaml" ? yamlParser3 : void 0,
+          source: input
+        });
+      } catch (error) {
+        context.stderr(`maestro snapshot: ${errorMessage4(error)}`);
+        return 1;
+      }
+      const snapshot = buildDeclarativeSnapshot(config, { path: input, format });
+      const output = serializeSnapshot(snapshot);
+      if (out) {
+        try {
+          deps.writeFile(out, output);
+        } catch (error) {
+          context.stderr(`maestro snapshot: could not write output file '${out}': ${errorMessage4(error)}`);
+          return 1;
+        }
+        context.stdout(`Snapshot written: ${out}`);
+        context.stdout(`Entities: ${snapshot.summary.entities}`);
+        context.stdout(`Consumers: ${snapshot.summary.consumers}`);
+        context.stdout(`Relations: ${snapshot.summary.relations}`);
+      } else {
+        context.stdout(output.replace(/\n$/, ""));
+      }
+      return 0;
+    }
+  };
+}
+
+// src/commands/introspect/parseIntrospectArgs.ts
+var ALIASES4 = { i: "input" };
+function parseFlags5(argv) {
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    const isLong = arg.startsWith("--");
+    const isShort = !isLong && arg.startsWith("-") && arg.length > 1;
+    if (!isLong && !isShort) continue;
+    const body = isLong ? arg.slice(2) : arg.slice(1);
+    const eqIndex = body.indexOf("=");
+    if (eqIndex !== -1) {
+      const key2 = body.slice(0, eqIndex);
+      flags[ALIASES4[key2] ?? key2] = body.slice(eqIndex + 1);
+      continue;
+    }
+    const key = ALIASES4[body] ?? body;
+    const next = argv[i + 1];
+    if (next !== void 0 && !next.startsWith("-")) {
+      flags[key] = next;
+      i++;
+    } else {
+      flags[key] = "true";
+    }
+  }
+  return flags;
+}
+function parseIntrospectArgs(argv) {
+  const flags = parseFlags5(argv);
+  const input = flags["input"];
+  if (!input || input === "true") {
+    return { ok: false, error: "Missing required flag --input <path> (or -i <path>)." };
+  }
+  const out = flags["out"] && flags["out"] !== "true" ? flags["out"] : void 0;
+  return { ok: true, value: { input, out } };
+}
+
+// src/commands/introspect/buildIntrospection.ts
+var INTROSPECTION_SCHEMA_VERSION = 1;
+var INTROSPECTION_KIND = "maestro.introspection";
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function nonEmptyString(value) {
+  return typeof value === "string" && value.length > 0;
+}
+function validateEndpoint(endpoint, path) {
+  if (!isObject(endpoint)) return `${path} must be an object with "table" and "field".`;
+  if (!nonEmptyString(endpoint["table"])) return `${path}.table must be a non-empty string.`;
+  if (!nonEmptyString(endpoint["field"])) return `${path}.field must be a non-empty string.`;
+  return void 0;
+}
+function validateIntrospectionResult(value) {
+  if (!isObject(value)) {
+    return { ok: false, error: 'input must be a JSON object with "entities" and "relations" arrays.' };
+  }
+  if (!Array.isArray(value["entities"])) {
+    return { ok: false, error: '"entities" must be an array.' };
+  }
+  if (!Array.isArray(value["relations"])) {
+    return { ok: false, error: '"relations" must be an array.' };
+  }
+  const entities = value["entities"];
+  for (let i = 0; i < entities.length; i++) {
+    const entity = entities[i];
+    if (!isObject(entity)) return { ok: false, error: `entities[${i}] must be an object.` };
+    if (!nonEmptyString(entity["table"])) {
+      return { ok: false, error: `entities[${i}].table must be a non-empty string.` };
+    }
+    if (!Array.isArray(entity["fields"])) {
+      return { ok: false, error: `entities[${i}].fields must be an array.` };
+    }
+    const fields = entity["fields"];
+    for (let j = 0; j < fields.length; j++) {
+      const field = fields[j];
+      const at = `entities[${i}].fields[${j}]`;
+      if (!isObject(field)) return { ok: false, error: `${at} must be an object.` };
+      if (!nonEmptyString(field["name"])) return { ok: false, error: `${at}.name must be a non-empty string.` };
+      if (typeof field["nativeType"] !== "string") return { ok: false, error: `${at}.nativeType must be a string.` };
+      if (typeof field["type"] !== "string") return { ok: false, error: `${at}.type must be a string.` };
+      if (typeof field["nullable"] !== "boolean") return { ok: false, error: `${at}.nullable must be a boolean.` };
+      if (typeof field["isPrimaryKey"] !== "boolean") {
+        return { ok: false, error: `${at}.isPrimaryKey must be a boolean.` };
+      }
+    }
+  }
+  const relations = value["relations"];
+  for (let i = 0; i < relations.length; i++) {
+    const relation = relations[i];
+    const at = `relations[${i}]`;
+    if (!isObject(relation)) return { ok: false, error: `${at} must be an object.` };
+    if (!nonEmptyString(relation["id"])) return { ok: false, error: `${at}.id must be a non-empty string.` };
+    if (typeof relation["type"] !== "string") return { ok: false, error: `${at}.type must be a string.` };
+    const fromError = validateEndpoint(relation["from"], `${at}.from`);
+    if (fromError) return { ok: false, error: fromError };
+    const toError = validateEndpoint(relation["to"], `${at}.to`);
+    if (toError) return { ok: false, error: toError };
+    if (relation["confidence"] !== "definite" && relation["confidence"] !== "inferred") {
+      return { ok: false, error: `${at}.confidence must be "definite" or "inferred".` };
+    }
+  }
+  return { ok: true, value };
+}
+function compareStrings2(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+function canonicalizeResult(result) {
+  const entities = [...result.entities].sort((a, b) => compareStrings2(a.table, b.table));
+  const relations = [...result.relations].sort((a, b) => compareStrings2(a.id, b.id));
+  return { entities, relations };
+}
+function sortKeys2(value) {
+  if (Array.isArray(value)) return value.map(sortKeys2);
+  if (value !== null && typeof value === "object") {
+    const sorted = {};
+    for (const key of Object.keys(value).sort()) {
+      sorted[key] = sortKeys2(value[key]);
+    }
+    return sorted;
+  }
+  return value;
+}
+function buildIntrospectionArtifact(result, source) {
+  const canonical = canonicalizeResult(result);
+  return {
+    schemaVersion: INTROSPECTION_SCHEMA_VERSION,
+    kind: INTROSPECTION_KIND,
+    source,
+    summary: {
+      entities: canonical.entities.length,
+      relations: canonical.relations.length
+    },
+    result: canonical
+  };
+}
+function serializeIntrospection(artifact) {
+  return `${JSON.stringify(sortKeys2(artifact), null, 2)}
+`;
+}
+
+// src/commands/introspect/IntrospectCommand.ts
+import { readFileSync as readFileSync5, writeFileSync as writeFileSync3 } from "fs";
+var defaultDeps5 = {
+  readFile: (path) => readFileSync5(path, "utf-8"),
+  writeFile: (path, content) => writeFileSync3(path, content, "utf-8")
+};
+function errorMessage5(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+var INTROSPECT_HELP_TEXT = `maestro introspect \u2014 Validate and canonicalize a local IntrospectionResult (offline)
+
+Reads a local JSON file describing an IntrospectionResult (the core's introspection contract:
+{ "entities": [...], "relations": [...] }), validates it against that contract, and emits a canonical,
+deterministic JSON artifact. The same (semantically equivalent) input always produces byte-identical
+output, so the artifact is a stable, versionable input for future comparison, generation or review.
+
+OFFLINE / LOCAL ONLY \u2014 this is NOT a database connector (yet). It does NOT connect to PostgreSQL,
+MySQL, MongoDB or any database, does NOT read a connection string or .env, does NOT load an ORM/driver,
+and does NOT execute any query. It operates only on the local JSON file you pass with --input, which is
+an intermediate/offline representation of an introspection \u2014 not a live schema read. Connecting to real
+datasources is a separate, not-yet-implemented step.
+
+This command does NOT create a Maestro engine (no createMaestro()), does NOT execute operations, and
+does NOT require declared operations to have an implementation. It never modifies the input file.
+
+Usage:
+  maestro introspect --input <path> [--out <path>]
+  maestro introspect -i <path>
+
+Flags:
+  --input, -i <path>   Required. Path to a local IntrospectionResult JSON file.
+  --out <path>         Optional. Write the canonical artifact to this file instead of stdout.
+
+Input format (JSON \u2014 the core's IntrospectionResult contract):
+  {
+    "entities": [
+      {
+        "table": "users",
+        "fields": [
+          { "name": "id", "nativeType": "uuid", "type": "uuid", "nullable": false, "isPrimaryKey": true }
+        ]
+      }
+    ],
+    "relations": [
+      {
+        "id": "orders.user_id->users.id",
+        "type": "many-to-one",
+        "from": { "table": "orders", "field": "user_id" },
+        "to":   { "table": "users",  "field": "id" },
+        "confidence": "definite"
+      }
+    ]
+  }
+
+Output format (JSON):
+  {
+    "schemaVersion": 1,
+    "kind": "maestro.introspection",
+    "source":  { "path": "<the --input value>" },
+    "summary": { "entities": N, "relations": N },
+    "result":  { "entities": [...], "relations": [...] }
+  }
+
+Determinism:
+  Entities are sorted by table, relations by id, and every object key is sorted. No timestamps,
+  absolute paths or hashes are ever included.
+
+Difference from other commands:
+  - introspect: validates/canonicalizes an IntrospectionResult (real DB-schema contract), offline.
+  - snapshot:   canonicalizes a declarative config file (maestro.config.yaml/json).
+  - diff:        compares two declarative config files.
+
+Exit codes:
+  0   The input is a valid IntrospectionResult and the artifact was produced.
+  1   Usage, file-read, parse, validation or write error.
+
+Examples:
+  maestro introspect --input ./introspection.json
+  maestro introspect -i ./introspection.json
+  maestro introspect --input ./introspection.json --out ./maestro.introspection.json`;
+function createIntrospectCommand(deps = defaultDeps5) {
+  return {
+    name: "introspect",
+    description: "Validate and canonicalize a local IntrospectionResult JSON file (offline)",
+    helpText: INTROSPECT_HELP_TEXT,
+    run(context) {
+      const parsed = parseIntrospectArgs(context.argv);
+      if (!parsed.ok) {
+        context.stderr(`maestro introspect: ${parsed.error}`);
+        return 1;
+      }
+      const { input, out } = parsed.value;
+      let content;
+      try {
+        content = deps.readFile(input);
+      } catch (error) {
+        context.stderr(`maestro introspect: could not read input file '${input}': ${errorMessage5(error)}`);
+        return 1;
+      }
+      let raw;
+      try {
+        raw = JSON.parse(content);
+      } catch (error) {
+        context.stderr(`maestro introspect: invalid JSON in '${input}': ${errorMessage5(error)}`);
+        return 1;
+      }
+      const validated = validateIntrospectionResult(raw);
+      if (!validated.ok) {
+        context.stderr(`maestro introspect: ${validated.error}`);
+        return 1;
+      }
+      const artifact = buildIntrospectionArtifact(validated.value, { path: input });
+      const output = serializeIntrospection(artifact);
+      if (out) {
+        try {
+          deps.writeFile(out, output);
+        } catch (error) {
+          context.stderr(`maestro introspect: could not write output file '${out}': ${errorMessage5(error)}`);
+          return 1;
+        }
+        context.stdout(`Introspection written: ${out}`);
+        context.stdout(`Entities: ${artifact.summary.entities}`);
+        context.stdout(`Relations: ${artifact.summary.relations}`);
+      } else {
+        context.stdout(output.replace(/\n$/, ""));
+      }
+      return 0;
+    }
+  };
+}
+
+// src/runCli.ts
+var defaultRegistry = new CommandRegistry();
+defaultRegistry.register(createGenerateCommand());
+defaultRegistry.register(createValidateCommand());
+defaultRegistry.register(createDiffCommand());
+defaultRegistry.register(createSnapshotCommand());
+defaultRegistry.register(createIntrospectCommand());
+async function runCli(options) {
+  const stdout = options.stdout ?? ((message) => console.log(message));
+  const stderr = options.stderr ?? ((message) => console.error(message));
+  const registry = options.registry ?? defaultRegistry;
+  const parsed = parseArgs(options.argv);
+  if (parsed.version) {
+    stdout(getCliVersion());
+    return 0;
+  }
+  const command = parsed.command ? registry.get(parsed.command) : void 0;
+  if (parsed.help) {
+    stdout(command?.helpText ?? formatHelp(registry));
+    return 0;
+  }
+  if (!parsed.command) {
+    stdout(formatHelp(registry));
+    return 0;
+  }
+  if (!command) {
+    stderr(`Unknown command '${parsed.command}'. Run "maestro --help" to see available commands.`);
+    return 1;
+  }
+  return command.run({ argv: parsed.args, stdout, stderr });
+}
+
+export {
+  CommandRegistry,
+  PLANNED_COMMANDS,
+  parseArgs,
+  formatHelp,
+  getCliVersion,
+  parseGenerateArgs,
+  createGenerateCommand,
+  parseValidateArgs,
+  createValidateCommand,
+  parseDiffArgs,
+  diffDeclarativeConfigs,
+  formatDeclarativeDiff,
+  createDiffCommand,
+  parseSnapshotArgs,
+  SNAPSHOT_SCHEMA_VERSION,
+  SNAPSHOT_KIND,
+  buildDeclarativeSnapshot,
+  serializeSnapshot,
+  createSnapshotCommand,
+  parseIntrospectArgs,
+  INTROSPECTION_SCHEMA_VERSION,
+  INTROSPECTION_KIND,
+  validateIntrospectionResult,
+  buildIntrospectionArtifact,
+  serializeIntrospection,
+  createIntrospectCommand,
+  defaultRegistry,
+  runCli
+};
+//# sourceMappingURL=chunk-CSDLIL7L.js.map