@theford/runly 0.0.0-stage → 0.20.0

package/schema/backlot.schema.json

@@ -0,0 +1,549 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/backlot-dev/backlot/main/schema/backlot.schema.json",
+  "title": "Runly stack manifest (runly.yml; backlot.yml and stack.yaml accepted)",
+  "description": "What a repo declares so runly can run environments for it, in the worktree the manifest lives in. Everything {{...}} is injected by the engine (ports, public_ports, services.<svc>.url, datastores.<ds>.url/.ns). Policy (TTLs, pool caps, the load budget, substrates) never lives here.",
+  "type": "object",
+  "required": [
+    "name",
+    "services"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]*$",
+      "description": "Stack name. A stack is this name plus the worktree the manifest is in; each worktree has one environment."
+    },
+    "services": {
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": {
+        "$ref": "#/$defs/service"
+      },
+      "description": "Supervised shell commands, one per service, run in the worktree. Commands, not containers."
+    },
+    "appliances": {
+      "type": "object",
+      "description": "Singular, machine-shared backing services (a Postgres server, a Redis) that environments point at but never own. Ensured (probe -> start once machine-wide -> wait), never supervised, never stopped automatically.",
+      "additionalProperties": {
+        "$ref": "#/$defs/appliance"
+      }
+    },
+    "datastores": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/$defs/datastore"
+      },
+      "description": "Data an environment owns: one namespace per environment (and per `runly db` copy) on an externally run server, or a sqlite file."
+    },
+    "builds": {
+      "enum": [
+        "parallel",
+        "serial"
+      ],
+      "default": "parallel",
+      "description": "How one `up` (or `warm`) runs its services' builds. `parallel` (default): in depends_on waves \u2014 a build runs after the builds of what its service depends on, and the builds of one wave run at once (the load budget holds the costliest wave's summed resources). `serial`: one at a time, in manifest order \u2014 for builds that share an output or a lock the build tool does not handle."
+    },
+    "caches": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Build and install output inside the worktree (node_modules, **/obj, .angular, ...). Environments run in the worktree (decision 0032), so this is what is NOT source: an upkeep `when:` glob never matches it. runly never deletes it."
+    },
+    "sync": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "keep": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Accepted and ignored."
+        },
+        "include": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Git-ignored files that still count as source (.env.local), so an upkeep `when:` glob can match them."
+        }
+      },
+      "description": "Only `include` is read; `keep` is accepted and ignored."
+    },
+    "outputs": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Accepted and ignored. Build outputs that decide a restart are declared per service (`services.<name>.outputs`)."
+    },
+    "upkeep": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/upkeepRule"
+      },
+      "description": "Closed list of (trigger files -> command) rules, run in order by `up` and `runly warm` when the content of a rule's trigger files changed since it last ran in this worktree."
+    },
+    "auth": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "logins": {
+          "oneOf": [
+            {
+              "$ref": "#/$defs/login"
+            },
+            {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "$ref": "#/$defs/login"
+              }
+            }
+          ],
+          "description": "Seeded login(s) consumers may use. Dev-grade by definition. A single object is one login; a list declares several, and the FIRST is the primary one `ctx.logins` reports."
+        },
+        "token": {
+          "type": "string",
+          "description": "Command printing an auth token on stdout (trimmed; `runly token` wraps it as {token, role}); {{role}} available, also as RUNLY_ROLE in its environment. Runs in the worktree."
+        }
+      }
+    },
+    "checks": {
+      "type": "object",
+      "description": "Accepted and ignored, with a one-line warning: runly runs no checks. Repo scripts read the environment from `runly ctx --env`."
+    },
+    "preview": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "forbidden": {
+          "type": "boolean",
+          "description": "When true, `runly preview` is refused (work-error), and a bind ends a live preview. Stacks with fixed dev credentials must set this."
+        },
+        "publisher": {
+          "type": "string",
+          "description": "Named preview publisher adapter (default: cloudflare-quick). Known: cloudflare-quick, cloudflare-named, tailscale (tailnet-only HTTPS via `tailscale serve`)."
+        },
+        "domain": {
+          "type": "string",
+          "description": "Zone a naming publisher publishes under, e.g. example.dev. Required by cloudflare-named; ignored by cloudflare-quick."
+        },
+        "prefix": {
+          "type": "string",
+          "description": "What makes a hostname this environment's own (<service>-<prefix>.<domain>). Unset means the environment id, which is unique by construction; set it only to pin a memorable name, and only where one environment of this stack runs at a time."
+        },
+        "https_port": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 65535,
+          "description": "tailscale publisher only: the HTTPS port on this machine's tailnet name. Unset means a port derived from the environment id and service, stable for the environment's lifetime. Pin it only where one environment of this stack publishes at a time; ignored by the Cloudflare publishers."
+        }
+      }
+    }
+  },
+  "$defs": {
+    "login": {
+      "type": "object",
+      "required": [
+        "user",
+        "password"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "user": {
+          "type": "string"
+        },
+        "password": {
+          "type": "string"
+        },
+        "role": {
+          "type": "string",
+          "description": "The role this login stands for, matching the {{role}} an `auth.token` hook takes. Informational."
+        },
+        "description": {
+          "type": "string",
+          "description": "What this login is FOR \u2014 the scope or permissions it exercises, so a consumer can pick the right one without reading the seed."
+        }
+      }
+    },
+    "service": {
+      "type": "object",
+      "required": [
+        "run"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "run": {
+          "type": "string",
+          "description": "The supervised process; the daemon is its parent. Runs in the worktree (or `cwd`) under `sh` (dash on Ubuntu, bash-as-sh on macOS) \u2014 write POSIX sh, no bashisms."
+        },
+        "build": {
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "object",
+              "required": [
+                "run"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "run": {
+                  "type": "string",
+                  "description": "The build command."
+                },
+                "when": {
+                  "type": "array",
+                  "minItems": 1,
+                  "items": {
+                    "type": "string"
+                  },
+                  "description": "Globs (relative to the stack root, git-listed, minus caches:) of what the build reads. While none of the matched files changed (path, size, mtime) since the last SUCCESSFUL build of this service in this worktree, the build is skipped and `up` says so; `up --rebuild` forces it."
+                },
+                "serial": {
+                  "type": "boolean",
+                  "default": false,
+                  "description": "Run this build alone, never at the same time as another service's build. By default the builds of services that do not depend on each other run at once (depends_on waves)."
+                }
+              }
+            }
+          ],
+          "description": "String form: runs on every `up` that starts or keeps this service, and on every `runly warm` \u2014 runly keeps no build cache; the build tool decides what is current. Object form `{run, when, serial}`: skipped while its `when:` files are unchanged since the last successful build and its `outputs:` are still what that build left; `serial: true` runs it alone. Builds otherwise run in depends_on waves (see top-level `builds`). Runs under `sh` (dash on Ubuntu, bash-as-sh on macOS) \u2014 write POSIX sh, no bashisms."
+        },
+        "outputs": {
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            {
+              "type": "object",
+              "required": [
+                "paths"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "paths": {
+                  "type": "array",
+                  "minItems": 1,
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "compare": {
+                  "enum": [
+                    "stat",
+                    "content"
+                  ],
+                  "default": "stat",
+                  "description": "stat: path, size and mtime (default). content: hash the files, so a build that rewrites identical files does not restart the service."
+                }
+              }
+            }
+          ],
+          "description": "Globs (relative to the stack root) of what `build:` produces, e.g. `backend/Host/bin/**` or `dist/web`. Every `up` snapshots them around the build and restarts this service only when they changed. Without it, a service with a build is restarted after every build. The object form chooses how they are compared."
+        },
+        "watch_run": {
+          "type": "string",
+          "description": "Accepted and ignored; the service always runs `run:`."
+        },
+        "cwd": {
+          "type": "string",
+          "description": "Working directory relative to the repo root."
+        },
+        "port": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*$",
+          "description": "Symbolic port name; the engine allocates a public port (held by the daemon's proxy) and starts the service on an internal one. In this service's own run/env, {{ports.<name>}} is the internal port to listen on; everywhere else it is the public port ({{public_ports.<name>}} is always public). Omit for portless services (workers)."
+        },
+        "env": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          },
+          "description": "Injected environment; values may template {{ports.*}}, {{public_ports.*}}, {{services.*.url}}, {{datastores.*.url}}, {{datastores.*.ns}}."
+        },
+        "env_from": {
+          "type": "object",
+          "propertyNames": {
+            "pattern": "^(?!BACKLOT_)[A-Za-z_][A-Za-z0-9_]*$"
+          },
+          "additionalProperties": {
+            "enum": [
+              "required",
+              "optional"
+            ]
+          },
+          "description": "Allowlisted caller environment inputs: `required` refuses an `up` without the variable, `optional` may be missing. Every `up` refreshes the values from its caller; reset-data keeps them. A supplied value overrides a same-named env entry; a missing optional input keeps an explicit env default, otherwise masks the daemon's value. Memory only: re-run up after a daemon restart. Not passed to builds, upkeep or exec."
+        },
+        "ready": {
+          "$ref": "#/$defs/readiness"
+        },
+        "fatal_logs": {
+          "type": "string",
+          "description": "ERE of log markers that fail a boot in seconds instead of polling readiness to timeout."
+        },
+        "depends_on": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Services that must be ready before this one starts. `up <svc>` starts them too, and a wake starts them through their ports; a service whose readiness needs another must list it."
+        },
+        "hot_reload": {
+          "type": "boolean",
+          "description": "Accepted and ignored. Whether an `up` restarts a running service is decided by its build `outputs:`; a service without a build keeps running."
+        },
+        "idle": {
+          "oneOf": [
+            {
+              "type": "string",
+              "pattern": "^(never|off|[0-9]+(\\.[0-9]+)?\\s*(ms|s|m|h))$"
+            },
+            {
+              "type": "number",
+              "minimum": 0
+            }
+          ],
+          "description": "How long this service may go without client bytes through its public port and without a runly verb on its environment before it is stopped; the next connection to its port starts it again (leased environments only). A duration (90s, 10m, 2h), seconds as a number, or `never`/`off`. Default BACKLOT_SERVICE_IDLE_MS (10 minutes)."
+        },
+        "resources": {
+          "$ref": "#/$defs/resources"
+        }
+      }
+    },
+    "readiness": {
+      "type": "object",
+      "additionalProperties": false,
+      "minProperties": 1,
+      "properties": {
+        "http": {
+          "type": "string",
+          "description": "Path requested on the service's internal port until it answers 200."
+        },
+        "log": {
+          "type": "string",
+          "description": "ERE that must appear in the service log (portless services)."
+        },
+        "cmd": {
+          "type": "string",
+          "description": "Command that must exit 0 (run in the worktree)."
+        },
+        "timeout": {
+          "type": "number",
+          "default": 120,
+          "description": "Seconds before service-not-ready."
+        }
+      }
+    },
+    "datastore": {
+      "type": "object",
+      "required": [
+        "driver"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "driver": {
+          "type": "string",
+          "enum": [
+            "sqlite",
+            "postgres",
+            "mssql",
+            "mysql",
+            "redis"
+          ]
+        },
+        "server": {
+          "type": "string",
+          "enum": [
+            "external"
+          ],
+          "default": "external",
+          "description": "runly never runs datastore servers; it probes them."
+        },
+        "probe": {
+          "type": "string",
+          "description": "host:port TCP-probed before anything starts (server drivers). Failure is an infra-error, never code blame."
+        },
+        "url": {
+          "type": "string",
+          "description": "Connection-string template handed to services, `ctx` and `runly ctx --env`; {{ns}} available. Required for server drivers; ignored for sqlite (the ns IS the file path)."
+        },
+        "create": {
+          "type": "string",
+          "description": "Repo command that creates+seeds a namespace; {{ns}} and {{preset}} available."
+        },
+        "drop": {
+          "type": "string",
+          "description": "Repo command that drops a namespace; {{ns}} available. Run before a restore, at teardown and for copies (recorded when the namespace is created, so a later drop needs no manifest). Required for `runly db` copies of a server datastore."
+        },
+        "template_restore": {
+          "type": "string",
+          "description": "Repo command that clones a baked template namespace into a fresh one; {{template}} and {{ns}} available (e.g. postgres: createdb -T {{template}} {{ns}}). When present, `create` bakes a template once per preset and template key (the create command, plus the trigger content of an @rebake-template rule), and every bind and copy restores from it."
+        },
+        "presets": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Named seed states; `--preset` and `default_preset` must name one of them. Omitted: the preset is `default` (or the default_preset name)."
+        },
+        "default_preset": {
+          "description": "The preset a datastore is created with when none is named (default: the first of `presets`). A preset name, or `{session, run}` read as one value (session, then run).",
+          "oneOf": [
+            {
+              "type": "string",
+              "minLength": 1
+            },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "run": {
+                  "type": "string"
+                },
+                "session": {
+                  "type": "string"
+                }
+              }
+            }
+          ]
+        },
+        "template": {
+          "type": "boolean",
+          "default": false,
+          "description": "sqlite only: bake a template file per preset and template key, and restore by copy. Server drivers use template_restore instead."
+        },
+        "ephemeral": {
+          "type": "boolean",
+          "default": false,
+          "description": "No presets or templates; `create` runs on first bind and a reset runs `drop` as the flush (Redis-class)."
+        },
+        "copies_only": {
+          "type": "boolean",
+          "default": false,
+          "description": "Never provisioned for an environment: the datastore exists only as the source of `runly db new|with` copies (its template is baked on the first copy and reused after). No service may template it, `ctx` and `ctx --env` do not list it, and `up --preset` / `reset-data` cannot name it."
+        },
+        "share_templates": {
+          "type": "boolean",
+          "default": true,
+          "description": "Share this datastore's baked templates with every worktree of the same stack name on this daemon (decision 0044). Applies only to a content-keyed template — one an `@rebake-template` rule names, so its key is the create command plus the content of the rule's trigger files; without such a rule templates stay per worktree. Set false when the baked content depends on the worktree beyond those files (an absolute path written into the data, say)."
+        },
+        "list": {
+          "type": "string",
+          "description": "Repo command printing the namespaces ({{ns}} values) of this datastore that exist on its server, one per line. Read only by `runly pool doctor`: a listed name in runly's naming (backlot_...) that no journal row or template marker references is an orphan, which `--fix` drops with `drop:` (decision 0037)."
+        }
+      }
+    },
+    "upkeepRule": {
+      "type": "object",
+      "required": [
+        "when",
+        "run"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "when": {
+          "type": "string",
+          "description": "A file path or glob (optionally written glob(...)), relative to the stack root, whose matched files' content triggers the rule. Recorded per worktree, direction-agnostic: a changed hash in either direction runs it again."
+        },
+        "run": {
+          "type": "string",
+          "description": "Repo command run in the worktree, or the engine built-in `@rebake-template <datastore>` (rebakes that datastore's template)."
+        },
+        "timeout": {
+          "type": "number",
+          "exclusiveMinimum": 0,
+          "description": "Command deadline in seconds (default 300). BACKLOT_CMD_TIMEOUT_S overrides this value."
+        }
+      }
+    },
+    "appliance": {
+      "type": "object",
+      "required": [
+        "probe"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "probe": {
+          "type": "string",
+          "description": "host:port TCP-probed; reachability IS the appliance's identity \u2014 whoever answers is the appliance, no matter who started it."
+        },
+        "start": {
+          "type": "string",
+          "description": "Daemonizing repo command (e.g. docker run -d ...) run ONCE machine-wide when the probe fails. Absent = today's behavior: unreachable is an infra-error you resolve yourself."
+        },
+        "stop": {
+          "type": "string",
+          "description": "Repo command for the explicit `runly appliance stop` verb. Never run automatically \u2014 appliances are durable; heat is the point."
+        },
+        "ready": {
+          "type": "string",
+          "description": "Optional readiness gate polled after TCP accepts (exit 0 = ready), e.g. pg_isready \u2014 TCP-accept alone can precede real readiness."
+        },
+        "timeout": {
+          "type": "number",
+          "default": 60,
+          "description": "Seconds to wait after start for probe (and ready:) to pass before infra-error."
+        },
+        "resources": {
+          "$ref": "#/$defs/resources",
+          "description": "What the appliance costs while running; counted against the load budget when an `up` would start it. Its build: entry is ignored."
+        }
+      }
+    },
+    "size": {
+      "oneOf": [
+        {
+          "type": "string",
+          "pattern": "^[0-9]+(\\.[0-9]+)?\\s*([KMGT]i?B?|[kmgt]i?b?)?$"
+        },
+        {
+          "type": "number",
+          "minimum": 0
+        }
+      ],
+      "description": "A size: bytes as a number, or a string with a K/M/G/T suffix (600M, 2G, 1.5GiB)."
+    },
+    "resources": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "What this costs the box, for the server-wide load budget. Left out = a conservative default (run 512M / 0.5 cpu; build 1G / 1 cpu), which `runly plan` says it assumed.",
+      "properties": {
+        "memory": {
+          "$ref": "#/$defs/size",
+          "description": "Resident memory while running."
+        },
+        "cpu": {
+          "type": "number",
+          "exclusiveMinimum": 0,
+          "description": "Cores while running."
+        },
+        "build": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "What its `build:` costs while it runs; held only while building.",
+          "properties": {
+            "memory": {
+              "$ref": "#/$defs/size"
+            },
+            "cpu": {
+              "type": "number",
+              "exclusiveMinimum": 0
+            }
+          }
+        }
+      }
+    }
+  }
+}