Add a CLI-surface drift gate on capability-sdk/pkg/clisurface

.github/workflows/cli-surface.yml

@@ -0,0 +1,63 @@
+name: CLI Surface Drift
+
+# Fails when the documented CLI surface drifts from the live cobra tree.
+# No `paths:` filter: docs-only PRs skip ci.yml.
+on:
+  # No `branches:` filter: `on.pull_request.branches` matches the BASE, so
+  # `branches: [main]` would skip stacked PRs.
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  cli-surface:
+    name: CLI Surface Drift
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          persist-credentials: false
+
+      - name: Setup Go
+        uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
+        with:
+          go-version-file: go.mod
+
+      - name: Snapshot the committed documentation
+        run: |
+          set -eo pipefail
+          find docs README.md -type f -exec sha256sum {} + \
+            | LC_ALL=C sort > "$RUNNER_TEMP/docs.before"
+          echo "baselined $(wc -l < "$RUNNER_TEMP/docs.before") file(s)"
+
+      - name: Check CLI surface and documentation for drift
+        run: |
+          set -eo pipefail
+          go test ./pkg/runner -run 'TestCLISurface' -count=1 -v \
+            | tee "$RUNNER_TEMP/gate.log"
+          for name in TestCLISurface TestCLISurfaceDocLint TestCLISurfaceGateDetectsRename; do
+            if ! grep -qE "^--- PASS: ${name} " "$RUNNER_TEMP/gate.log"; then
+              echo "::error::${name} did not run. The drift gate is not executing; check the -run pattern against the test names in pkg/runner/cli_surface_test.go."
+              exit 1
+            fi
+          done
+
+      - name: Verify the gate did not rewrite the goldens
+        run: |
+          set -eo pipefail
+          find docs README.md -type f -exec sha256sum {} + \
+            | LC_ALL=C sort > "$RUNNER_TEMP/docs.after"
+          if ! diff -u "$RUNNER_TEMP/docs.before" "$RUNNER_TEMP/docs.after"; then
+            echo "::error::The drift gate wrote to the committed documentation; the diff above names every file added, removed or changed. Check mode must compare without writing, so this is a defect in the gate itself -- pkg/runner/cli_surface_test.go, or a clisurface write reached outside the -update branch. Regenerating with 'make cli-docs' will not fix it."
+            exit 1
+          fi

.goreleaser.yaml

@@ -30,6 +30,10 @@ archives:
 checksum:
   name_template: "checksums.txt"
 
+release:
+  extra_files:
+    - glob: docs/cli-surface.json
+
 changelog:
   sort: asc
   filters:

Makefile

@@ -20,7 +20,7 @@ LDFLAGS := -s -w
 # Declare all phony targets
 .PHONY: all build build-all build-linux build-darwin build-windows \
         release release-checksums \
-        test test-verbose test-coverage lint clean help
+        test test-verbose test-coverage lint clean help cli-docs
 
 # =============================================================================
 # Build targets (local development)
@@ -79,6 +79,11 @@ test-coverage: ## Run tests with coverage report
 lint: ## Run linter
 	golangci-lint run ./...
 
+cli-docs: ## Regenerate CLI surface docs from the live cobra tree
+	@GOWORK=off go test ./pkg/runner -list 'TestCLISurface' | grep -qE '^TestCLISurface$$' \
+	  || { echo "cli-docs: 'go test -list' did not report TestCLISurface in ./pkg/runner. Either the -update writer was renamed, or the package failed to build -- run 'go build ./pkg/runner' to tell which. 'go test -run' exits 0 when its pattern matches nothing, so without this check the target would report success having regenerated nothing at all."; exit 1; }
+	GOWORK=off go test ./pkg/runner -run 'TestCLISurface' -count=1 -update
+
 clean: ## Clean build artifacts
 	rm -rf $(BUILD_DIR) $(DIST_DIR)
 	rm -f coverage.out coverage.html

README.md

@@ -80,6 +80,22 @@ julius probe https://target.example.com
 +----------------------------+---------+-------------+-------------+--------+-------+
 ```
 
+### Subcommands
+
+<!-- BEGIN generated: cli-subcommands -->
+Julius organizes its functionality into these focused subcommands:
+
+```bash
+julius list     # List all available probe definitions
+julius probe    # Probe targets to identify LLM services
+julius validate # Validate probe definition files
+```
+<!-- END generated: cli-subcommands -->
+
+<!-- BEGIN generated: cli-aliases -->
+The full reference — every subcommand, alias and flag, including the ones hidden from `--help` — is generated into [docs/CLI.md](docs/CLI.md).
+<!-- END generated: cli-aliases -->
+
 ## Supported LLM Services
 
 Julius identifies 64 LLM platforms across self-hosted, gateway, MCP, RAG/orchestration, and cloud-managed categories:

docs/CLI.md

@@ -0,0 +1,119 @@
+<!-- Generated from the live cobra command tree by 'make cli-docs'. Do not edit by hand. -->
+
+# julius CLI reference
+
+Every command, alias and flag below is derived from the cobra command tree, not from prose.
+Schema version 1, surface hash `sha256:0b90ec6c9ac2f198300eb2bb9b760049de4257ac3240da746f689915930e3299`.
+
+Regenerate with `make cli-docs` after adding, removing or renaming a command or a flag.
+
+## Command index
+
+| Command | Aliases | Description |
+| --- | --- | --- |
+| [`julius`](#julius) | *(none)* | Julius - LLM Service Fingerprinting Tool |
+| [`julius list`](#julius-list) | *(none)* | List all available probe definitions |
+| [`julius probe`](#julius-probe) | *(none)* | Probe targets to identify LLM services |
+| [`julius validate`](#julius-validate) | *(none)* | Validate probe definition files |
+
+## `julius`
+
+Julius - LLM Service Fingerprinting Tool
+
+- Usage: `julius`
+- Aliases: *(none)*
+- Requires a subcommand
+
+### Flags
+
+| Flag | Short | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `--banner` |  | bool | `true` | Show ASCII banner |
+| `--ca-cert` |  | string |  | Path to custom CA certificate file |
+| `--concurrency` | `-c` | int | `10` | Maximum concurrent probe requests per target |
+| `--insecure` |  | bool | `false` | Skip TLS certificate verification |
+| `--max-response-size` |  | int64 | `10485760` | Maximum response body size in bytes (default 10MB) |
+| `--no-color` |  | bool | `false` | Disable color output |
+| `--output` | `-o` | string | `table` | Output format (table, json, jsonl) |
+| `--probes-dir` | `-p` | string |  | Override probe definitions directory |
+| `--quiet` | `-q` | bool | `false` | Suppress non-match output |
+| `--timeout` | `-t` | int | `5` | HTTP timeout in seconds |
+| `--verbose` | `-v` | bool | `false` | Verbose output |
+
+## `julius list`
+
+List all available probe definitions
+
+- Usage: `julius list`
+- Aliases: *(none)*
+
+### Inherited flags
+
+| Flag | Short | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `--banner` |  | bool | `true` | Show ASCII banner |
+| `--ca-cert` |  | string |  | Path to custom CA certificate file |
+| `--concurrency` | `-c` | int | `10` | Maximum concurrent probe requests per target |
+| `--insecure` |  | bool | `false` | Skip TLS certificate verification |
+| `--max-response-size` |  | int64 | `10485760` | Maximum response body size in bytes (default 10MB) |
+| `--no-color` |  | bool | `false` | Disable color output |
+| `--output` | `-o` | string | `table` | Output format (table, json, jsonl) |
+| `--probes-dir` | `-p` | string |  | Override probe definitions directory |
+| `--quiet` | `-q` | bool | `false` | Suppress non-match output |
+| `--timeout` | `-t` | int | `5` | HTTP timeout in seconds |
+| `--verbose` | `-v` | bool | `false` | Verbose output |
+
+## `julius probe`
+
+Probe targets to identify LLM services
+
+- Usage: `julius probe [targets...]`
+- Aliases: *(none)*
+
+### Flags
+
+| Flag | Short | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `--augustus` |  | bool | `false` | Include Augustus generator configs in output |
+| `--base-paths` |  | string |  | Comma-separated path prefixes to prepend to probe paths (e.g., /api,/proxy) |
+| `--file` | `-f` | string |  | Read targets from file |
+| `--header` | `-H` | stringArray | `[]` | Custom HTTP header (e.g., "Authorization: Bearer token"). Can be specified multiple times |
+
+### Inherited flags
+
+| Flag | Short | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `--banner` |  | bool | `true` | Show ASCII banner |
+| `--ca-cert` |  | string |  | Path to custom CA certificate file |
+| `--concurrency` | `-c` | int | `10` | Maximum concurrent probe requests per target |
+| `--insecure` |  | bool | `false` | Skip TLS certificate verification |
+| `--max-response-size` |  | int64 | `10485760` | Maximum response body size in bytes (default 10MB) |
+| `--no-color` |  | bool | `false` | Disable color output |
+| `--output` | `-o` | string | `table` | Output format (table, json, jsonl) |
+| `--probes-dir` | `-p` | string |  | Override probe definitions directory |
+| `--quiet` | `-q` | bool | `false` | Suppress non-match output |
+| `--timeout` | `-t` | int | `5` | HTTP timeout in seconds |
+| `--verbose` | `-v` | bool | `false` | Verbose output |
+
+## `julius validate`
+
+Validate probe definition files
+
+- Usage: `julius validate [directory]`
+- Aliases: *(none)*
+
+### Inherited flags
+
+| Flag | Short | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `--banner` |  | bool | `true` | Show ASCII banner |
+| `--ca-cert` |  | string |  | Path to custom CA certificate file |
+| `--concurrency` | `-c` | int | `10` | Maximum concurrent probe requests per target |
+| `--insecure` |  | bool | `false` | Skip TLS certificate verification |
+| `--max-response-size` |  | int64 | `10485760` | Maximum response body size in bytes (default 10MB) |
+| `--no-color` |  | bool | `false` | Disable color output |
+| `--output` | `-o` | string | `table` | Output format (table, json, jsonl) |
+| `--probes-dir` | `-p` | string |  | Override probe definitions directory |
+| `--quiet` | `-q` | bool | `false` | Suppress non-match output |
+| `--timeout` | `-t` | int | `5` | HTTP timeout in seconds |
+| `--verbose` | `-v` | bool | `false` | Verbose output |

docs/cli-surface-allow.txt

@@ -0,0 +1,13 @@
+# Flag names documentation may mention even though the CLI does not accept them.
+#
+# The CLI-surface doc lint (see pkg/runner/cli_surface_test.go) checks every julius invocation in
+# a fenced code block, every backticked flag name in prose, and every flag name
+# in a Go comment under the configured Go directories against the flags cobra
+# actually registers. This file is the escape hatch for deliberate mentions.
+# Every entry MUST carry a '#' reason: the gate rejects an entry without one,
+# because an unexplained exception is how a stale flag reference survives forever.
+#
+# Keep this list as short as possible. If a mention is not deliberate, fix the
+# document instead of allowing it.
+
+--api-key  # vLLM's own flag, named in SECURITY.md as the recommended configuration for that service