Analyzer cli agent mode

.cargo/config.toml

@@ -0,0 +1,2 @@
+[net]
+git-fetch-with-cli = true

.github/workflows/ci.yml

@@ -16,6 +16,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+      - uses: webfactory/ssh-agent@v0.9.0
+        with:
+          ssh-private-key: ${{ secrets.OPENAPI_TO_DISCOVERY_DEPLOY_KEY }}
       - uses: dtolnay/rust-toolchain@stable
       - uses: Swatinem/rust-cache@v2
       - run: cargo check --all-targets
@@ -25,6 +28,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+      - uses: webfactory/ssh-agent@v0.9.0
+        with:
+          ssh-private-key: ${{ secrets.OPENAPI_TO_DISCOVERY_DEPLOY_KEY }}
       - uses: dtolnay/rust-toolchain@stable
       - uses: Swatinem/rust-cache@v2
       - run: cargo test
@@ -44,6 +50,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+      - uses: webfactory/ssh-agent@v0.9.0
+        with:
+          ssh-private-key: ${{ secrets.OPENAPI_TO_DISCOVERY_DEPLOY_KEY }}
       - uses: dtolnay/rust-toolchain@stable
         with:
           components: clippy

.github/workflows/release.yml

@@ -41,6 +41,9 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
+      - uses: webfactory/ssh-agent@v0.9.0
+        with:
+          ssh-private-key: ${{ secrets.OPENAPI_TO_DISCOVERY_DEPLOY_KEY }}
       - uses: dtolnay/rust-toolchain@stable
 
       - uses: taiki-e/setup-cross-toolchain-action@v1

.github/workflows/update-discovery.yml

@@ -0,0 +1,96 @@
+name: Update Discovery Documents
+
+on:
+  schedule:
+    - cron: '0 * * * *' # hourly
+  workflow_dispatch: {} # manual trigger
+
+permissions:
+  contents: write
+  pull-requests: write
+
+env:
+  SERVICES: |
+    analyzer=https://analyzer.exein.dev/analyzer-discovery.json
+    # isaac=https://analyzer.exein.dev/isaac-discovery.json
+    # vuln-tracker=https://analyzer.exein.dev/vuln-tracker-discovery.json
+
+jobs:
+  update:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Fetch all discovery documents
+        run: |
+          mkdir -p discovery
+          while IFS='=' read -r name url; do
+            [ -z "$name" ] && continue
+            [[ "$name" == \#* ]] && continue
+            echo "Fetching $name from $url"
+            curl -sf "$url" \
+              -H "Authorization: Bearer ${{ secrets.ANALYZER_API_KEY }}" \
+              -o "discovery/${name}.json.new" || echo "WARN: failed to fetch $name"
+          done <<< "$SERVICES"
+
+      - name: Check for changes
+        id: diff
+        run: |
+          changed=false
+          for f in discovery/*.json.new; do
+            [ ! -f "$f" ] && continue
+            base="${f%.new}"
+            if ! diff -q "$base" "$f" > /dev/null 2>&1; then
+              mv "$f" "$base"
+              changed=true
+            else
+              rm "$f"
+            fi
+          done
+          echo "changed=$changed" >> "$GITHUB_OUTPUT"
+
+      - name: Configure SSH for private dependencies
+        if: steps.diff.outputs.changed == 'true'
+        uses: webfactory/ssh-agent@v0.9.0
+        with:
+          ssh-private-key: ${{ secrets.OPENAPI_TO_DISCOVERY_DEPLOY_KEY }}
+
+      - name: Install Rust toolchain
+        if: steps.diff.outputs.changed == 'true'
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache cargo
+        if: steps.diff.outputs.changed == 'true'
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-${{ hashFiles('Cargo.lock') }}
+
+      - name: Regenerate skills
+        if: steps.diff.outputs.changed == 'true'
+        run: |
+          cargo build --release
+          for f in discovery/*.json; do
+            [ ! -f "$f" ] && continue
+            name="$(basename "$f" .json)"
+            echo "Generating skills for $name"
+            ./target/release/analyzer --discovery "$f" generate-skills \
+              || echo "WARN: failed to generate skills for $name"
+          done
+
+      - name: Create PR
+        if: steps.diff.outputs.changed == 'true'
+        uses: peter-evans/create-pull-request@v6
+        with:
+          title: "update: Discovery Documents + skills"
+          body: |
+            Auto-generated from upstream API changes.
+
+            Discovery documents in `discovery/` have changed.
+            Skill files in `skills/` have been regenerated.
+          branch: update-discovery
+          commit-message: "update: discovery documents + regenerated skills"
+          delete-branch: true

.gitignore

@@ -1,2 +1,6 @@
 /target
 Cargo.lock
+usage_examples.txt
+*-discovery.json
+*20*.txt
+.env

CLAUDE.md

@@ -0,0 +1 @@
+When using or contributing to this repository, follow the guidelines in [CONTEXT.md](CONTEXT.md).

CONTEXT.md

@@ -0,0 +1,145 @@
+# Analyzer CLI (`analyzer`) Context
+
+The `analyzer` CLI provides dynamic access to firmware and software security APIs by parsing Discovery Documents at runtime. It supports multiple API services through a compile-time service registry, with each service backed by its own Discovery Document fetched and cached automatically.
+
+## Registered Services
+
+| Alias | Description |
+|-------|-------------|
+| `analyzer` | Firmware and software image security analysis |
+
+## Agent Integration (Claude Code)
+
+To use the `analyzer` CLI with Claude Code (or other AI agents), run the one-time setup:
+
+```bash
+analyzer init-agent
+```
+
+This installs skills, usage context, and permissions into `~/.claude/` so that Claude Code automatically discovers the `analyzer` CLI in every project — no source code or manual configuration needed.
+
+What it writes:
+
+| File | Purpose |
+|------|---------|
+| `~/.claude/skills/` | Per-resource API skill files (generated from discovery documents) |
+| `~/.claude/settings.json` | Allowlists the `analyzer` binary for Claude Code |
+
+Skills are loaded on-demand by Claude Code — no global `CLAUDE.md` or `CONTEXT.md` is written, so the analyzer context only appears when relevant.
+
+Re-run `analyzer init-agent` after upgrading to refresh skills.
+
+## Rules of Engagement for Agents
+
+* **Schema First:** *If you don't know the exact JSON payload structure, run `analyzer schema <service>.<resource>.<method>` first to inspect the schema before executing.*
+* **Context Window Protection:** *API responses can be large. ALWAYS use `--fields` when listing or getting resources to avoid overwhelming your context window.*
+* **Dry-Run Safety:** *Always use the `--dry-run` flag for mutating operations (create, update, delete) to validate your JSON payload before actual execution.*
+* **Poll, Don't Guess:** *After scheduling a scan, poll the status endpoint until it completes. Do not assume timing or make further requests against incomplete scans.*
+
+## Core Syntax
+
+```bash
+# API commands (service name is first positional arg)
+analyzer api <service> <resource> [sub-resource...] <method> [flags]
+
+# Schema introspection (service name is first dotted segment)
+analyzer schema <service>.<resource>.<method>
+
+# Navigation
+analyzer api analyzer --help
+analyzer api analyzer scans --help
+```
+
+### Key Flags
+
+| Flag | Purpose |
+|------|---------|
+| `--params '<JSON>'` | Path and query parameters (e.g., `{"id": "..."}`) |
+| `--json '<JSON>'` | Request body for POST/PUT/PATCH methods |
+| `--fields '<MASK>'` | Comma-separated response fields to include (context window protection) |
+| `--page-all` | Auto-paginate results as NDJSON (one JSON line per page) |
+| `--dry-run` | Validate and print the request without executing |
+| `--format human\|json\|table` | Output format (default: `human`) |
+| `--discovery <path-or-url>` | Override discovery source for dev/testing |
+
+## Schema Introspection
+
+The CLI is self-documenting. Use `analyzer schema` to discover parameters, request/response schemas, and types at runtime — no static docs needed.
+
+```bash
+# Browse all resources for a service
+analyzer schema analyzer.api
+
+# Inspect a method's params, types, and defaults
+analyzer schema analyzer.scans.create
+analyzer schema analyzer.objects.get
+
+# Browse a sub-resource tree
+analyzer schema analyzer.scans.compliance-check
+```
+
+Use `analyzer schema` output to build your `--params` and `--json` flags.
+
+## Usage Patterns
+
+### Reading Data
+
+Always use `--fields` to minimize tokens.
+
+```bash
+# List objects (efficient)
+analyzer api analyzer objects list --params '{"limit": 10}' --fields "id,name,tags"
+
+# Get scan details
+analyzer api analyzer scans get --params '{"id": "SCAN_ID"}' --fields "id,status,score"
+
+# Check service health
+analyzer api analyzer health list
+```
+
+### Writing Data
+
+Use `--json` for the request body. Always `--dry-run` first.
+
+```bash
+analyzer schema analyzer.objects.create
+analyzer api analyzer objects create --json '{"name": "Router FW v2.1"}' --dry-run
+```
+
+### Pagination (NDJSON)
+
+Use `--page-all` for large result sets. Output is one JSON line per page.
+
+```bash
+analyzer api analyzer scans results get \
+  --params '{"scan_id": "SCAN_ID", "analysis_id": "cve"}' \
+  --page-all --fields "id,severity,score"
+```
+
+### Deleting Data
+
+```bash
+analyzer api analyzer objects delete --params '{"id": "OBJ_ID"}' --dry-run
+```
+
+## Human-Friendly Commands
+
+Classic CLI subcommands (unchanged by multi-service routing):
+
+```bash
+analyzer login
+analyzer whoami
+analyzer object list
+analyzer scan new --object OBJ_ID -f firmware.bin -t linux --wait
+analyzer scan score --scan SCAN_ID
+```
+
+## Error Handling
+
+All errors are JSON on stderr with a non-zero exit code:
+
+```json
+{"error": {"code": 404, "message": "Object not found"}}
+```
+
+Exit `0` = success, non-zero = failure. Parse error JSON to decide next steps.

Cargo.toml

@@ -15,11 +15,36 @@ name = "analyzer"
 path = "src/main.rs"
 
 [dependencies]
-clap = { version = "4", features = ["derive", "env", "color", "help", "usage", "error-context", "suggestions", "wrap_help"] }
-reqwest = { version = "0.12", default-features = false, features = ["json", "multipart", "stream", "rustls-tls"] }
+
+# internal
+openapi-to-discovery = { git = "ssh://git@github.com/exein-io/openapi-to-discovery" }
+
+# 3rdparty
+clap = { version = "4", features = [
+   "derive",
+   "env",
+   "color",
+   "help",
+   "usage",
+   "error-context",
+   "suggestions",
+   "wrap_help",
+   "string",
+] }
+reqwest = { version = "0.12", default-features = false, features = [
+   "json",
+   "multipart",
+   "stream",
+   "rustls-tls",
+] }
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
-tokio = { version = "1", features = ["rt-multi-thread", "macros", "fs", "io-util"] }
+tokio = { version = "1", features = [
+   "rt-multi-thread",
+   "macros",
+   "fs",
+   "io-util",
+] }
 tokio-util = { version = "0.7", features = ["io"] }
 tokio-stream = "0.1"
 futures = "0.3"
@@ -39,8 +64,10 @@ clap_complete = "4"
 
 [dev-dependencies]
 assert_cmd = "2"
+filetime = "0.2"
 predicates = "3"
 tempfile = "3"
+test-case = "3"
 wiremock = "0.6"
 
 [profile.release]