permdock 0.3.1 → 0.5.0

package/schemas/cli-commands-v1.json

@@ -0,0 +1,164 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://permdock.com/schemas/cli-commands-v1.json",
+  "title": "PermDock CLI commands v1",
+  "description": "What `permdock --help --json` prints: every command with its arguments, options, examples, side effects and docs page, read from the same manifest the parser uses. `permdock <command> --help --json` prints the same document with that command only. The shape follows better-supabase's `cli-commands-v1`; `docs` and `config` are PermDock's own. Fields are only added within v1.",
+  "type": "object",
+  "required": ["$schema", "name", "version", "options", "commands"],
+  "properties": {
+    "$schema": {
+      "const": "https://permdock.com/schemas/cli-commands-v1.json"
+    },
+    "name": {
+      "const": "permdock"
+    },
+    "version": {
+      "type": "string",
+      "description": "The installed permdock version."
+    },
+    "options": {
+      "description": "The global options every command accepts.",
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/option"
+      }
+    },
+    "commands": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/command"
+      }
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "command": {
+      "type": "object",
+      "required": [
+        "name",
+        "path",
+        "description",
+        "docs",
+        "examples",
+        "effects",
+        "config",
+        "arguments",
+        "options"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "The last word of `path`."
+        },
+        "path": {
+          "type": "string",
+          "description": "The words after `permdock`, such as `rls generate`."
+        },
+        "description": {
+          "type": "string"
+        },
+        "docs": {
+          "type": "string",
+          "format": "uri"
+        },
+        "examples": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Complete command lines, starting with `permdock`."
+        },
+        "effects": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "enum": [
+              "files",
+              "rewrite",
+              "database:read",
+              "database:write",
+              "network",
+              "cloud:write",
+              "install"
+            ]
+          },
+          "description": "What the command may change. Empty means it only reads and prints. In agent mode, `rewrite`, `cloud:write`, and `files` with `--force` need a `--confirm` token."
+        },
+        "config": {
+          "type": "boolean",
+          "description": "Whether the command reads permdock.config.ts."
+        },
+        "arguments": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "description", "required", "variadic"],
+            "properties": {
+              "name": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              },
+              "required": {
+                "type": "boolean"
+              },
+              "variadic": {
+                "type": "boolean"
+              }
+            },
+            "additionalProperties": false
+          }
+        },
+        "options": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/option"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "option": {
+      "type": "object",
+      "required": ["name", "type", "description"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*$",
+          "description": "Written `--<name>` on the command line."
+        },
+        "type": {
+          "enum": ["boolean", "string", "enum"]
+        },
+        "description": {
+          "type": "string"
+        },
+        "aliases": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z]$"
+          }
+        },
+        "choices": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "default": {
+          "type": ["boolean", "string"]
+        },
+        "list": {
+          "const": true,
+          "description": "Takes several values, repeated."
+        },
+        "valueHint": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/schemas/cli-result-v1.json

@@ -0,0 +1,96 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://permdock.com/schemas/cli-result-v1.json",
+  "title": "PermDock CLI result v1",
+  "description": "What every `permdock` command prints on stdout under `--json`, `--format json` or agent mode: one envelope per run, success or not. `data` is the command's report; `error` is RFC 9457 Problem Details. Fields are only added within v1.",
+  "type": "object",
+  "required": ["$schema", "status"],
+  "properties": {
+    "$schema": {
+      "const": "https://permdock.com/schemas/cli-result-v1.json"
+    },
+    "status": {
+      "enum": ["success", "error", "action_required"],
+      "description": "`action_required` exits 3: the run needs input, consent or a login that only a person can give."
+    },
+    "data": {
+      "description": "The command's report. Its shape is the command's own; a report with its own `$schema` keeps it."
+    },
+    "error": { "$ref": "#/$defs/problem" },
+    "next": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/nextStep" },
+      "description": "Commands that move the run forward, in order."
+    }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "status": { "const": "success" } } },
+      "then": { "not": { "required": ["error"] } },
+      "else": { "required": ["error"] }
+    }
+  ],
+  "$defs": {
+    "nextStep": {
+      "type": "object",
+      "required": ["command", "when"],
+      "properties": {
+        "command": {
+          "type": "string",
+          "description": "A complete command line, starting with `permdock`."
+        },
+        "when": {
+          "type": "string",
+          "description": "The condition under which to run it, such as `after the person agrees`."
+        }
+      },
+      "additionalProperties": false
+    },
+    "problem": {
+      "type": "object",
+      "required": ["type", "title", "detail", "code", "exitCode"],
+      "properties": {
+        "type": {
+          "type": "string",
+          "pattern": "^https://permdock\\.com/docs/cli/errors#[a-z_]+$",
+          "description": "The code's heading on the errors page, `https://permdock.com/docs/cli/errors#<code>`."
+        },
+        "title": { "type": "string" },
+        "detail": { "type": "string" },
+        "code": {
+          "enum": [
+            "usage",
+            "unknown_command",
+            "unknown_flag",
+            "invalid_value",
+            "command_moved",
+            "flag_renamed",
+            "missing_value",
+            "config_not_found",
+            "config_invalid",
+            "dependency_missing",
+            "database_unreachable",
+            "network_error",
+            "request_failed",
+            "auth_required",
+            "dirty_worktree",
+            "write_failed",
+            "check_failed",
+            "input_required",
+            "consent_required",
+            "cancelled",
+            "internal"
+          ],
+          "description": "Stable, snake_case; new codes are only added within v1."
+        },
+        "command": {
+          "type": "string",
+          "description": "The command path, such as `rls generate`."
+        },
+        "exitCode": { "enum": [1, 2, 3, 130, 143] }
+      },
+      "additionalProperties": true
+    }
+  }
+}