backlot 0.4.0

package/schema/stack.schema.json

@@ -0,0 +1,172 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/backlot-dev/backlot/main/schema/stack.schema.json",
+  "title": "backlot stack manifest (stack.yaml)",
+  "description": "What a repo declares so backlot can broker environments for it. Everything {{...}} is injected by the engine (symbolic ports, datastore URLs, service URLs). Policy (pool sizes, TTLs, substrates) never lives here.",
+  "type": "object",
+  "required": ["name", "services"],
+  "additionalProperties": false,
+  "properties": {
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]*$",
+      "description": "Stack identity; pools are keyed by repo + this name."
+    },
+    "services": {
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": { "$ref": "#/$defs/service" },
+      "description": "Supervised shell commands, one per service. Commands, not containers."
+    },
+    "datastores": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#/$defs/datastore" }
+    },
+    "caches": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Paths (globs allowed) preserved by the bind-time reset: node_modules, **/obj, .angular, ..."
+    },
+    "sync": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "keep": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Generated files preserved across binds even though tracked/derived."
+        },
+        "include": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Git-ignored files that must ride along with a binding (.env.local)."
+        }
+      }
+    },
+    "outputs": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Artifacts produced env-side but owned worktree-side (lockfiles, generated clients). Reported as outputs_changed; copied back only by explicit `backlot pull`."
+    },
+    "upkeep": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/upkeepRule" },
+      "description": "Closed list of fingerprint->action rules, run at bind time in order (decision 0008)."
+    },
+    "auth": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "logins": {
+          "type": "object",
+          "required": ["user", "password"],
+          "additionalProperties": false,
+          "properties": {
+            "user": { "type": "string" },
+            "password": { "type": "string" }
+          },
+          "description": "A seeded login consumers may use. Dev-grade by definition."
+        },
+        "token": {
+          "type": "string",
+          "description": "Command minting an auth token; {{role}} available. Must print JSON."
+        }
+      }
+    },
+    "checks": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#/$defs/check" },
+      "description": "Named runnable proofs (e2e, smoke). `backlot run <name>`."
+    }
+  },
+  "$defs": {
+    "service": {
+      "type": "object",
+      "required": ["run"],
+      "additionalProperties": false,
+      "properties": {
+        "run": { "type": "string", "description": "The supervised process. Daemon is its parent." },
+        "build": { "type": "string", "description": "Run at bind when fingerprints demand; never during serve." },
+        "watch_run": { "type": "string", "description": "Hot-reload alternative to run:, used only by --watch session leases." },
+        "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 the number and injects {{ports.<name>}}. Omit for portless services (workers)."
+        },
+        "env": {
+          "type": "object",
+          "additionalProperties": { "type": "string" },
+          "description": "Injected environment; values may template {{ports.*}}, {{datastores.*.url}}, {{services.*.url}}."
+        },
+        "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."
+        }
+      }
+    },
+    "readiness": {
+      "type": "object",
+      "additionalProperties": false,
+      "minProperties": 1,
+      "properties": {
+        "http": { "type": "string", "description": "Path polled on the service's port until 200." },
+        "log": { "type": "string", "description": "ERE that must appear in the service log (portless services)." },
+        "cmd": { "type": "string", "description": "Command that must exit 0." },
+        "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": "backlot 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/checks; {{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. Best-effort (run before restore and on recycle)." },
+        "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 once per seed-content hash and every bind restores in seconds." },
+        "presets": { "type": "array", "items": { "type": "string" }, "description": "Named seed states." },
+        "default_preset": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "run": { "type": "string" },
+            "session": { "type": "string" }
+          }
+        },
+        "template": { "type": "boolean", "default": false, "description": "sqlite only: bake a template file per seed-content hash and restore by copy. Server drivers use template_restore instead." },
+        "ephemeral": { "type": "boolean", "default": false, "description": "No presets; reset-data = flush (Redis-class)." }
+      }
+    },
+    "upkeepRule": {
+      "type": "object",
+      "required": ["when", "run"],
+      "additionalProperties": false,
+      "properties": {
+        "when": { "type": "string", "description": "A file path or glob(...) whose content hash triggers the rule (direction-agnostic per-env ledger)." },
+        "run": { "type": "string", "description": "Repo command, or an engine built-in prefixed with @ (e.g. @rebake-template <datastore>)." }
+      }
+    },
+    "check": {
+      "type": "object",
+      "required": ["run"],
+      "additionalProperties": false,
+      "properties": {
+        "run": { "type": "string" },
+        "cwd": { "type": "string" },
+        "env": { "type": "object", "additionalProperties": { "type": "string" } },
+        "artifacts": { "type": "array", "items": { "type": "string" }, "description": "Globs collected into the verdict's artifacts dir." },
+        "timeout": { "type": "number", "default": 600, "description": "Seconds before the check's whole process group is killed — a hung check must never hold its environment forever." }
+      }
+    }
+  }
+}