graphddb 0.1.0

package/dist/cli.js

@@ -0,0 +1,890 @@
+#!/usr/bin/env node
+import {
+  buildBridgeBundle,
+  normalizeSelectSpec
+} from "./chunk-6LEHSX45.js";
+import {
+  MetadataRegistry
+} from "./chunk-347U24SB.js";
+
+// src/generated/program.ts
+import { Command } from "commander";
+
+// src/generated/policy-runtime.ts
+var RISK_ORDER = {
+  low: 0,
+  medium: 1,
+  high: 2,
+  critical: 3
+};
+function maxRiskLevel(...levels) {
+  let max = "low";
+  for (const level of levels) {
+    if (RISK_ORDER[level] > RISK_ORDER[max]) {
+      max = level;
+    }
+  }
+  return max;
+}
+function isOptionActive(definition, value, specified) {
+  const schemaType = definition.schema?.type;
+  if (schemaType === "boolean") {
+    return value === true;
+  }
+  if (definition.repeatable) {
+    return specified && Array.isArray(value) && value.length > 0;
+  }
+  return specified && value != null;
+}
+function derivePolicy(input) {
+  const sideEffects = /* @__PURE__ */ new Set();
+  const reads = [];
+  const writes = [];
+  const networkEffects = [];
+  const riskLevels = [];
+  let executionMode;
+  let explicitConfirmation;
+  if (input.command_effects) {
+    const ce = input.command_effects;
+    riskLevels.push(ce.risk_level ?? "low");
+    if (ce.writes) {
+      sideEffects.add("file_write");
+      for (const w of ce.writes) {
+        writes.push({
+          kind: "semantic",
+          target: w.target,
+          description: w.description,
+          overwrite: w.overwrite,
+          destructive: w.destructive,
+          ...w.idempotent !== void 0 ? { idempotent: w.idempotent } : {},
+          ...w.idempotency_key ? { idempotency_key: w.idempotency_key } : {},
+          ...w.idempotent_note ? { idempotent_note: w.idempotent_note } : {},
+          source: `command:${input.command_id}`
+        });
+      }
+    }
+    if (ce.reads) {
+      for (const r of ce.reads) {
+        reads.push({
+          kind: "semantic",
+          target: r.target,
+          description: r.description,
+          source: `command:${input.command_id}`
+        });
+      }
+    }
+    if (ce.network) {
+      sideEffects.add("network");
+      if (typeof ce.network === "object") {
+        networkEffects.push({
+          ...ce.network.description ? { description: ce.network.description } : {},
+          ...ce.network.domains ? { domains: ce.network.domains } : {},
+          ...ce.network.idempotent !== void 0 ? { idempotent: ce.network.idempotent } : {},
+          ...ce.network.idempotency_key ? { idempotency_key: ce.network.idempotency_key } : {},
+          ...ce.network.idempotent_note ? { idempotent_note: ce.network.idempotent_note } : {},
+          source: `command:${input.command_id}`
+        });
+      }
+    }
+    if (ce.execution_mode) {
+      executionMode = ce.execution_mode;
+    }
+    if (ce.requires_confirmation !== void 0) {
+      explicitConfirmation = ce.requires_confirmation;
+    }
+  }
+  for (const [optName, optInput] of Object.entries(input.options)) {
+    const { definition, value, specified } = optInput;
+    const active = isOptionActive(definition, value, specified);
+    if (!active) continue;
+    if (definition.file) {
+      const filePath = typeof value === "string" ? value : void 0;
+      const mode = definition.file.mode;
+      if (mode === "read" || mode === "readWrite") {
+        reads.push({
+          kind: "option-file",
+          option: optName,
+          path: filePath,
+          source: `option:${optName}`
+        });
+      }
+      if (mode === "write" || mode === "append" || mode === "readWrite") {
+        sideEffects.add("file_write");
+        writes.push({
+          kind: "option-file",
+          option: optName,
+          path: filePath,
+          mode,
+          source: `option:${optName}`
+        });
+      }
+    }
+    if (definition.effects) {
+      const eff = definition.effects;
+      riskLevels.push(eff.risk_level ?? "low");
+      if (eff.writes) {
+        sideEffects.add("file_write");
+        for (const w of eff.writes) {
+          writes.push({
+            kind: "semantic",
+            target: w.target,
+            description: w.description,
+            overwrite: w.overwrite,
+            destructive: w.destructive,
+            ...w.idempotent !== void 0 ? { idempotent: w.idempotent } : {},
+            ...w.idempotency_key ? { idempotency_key: w.idempotency_key } : {},
+            ...w.idempotent_note ? { idempotent_note: w.idempotent_note } : {},
+            source: `option:${optName}`
+          });
+        }
+      }
+      if (eff.reads) {
+        for (const r of eff.reads) {
+          reads.push({
+            kind: "semantic",
+            target: r.target,
+            description: r.description,
+            source: `option:${optName}`
+          });
+        }
+      }
+      if (eff.network) {
+        sideEffects.add("network");
+        if (typeof eff.network === "object") {
+          networkEffects.push({
+            ...eff.network.description ? { description: eff.network.description } : {},
+            ...eff.network.domains ? { domains: eff.network.domains } : {},
+            ...eff.network.idempotent !== void 0 ? { idempotent: eff.network.idempotent } : {},
+            ...eff.network.idempotency_key ? { idempotency_key: eff.network.idempotency_key } : {},
+            ...eff.network.idempotent_note ? { idempotent_note: eff.network.idempotent_note } : {},
+            source: `option:${optName}`
+          });
+        }
+      }
+      if (eff.execution_mode && !executionMode) {
+        executionMode = eff.execution_mode;
+      }
+      if (eff.requires_confirmation !== void 0 && explicitConfirmation === void 0) {
+        explicitConfirmation = eff.requires_confirmation;
+      }
+    }
+  }
+  const finalRiskLevel = riskLevels.length > 0 ? maxRiskLevel(...riskLevels) : "low";
+  const requiresConfirmation = explicitConfirmation ?? (finalRiskLevel === "high" || finalRiskLevel === "critical");
+  let requiresSecrets;
+  if (input.env) {
+    const secrets = [];
+    for (const [envName, envVar] of Object.entries(input.env)) {
+      if (envVar.sensitive) {
+        secrets.push(envName);
+      }
+    }
+    if (secrets.length > 0) {
+      requiresSecrets = secrets;
+    }
+  }
+  const semanticWrites = writes.filter((w) => w.kind === "semantic");
+  const idempotent = semanticWrites.every((w) => w.idempotent === true) && networkEffects.every((n) => n.idempotent === true);
+  return {
+    risk_level: finalRiskLevel,
+    requires_confirmation: requiresConfirmation,
+    idempotent,
+    side_effects: [...sideEffects],
+    reads,
+    writes,
+    ...networkEffects.length > 0 ? { network: networkEffects } : {},
+    ...executionMode ? { execution_mode: executionMode } : {},
+    ...requiresSecrets ? { requires_secrets: requiresSecrets } : {}
+  };
+}
+
+// src/generated/policy.ts
+var commandDefinitions = {
+  "generate.python": {
+    "effects": {
+      "risk_level": "low",
+      "reads": [
+        "ts-definitions"
+      ],
+      "writes": [
+        "generated-code"
+      ]
+    },
+    "options": [
+      {
+        "name": "entry",
+        "schema": {
+          "type": "string"
+        },
+        "file": {
+          "mode": "read",
+          "exists": true,
+          "media_type": "application/typescript",
+          "encoding": "utf-8"
+        }
+      },
+      {
+        "name": "queries",
+        "schema": {
+          "type": "string"
+        },
+        "file": {
+          "mode": "read",
+          "exists": true,
+          "media_type": "application/typescript",
+          "encoding": "utf-8"
+        }
+      },
+      {
+        "name": "commands",
+        "schema": {
+          "type": "string"
+        },
+        "file": {
+          "mode": "read",
+          "exists": true,
+          "media_type": "application/typescript",
+          "encoding": "utf-8"
+        }
+      },
+      {
+        "name": "transactions",
+        "schema": {
+          "type": "string"
+        },
+        "file": {
+          "mode": "read",
+          "exists": true,
+          "media_type": "application/typescript",
+          "encoding": "utf-8"
+        }
+      },
+      {
+        "name": "contracts",
+        "schema": {
+          "type": "string"
+        },
+        "file": {
+          "mode": "read",
+          "exists": true,
+          "media_type": "application/typescript",
+          "encoding": "utf-8"
+        }
+      },
+      {
+        "name": "contexts",
+        "schema": {
+          "type": "string"
+        },
+        "file": {
+          "mode": "read",
+          "exists": true,
+          "media_type": "application/typescript",
+          "encoding": "utf-8"
+        }
+      },
+      {
+        "name": "dataclass",
+        "schema": {
+          "type": "boolean"
+        }
+      },
+      {
+        "name": "out",
+        "schema": {
+          "type": "string"
+        }
+      }
+    ]
+  }
+};
+function deriveCommandPolicy(command_id, optionValues) {
+  const def = commandDefinitions[command_id];
+  if (!def) throw new Error(`Unknown command: ${command_id}`);
+  const cmdDef = def;
+  const options = {};
+  const active_options = [];
+  for (const optDef of cmdDef.options ?? []) {
+    const value = optionValues[optDef.name];
+    const specified = optDef.name in optionValues && value !== void 0;
+    options[optDef.name] = { value, specified, definition: optDef };
+    if (isOptionActive(optDef, value, specified)) {
+      active_options.push(optDef.name);
+    }
+  }
+  const policy = derivePolicy({
+    command_id,
+    command_effects: cmdDef.effects,
+    options,
+    env: cmdDef.env
+  });
+  return { command: command_id, active_options, policy };
+}
+
+// src/generated/contract.ts
+var CONTRACT_YAML = "cli_contracts: 0.1.0\n\ninfo:\n  title: GraphDDB CLI\n  version: 0.1.0\n  description: >-\n    Contract for the graphddb code-generation CLI. The CLI reads TypeScript\n    GraphDDB model / query / command definitions (the single source of truth)\n    and emits Python bindings (manifest.json, operations.json, types.py,\n    repositories.py, __init__.py) for the Python bridge runtime.\n  license:\n    name: MIT\n  contact:\n    name: foo-log-inc\n    url: https://github.com/foo-log-inc/graphddb\n\nartifact_slots:\n  ts-definitions:\n    description: >-\n      TypeScript GraphDDB definition modules (entity models, defineQueries,\n      defineCommands) used as the single source of truth.\n    direction: read\n  generated-code:\n    description: >-\n      Generated Python bindings and JSON specs written to the output directory\n      (manifest.json, operations.json, types.py, repositories.py, __init__.py).\n    direction: write\n\ncommand_sets:\n  graphddb:\n    summary: Graph data modeling on DynamoDB \u2014 code generation CLI.\n    x-stdin: >-\n      No command reads from stdin. All inputs are provided via file options.\n\n    commands:\n      # \u2500\u2500 generate python \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n      generate.python:\n        summary: Generate Python bindings from TypeScript GraphDDB definitions.\n        description: >-\n          Loads the TypeScript entity models, query definitions, and command\n          definitions, builds the serializable manifest / operations bundle, and\n          writes the Python bridge bindings (manifest.json, operations.json,\n          types.py, repositories.py, __init__.py) to the output directory.\n          Output is deterministic for a given set of inputs.\n        usage:\n          - graphddb generate python --entry models.ts --queries queries.ts --commands commands.ts --out generated/\n          - graphddb generate python --entry definitions.ts --out generated/\n\n        effects:\n          risk_level: low\n          reads:\n            - ts-definitions\n          writes:\n            - generated-code\n\n        x-agent:\n          recommended_before_use:\n            - \"Ensure the TypeScript definitions type-check and lint cleanly.\"\n\n        options:\n          - name: entry\n            aliases: [e]\n            required: true\n            description: >-\n              Entry module that registers the entity models (side-effecting\n              import). May also export queries / commands.\n            value_name: file\n            schema:\n              type: string\n            file:\n              mode: read\n              exists: true\n              media_type: application/typescript\n              encoding: utf-8\n\n          - name: queries\n            aliases: [q]\n            description: >-\n              Module exporting `queries` (a defineQueries map). Defaults to the\n              entry module when omitted.\n            value_name: file\n            schema:\n              type: string\n            file:\n              mode: read\n              exists: true\n              media_type: application/typescript\n              encoding: utf-8\n\n          - name: commands\n            aliases: [c]\n            description: >-\n              Module exporting `commands` (a defineCommands map). Defaults to the\n              entry module when omitted.\n            value_name: file\n            schema:\n              type: string\n            file:\n              mode: read\n              exists: true\n              media_type: application/typescript\n              encoding: utf-8\n\n          - name: transactions\n            aliases: [t]\n            description: >-\n              Module exporting `transactions` (a defineTransactions map).\n              Defaults to the commands module (or the entry module) when omitted.\n              Optional \u2014 a project with no declarative transactions omits it.\n            value_name: file\n            schema:\n              type: string\n            file:\n              mode: read\n              exists: true\n              media_type: application/typescript\n              encoding: utf-8\n\n          - name: contracts\n            description: >-\n              Module exporting `contracts` (a map of publicQueryModel /\n              publicCommandModel results \u2014 the CQRS Contract layer). Defaults to\n              the entry module when omitted. Optional \u2014 a project with no\n              contracts omits it, and the output gains no `contracts` content.\n            value_name: file\n            schema:\n              type: string\n            file:\n              mode: read\n              exists: true\n              media_type: application/typescript\n              encoding: utf-8\n\n          - name: contexts\n            description: >-\n              Module exporting `contexts` (context-ownership: context name \u2192 the\n              Model / Contract names that belong to it). Defaults to the\n              contracts module (or the entry module) when omitted. Optional \u2014\n              consumed by the boundary lint to tell own from foreign.\n            value_name: file\n            schema:\n              type: string\n            file:\n              mode: read\n              exists: true\n              media_type: application/typescript\n              encoding: utf-8\n\n          - name: dataclass\n            description: >-\n              Emit Python result / element types as @dataclass classes instead\n              of TypedDict (decimal / Optional / Connection mapped accordingly).\n            schema:\n              type: boolean\n\n          - name: out\n            aliases: [o]\n            required: true\n            description: Output directory for the generated Python bindings.\n            value_name: dir\n            schema:\n              type: string\n\n        exits:\n          '0':\n            description: Generation succeeded.\n            stdout:\n              format: json\n              schema:\n                $ref: '#/components/schemas/GenerateResult'\n            files:\n              - path: '{options.out}/manifest.json'\n                required: true\n                media_type: application/json\n                description: Entity / table / key / relation metadata.\n              - path: '{options.out}/operations.json'\n                required: true\n                media_type: application/json\n                description: Per-query / per-command execution specs.\n              - path: '{options.out}/types.py'\n                required: true\n                media_type: text/x-python\n                description: TypedDict result types derived from query selects.\n              - path: '{options.out}/repositories.py'\n                required: true\n                media_type: text/x-python\n                description: Per-entity repository classes (sync methods).\n              - path: '{options.out}/__init__.py'\n                required: true\n                media_type: text/x-python\n                description: Package re-exports for the generated bindings.\n\n          '1':\n            description: Unexpected error.\n            stderr:\n              format: json\n              schema:\n                $ref: '#/components/schemas/Error'\n\n          '2':\n            description: Invalid arguments (missing/unreadable input or output).\n            stderr:\n              format: json\n              schema:\n                $ref: '#/components/schemas/Error'\n\ncomponents:\n  schemas:\n    GenerateResult:\n      type: object\n      required: [status, outDir, files]\n      properties:\n        status:\n          type: string\n          enum: [ok]\n        outDir:\n          type: string\n          description: Output directory the files were written to.\n        files:\n          type: array\n          description: Paths of the generated files (relative to outDir).\n          items:\n            type: string\n    Error:\n      type: object\n      required: [code, message]\n      properties:\n        code:\n          type: string\n        message:\n          type: string\n";
+var CONTRACT_JSON_STR = '{\n  "cli_contracts": "0.1.0",\n  "info": {\n    "title": "GraphDDB CLI",\n    "version": "0.1.0",\n    "description": "Contract for the graphddb code-generation CLI. The CLI reads TypeScript GraphDDB model / query / command definitions (the single source of truth) and emits Python bindings (manifest.json, operations.json, types.py, repositories.py, __init__.py) for the Python bridge runtime.",\n    "license": {\n      "name": "MIT"\n    },\n    "contact": {\n      "name": "foo-log-inc",\n      "url": "https://github.com/foo-log-inc/graphddb"\n    }\n  },\n  "artifact_slots": {\n    "ts-definitions": {\n      "description": "TypeScript GraphDDB definition modules (entity models, defineQueries, defineCommands) used as the single source of truth.",\n      "direction": "read"\n    },\n    "generated-code": {\n      "description": "Generated Python bindings and JSON specs written to the output directory (manifest.json, operations.json, types.py, repositories.py, __init__.py).",\n      "direction": "write"\n    }\n  },\n  "command_sets": {\n    "graphddb": {\n      "summary": "Graph data modeling on DynamoDB \u2014 code generation CLI.",\n      "x-stdin": "No command reads from stdin. All inputs are provided via file options.",\n      "commands": {\n        "generate.python": {\n          "summary": "Generate Python bindings from TypeScript GraphDDB definitions.",\n          "description": "Loads the TypeScript entity models, query definitions, and command definitions, builds the serializable manifest / operations bundle, and writes the Python bridge bindings (manifest.json, operations.json, types.py, repositories.py, __init__.py) to the output directory. Output is deterministic for a given set of inputs.",\n          "usage": [\n            "graphddb generate python --entry models.ts --queries queries.ts --commands commands.ts --out generated/",\n            "graphddb generate python --entry definitions.ts --out generated/"\n          ],\n          "effects": {\n            "risk_level": "low",\n            "reads": [\n              "ts-definitions"\n            ],\n            "writes": [\n              "generated-code"\n            ]\n          },\n          "x-agent": {\n            "recommended_before_use": [\n              "Ensure the TypeScript definitions type-check and lint cleanly."\n            ]\n          },\n          "options": [\n            {\n              "name": "entry",\n              "aliases": [\n                "e"\n              ],\n              "required": true,\n              "description": "Entry module that registers the entity models (side-effecting import). May also export queries / commands.",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              },\n              "file": {\n                "mode": "read",\n                "exists": true,\n                "media_type": "application/typescript",\n                "encoding": "utf-8"\n              }\n            },\n            {\n              "name": "queries",\n              "aliases": [\n                "q"\n              ],\n              "description": "Module exporting `queries` (a defineQueries map). Defaults to the entry module when omitted.",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              },\n              "file": {\n                "mode": "read",\n                "exists": true,\n                "media_type": "application/typescript",\n                "encoding": "utf-8"\n              }\n            },\n            {\n              "name": "commands",\n              "aliases": [\n                "c"\n              ],\n              "description": "Module exporting `commands` (a defineCommands map). Defaults to the entry module when omitted.",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              },\n              "file": {\n                "mode": "read",\n                "exists": true,\n                "media_type": "application/typescript",\n                "encoding": "utf-8"\n              }\n            },\n            {\n              "name": "transactions",\n              "aliases": [\n                "t"\n              ],\n              "description": "Module exporting `transactions` (a defineTransactions map). Defaults to the commands module (or the entry module) when omitted. Optional \u2014 a project with no declarative transactions omits it.",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              },\n              "file": {\n                "mode": "read",\n                "exists": true,\n                "media_type": "application/typescript",\n                "encoding": "utf-8"\n              }\n            },\n            {\n              "name": "contracts",\n              "description": "Module exporting `contracts` (a map of publicQueryModel / publicCommandModel results \u2014 the CQRS Contract layer). Defaults to the entry module when omitted. Optional \u2014 a project with no contracts omits it, and the output gains no `contracts` content.",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              },\n              "file": {\n                "mode": "read",\n                "exists": true,\n                "media_type": "application/typescript",\n                "encoding": "utf-8"\n              }\n            },\n            {\n              "name": "contexts",\n              "description": "Module exporting `contexts` (context-ownership: context name \u2192 the Model / Contract names that belong to it). Defaults to the contracts module (or the entry module) when omitted. Optional \u2014 consumed by the boundary lint to tell own from foreign.",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              },\n              "file": {\n                "mode": "read",\n                "exists": true,\n                "media_type": "application/typescript",\n                "encoding": "utf-8"\n              }\n            },\n            {\n              "name": "dataclass",\n              "description": "Emit Python result / element types as @dataclass classes instead of TypedDict (decimal / Optional / Connection mapped accordingly).",\n              "schema": {\n                "type": "boolean"\n              }\n            },\n            {\n              "name": "out",\n              "aliases": [\n                "o"\n              ],\n              "required": true,\n              "description": "Output directory for the generated Python bindings.",\n              "value_name": "dir",\n              "schema": {\n                "type": "string"\n              }\n            }\n          ],\n          "exits": {\n            "0": {\n              "description": "Generation succeeded.",\n              "stdout": {\n                "format": "json",\n                "schema": {\n                  "$ref": "#/components/schemas/GenerateResult"\n                }\n              },\n              "files": [\n                {\n                  "path": "{options.out}/manifest.json",\n                  "required": true,\n                  "media_type": "application/json",\n                  "description": "Entity / table / key / relation metadata."\n                },\n                {\n                  "path": "{options.out}/operations.json",\n                  "required": true,\n                  "media_type": "application/json",\n                  "description": "Per-query / per-command execution specs."\n                },\n                {\n                  "path": "{options.out}/types.py",\n                  "required": true,\n                  "media_type": "text/x-python",\n                  "description": "TypedDict result types derived from query selects."\n                },\n                {\n                  "path": "{options.out}/repositories.py",\n                  "required": true,\n                  "media_type": "text/x-python",\n                  "description": "Per-entity repository classes (sync methods)."\n                },\n                {\n                  "path": "{options.out}/__init__.py",\n                  "required": true,\n                  "media_type": "text/x-python",\n                  "description": "Package re-exports for the generated bindings."\n                }\n              ]\n            },\n            "1": {\n              "description": "Unexpected error.",\n              "stderr": {\n                "format": "json",\n                "schema": {\n                  "$ref": "#/components/schemas/Error"\n                }\n              }\n            },\n            "2": {\n              "description": "Invalid arguments (missing/unreadable input or output).",\n              "stderr": {\n                "format": "json",\n                "schema": {\n                  "$ref": "#/components/schemas/Error"\n                }\n              }\n            }\n          }\n        }\n      }\n    }\n  },\n  "components": {\n    "schemas": {\n      "GenerateResult": {\n        "type": "object",\n        "required": [\n          "status",\n          "outDir",\n          "files"\n        ],\n        "properties": {\n          "status": {\n            "type": "string",\n            "enum": [\n              "ok"\n            ]\n          },\n          "outDir": {\n            "type": "string",\n            "description": "Output directory the files were written to."\n          },\n          "files": {\n            "type": "array",\n            "description": "Paths of the generated files (relative to outDir).",\n            "items": {\n              "type": "string"\n            }\n          }\n        }\n      },\n      "Error": {\n        "type": "object",\n        "required": [\n          "code",\n          "message"\n        ],\n        "properties": {\n          "code": {\n            "type": "string"\n          },\n          "message": {\n            "type": "string"\n          }\n        }\n      }\n    }\n  }\n}';
+
+// src/generated/program.ts
+function createProgram(handlers2, version) {
+  const program = new Command();
+  program.name("graphddb").version(version, "-V, --version").description("Graph data modeling on DynamoDB \u2014 code generation CLI.");
+  program.option("--introspect", "Output derived policy as JSON without executing the command");
+  const __cmd_generate = program.command("generate");
+  __cmd_generate.command("python").description("Generate Python bindings from TypeScript GraphDDB definitions.").option("-e, --entry <file>", "Entry module that registers the entity models (side-effecting import). May also export queries / commands.").option("-q, --queries <file>", "Module exporting `queries` (a defineQueries map). Defaults to the entry module when omitted.").option("-c, --commands <file>", "Module exporting `commands` (a defineCommands map). Defaults to the entry module when omitted.").option("-t, --transactions <file>", "Module exporting `transactions` (a defineTransactions map). Defaults to the commands module (or the entry module) when omitted. Optional \u2014 a project with no declarative transactions omits it.").option("--contracts <file>", "Module exporting `contracts` (a map of publicQueryModel / publicCommandModel results \u2014 the CQRS Contract layer). Defaults to the entry module when omitted. Optional \u2014 a project with no contracts omits it, and the output gains no `contracts` content.").option("--contexts <file>", "Module exporting `contexts` (context-ownership: context name \u2192 the Model / Contract names that belong to it). Defaults to the contracts module (or the entry module) when omitted. Optional \u2014 consumed by the boundary lint to tell own from foreign.").option("--dataclass", "Emit Python result / element types as @dataclass classes instead of TypedDict (decimal / Optional / Connection mapped accordingly).").option("-o, --out <dir>", "Output directory for the generated Python bindings.").action(async (opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    if (globalOpts.introspect) {
+      const policy = deriveCommandPolicy("generate.python", opts);
+      console.log(JSON.stringify(policy, null, 2));
+      return;
+    }
+    await handlers2.generatePython(opts, globalOpts);
+  });
+  program.command("extract").description("Extract contract specification for this CLI tool.").argument("[commands...]", "Command IDs to extract. Use dot notation.").option("-a, --all", "Extract all commands.", false).option("--include-meta", "Include extraction metadata.", true).option("-F, --format <format>", "Output format (yaml or json).", "yaml").action(async (commands, opts, cmd) => {
+    if (commands.length === 0 && !opts.all) {
+      process.stderr.write(JSON.stringify({ code: "INVALID_ARGS", message: "Specify command IDs or use --all" }) + "\n");
+      process.exit(2);
+    }
+    const format = opts.format || "yaml";
+    const doc = JSON.parse(CONTRACT_JSON_STR);
+    const cmdIds = opts.all ? [] : commands;
+    if (cmdIds.length === 0) {
+      if (format === "json") {
+        const out = {};
+        if (opts.includeMeta) {
+          out._meta = {
+            source: "embedded",
+            type: "cli-contracts/extract",
+            extractedAt: (/* @__PURE__ */ new Date()).toISOString(),
+            specVersion: doc.cli_contracts ?? "0.1.0",
+            commands: ["graphddb.generate.python"]
+          };
+        }
+        Object.assign(out, doc);
+        process.stdout.write(JSON.stringify(out, null, 2) + "\n");
+      } else {
+        const yamlLines = [];
+        yamlLines.push("# graphddb extract");
+        yamlLines.push("# source: embedded");
+        yamlLines.push("# type: cli-contracts/command-extract");
+        if (opts.includeMeta) {
+          yamlLines.push("---");
+          yamlLines.push("source: embedded");
+          yamlLines.push("type: cli-contracts/command-extract");
+          yamlLines.push("extractedAt: " + (/* @__PURE__ */ new Date()).toISOString());
+          yamlLines.push("spec_version: " + (doc.cli_contracts ?? "0.1.0"));
+          yamlLines.push("commands:");
+          for (const id of ["graphddb.generate.python"]) {
+            yamlLines.push("  - " + id);
+          }
+        }
+        yamlLines.push("---");
+        yamlLines.push(CONTRACT_YAML);
+        process.stdout.write(yamlLines.join("\n") + "\n");
+      }
+    } else {
+      const filtered = {
+        cli_contracts: doc.cli_contracts,
+        info: doc.info,
+        command_sets: {}
+      };
+      const fcs = filtered.command_sets;
+      for (const [setId, cs] of Object.entries(doc.command_sets ?? {})) {
+        const cmds = cs.commands;
+        if (!cmds) continue;
+        const matched = {};
+        for (const [cmdId, cmdDef] of Object.entries(cmds)) {
+          const fullId = setId + "." + cmdId;
+          if (cmdIds.some((id) => id === cmdId || id === fullId || cmdId.startsWith(id + "."))) {
+            matched[cmdId] = cmdDef;
+          }
+        }
+        if (Object.keys(matched).length > 0) {
+          const setCopy = { ...cs };
+          setCopy.commands = matched;
+          fcs[setId] = setCopy;
+        }
+      }
+      if (doc.components) filtered.components = doc.components;
+      process.stdout.write(JSON.stringify(filtered, null, 2) + "\n");
+    }
+    process.exit(0);
+  });
+  return program;
+}
+
+// src/cli/handlers.ts
+import { mkdirSync, writeFileSync } from "fs";
+import { pathToFileURL } from "url";
+import { isAbsolute, resolve } from "path";
+
+// src/codegen/python.ts
+var PY_HEADER = "# DO NOT EDIT. Generated by GraphDDB.";
+function toPascalCase(name) {
+  return name.replace(/[_-]+/g, " ").replace(/([a-z0-9])([A-Z])/g, "$1 $2").split(/\s+/).filter(Boolean).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join("");
+}
+function toSnakeCase(name) {
+  return name.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/[-\s.]+/g, "_").toLowerCase();
+}
+function entityBaseName(entity) {
+  return entity.replace(/Model$/, "");
+}
+function pyScalarType(type) {
+  switch (type) {
+    case "number":
+    case "numberSet":
+      return "float";
+    case "boolean":
+      return "bool";
+    case "binary":
+      return "bytes";
+    case "list":
+      return "list";
+    case "map":
+      return "dict";
+    case "stringSet":
+    case "string":
+    default:
+      return "str";
+  }
+}
+function pyParamType(spec) {
+  if (spec.type === "literal" && spec.literals && spec.literals.length > 0) {
+    const lits = spec.literals.map((l) => typeof l === "string" ? JSON.stringify(l) : String(l)).join(", ");
+    return `Literal[${lits}]`;
+  }
+  return spec.type === "number" ? "float" : "str";
+}
+function txElementTypeName(txName, paramName) {
+  return `${toPascalCase(txName)}${toPascalCase(paramName)}Item`;
+}
+function pyTransactionParamType(txName, paramName, spec) {
+  if (spec.type === "array") {
+    return `list[${txElementTypeName(txName, paramName)}]`;
+  }
+  return pyParamType(spec);
+}
+function collectResultTypes(manifest, entity, select, typeName, out, seen) {
+  const meta = manifest.entities[entity];
+  const fields = [];
+  for (const field of Object.keys(select).sort()) {
+    const value = select[field];
+    const relation = meta?.relations[field];
+    if (relation) {
+      const spec = normalizeSelectSpec(value);
+      const childSelect = spec.select ?? {};
+      const itemTypeName = `${typeName}${toPascalCase(field)}Item`;
+      collectResultTypes(
+        manifest,
+        relation.target,
+        childSelect,
+        itemTypeName,
+        out,
+        seen
+      );
+      if (relation.type === "hasMany") {
+        const connName = `${itemTypeName}Connection`;
+        if (!seen.has(connName)) {
+          seen.add(connName);
+          out.push({
+            name: connName,
+            fields: [
+              ["items", `list[${itemTypeName}]`],
+              ["cursor", "str | None"]
+            ]
+          });
+        }
+        fields.push([field, connName]);
+      } else {
+        fields.push([field, `${itemTypeName} | None`]);
+      }
+      continue;
+    }
+    if (value === true) {
+      const fieldType = meta?.fields[field]?.type ?? "string";
+      fields.push([field, pyScalarType(fieldType)]);
+    }
+  }
+  if (!seen.has(typeName)) {
+    seen.add(typeName);
+    out.push({ name: typeName, fields });
+  }
+}
+function selectOf(def) {
+  return def.select ?? {};
+}
+function queryResultTypeName(queryName) {
+  return `${toPascalCase(queryName)}Result`;
+}
+function renderTypedDict(cls) {
+  if (cls.fields.length === 0) {
+    return `class ${cls.name}(TypedDict):
+    pass`;
+  }
+  const lines = cls.fields.map(([name, type]) => `    ${name}: ${type}`);
+  return `class ${cls.name}(TypedDict):
+${lines.join("\n")}`;
+}
+function renderDataclass(cls) {
+  if (cls.fields.length === 0) {
+    return `@dataclass
+class ${cls.name}:
+    pass`;
+  }
+  const lines = cls.fields.map(
+    ([name, type]) => type.endsWith("| None") ? `    ${name}: ${type} = None` : `    ${name}: ${type}`
+  );
+  const required = lines.filter((l) => !l.endsWith("= None"));
+  const optional = lines.filter((l) => l.endsWith("= None"));
+  return `@dataclass
+class ${cls.name}:
+${[...required, ...optional].join("\n")}`;
+}
+function collectTransactionElementTypes(transactions, out, seen) {
+  for (const txName of Object.keys(transactions).sort()) {
+    const spec = transactions[txName];
+    for (const paramName of Object.keys(spec.params).sort()) {
+      const p = spec.params[paramName];
+      if (p.type !== "array" || !p.element) continue;
+      const name = txElementTypeName(txName, paramName);
+      if (seen.has(name)) continue;
+      seen.add(name);
+      const fields = [];
+      for (const field of Object.keys(p.element).sort()) {
+        fields.push([field, pyParamType(p.element[field])]);
+      }
+      out.push({ name, fields });
+    }
+  }
+}
+function generateTypes(manifest, queries, transactions = {}, options = {}) {
+  const classes = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const queryName of Object.keys(queries).sort()) {
+    const def = queries[queryName];
+    collectResultTypes(
+      manifest,
+      def.entity.name,
+      selectOf(def),
+      queryResultTypeName(queryName),
+      classes,
+      seen
+    );
+  }
+  collectTransactionElementTypes(transactions, classes, seen);
+  const useDataclass = Boolean(options.dataclass);
+  const render = useDataclass ? renderDataclass : renderTypedDict;
+  const body = classes.length === 0 ? "# (no query result types)" : classes.map(render).join("\n\n\n");
+  const usesLiteral = classes.some(
+    (c) => c.fields.some(([, type]) => type.includes("Literal["))
+  );
+  const lines = [PY_HEADER, "", "from __future__ import annotations", ""];
+  if (useDataclass) {
+    lines.push("from dataclasses import dataclass");
+    if (usesLiteral) lines.push("from typing import Literal");
+  } else {
+    lines.push(
+      usesLiteral ? "from typing import Literal, TypedDict" : "from typing import TypedDict"
+    );
+  }
+  lines.push("", "", body, "");
+  return lines.join("\n");
+}
+function methodParams(def) {
+  const params = def.params;
+  const out = [];
+  for (const name of Object.keys(params).sort()) {
+    const d = params[name];
+    const spec = d.literals === void 0 ? { type: d.kind, required: d.required } : {
+      type: d.kind,
+      required: d.required,
+      literals: d.literals
+    };
+    out.push({ argName: toSnakeCase(name), pyType: pyParamType(spec), originalName: name });
+  }
+  return out;
+}
+function collectRepositories(queries, commands) {
+  const byEntity = /* @__PURE__ */ new Map();
+  const ensure = (entity) => {
+    const cls = `${entityBaseName(entity)}Repository`;
+    let methods = byEntity.get(cls);
+    if (!methods) {
+      methods = [];
+      byEntity.set(cls, methods);
+    }
+    return methods;
+  };
+  for (const name of Object.keys(queries).sort()) {
+    const def = queries[name];
+    ensure(def.entity.name).push({
+      methodName: toSnakeCase(name),
+      params: methodParams(def),
+      returnType: `${queryResultTypeName(name)} | None`,
+      kind: "query",
+      operationId: name
+    });
+  }
+  for (const name of Object.keys(commands).sort()) {
+    const def = commands[name];
+    ensure(def.entity.name).push({
+      methodName: toSnakeCase(name),
+      params: methodParams(def),
+      returnType: "None",
+      kind: "command",
+      operationId: name
+    });
+  }
+  return [...byEntity.keys()].sort().map((className) => ({
+    className,
+    methods: byEntity.get(className).slice().sort((a, b) => a.methodName.localeCompare(b.methodName))
+  }));
+}
+function renderMethod(m) {
+  const sig = m.params.map((p) => `${p.argName}: ${p.pyType}`).join(", ");
+  const head = `    def ${m.methodName}(self${sig ? ", " + sig : ""}) -> ${m.returnType}:`;
+  const paramsDict = m.params.map((p) => `"${p.originalName}": ${p.argName}`).join(", ");
+  const paramsArg = paramsDict ? `{${paramsDict}}` : "{}";
+  if (m.kind === "query") {
+    return [
+      head,
+      `        return self._runtime.execute_query(`,
+      `            query_id="${m.operationId}",`,
+      `            params=${paramsArg},`,
+      `        )`
+    ].join("\n");
+  }
+  return [
+    head,
+    `        self._runtime.execute_command(`,
+    `            command_id="${m.operationId}",`,
+    `            params=${paramsArg},`,
+    `        )`
+  ].join("\n");
+}
+function renderRepoClass(cls) {
+  const methods = cls.methods.length === 0 ? ["    pass"] : cls.methods.map(renderMethod);
+  return [
+    `class ${cls.className}:`,
+    `    def __init__(self, runtime: GraphDDBRuntime) -> None:`,
+    `        self._runtime = runtime`,
+    "",
+    methods.join("\n\n")
+  ].join("\n");
+}
+function transactionMethodParams(txName, spec) {
+  const params = [];
+  const elementTypes = [];
+  for (const name of Object.keys(spec.params).sort()) {
+    const p = spec.params[name];
+    if (p.type === "array") elementTypes.push(txElementTypeName(txName, name));
+    params.push({
+      argName: toSnakeCase(name),
+      pyType: pyTransactionParamType(txName, name, p),
+      originalName: name
+    });
+  }
+  return { params, elementTypes };
+}
+function collectTransactionMethods(transactions) {
+  return Object.keys(transactions).sort().map((name) => {
+    const { params, elementTypes } = transactionMethodParams(
+      name,
+      transactions[name]
+    );
+    return {
+      methodName: toSnakeCase(name),
+      params,
+      transactionId: name,
+      elementTypes
+    };
+  });
+}
+function renderTxMethod(m) {
+  const sig = m.params.map((p) => `${p.argName}: ${p.pyType}`).join(", ");
+  const head = `    def ${m.methodName}(self${sig ? ", " + sig : ""}) -> None:`;
+  const paramsDict = m.params.map((p) => `"${p.originalName}": ${p.argName}`).join(", ");
+  const paramsArg = paramsDict ? `{${paramsDict}}` : "{}";
+  return [
+    head,
+    `        self._runtime.execute_transaction(`,
+    `            transaction_id="${m.transactionId}",`,
+    `            params=${paramsArg},`,
+    `        )`
+  ].join("\n");
+}
+function renderTransactionsClass(methods) {
+  const body = methods.length === 0 ? ["    pass"] : methods.map(renderTxMethod);
+  return [
+    `class TransactionsRepository:`,
+    `    def __init__(self, runtime: GraphDDBRuntime) -> None:`,
+    `        self._runtime = runtime`,
+    "",
+    body.join("\n\n")
+  ].join("\n");
+}
+function generateRepositories(queries, commands, transactions = {}) {
+  const classes = collectRepositories(queries, commands);
+  const txMethods = collectTransactionMethods(transactions);
+  const resultTypes = /* @__PURE__ */ new Set();
+  for (const name of Object.keys(queries)) {
+    resultTypes.add(queryResultTypeName(name));
+  }
+  const elementTypes = /* @__PURE__ */ new Set();
+  for (const m of txMethods) for (const t of m.elementTypes) elementTypes.add(t);
+  const sortedTypes = [...resultTypes, ...elementTypes].sort();
+  const importTypes = sortedTypes.length === 0 ? "" : `from .types import (
+${sortedTypes.map((t) => `    ${t},`).join("\n")}
+)
+`;
+  const repoBodies = classes.map(renderRepoClass);
+  if (txMethods.length > 0) repoBodies.push(renderTransactionsClass(txMethods));
+  const body = repoBodies.length === 0 ? "# (no repositories)" : repoBodies.join("\n\n\n");
+  const usesLiteral = classes.some(
+    (c) => c.methods.some((m) => m.params.some((p) => p.pyType.startsWith("Literal[")))
+  );
+  const lines = [PY_HEADER, "", "from __future__ import annotations", ""];
+  if (usesLiteral) lines.push("from typing import Literal", "");
+  lines.push("from graphddb_runtime import GraphDDBRuntime");
+  if (importTypes) lines.push(importTypes.replace(/\n$/, ""));
+  lines.push("", body, "");
+  return lines.join("\n");
+}
+function repositoryClassNames(queries, commands, transactions = {}) {
+  const names = collectRepositories(queries, commands).map((c) => c.className);
+  if (Object.keys(transactions).length > 0) names.push("TransactionsRepository");
+  return names;
+}
+function generateInit(queries, commands, transactions = {}) {
+  const repos = repositoryClassNames(queries, commands, transactions);
+  const resultTypes = Object.keys(queries).sort().map(queryResultTypeName);
+  const lines = [PY_HEADER, "", "from __future__ import annotations", ""];
+  if (resultTypes.length > 0) {
+    lines.push(`from .types import (`);
+    for (const t of resultTypes) lines.push(`    ${t},`);
+    lines.push(`)`);
+  }
+  if (repos.length > 0) {
+    lines.push(`from .repositories import (`);
+    for (const r of repos) lines.push(`    ${r},`);
+    lines.push(`)`);
+  }
+  const all = [...resultTypes, ...repos].sort();
+  lines.push("");
+  lines.push("__all__ = [");
+  for (const name of all) lines.push(`    "${name}",`);
+  lines.push("]");
+  lines.push("");
+  return lines.join("\n");
+}
+
+// src/codegen/index.ts
+var OUTPUT_FILES = [
+  "manifest.json",
+  "operations.json",
+  "types.py",
+  "repositories.py",
+  "__init__.py"
+];
+function renderBundle(queries = {}, commands = {}, registry = MetadataRegistry, transactions = {}, options = {}) {
+  const bundle = buildBridgeBundle(
+    queries,
+    commands,
+    registry,
+    transactions,
+    options.contracts ?? {}
+  );
+  const txSpecs = bundle.operations.transactions ?? {};
+  return {
+    "manifest.json": JSON.stringify(bundle.manifest, null, 2) + "\n",
+    "operations.json": JSON.stringify(bundle.operations, null, 2) + "\n",
+    "types.py": generateTypes(bundle.manifest, queries, txSpecs, options),
+    "repositories.py": generateRepositories(queries, commands, txSpecs),
+    "__init__.py": generateInit(queries, commands, txSpecs)
+  };
+}
+
+// src/cli/handlers.ts
+function fail(code, message, exitCode) {
+  process.stderr.write(JSON.stringify({ code, message }) + "\n");
+  process.exit(exitCode);
+}
+function toUrl(file) {
+  const abs = isAbsolute(file) ? file : resolve(process.cwd(), file);
+  return pathToFileURL(abs).href;
+}
+async function loadDefinitionMap(file, exportName) {
+  const mod = await import(toUrl(file));
+  const value = mod[exportName];
+  if (value === void 0 || value === null) {
+    fail(
+      "INVALID_ARGS",
+      `Module '${file}' has no '${exportName}' export.`,
+      2
+    );
+  }
+  return value;
+}
+async function loadOptionalMap(file, exportName) {
+  const mod = await import(toUrl(file));
+  const value = mod[exportName];
+  if (value === void 0 || value === null) return {};
+  return value;
+}
+var handlers = {
+  async generatePython(options) {
+    const {
+      entry,
+      queries: queriesPath,
+      commands: commandsPath,
+      transactions: transactionsPath,
+      contracts: contractsPath,
+      contexts: contextsPath,
+      dataclass,
+      out
+    } = options;
+    if (!entry) fail("INVALID_ARGS", "Missing required option --entry.", 2);
+    if (!out) fail("INVALID_ARGS", "Missing required option --out.", 2);
+    try {
+      await import(toUrl(entry));
+      const queries = await loadDefinitionMap(queriesPath ?? entry, "queries");
+      const commands = await loadDefinitionMap(commandsPath ?? entry, "commands");
+      const transactions = await loadOptionalMap(
+        transactionsPath ?? commandsPath ?? entry,
+        "transactions"
+      );
+      const contracts = await loadOptionalMap(
+        contractsPath ?? entry,
+        "contracts"
+      );
+      const contexts = await loadOptionalMap(
+        contextsPath ?? contractsPath ?? entry,
+        "contexts"
+      );
+      const files = renderBundle(queries, commands, void 0, transactions, {
+        dataclass: Boolean(dataclass),
+        contracts: { contracts, contexts }
+      });
+      void dataclass;
+      const outDir = isAbsolute(out) ? out : resolve(process.cwd(), out);
+      mkdirSync(outDir, { recursive: true });
+      for (const name of OUTPUT_FILES) {
+        writeFileSync(resolve(outDir, name), files[name], "utf8");
+      }
+      process.stdout.write(
+        JSON.stringify({
+          status: "ok",
+          outDir: out,
+          files: [...OUTPUT_FILES]
+        }) + "\n"
+      );
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      fail("GENERATION_FAILED", message, 1);
+    }
+  }
+};
+
+// src/cli.ts
+var VERSION = "0.1.0";
+createProgram(handlers, VERSION).parseAsync(process.argv);