@intentius/sql-yodeler 0.1.0 → 0.2.0

package/schemas/mcp.schema.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/sql-yodeler/schemas/v1/mcp.schema.json",
+  "title": "A yodel mcp tool result",
+  "description": "Version 1. Every tool of yodel mcp returns this envelope, as the call's structuredContent and as its text. results follows the schema resultsSchema names: the command's own (status, plan, lint, drift) or a definition here (history, explain). Within a version, fields are only added; a reader ignores fields it does not know.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "tool", "command", "exit", "results", "resultsSchema"],
+  "properties": {
+    "schema": { "description": "The envelope's version.", "const": 1 },
+    "tool": { "enum": ["status", "plan", "lint", "drift", "history", "explain"] },
+    "command": { "description": "The yodel command line the tool ran.", "type": "string" },
+    "exit": { "description": "The command's exit code, the same as on a terminal (yodel --help lists them).", "type": "integer" },
+    "results": { "description": "What the command printed with --json; null when it printed nothing (it failed: see error)." },
+    "resultsSchema": { "description": "The $id of the schema results follows.", "type": "string" },
+    "error": { "description": "What the command wrote to stderr: why it failed when results is null, else notices.", "type": "string" },
+    "forPerson": {
+      "description": "Steps that belong to a person, each with the command the person runs. An agent shows them and never runs them.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["action", "command"],
+        "properties": { "action": { "type": "string" }, "command": { "type": "string" } }
+      }
+    }
+  },
+  "$defs": {
+    "history": {
+      "description": "The history tool: the migrations the environment's history records applied, from yodel status.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["environment", "history", "applied"],
+      "properties": {
+        "environment": { "type": "string" },
+        "server": { "$ref": "common.schema.json#/$defs/server" },
+        "history": { "$ref": "status.schema.json#/$defs/report/properties/history" },
+        "applied": { "$ref": "status.schema.json#/$defs/report/properties/applied" }
+      }
+    },
+    "explain": {
+      "description": "The explain tool: a lint rule, or an exit code.",
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["topic", "kind", "rule", "docs"],
+          "properties": {
+            "topic": { "type": "string" },
+            "kind": { "const": "lint-rule" },
+            "rule": { "$ref": "lint-rules.schema.json#/items" },
+            "docs": { "type": "string" }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["topic", "kind", "code", "meaning", "docs"],
+          "properties": {
+            "topic": { "type": "string" },
+            "kind": { "const": "exit-code" },
+            "code": { "type": "integer" },
+            "meaning": { "type": "string" },
+            "docs": { "type": "string" }
+          }
+        }
+      ]
+    }
+  }
+}

package/schemas/new.schema.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/sql-yodeler/schemas/v1/new.schema.json",
+  "title": "yodel new <name> --json",
+  "description": "Version 1. The migration written (written true), or why none was: a backfill template to fill in, a --replace that kept the migration, or no change from the newest migration's recorded schema. Within a version, fields are only added; a reader ignores fields it does not know.",
+  "oneOf": [{ "$ref": "#/$defs/written" }, { "$ref": "#/$defs/template" }, { "$ref": "#/$defs/kept" }, { "$ref": "#/$defs/unchanged" }],
+  "$defs": {
+    "written": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["written", "id", "path", "parent", "checksum", "dialect", "statements", "ops", "manual", "hints", "checks"],
+      "properties": {
+        "written": { "const": true },
+        "id": { "type": "string" },
+        "path": { "type": "string" },
+        "parent": { "type": ["string", "null"] },
+        "checksum": { "type": "string" },
+        "dialect": { "$ref": "common.schema.json#/$defs/dialect" },
+        "statements": { "type": "integer", "minimum": 0 },
+        "ops": {
+          "description": "The Op steps written, which yodel apply runs or refuses.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["op", "object", "name", "rules"],
+            "properties": { "op": { "type": "string" }, "object": { "type": "string" }, "name": { "type": "string" }, "rules": { "$ref": "common.schema.json#/$defs/stringList" } }
+          }
+        },
+        "manual": {
+          "description": "The manual steps written: yodel apply refuses them.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["object", "name", "rules", "detail"],
+            "properties": { "object": { "type": "string" }, "name": { "type": "string" }, "rules": { "$ref": "common.schema.json#/$defs/stringList" }, "detail": { "type": "string" } }
+          }
+        },
+        "hints": { "$ref": "common.schema.json#/$defs/stringList" },
+        "checks": { "type": "array", "items": { "$ref": "common.schema.json#/$defs/check" } }
+      }
+    },
+    "template": {
+      "description": "--backfill named a file that is not there: the template was written to it, and no migration.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["written", "template"],
+      "properties": { "written": { "const": false }, "template": { "type": "string" } }
+    },
+    "kept": {
+      "description": "--replace: the replacement would be the same, so the migration was kept.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["written", "replaced", "kept"],
+      "properties": { "written": { "const": false }, "replaced": { "type": "null" }, "kept": { "type": "string" } }
+    },
+    "unchanged": {
+      "description": "The declared schema matches the newest migration's recorded schema.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["written", "parent", "dialect", "hints"],
+      "properties": {
+        "written": { "const": false },
+        "parent": { "type": ["string", "null"] },
+        "dialect": { "$ref": "common.schema.json#/$defs/dialect" },
+        "hints": { "$ref": "common.schema.json#/$defs/stringList" }
+      }
+    }
+  }
+}

package/schemas/plan.schema.json

@@ -0,0 +1,371 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/sql-yodeler/schemas/v1/plan.schema.json",
+  "title": "yodel plan <env> --json",
+  "description": "Version 1. A project with migrations prints the versioned plan (mode \"versioned\"); a project without prints the declarative plan, chant's diff with the environment and dialect it is of. Within a version, fields are only added; a reader ignores fields it does not know.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/versioned"
+    },
+    {
+      "$ref": "#/$defs/declarative"
+    }
+  ],
+  "$defs": {
+    "declarative": {
+      "description": "chant's diff (chant sql plan --json) with environment, dialect and server added. chant owns the diff's fields: ones beyond those listed may appear.",
+      "type": "object",
+      "required": [
+        "environment",
+        "dialect",
+        "changes",
+        "hints"
+      ],
+      "properties": {
+        "environment": {
+          "type": "string"
+        },
+        "dialect": {
+          "$ref": "common.schema.json#/$defs/dialect"
+        },
+        "server": {
+          "$ref": "common.schema.json#/$defs/server"
+        },
+        "changes": {
+          "type": "array",
+          "items": {
+            "$ref": "common.schema.json#/$defs/change"
+          }
+        },
+        "hints": {
+          "$ref": "common.schema.json#/$defs/stringList"
+        },
+        "rebuilds": {
+          "description": "ClickHouse: the changes that need a ClickHouseRebuildOp.",
+          "type": "array",
+          "items": {
+            "$ref": "common.schema.json#/$defs/change"
+          }
+        },
+        "rebuildOps": {
+          "type": "array",
+          "items": {
+            "type": "object"
+          }
+        },
+        "refused": {
+          "description": "Postgres: the changes that need a PostgresMigrationOp.",
+          "type": "array",
+          "items": {
+            "$ref": "common.schema.json#/$defs/change"
+          }
+        },
+        "migrationOps": {
+          "type": "array",
+          "items": {
+            "type": "object"
+          }
+        },
+        "mode": false
+      }
+    },
+    "stepChange": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "rule",
+        "class",
+        "field"
+      ],
+      "properties": {
+        "rule": {
+          "type": "string"
+        },
+        "class": {
+          "type": "string"
+        },
+        "field": {
+          "type": "string"
+        },
+        "destructive": {
+          "const": true
+        }
+      }
+    },
+    "step": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "index",
+        "kind",
+        "object",
+        "name",
+        "done"
+      ],
+      "properties": {
+        "index": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "kind": {
+          "enum": [
+            "statement",
+            "op",
+            "manual"
+          ]
+        },
+        "object": {
+          "type": "string"
+        },
+        "name": {
+          "type": "string"
+        },
+        "rule": {
+          "type": "string"
+        },
+        "class": {
+          "type": "string"
+        },
+        "destructive": {
+          "const": true
+        },
+        "changes": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/stepChange"
+          }
+        },
+        "sql": {
+          "description": "A statement step's SQL, with passwords, secrets and tokens redacted.",
+          "type": "string"
+        },
+        "detail": {
+          "type": "string"
+        },
+        "op": {
+          "type": "string"
+        },
+        "applyRuns": {
+          "description": "An Op or manual step: whether yodel apply runs it.",
+          "type": "boolean"
+        },
+        "refused": {
+          "description": "Why yodel apply does not run this step.",
+          "type": "string"
+        },
+        "done": {
+          "description": "It succeeded in an earlier run and is not sent again.",
+          "type": "boolean"
+        }
+      }
+    },
+    "moved": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "part",
+          "message"
+        ],
+        "properties": {
+          "part": {
+            "enum": [
+              "environment",
+              "history",
+              "pending",
+              "live"
+            ]
+          },
+          "message": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "versioned": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "environment",
+        "dialect",
+        "mode",
+        "applied",
+        "pending",
+        "problems",
+        "notes"
+      ],
+      "properties": {
+        "environment": {
+          "type": "string"
+        },
+        "dialect": {
+          "$ref": "common.schema.json#/$defs/dialect"
+        },
+        "mode": {
+          "const": "versioned"
+        },
+        "server": {
+          "$ref": "common.schema.json#/$defs/server"
+        },
+        "history": {
+          "description": "<database>.history, and on ClickHouse the topology and where it came from.",
+          "type": "string"
+        },
+        "applied": {
+          "description": "How many migrations the history records applied.",
+          "type": "integer",
+          "minimum": 0
+        },
+        "pending": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "id",
+              "outOfOrder",
+              "steps"
+            ],
+            "properties": {
+              "id": {
+                "type": "string"
+              },
+              "outOfOrder": {
+                "type": "boolean"
+              },
+              "resumeAt": {
+                "type": "integer"
+              },
+              "checks": {
+                "type": "array",
+                "items": {
+                  "$ref": "common.schema.json#/$defs/check"
+                }
+              },
+              "steps": {
+                "type": "array",
+                "items": {
+                  "$ref": "#/$defs/step"
+                }
+              }
+            }
+          }
+        },
+        "problems": {
+          "description": "Directory problems, checksum mismatches, out-of-order migrations.",
+          "$ref": "common.schema.json#/$defs/stringList"
+        },
+        "refusal": {
+          "$ref": "common.schema.json#/$defs/refusal"
+        },
+        "planDigest": {
+          "description": "The digest the migrations Op's gate binds; absent when apply would refuse or has nothing to do.",
+          "type": "string"
+        },
+        "policy": {
+          "$ref": "common.schema.json#/$defs/policy"
+        },
+        "op": {
+          "description": "The migrations Op.",
+          "type": "string"
+        },
+        "gate": {
+          "description": "The Op's gate.",
+          "type": "string"
+        },
+        "approve": {
+          "description": "The command a person runs to approve this plan. An agent prints it and never runs it.",
+          "type": "string"
+        },
+        "approval": {
+          "description": "The newest approval of the gate in chant's ledger.",
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "by",
+            "at",
+            "holds",
+            "sameDigest"
+          ],
+          "properties": {
+            "digest": {
+              "type": "string"
+            },
+            "by": {
+              "type": "string"
+            },
+            "at": {
+              "type": "string"
+            },
+            "holds": {
+              "type": "boolean"
+            },
+            "sameDigest": {
+              "type": "boolean"
+            },
+            "askedAgain": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "at"
+              ],
+              "properties": {
+                "at": {
+                  "type": "string"
+                },
+                "digest": {
+                  "type": "string"
+                }
+              }
+            },
+            "moved": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "confirmed",
+                "changes"
+              ],
+              "properties": {
+                "confirmed": {
+                  "type": "boolean"
+                },
+                "changes": {
+                  "$ref": "#/$defs/moved"
+                }
+              }
+            }
+          }
+        },
+        "opMissing": {
+          "description": "The project declares no migrations Op for the environment: the first line of how to declare one.",
+          "type": "string"
+        },
+        "sinceLast": {
+          "description": "The pull request comment this plan replaces showed another digest: what moved since.",
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "digest",
+            "confirmed",
+            "changes"
+          ],
+          "properties": {
+            "digest": {
+              "type": "string"
+            },
+            "confirmed": {
+              "type": "boolean"
+            },
+            "changes": {
+              "$ref": "#/$defs/moved"
+            }
+          }
+        },
+        "notes": {
+          "$ref": "common.schema.json#/$defs/stringList"
+        }
+      }
+    }
+  }
+}

package/schemas/rebase.schema.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/sql-yodeler/schemas/v1/rebase.schema.json",
+  "title": "yodel rebase --json",
+  "description": "Version 1. The migration moved onto its new parent and every migration rewritten, or rebased false when there was nothing to move. Within a version, fields are only added; a reader ignores fields it does not know.",
+  "oneOf": [
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["rebased"],
+      "properties": { "rebased": { "const": false } }
+    },
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["rebased", "moved", "from", "onto", "historiesChecked", "rewritten"],
+      "properties": {
+        "rebased": { "const": true },
+        "moved": { "type": "string" },
+        "from": { "type": ["string", "null"] },
+        "onto": { "type": "string" },
+        "historiesChecked": { "description": "The environments (--env) whose histories were checked so a migration that ran is never moved.", "$ref": "common.schema.json#/$defs/stringList" },
+        "rewritten": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "path", "oldParent", "parent", "oldChecksum", "checksum", "statements", "refused", "silences", "handEdited"],
+            "properties": {
+              "id": { "type": "string" },
+              "path": { "type": "string" },
+              "oldParent": { "type": ["string", "null"] },
+              "parent": { "type": ["string", "null"] },
+              "oldChecksum": { "type": "string" },
+              "checksum": { "type": "string" },
+              "statements": { "type": "integer", "minimum": 0 },
+              "refused": { "type": "boolean" },
+              "silences": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["step", "rule", "reason", "line"],
+                  "properties": { "step": { "type": "integer" }, "rule": { "type": "string" }, "reason": { "type": "string" }, "line": { "type": "integer" } }
+                }
+              },
+              "handEdited": { "type": "boolean" }
+            }
+          }
+        }
+      }
+    }
+  ]
+}

package/schemas/repair.schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/sql-yodeler/schemas/v1/repair.schema.json",
+  "title": "yodel repair <env> <id> --reason <text> --json",
+  "description": "Version 1. The checksum recorded for an applied migration, with the reason, and whether migration.json's own checksum field was written again. Within a version, fields are only added; a reader ignores fields it does not know.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["repaired", "id", "environment", "oldChecksum", "newChecksum", "reason", "seq", "runId", "migrationJsonUpdated"],
+  "properties": {
+    "repaired": { "const": true },
+    "id": { "type": "string" },
+    "environment": { "type": "string" },
+    "oldChecksum": { "type": "string" },
+    "newChecksum": { "type": "string" },
+    "reason": { "type": "string" },
+    "seq": { "type": "integer" },
+    "runId": { "type": "string" },
+    "migrationJsonUpdated": { "type": "boolean" }
+  }
+}