@crvouga/dev-fleet 0.2.0 → 0.4.0

package/schema/fleet.schema.json

@@ -107,6 +107,14 @@
                 "description": "The port the worker T3 server listens on, normally 3773."
               }
             }
+          },
+          "toolProfiles": {
+            "type": "array",
+            "uniqueItems": true,
+            "items": {
+              "enum": ["web", "go", "rust", "jvm"]
+            },
+            "description": "Tool profiles this worker installs on top of the fleet-wide ones: web (pnpm, Deno, Yarn), go, rust (with CMake and Ninja), jvm (Temurin). Each is a locked tool set dev-fleet ships."
           }
         }
       }
@@ -126,6 +134,41 @@
               "type": "string",
               "pattern": "^https://[A-Za-z0-9.-]+$",
               "description": "Public HTTPS origin of the CLI proxy every node uses."
+            },
+            "accounts": {
+              "type": "object",
+              "additionalProperties": false,
+              "description": "How provider accounts signed in on the proxy are watched and chosen. See docs/accounts.md.",
+              "properties": {
+                "minimumUsable": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "description": "proxy:account:<provider> warns when a provider has fewer usable accounts than this (default 2) and fails when it has none."
+                },
+                "selection": {
+                  "type": "object",
+                  "description": "Per provider (claude, codex, antigravity): which account an unpinned request goes to first. Accounts cooling down are always skipped.",
+                  "additionalProperties": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": ["strategy"],
+                    "properties": {
+                      "strategy": {
+                        "enum": [
+                          "fill-first",
+                          "round-robin",
+                          "least-recently-limited"
+                        ]
+                      },
+                      "order": {
+                        "type": "array",
+                        "items": { "type": "string" },
+                        "description": "Account labels (sign-in emails) first, in this order; the others follow in the order of their routing prefix."
+                      }
+                    }
+                  }
+                }
+              }
             }
           }
         },
@@ -156,6 +199,49 @@
               "type": "string",
               "format": "email",
               "description": "Read-only Beszel account visitors are signed in as."
+            },
+            "backups": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["schedule", "keep", "storage"],
+              "description": "Scheduled off-machine backups of the monitoring hub. fleet-sync sets them through the hub's API, with the keys of the secrets monitoring-backup-access-key and monitoring-backup-secret-key; without this block the hub's backups are only read, and beszel:backup warns.",
+              "properties": {
+                "schedule": {
+                  "type": "string",
+                  "pattern": "^[0-9*/,-]+( [0-9*/,-]+){4}$",
+                  "description": "A cron expression in the hub's time zone, for example 0 3 * * *."
+                },
+                "keep": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "maximum": 365,
+                  "description": "How many scheduled backups the hub keeps."
+                },
+                "storage": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["bucket", "endpoint", "region"],
+                  "description": "S3-compatible storage off the manager. Never its keys.",
+                  "properties": {
+                    "bucket": {
+                      "type": "string",
+                      "pattern": "^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$"
+                    },
+                    "endpoint": {
+                      "type": "string",
+                      "pattern": "^https://[A-Za-z0-9.-]+(:[0-9]+)?$"
+                    },
+                    "region": {
+                      "type": "string",
+                      "pattern": "^[a-z0-9-]{1,32}$"
+                    },
+                    "forcePathStyle": {
+                      "type": "boolean",
+                      "description": "Path-style requests, for services that need them (MinIO)."
+                    }
+                  }
+                }
+              }
             }
           }
         }
@@ -228,9 +314,26 @@
         },
         "neverSleep": {
           "const": true
+        },
+        "toolProfiles": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "enum": ["web", "go", "rust", "jvm"]
+          },
+          "description": "Tool profiles every worker installs on top of the base tools: web (pnpm, Deno, Yarn), go, rust (with CMake and Ninja), jvm (Temurin). Each worker passes a tool:<name> check for each of their tools."
+        },
+        "tools": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "pattern": "^[A-Za-z0-9@:/._-]{1,75}$"
+          },
+          "description": "Single tools every worker installs: names of tools dev-fleet's mise.toml pins (for example fd or ripgrep). A tool it does not pin is refused; ask for it in an issue."
         }
       },
-      "description": "Policy every worker must meet. All but the two logins and the capabilities are fixed."
+      "description": "Policy every worker must meet. All but the two logins, the capabilities and the tools are fixed."
     },
     "source": {
       "type": "object",
@@ -244,6 +347,37 @@
         }
       }
     },
+    "ides": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": { "enum": ["t3"] },
+      "description": "The IDEs every machine runs. Defaults to [\"t3\"]; the README's support matrix lists the supported ones."
+    },
+    "t3": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "What every machine's T3 Code holds beyond the provider instances generated from the proxy's accounts.",
+      "properties": {
+        "profile": {
+          "type": "object",
+          "description": "Top-level T3 settings every machine holds the same (tool servers, projects, selected preferences). Keys not named here stay local; a key edited on a machine since dev-fleet last wrote it is reported as a conflict, never overwritten.",
+          "propertyNames": {
+            "pattern": "^[a-zA-Z][a-zA-Z0-9_-]{0,63}$",
+            "not": { "const": "providerInstances" }
+          }
+        },
+        "requiredModels": {
+          "type": "object",
+          "description": "Models T3 must offer, and the proxy must serve, for every account of a tool, by tool (claude, codex, opencode).",
+          "propertyNames": { "pattern": "^[a-zA-Z][a-zA-Z0-9_-]{0,63}$" },
+          "additionalProperties": {
+            "type": "array",
+            "items": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }
+          }
+        }
+      }
+    },
     "state": {
       "description": "The bucket that holds the fleet state (the roster, the approved revision and the configuration last applied). Any S3-compatible service, or a directory. Never credentials: a devfleet command reads those from DEVFLEET_BUCKET_ACCESS_KEY_ID and DEVFLEET_BUCKET_SECRET_ACCESS_KEY.",
       "oneOf": [
@@ -409,12 +543,121 @@
                       "pattern": "^[A-Za-z0-9_]+$"
                     }
                   }
+                },
+                "monitoring-backup-access-key": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["path", "field"],
+                  "properties": {
+                    "path": {
+                      "type": "string",
+                      "pattern": "^[A-Za-z0-9._/-]+$"
+                    },
+                    "field": {
+                      "type": "string",
+                      "pattern": "^[A-Za-z0-9_]+$"
+                    }
+                  },
+                  "description": "Only with services.monitoring.backups: the access key of the hub's backup storage."
+                },
+                "monitoring-backup-secret-key": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["path", "field"],
+                  "properties": {
+                    "path": {
+                      "type": "string",
+                      "pattern": "^[A-Za-z0-9._/-]+$"
+                    },
+                    "field": {
+                      "type": "string",
+                      "pattern": "^[A-Za-z0-9_]+$"
+                    }
+                  },
+                  "description": "Only with services.monitoring.backups: the secret key of the hub's backup storage."
+                },
+                "notify-webhook-url": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["path", "field"],
+                  "properties": {
+                    "path": {
+                      "type": "string",
+                      "pattern": "^[A-Za-z0-9._/-]+$"
+                    },
+                    "field": {
+                      "type": "string",
+                      "pattern": "^[A-Za-z0-9_]+$"
+                    }
+                  },
+                  "description": "Only with the webhook notify target: the URL fleet-watch POSTs JSON to."
+                },
+                "notify-ntfy-url": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["path", "field"],
+                  "properties": {
+                    "path": {
+                      "type": "string",
+                      "pattern": "^[A-Za-z0-9._/-]+$"
+                    },
+                    "field": {
+                      "type": "string",
+                      "pattern": "^[A-Za-z0-9_]+$"
+                    }
+                  },
+                  "description": "Only with the ntfy notify target: the ntfy topic URL fleet-watch publishes to."
                 }
               }
             }
           }
         }
       ]
+    },
+    "git": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "email"],
+      "description": "The Git identity every node, the manager included, commits with, and the GitHub credential helper it pushes with. fleet-sync writes them in ~/.config/git/config and measures them as worker:git-identity and worker:git-push-auth.",
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[^\"\\\\\\n\\r]{1,100}$",
+          "description": "user.name of every commit."
+        },
+        "email": {
+          "type": "string",
+          "format": "email",
+          "description": "user.email of every commit, for example the account's noreply address."
+        },
+        "verifyRepository": {
+          "type": "string",
+          "pattern": "^https://github\\.com/[A-Za-z0-9_.-]{1,100}/[A-Za-z0-9_.-]{1,100}$",
+          "description": "A GitHub repository the fleet's account can push to, ideally private. Each node lists it through git with its own credentials."
+        }
+      }
+    },
+    "notify": {
+      "description": "Where fleet-watch sends a notification when a machine becomes unhealthy or recovers. Each target's address is a secret: notify-webhook-url (a JSON POST) or notify-ntfy-url (an ntfy topic URL).",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["targets"],
+      "properties": {
+        "targets": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "enum": ["webhook", "ntfy"]
+          }
+        },
+        "repeatHours": {
+          "description": "Notify again about a machine that stays unhealthy this often. 0 never repeats; the default is 24.",
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 720
+        }
+      }
     }
   }
 }

package/schema/output/check.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "check.schema.json",
+  "title": "One check of a dev-fleet report",
+  "description": "The id is listed in schema/check-ids.json.",
+  "type": "object",
+  "required": ["id", "status", "summary"],
+  "properties": {
+    "id": { "type": "string", "pattern": "^[a-z0-9-]+(:[A-Za-z0-9:._-]+)?$" },
+    "status": { "enum": ["pass", "warn", "fail", "skip"] },
+    "summary": { "type": "string" },
+    "required": { "type": "boolean" },
+    "phaseDurationMs": { "type": "number" },
+    "remedy": {
+      "type": "object",
+      "required": ["action"],
+      "properties": {
+        "action": { "type": "string" },
+        "command": { "type": "string" }
+      }
+    }
+  }
+}

package/schema/output/error.schema.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "error.schema.json",
+  "title": "A dev-fleet error, version 1",
+  "description": "What a command prints with --json when it fails before a report: raw subprocess output and exception details are withheld.",
+  "type": "object",
+  "required": ["version", "ok", "code", "error"],
+  "properties": {
+    "version": { "const": 1 },
+    "ok": { "const": false },
+    "code": { "type": "string" },
+    "error": { "type": "string" }
+  }
+}

package/schema/output/fleet-report.schema.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "fleet-report.schema.json",
+  "title": "The fleet-report output, version 1",
+  "type": "object",
+  "required": [
+    "version",
+    "command",
+    "ok",
+    "since",
+    "runs",
+    "succeeded",
+    "successRate",
+    "meanDurationMs",
+    "failingChecks",
+    "notReady",
+    "entries"
+  ],
+  "properties": {
+    "version": { "const": 1 },
+    "command": { "const": "fleet-report" },
+    "ok": { "type": "boolean" },
+    "since": { "type": "string" },
+    "runs": { "type": "integer" },
+    "succeeded": { "type": "integer" },
+    "successRate": { "type": ["number", "null"] },
+    "meanDurationMs": { "type": ["number", "null"] },
+    "failingChecks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "runs"],
+        "properties": {
+          "id": { "type": "string" },
+          "runs": { "type": "integer" }
+        }
+      }
+    },
+    "notReady": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["node", "ms"],
+        "properties": {
+          "node": { "type": "string" },
+          "ms": { "type": "number" }
+        }
+      }
+    },
+    "entries": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "startedAt",
+          "finishedAt",
+          "durationMs",
+          "trigger",
+          "revision",
+          "ok",
+          "exitCode",
+          "failing",
+          "notReady"
+        ],
+        "properties": {
+          "startedAt": { "type": "string" },
+          "finishedAt": { "type": "string" },
+          "durationMs": { "type": "number" },
+          "trigger": { "enum": ["operator", "schedule"] },
+          "revision": { "type": ["string", "null"] },
+          "ok": { "type": "boolean" },
+          "exitCode": { "type": "integer" },
+          "failing": { "type": "array", "items": { "type": "string" } },
+          "notReady": { "type": "array", "items": { "type": "string" } }
+        }
+      }
+    }
+  }
+}

package/schema/output/fleet-sync.schema.json

@@ -0,0 +1,112 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "fleet-sync.schema.json",
+  "title": "The fleet-sync report, version 3",
+  "description": "What devfleet fleet-sync prints with --json. A preview (--dry-run) adds plan.",
+  "type": "object",
+  "required": [
+    "version",
+    "command",
+    "execution",
+    "ok",
+    "applied",
+    "desiredRevision",
+    "checks",
+    "nodes",
+    "candidates",
+    "dashboardUrl"
+  ],
+  "properties": {
+    "version": { "const": 3 },
+    "command": { "const": "fleet-sync" },
+    "execution": { "const": "manager-push" },
+    "ok": { "type": "boolean" },
+    "applied": { "type": "boolean" },
+    "desiredRevision": { "type": ["string", "null"] },
+    "checks": { "type": "array", "items": { "$ref": "check.schema.json" } },
+    "candidates": { "type": "integer" },
+    "dashboardUrl": { "type": ["string", "null"] },
+    "planFingerprint": { "type": "string" },
+    "nodes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "node",
+          "checks",
+          "reachability",
+          "desiredRevision",
+          "appliedRevision",
+          "durationMs"
+        ],
+        "properties": {
+          "node": { "type": "string" },
+          "role": { "enum": ["manager", "worker"] },
+          "reachability": {
+            "enum": ["online", "offline", "missing", "conflict", "unknown"]
+          },
+          "desiredRevision": { "type": ["string", "null"] },
+          "appliedRevision": { "type": ["string", "null"] },
+          "durationMs": { "type": "number" },
+          "checks": {
+            "type": "array",
+            "items": { "$ref": "check.schema.json" }
+          }
+        }
+      }
+    },
+    "plan": {
+      "type": "object",
+      "required": ["state", "revision", "known", "tools", "restarts", "nodes"],
+      "properties": {
+        "state": { "type": "string" },
+        "known": { "type": "boolean" },
+        "revision": {
+          "type": "object",
+          "required": ["from", "to"],
+          "properties": {
+            "from": { "type": ["string", "null"] },
+            "to": { "type": "string" }
+          }
+        },
+        "tools": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["tool", "from", "to"],
+            "properties": {
+              "tool": { "type": "string" },
+              "from": { "type": ["string", "null"] },
+              "to": { "type": ["string", "null"] }
+            }
+          }
+        },
+        "restarts": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["service", "reason", "endsRunningTurns"],
+            "properties": {
+              "service": { "type": "string" },
+              "reason": { "type": "string" },
+              "endsRunningTurns": { "type": "boolean" }
+            }
+          }
+        },
+        "nodes": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["node", "from", "to", "changes"],
+            "properties": {
+              "node": { "type": "string" },
+              "from": { "type": ["string", "null"] },
+              "to": { "type": "string" },
+              "changes": { "type": "boolean" }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/schema/output/report.schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "report.schema.json",
+  "title": "A dev-fleet diagnostic report, version 1",
+  "description": "What fleet-status, fleet-state and the other diagnostic commands print with --json.",
+  "type": "object",
+  "required": ["version", "command", "ok", "generatedAt", "nodes", "summary"],
+  "properties": {
+    "version": { "const": 1 },
+    "command": { "type": "string" },
+    "ok": { "type": "boolean" },
+    "generatedAt": { "type": "string" },
+    "nodes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["node", "checks"],
+        "properties": {
+          "node": { "type": "string" },
+          "checks": {
+            "type": "array",
+            "items": { "$ref": "check.schema.json" }
+          }
+        }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "required": ["pass", "warn", "fail", "skip"],
+      "properties": {
+        "pass": { "type": "integer" },
+        "warn": { "type": "integer" },
+        "fail": { "type": "integer" },
+        "skip": { "type": "integer" }
+      }
+    }
+  }
+}