Merge remote-tracking branch 'refs/remotes/origin/main'

8bitAlex · 8bitAlex · commit 2178c74d3f61 · 2026-05-11T14:35:08.000-07:00
diff --git a/README.md b/README.md
@@ -222,7 +222,7 @@ Supported formats: `.yaml`, `.yml`, `.json`
 
 Example `my-project.raid.yaml`:
 ```yaml
-# yaml-language-server: $schema=https://raw.githubusercontent.com/8bitalex/raid/main/schemas/raid-profile.schema.json
+# yaml-language-server: $schema=https://raidcli.dev/schema/v1/raid-profile.schema.json
 
 name: my-project
 
@@ -288,7 +288,7 @@ Multiple profiles can be defined in a single file using YAML document separators
 Individual repositories can carry their own `raid.yaml` at their root to define repo-specific environments and commands. These are merged with the profile configuration at load time. Committing this file to each repo is the primary way knowledge is shared — the command for running tests, applying patches, or starting a proxy lives here instead of in a wiki.
 
 ```yaml
-# yaml-language-server: $schema=https://raw.githubusercontent.com/8bitalex/raid/main/schemas/raid-repo.schema.json
+# yaml-language-server: $schema=https://raidcli.dev/schema/v1/raid-repo.schema.json
 
 name: my-service
 branch: main
diff --git a/docs/examples/demo.raid.yaml b/docs/examples/demo.raid.yaml
@@ -1,4 +1,4 @@
-# yaml-language-server: $schema=https://raw.githubusercontent.com/8bitalex/raid/main/schemas/raid-profile.schema.json
+# yaml-language-server: $schema=https://raidcli.dev/schema/v1/raid-profile.schema.json
 
 # This is a raid profile definition for a fictional company called Acme. It defines two repositories (web and api) 
 # and a development environment with tasks to set up and run the projects.
diff --git a/docs/examples/example.raid.yaml b/docs/examples/example.raid.yaml
@@ -1,4 +1,4 @@
-# yaml-language-server: $schema=../../schemas/raid-profile.schema.json
+# yaml-language-server: $schema=https://raidcli.dev/schema/v1/raid-profile.schema.json
 
 name: raid
 repositories:
diff --git a/docs/examples/raid.yaml b/docs/examples/raid.yaml
@@ -1,4 +1,4 @@
-# yaml-language-server: $schema=../../schemas/raid-repo.schema.json
+# yaml-language-server: $schema=https://raidcli.dev/schema/v1/raid-repo.schema.json
 
 name: raid
 branch: main
diff --git a/llms.txt b/llms.txt
@@ -41,9 +41,9 @@ Raid is written in Go, distributed as a single self-contained binary, and publis
 
 ## Schemas
 
-- [Profile JSON Schema](https://raw.githubusercontent.com/8bitalex/raid/main/schemas/raid-profile.schema.json): Validation schema for `*.raid.yaml` profile files
-- [Repository JSON Schema](https://raw.githubusercontent.com/8bitalex/raid/main/schemas/raid-repo.schema.json): Validation schema for per-repo `raid.yaml` files
-- [Shared definitions schema](https://raw.githubusercontent.com/8bitalex/raid/main/schemas/raid-defs.schema.json): Common type definitions referenced by both schemas
+- [Profile JSON Schema](https://raidcli.dev/schema/v1/raid-profile.schema.json): Validation schema for `*.raid.yaml` profile files (v1 — stable URL)
+- [Repository JSON Schema](https://raidcli.dev/schema/v1/raid-repo.schema.json): Validation schema for per-repo `raid.yaml` files (v1 — stable URL)
+- [Shared definitions schema](https://raidcli.dev/schema/v1/raid-defs.schema.json): Common type definitions referenced by both schemas (v1 — stable URL)
 - [SchemaStore catalog](https://www.schemastore.org/api/json/catalog.json): Published catalog entries — auto-discovered by VS Code, JetBrains, Neovim, and other editors using the schemastore catalog
 
 ## Examples
diff --git a/schemas/README.md b/schemas/README.md
@@ -1,51 +1,59 @@
 # Raid Schema Specifications
 
-This directory contains JSON Schema definitions for Raid configuration files.
+This directory contains the JSON Schema definitions for Raid configuration files.
+It is the **single source of truth** for the schemas — files here are both:
 
-## Schema Files
-
-- `raid-profile.schema.json` - Schema for raid profile configuration files
-- `raid-repo.schema.json` - Schema for individual repository configuration files
-
-## Schema Version
-
-These schemas follow the **JSON Schema Draft 2020-12** specification and are compatible with the `github.com/santhosh-tekuri/jsonschema/v6` library (v6.0.2).
+1. Embedded into the Go binary via `go:embed` (used at runtime to validate
+   profile and repo files), and
+2. Copied into `site/static/schema/v1/` by `site/plugins/copy-schemas.ts` at
+   docsite build time, so they are served at the canonical URLs:
 
-The `$schema` field is properly supported and the library fully validates against the JSON Schema Draft 2020-12 specification.
+   - https://raidcli.dev/schema/v1/raid-defs.schema.json
+   - https://raidcli.dev/schema/v1/raid-profile.schema.json
+   - https://raidcli.dev/schema/v1/raid-repo.schema.json
 
-## Usage
-
-The schemas are used to validate YAML and JSON configuration files in the Raid CLI tool. The validation ensures that configuration files have the correct structure and required fields.
+## Schema Files
 
-### Supported File Formats
+- `raid-defs.schema.json` — Shared `$defs` (task types, environments,
+  commands, install). Referenced from the other two schemas.
+- `raid-profile.schema.json` — Profile file schema (`*.raid.yaml`).
+- `raid-repo.schema.json` — Per-repository schema (`raid.yaml`).
 
-- YAML files (`.yaml`, `.yml`)
-- JSON files (`.json`)
+## Versioning
 
-### Validation
+The `/schema/v1/` path is a **public stability contract**.
 
-Profile files are validated against `raid-profile.schema.json` when using the `raid profile add` command. The validation checks:
+- Additive changes (new optional fields, new task types, new enum values) are
+  allowed within v1.
+- Breaking changes (renaming or removing a field, tightening a `required` list,
+  removing an enum value, turning an optional field required) require a new
+  major version. Cut a `/schema/v2/` folder by freezing the current v1 files
+  alongside the source and evolving the source separately.
+- Bump the second position of `version` in `src/resources/app.properties` when
+  publishing a new major schema version.
 
-- Required fields are present
-- Data types are correct
-- Structure matches the schema definition
+The `$id` fields are baked as absolute URLs so external validators resolve
+cross-references without depending on the retrieval URL. Internal validation
+(see `src/internal/lib/lib.go`) registers each embedded schema under its `$id`
+and compiles by URL — no network access at runtime.
 
-## Schema Structure
+## Schema draft
 
-### Raid Profile Schema
+These schemas follow **JSON Schema Draft 2020-12** and are validated with
+[`github.com/santhosh-tekuri/jsonschema/v6`](https://github.com/santhosh-tekuri/jsonschema)
+(v6.0.2).
 
-A raid profile configuration must contain:
+## Supported file formats
 
-- `name` (string, required) - The name of the raid profile
-- `repositories` (array, optional) - Array of repository configurations
-  - Each repository must have:
-    - `name` (string, required) - The name of the repository
-    - `path` (string, required) - The local path to the repository
-    - `url` (string, required) - The URL of the repository
+YAML (`.yaml`, `.yml`) and JSON (`.json`).
 
-### Raid Repository Schema
+## Usage
 
-A repository configuration must contain:
+Profile files are validated against `raid-profile.schema.json` by `raid profile
+add` and during config load. Repository `raid.yaml` files are validated against
+`raid-repo.schema.json` when a repo is loaded.
 
-- `name` (string, required) - The name of the repository
-- `branch` (string, required) - The branch to checkout
+Editors that consult [SchemaStore](https://www.schemastore.org/) — VS Code +
+Red Hat YAML, JetBrains, Neovim `yaml-language-server`, Helix — auto-associate
+`*.raid.yaml` and `raid.yaml` with the published schemas, so the `# yaml-language-server`
+modeline is optional.
diff --git a/schemas/raid-defs.schema.json b/schemas/raid-defs.schema.json
@@ -1,6 +1,6 @@
 {
     "$schema": "https://json-schema.org/draft/2020-12/schema",
-    "$id": "raid-defs.schema.json",
+    "$id": "https://raidcli.dev/schema/v1/raid-defs.schema.json",
     "title": "Raid Schema Definitions",
     "description": "Shared schema definitions for raid",
     "type": "object",
diff --git a/schemas/raid-profile.schema.json b/schemas/raid-profile.schema.json
@@ -1,6 +1,6 @@
-{ 
+{
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "raid-profile.schema.json",
+  "$id": "https://raidcli.dev/schema/v1/raid-profile.schema.json",
   "title": "Raid Profile Configuration",
   "description": "Configuration for one or more raid profiles.",
   "type": "object",
@@ -34,22 +34,21 @@
       "minItems": 1
     },
     "environments": {
-      "$ref": "raid-defs.schema.json#/properties/environments"
+      "$ref": "https://raidcli.dev/schema/v1/raid-defs.schema.json#/properties/environments"
     },
     "install": {
-      "$ref": "raid-defs.schema.json#/properties/install"
+      "$ref": "https://raidcli.dev/schema/v1/raid-defs.schema.json#/properties/install"
     },
     "task_groups": {
       "type": "object",
       "description": "Named reusable task sequences. Reference them in any task list with type: Group and ref: <name>.",
       "additionalProperties": {
-        "$ref": "raid-defs.schema.json#/properties/tasks"
+        "$ref": "https://raidcli.dev/schema/v1/raid-defs.schema.json#/properties/tasks"
       }
     },
     "commands": {
-      "$ref": "raid-defs.schema.json#/properties/commands"
+      "$ref": "https://raidcli.dev/schema/v1/raid-defs.schema.json#/properties/commands"
     }
   },
   "required": ["name"]
 }
-
diff --git a/schemas/raid-repo.schema.json b/schemas/raid-repo.schema.json
@@ -1,6 +1,6 @@
 {
     "$schema": "https://json-schema.org/draft/2020-12/schema",
-    "$id": "raid-repo.schema.json",
+    "$id": "https://raidcli.dev/schema/v1/raid-repo.schema.json",
     "title": "Raid Repository Configuration",
     "description": "Configuration for a single repository.",
     "type": "object",
@@ -15,14 +15,14 @@
             "description": "The branch to checkout"
         },
         "environments": {
-            "$ref": "raid-defs.schema.json#/properties/environments"
+            "$ref": "https://raidcli.dev/schema/v1/raid-defs.schema.json#/properties/environments"
         },
         "install": {
-            "$ref": "raid-defs.schema.json#/properties/install"
+            "$ref": "https://raidcli.dev/schema/v1/raid-defs.schema.json#/properties/install"
         },
         "commands": {
-            "$ref": "raid-defs.schema.json#/properties/commands"
+            "$ref": "https://raidcli.dev/schema/v1/raid-defs.schema.json#/properties/commands"
         }
     },
     "required": ["name","branch"]
-}
+}
diff --git a/site/.gitignore b/site/.gitignore
@@ -10,6 +10,9 @@
 raid
 .env
 
+# Schemas copied from /schemas by plugins/copy-schemas.ts at build time
+/static/schema/
+
 # Misc
 .DS_Store
 .env.local
diff --git a/site/docs/examples/new-developer.mdx b/site/docs/examples/new-developer.mdx
@@ -15,7 +15,7 @@ The team has three repositories — an API, a frontend, and a shared config libr
 The team commits this file to an internal `dev-environment` repo:
 
 ```yaml title="acme.raid.yaml"
-# yaml-language-server: $schema=https://raw.githubusercontent.com/8bitalex/raid/main/schemas/raid-profile.schema.json
+# yaml-language-server: $schema=https://raidcli.dev/schema/v1/raid-profile.schema.json
 name: acme-platform
 
 repositories:
@@ -60,7 +60,7 @@ install:
 Each repo ships its own `raid.yaml` defining the commands and environment variables specific to that service:
 
 ```yaml title="~/dev/acme/api/raid.yaml"
-# yaml-language-server: $schema=https://raw.githubusercontent.com/8bitalex/raid/main/schemas/raid-repo.schema.json
+# yaml-language-server: $schema=https://raidcli.dev/schema/v1/raid-repo.schema.json
 name: "api"
 branch: "main"
 
@@ -92,7 +92,7 @@ environments:
 ```
 
 ```yaml title="~/dev/acme/frontend/raid.yaml"
-# yaml-language-server: $schema=https://raw.githubusercontent.com/8bitalex/raid/main/schemas/raid-repo.schema.json
+# yaml-language-server: $schema=https://raidcli.dev/schema/v1/raid-repo.schema.json
 name: "frontend"
 branch: "main"
 
diff --git a/site/docs/references/schema.mdx b/site/docs/references/schema.mdx
@@ -6,6 +6,31 @@ sidebar_position: 5
 
 Complete field reference for profile files and repository `raid.yaml` files.
 
+## Published JSON Schemas
+
+Raid publishes versioned JSON Schemas under a stable URL. Point your editor or
+agent at these to get autocomplete, validation, and inline docs:
+
+| File | Schema URL |
+|---|---|
+| `*.raid.yaml` profile files | `https://raidcli.dev/schema/v1/raid-profile.schema.json` |
+| Per-repo `raid.yaml` files | `https://raidcli.dev/schema/v1/raid-repo.schema.json` |
+| Shared `$defs` (referenced by the two above) | `https://raidcli.dev/schema/v1/raid-defs.schema.json` |
+
+The `/v1/` path is a stability contract — schemas under it are kept
+backwards-compatible. Breaking changes will publish to `/v2/`.
+
+Add a `# yaml-language-server` modeline to wire schema validation in your editor:
+
+```yaml
+# yaml-language-server: $schema=https://raidcli.dev/schema/v1/raid-profile.schema.json
+name: my-project
+```
+
+Editors that consult SchemaStore (VS Code + Red Hat YAML, JetBrains, Neovim
+with `yaml-language-server`, Helix, …) auto-associate `*.raid.yaml` and
+`raid.yaml` with the published schemas, so the modeline is optional.
+
 ---
 
 ## Profile file
diff --git a/site/docs/whats-new.mdx b/site/docs/whats-new.mdx
@@ -9,6 +9,10 @@ description: Feature-by-feature release notes for Raid.
 
 User-visible changes per release, latest first. For full commit history see the [GitHub releases page](https://github.com/8bitalex/raid/releases).
 
+## 0.11.1 — upcoming
+
+**Schemas published at a stable URL.** The profile, repo, and shared-defs JSON Schemas are now served at `https://raidcli.dev/schema/v1/raid-profile.schema.json`, `…/raid-repo.schema.json`, and `…/raid-defs.schema.json`. Generated profile and repo templates point at these URLs out of the box, so YAML LSPs and agents get autocomplete and inline validation against the canonical contract. The `/v1/` path is a stability promise — additive changes only; breaking changes will publish to `/v2/`. The docsite build copies `schemas/` into `static/schema/v1/`, so the canonical source remains the single Go-embedded copy. Closes [#48](https://github.com/8bitAlex/raid/issues/48).
+
 ## 0.11.0 — upcoming
 
 **Declared arguments and flags on custom commands.** `commands[]` entries now accept an `args` list (named positional arguments) and a `flags` list (long/short options with optional default and type — `string`, `bool`, or `int`). Declared values are exported as env vars named after each entry (uppercased), so `args: [{name: ticket, required: true}]` makes `$TICKET` available in tasks for the duration of the command. Cobra enforces required values and validates positional cardinality before raid runs anything. `RAID_ARG_N` continues to work for unnamed positional arguments. Closes [#26](https://github.com/8bitAlex/raid/issues/26).
diff --git a/site/docusaurus.config.ts b/site/docusaurus.config.ts
@@ -51,6 +51,7 @@ const config: Config = {
   ],
 
   plugins: [
+    require.resolve('./plugins/copy-schemas.ts'),
     [
       '@easyops-cn/docusaurus-search-local',
       {
diff --git a/site/plugins/copy-schemas.ts b/site/plugins/copy-schemas.ts
@@ -0,0 +1,27 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import type { LoadContext, Plugin } from '@docusaurus/types';
+
+// copy-schemas publishes the JSON schemas under static/schema/v1/.
+// The repo's schemas/ directory is the single source of truth (also embedded
+// into the Go binary). This plugin copies them into the static tree before
+// Docusaurus walks static/, so it serves them at
+// https://raidcli.dev/schema/v1/<name>.
+//
+// The /v1/ path is part of the public schema contract: schemas under that URL
+// must remain backwards compatible. Breaking changes get a new /v2/ path.
+const repoRoot = path.resolve(__dirname, '..', '..');
+const srcDir = path.join(repoRoot, 'schemas');
+const destDir = path.join(__dirname, '..', 'static', 'schema', 'v1');
+
+fs.mkdirSync(destDir, { recursive: true });
+for (const entry of fs.readdirSync(srcDir)) {
+  if (!entry.endsWith('.schema.json')) continue;
+  fs.copyFileSync(path.join(srcDir, entry), path.join(destDir, entry));
+}
+
+export default function copySchemasPlugin(_context: LoadContext): Plugin {
+  return {
+    name: 'copy-schemas',
+  };
+}
diff --git a/src/internal/lib/lib.go b/src/internal/lib/lib.go
@@ -547,10 +547,11 @@ func ValidateSchema(path string, schemaPath string) error {
 }
 
 // validateWithEmbeddedSchema validates path against a schema embedded in the binary.
-// schemaName must be the bare filename of a schema in the embedded schemas directory
-// (e.g. "raid-profile.schema.json"). All embedded schemas are registered so that
-// cross-schema $ref values resolve correctly.
-func validateWithEmbeddedSchema(path, schemaName string) error {
+// schemaID must be the canonical $id URL of an embedded schema
+// (e.g. "https://raidcli.dev/schema/v1/raid-profile.schema.json"). All embedded
+// schemas are registered under their $id so cross-schema $ref values resolve
+// correctly without any network access.
+func validateWithEmbeddedSchema(path, schemaID string) error {
 	path = sys.ExpandPath(path)
 	if path == "" || !sys.FileExists(path) {
 		return fmt.Errorf("file not found at %s", path)
@@ -562,20 +563,28 @@ func validateWithEmbeddedSchema(path, schemaName string) error {
 		return fmt.Errorf("failed to read embedded schemas: %w", err)
 	}
 	for _, entry := range entries {
-		data, err := schemas.FS.ReadFile(entry.Name())
+		name := entry.Name()
+		if !strings.HasSuffix(name, ".schema.json") {
+			continue
+		}
+		data, err := schemas.FS.ReadFile(name)
 		if err != nil {
-			return fmt.Errorf("failed to read embedded schema %s: %w", entry.Name(), err)
+			return fmt.Errorf("failed to read embedded schema %s: %w", name, err)
 		}
-		var doc any
+		var doc map[string]any
 		if err := json.Unmarshal(data, &doc); err != nil {
-			return fmt.Errorf("failed to parse embedded schema %s: %w", entry.Name(), err)
+			return fmt.Errorf("failed to parse embedded schema %s: %w", name, err)
+		}
+		id, _ := doc["$id"].(string)
+		if id == "" {
+			return fmt.Errorf("embedded schema %s is missing $id", name)
 		}
-		if err := c.AddResource(entry.Name(), doc); err != nil {
-			return fmt.Errorf("failed to register embedded schema %s: %w", entry.Name(), err)
+		if err := c.AddResource(id, doc); err != nil {
+			return fmt.Errorf("failed to register embedded schema %s: %w", name, err)
 		}
 	}
 
-	sch, err := c.Compile(schemaName)
+	sch, err := c.Compile(schemaID)
 	if err != nil {
 		return err
 	}
diff --git a/src/internal/lib/lib_test.go b/src/internal/lib/lib_test.go
diff --git a/src/internal/lib/profile.go b/src/internal/lib/profile.go
diff --git a/src/internal/lib/repo.go b/src/internal/lib/repo.go
diff --git a/src/internal/lib/schemas_published_test.go b/src/internal/lib/schemas_published_test.go
diff --git a/src/resources/app.properties b/src/resources/app.properties
diff --git a/src/resources/profile-template b/src/resources/profile-template
diff --git a/src/resources/repo-template b/src/resources/repo-template

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# yaml-language-server: $schema=https://raw.githubusercontent.com/8bitalex/raid/main/schemas/raid-profile.schema.json`
	`1`	`+# yaml-language-server: $schema=https://raidcli.dev/schema/v1/raid-profile.schema.json`
`2`	`2`
`3`	`3`	`# This is a raid profile definition for a fictional company called Acme. It defines two repositories (web and api)`
`4`	`4`	`# and a development environment with tasks to set up and run the projects.`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# yaml-language-server: $schema=../../schemas/raid-profile.schema.json`
	`1`	`+# yaml-language-server: $schema=https://raidcli.dev/schema/v1/raid-profile.schema.json`
`2`	`2`
`3`	`3`	`name: raid`
`4`	`4`	`repositories:`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"$schema": "https://json-schema.org/draft/2020-12/schema",`
`3`		`- "$id": "raid-defs.schema.json",`
	`3`	`+ "$id": "https://raidcli.dev/schema/v1/raid-defs.schema.json",`
`4`	`4`	`"title": "Raid Schema Definitions",`
`5`	`5`	`"description": "Shared schema definitions for raid",`
`6`	`6`	`"type": "object",`