@crvouga/dev-fleet 0.7.0 → 0.9.0

package/schema/check-ids.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "check-ids.schema.json",
+  "title": "The check-ID registry, version 1",
+  "description": "schema/check-ids.json: every check ID dev-fleet reports, generated from the code.",
+  "type": "object",
+  "required": ["version", "checks"],
+  "properties": {
+    "version": { "const": 1 },
+    "checks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "meaning", "severity", "repair"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z0-9-]+(:[A-Za-z0-9:.*_-]+)?$"
+          },
+          "meaning": { "type": "string" },
+          "severity": { "enum": ["required", "advisory"] },
+          "requirement": { "const": true },
+          "repair": {
+            "type": "object",
+            "properties": {
+              "recipe": { "type": "string" },
+              "manual": { "type": "string" }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/schema/fleet.schema.json

@@ -53,27 +53,45 @@
         "neverSleepOnPower": {
           "const": true,
           "description": "Workers depend on the manager's singleton services, so it never sleeps on AC power."
+        },
+        "schedule": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "How often the manager's scheduled jobs run. Each defaults to the interval in ansible/macos/policy.json.",
+          "properties": {
+            "syncMinutes": {
+              "type": "integer",
+              "minimum": 5,
+              "maximum": 1440,
+              "description": "fleet-sync --schedule converges the fleet this often (default 30)."
+            },
+            "watchMinutes": {
+              "type": "integer",
+              "minimum": 5,
+              "maximum": 1440,
+              "description": "fleet-watch checks the fleet and stores its heartbeat this often (default 15). Keep it well under the max-age-minutes of the heartbeat workflow."
+            }
+          }
         }
       }
     },
     "workers": {
       "type": "array",
-      "minItems": 1,
       "maxItems": 64,
       "items": {
         "type": "object",
         "additionalProperties": false,
-        "required": ["id", "ssh", "os"],
+        "required": ["id", "os"],
         "properties": {
           "id": {
             "type": "string",
             "pattern": "^[a-z][a-z0-9-]{0,62}$",
-            "description": "A short stable id for the worker. The first worker listed is the canary: a revision new to the fleet must pass there before the others receive it."
+            "description": "A short stable id for the worker. A revision new to the fleet must pass on one worker, the canary, before the others receive it: the one named under canary, or else the first reachable worker in this order."
           },
           "ssh": {
             "type": "string",
             "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]{0,252}$",
-            "description": "The worker's Host alias in the manager's ~/.ssh/config. It must work with BatchMode=yes and a host key already in known_hosts."
+            "description": "Optional: a Host alias in the operator's own ~/.ssh/config, checked against their own known_hosts. Without one the worker is reached from its network block (user, sshPort, tailscaleName) with a host key pinned in the fleet state or given as network.hostKey, against a known_hosts file dev-fleet owns; the operator's ~/.ssh is neither read for it nor changed."
           },
           "os": {
             "const": "linux",
@@ -105,9 +123,38 @@
                 "minimum": 1,
                 "maximum": 65535,
                 "description": "The port the worker T3 server listens on, normally 3773."
+              },
+              "hostKey": {
+                "type": "string",
+                "pattern": "^(ssh-ed25519|ecdsa-sha2-nistp256|ssh-rsa) [A-Za-z0-9+/=]{16,}$",
+                "description": "The SSH host public key, \"TYPE BASE64\", given as data (a worker record writes it). It is the pinned key; a worker without one is pinned in the fleet state (fleet-node-replace --host-key, fleet-node-seed --apply)."
               }
             }
           },
+          "features": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "preset": {
+                "enum": ["editing"],
+                "description": "A named set of features, applied before the fields beside it. editing: no containers, a headless session and only the base tools (it adds no tool profile)."
+              },
+              "containers": {
+                "type": "boolean",
+                "description": "Docker on the worker: its packages, service, docker group membership, the docker-cli tool and the Docker step of the disk GC. Default true. Turning it off on an existing worker removes what dev-fleet installed for it; fleet-sync --dry-run lists what."
+              },
+              "session": {
+                "enum": ["desktop", "headless"],
+                "description": "How the worker runs T3. desktop (default): the pinned desktop app in an auto-login graphical session. headless: the pinned T3 server as a lingering user service, with no display manager. ~/.t3 is kept when this changes."
+              }
+            },
+            "description": "This worker's features, over the fleet-wide worker.features."
+          },
+          "powerRecoveryNote": {
+            "type": "string",
+            "pattern": "^[^\\n\\r]{1,120}$",
+            "description": "On a virtual machine, who restarts it after a power loss (for example: provider restarts instances). Shown with worker:power-loss-recovery, which is not applicable to a virtual machine."
+          },
           "toolProfiles": {
             "type": "array",
             "uniqueItems": true,
@@ -115,10 +162,152 @@
               "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."
+          },
+          "exposure": {
+            "type": "object",
+            "additionalProperties": false,
+            "description": "What this worker opens beyond loopback and the tailnet. A field named here replaces the one of worker.exposure.",
+            "properties": {
+              "publicSsh": {
+                "type": "boolean",
+                "description": "Break-glass: keep the SSH port open beyond the tailnet. Default false: after enrolment SSH is reached only over the tailnet."
+              },
+              "publicPorts": {
+                "type": "array",
+                "maxItems": 32,
+                "uniqueItems": true,
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["protocol", "port"],
+                  "properties": {
+                    "protocol": {
+                      "enum": ["tcp", "udp"]
+                    },
+                    "port": {
+                      "type": "integer",
+                      "minimum": 1,
+                      "maximum": 65535
+                    }
+                  }
+                },
+                "description": "Ports opened on every interface; a listener on one passes worker:exposure. Default none."
+              },
+              "otherListeners": {
+                "enum": ["warn", "fail"],
+                "description": "How worker:exposure reports a listener beyond loopback and the tailnet that no fleet service owns, such as an agent's development server on 0.0.0.0. The firewall closes it either way. Default warn; a fleet service there always fails."
+              }
+            }
+          },
+          "labels": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string",
+              "pattern": "^[^\\u0000-\\u001f\\u007f]{0,128}$"
+            },
+            "description": "Free-form labels, from a worker record; only displayed. Names are lowercase, at most 32 of them."
+          },
+          "billing": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["hourlyRate"],
+            "properties": {
+              "hourlyRate": {
+                "type": "number",
+                "minimum": 0,
+                "description": "What one hour of running costs, as you declare it. dev-fleet asks no pricing API; it only displays and sums it."
+              },
+              "currency": {
+                "type": "string",
+                "pattern": "^[A-Z]{3}$"
+              },
+              "note": {
+                "type": "string",
+                "pattern": "^[^\\u0000-\\u001f\\u007f]{1,200}$"
+              }
+            },
+            "description": "What the worker costs while it runs: fleet-status sums it for idle workers."
+          },
+          "origin": {
+            "const": "records",
+            "description": "Written by dev-fleet for a worker read from workerRecords, in the copy it installs and stores; do not write it."
           }
         }
       }
     },
+    "canary": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]{0,62}$",
+      "description": "The id of the worker that proves a revision new to the fleet first. When it is unreachable, the next reachable worker proves it instead. Default: the first reachable worker."
+    },
+    "workerRecords": {
+      "type": "array",
+      "maxItems": 8,
+      "items": {
+        "oneOf": [
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["file"],
+            "properties": {
+              "file": {
+                "type": "string",
+                "description": "A JSON file of worker records (schema/worker-record.schema.json), relative to fleet.json."
+              }
+            }
+          },
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["command"],
+            "properties": {
+              "command": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                  "type": "string"
+                },
+                "description": "A command run where fleet.json is that prints worker records, such as an infrastructure tool printing its outputs."
+              }
+            }
+          }
+        ]
+      },
+      "description": "Where generated worker records are read: their workers join the list above. An infrastructure tool writes them; dev-fleet only reads them and never creates a machine. A worker whose record disappears is retired by the next fleet-sync."
+    },
+    "parking": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "idleAfterHours": {
+          "type": "number",
+          "minimum": 1,
+          "maximum": 8760,
+          "description": "A worker that has run no agent turn for longer is reported as worker:idle."
+        },
+        "autoPark": {
+          "type": "boolean",
+          "description": "fleet-watch parks a worker idle longer than idleAfterHours. Off unless true."
+        },
+        "stop": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string"
+          },
+          "description": "Run with the worker ID as its last argument when the worker is parked."
+        },
+        "start": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string"
+          },
+          "description": "Run with the worker ID as its last argument when the worker is resumed."
+        }
+      },
+      "description": "Workers that are stopped on purpose (fleet-node-park) and when an idle one is reported."
+    },
     "services": {
       "type": "object",
       "additionalProperties": false,
@@ -162,7 +351,9 @@
                       },
                       "order": {
                         "type": "array",
-                        "items": { "type": "string" },
+                        "items": {
+                          "type": "string"
+                        },
                         "description": "Account labels (sign-in emails) first, in this order; the others follow in the order of their routing prefix."
                       }
                     }
@@ -259,7 +450,9 @@
         },
         "architectures": {
           "type": "array",
-          "items": { "enum": ["amd64", "arm64"] },
+          "items": {
+            "enum": ["amd64", "arm64"]
+          },
           "description": "Exactly the architectures the policy names for that release."
         }
       },
@@ -319,6 +512,25 @@
         "neverSleep": {
           "const": true
         },
+        "features": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "preset": {
+              "enum": ["editing"],
+              "description": "A named set of features, applied before the fields beside it. editing: no containers, a headless session and only the base tools (it adds no tool profile)."
+            },
+            "containers": {
+              "type": "boolean",
+              "description": "Docker on the worker: its packages, service, docker group membership, the docker-cli tool and the Docker step of the disk GC. Default true. Turning it off on an existing worker removes what dev-fleet installed for it; fleet-sync --dry-run lists what."
+            },
+            "session": {
+              "enum": ["desktop", "headless"],
+              "description": "How the worker runs T3. desktop (default): the pinned desktop app in an auto-login graphical session. headless: the pinned T3 server as a lingering user service, with no display manager. ~/.t3 is kept when this changes."
+            }
+          },
+          "description": "Features every worker has unless its own features say otherwise. Absent: containers and a desktop session, as before features existed."
+        },
         "toolProfiles": {
           "type": "array",
           "uniqueItems": true,
@@ -335,6 +547,42 @@
             "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."
+        },
+        "exposure": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "What every worker opens beyond loopback and the tailnet. Without it inbound traffic arrives only over loopback and the tailnet, sshd takes keys only and no root login, and published container ports are closed beyond the tailnet.",
+          "properties": {
+            "publicSsh": {
+              "type": "boolean",
+              "description": "Break-glass: keep the SSH port open beyond the tailnet. Default false: after enrolment SSH is reached only over the tailnet."
+            },
+            "publicPorts": {
+              "type": "array",
+              "maxItems": 32,
+              "uniqueItems": true,
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["protocol", "port"],
+                "properties": {
+                  "protocol": {
+                    "enum": ["tcp", "udp"]
+                  },
+                  "port": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 65535
+                  }
+                }
+              },
+              "description": "Ports opened on every interface; a listener on one passes worker:exposure. Default none."
+            },
+            "otherListeners": {
+              "enum": ["warn", "fail"],
+              "description": "How worker:exposure reports a listener beyond loopback and the tailnet that no fleet service owns, such as an agent's development server on 0.0.0.0. The firewall closes it either way. Default warn; a fleet service there always fails."
+            }
+          }
         }
       },
       "description": "Policy every worker must meet. All but the two logins, the capabilities and the tools are fixed."
@@ -355,7 +603,9 @@
       "type": "array",
       "minItems": 1,
       "uniqueItems": true,
-      "items": { "enum": ["t3"] },
+      "items": {
+        "enum": ["t3"]
+      },
       "description": "The IDEs every machine runs. Defaults to [\"t3\"]; the README's support matrix lists the supported ones."
     },
     "t3": {
@@ -368,16 +618,23 @@
           "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" }
+            "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}$" },
+          "propertyNames": {
+            "pattern": "^[a-zA-Z][a-zA-Z0-9_-]{0,63}$"
+          },
           "additionalProperties": {
             "type": "array",
-            "items": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }
+            "items": {
+              "type": "string",
+              "pattern": "^[A-Za-z0-9._:-]{1,128}$"
+            }
           }
         }
       }
@@ -626,6 +883,38 @@
                       "pattern": "^[A-Za-z0-9_]+$"
                     }
                   }
+                },
+                "tailnet-auth-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": "Optional: a short-lived, single-use, tagged Tailscale auth key a new worker joins the tailnet with (fleet-node-seed)."
+                },
+                "tailnet-admin": {
+                  "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 tailnet: an API credential of the tailnet's control plane that creates single-use auth keys for new workers. It stays on the manager."
                 }
               },
               "description": "Required for every secret except github-token, which defaults to the field GITHUB_TOKEN beside proxy-client-key."
@@ -654,6 +943,10 @@
           "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."
+        },
+        "signing": {
+          "enum": ["ssh"],
+          "description": "Sign every commit and tag. ssh: each node makes an SSH key of its own (~/.ssh/dev-fleet-git-signing), which never leaves it, and signs with it; measured as worker:git-signing. GitHub shows the commits as verified once each node's public key is added as a signing key to the account."
         }
       }
     },
@@ -740,6 +1033,52 @@
           "description": "owner/name of a repository fleet-github-verify branches, pushes to and opens pull requests on, then cleans up."
         }
       }
+    },
+    "tailnet": {
+      "description": "Optional: the tailnet control plane fleet-sync and fleet-node-seed enrol new workers with, without a login on the machine. Its credential is the secret tailnet-admin.",
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["api", "tag"],
+          "properties": {
+            "api": { "const": "tailscale" },
+            "url": {
+              "type": "string",
+              "pattern": "^https://[A-Za-z0-9.-]{1,253}(:[0-9]{1,5})?$",
+              "description": "The API origin. Default: https://api.tailscale.com."
+            },
+            "tag": {
+              "type": "string",
+              "pattern": "^tag:[a-z0-9][a-z0-9-]{0,62}$",
+              "description": "The tag every enrolled worker carries, so access rules and key expiry apply to workers as a group."
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["api", "url", "tag", "user"],
+          "properties": {
+            "api": { "const": "headscale" },
+            "url": {
+              "type": "string",
+              "pattern": "^https://[A-Za-z0-9.-]{1,253}(:[0-9]{1,5})?$",
+              "description": "The Headscale server: its API, and the login server workers join."
+            },
+            "tag": {
+              "type": "string",
+              "pattern": "^tag:[a-z0-9][a-z0-9-]{0,62}$",
+              "description": "The tag every enrolled worker carries, so access rules apply to workers as a group."
+            },
+            "user": {
+              "type": "string",
+              "pattern": "^[A-Za-z0-9._@-]{1,64}$",
+              "description": "The Headscale user the keys belong to (its ID from Headscale 0.26)."
+            }
+          }
+        }
+      ]
     }
   }
 }

package/schema/output/check.schema.json

@@ -7,7 +7,7 @@
   "required": ["id", "status", "summary"],
   "properties": {
     "id": { "type": "string", "pattern": "^[a-z0-9-]+(:[A-Za-z0-9:._-]+)?$" },
-    "status": { "enum": ["pass", "warn", "fail", "skip"] },
+    "status": { "enum": ["pass", "warn", "fail", "skip", "not-applicable"] },
     "summary": { "type": "string" },
     "required": { "type": "boolean" },
     "phaseDurationMs": { "type": "number" },

package/schema/output/fleet-state-definition.schema.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "fleet-state-definition.schema.json",
+  "title": "A fleet configuration printed by fleet-state, version 1",
+  "description": "What devfleet fleet-state --example and fleet-state --export print with --json: the configuration itself is definition, and follows schema/fleet.schema.json.",
+  "type": "object",
+  "required": ["version", "command", "ok", "definition"],
+  "properties": {
+    "version": { "const": 1 },
+    "command": { "const": "fleet-state" },
+    "ok": { "const": true },
+    "definition": { "type": "object" }
+  }
+}

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

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "fleet-sync-schedule.schema.json",
+  "title": "The fleet-sync --schedule report, version 2",
+  "description": "What devfleet fleet-sync --schedule ACTION prints with --json. status names whether the schedule is installed, its interval, its last three runs and the manager:schedule check; enable, pause, resume and disable say whether the change was made.",
+  "type": "object",
+  "required": ["version", "command", "scheduling"],
+  "properties": {
+    "version": { "const": 2 },
+    "command": { "const": "fleet-sync" },
+    "execution": { "const": "manager-push" },
+    "ok": { "type": "boolean" },
+    "scheduling": {
+      "type": ["string", "object"],
+      "properties": {
+        "installed": { "type": "boolean" },
+        "supported": { "type": "boolean" }
+      }
+    },
+    "intervalSeconds": { "type": "integer" },
+    "revision": { "type": "string" },
+    "summary": { "type": "string" },
+    "runs": { "type": "array", "items": { "type": "object" } },
+    "checks": { "type": "array", "items": { "$ref": "check.schema.json" } }
+  }
+}

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

@@ -27,6 +27,12 @@
     "candidates": { "type": "integer" },
     "dashboardUrl": { "type": ["string", "null"] },
     "planFingerprint": { "type": "string" },
+    "canary": { "type": "string" },
+    "enrolled": {
+      "description": "The workers this run enrolled: added to the roster, or bound to their tailnet device.",
+      "type": "array",
+      "items": { "type": "string" }
+    },
     "nodes": {
       "type": "array",
       "items": {
@@ -105,6 +111,18 @@
               "changes": { "type": "boolean" }
             }
           }
+        },
+        "removals": {
+          "type": "array",
+          "description": "What the sync removes from a worker whose features the fleet configuration turned off since it was last applied.",
+          "items": {
+            "type": "object",
+            "required": ["node", "removes"],
+            "properties": {
+              "node": { "type": "string" },
+              "removes": { "type": "array", "items": { "type": "string" } }
+            }
+          }
         }
       }
     }

package/schema/output/report.schema.json

@@ -26,12 +26,13 @@
     },
     "summary": {
       "type": "object",
-      "required": ["pass", "warn", "fail", "skip"],
+      "required": ["pass", "warn", "fail", "skip", "not-applicable"],
       "properties": {
         "pass": { "type": "integer" },
         "warn": { "type": "integer" },
         "fail": { "type": "integer" },
-        "skip": { "type": "integer" }
+        "skip": { "type": "integer" },
+        "not-applicable": { "type": "integer" }
       }
     }
   }