diff --git a/.claude/skills/swamp-data/SKILL.md b/.claude/skills/swamp-data/SKILL.md index c36fc4d3..f4dc172c 100644 --- a/.claude/skills/swamp-data/SKILL.md +++ b/.claude/skills/swamp-data/SKILL.md @@ -302,13 +302,22 @@ transparently resolves to the new name. - Reorganizing data after a model's purpose evolves - Fixing typos in data names without losing history -```bash -# Rename a data instance -swamp data rename my-model old-name new-name - -# With explicit repo directory -swamp data rename my-model old-name new-name --repo-dir ./my-repo -``` +**Rename workflow:** + +1. **Verify** the new name doesn't already exist: + ```bash + swamp data get my-model new-name --no-content --json + ``` + This should return an error (not found). If it succeeds, the name is taken. +2. **Rename** the data instance: + ```bash + swamp data rename my-model old-name new-name + ``` +3. **Confirm** the forward reference works: + ```bash + swamp data get my-model old-name --no-content --json + ``` + Should resolve to `new-name` via the forward reference. **What happens:** @@ -334,13 +343,21 @@ overwrite the forward reference. Clean up expired data and old versions based on lifecycle settings. -**Preview what would be deleted:** +**IMPORTANT: Always dry-run first.** GC deletes data permanently. Follow this +workflow: -```bash -swamp data gc --dry-run --json -``` +1. **Preview** what will be deleted: + ```bash + swamp data gc --dry-run --json + ``` +2. **Review** the output — verify only expected items appear +3. **Run** the actual GC only after confirming the dry-run output: + ```bash + swamp data gc --json + swamp data gc -f --json # Skip confirmation prompt + ``` -**Output shape:** +**Dry-run output shape:** ```json { @@ -351,25 +368,12 @@ swamp data gc --dry-run --json "modelId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "dataName": "cache", "reason": "lifetime:ephemeral" - }, - { - "type": "other-type", - "modelId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e", - "dataName": "log", - "reason": "lifetime:1h" } ] } ``` -**Run garbage collection:** - -```bash -swamp data gc --json -swamp data gc -f --json # Skip confirmation prompt -``` - -**Output shape:** +**GC output shape:** ```json { @@ -410,13 +414,14 @@ Data is stored in the `.swamp/data/` directory: ## When to Use Other Skills -| Need | Use Skill | -| -------------------- | ------------------------------- | -| Create/run models | `swamp-model` | -| View model outputs | `swamp-model` (output commands) | -| Create/run workflows | `swamp-workflow` | -| Repository structure | `swamp-repo` | -| Manage secrets | `swamp-vault` | +| Need | Use Skill | +| -------------------------- | ------------------------------- | +| Create/run models | `swamp-model` | +| View model outputs | `swamp-model` (output commands) | +| Create/run workflows | `swamp-workflow` | +| Repository structure | `swamp-repo` | +| Manage secrets | `swamp-vault` | +| Understand swamp internals | `swamp-troubleshooting` | ## References diff --git a/.claude/skills/swamp-extension-datastore/SKILL.md b/.claude/skills/swamp-extension-datastore/SKILL.md index 90845e8f..01f38a05 100644 --- a/.claude/skills/swamp-extension-datastore/SKILL.md +++ b/.claude/skills/swamp-extension-datastore/SKILL.md @@ -199,6 +199,7 @@ swamp datastore status --json | Create custom execution drivers | `swamp-extension-driver` | | Repository setup and configuration | `swamp-repo` | | Manage secrets for datastore config | `swamp-vault` | +| Understand swamp internals | `swamp-troubleshooting` | ## References diff --git a/.claude/skills/swamp-extension-driver/SKILL.md b/.claude/skills/swamp-extension-driver/SKILL.md index b09e7e2b..0e13bb8a 100644 --- a/.claude/skills/swamp-extension-driver/SKILL.md +++ b/.claude/skills/swamp-extension-driver/SKILL.md @@ -233,3 +233,12 @@ driver file — swamp silently skips files that fail to compile. - **Troubleshooting**: See [references/troubleshooting.md](references/troubleshooting.md) for common issues (driver not found, output types, resolution priority) + +## When to Use Other Skills + +| Need | Use Skill | +| -------------------------- | ----------------------- | +| Use existing models | `swamp-model` | +| Create custom models | `swamp-extension-model` | +| Repository structure | `swamp-repo` | +| Understand swamp internals | `swamp-troubleshooting` | diff --git a/.claude/skills/swamp-extension-model/SKILL.md b/.claude/skills/swamp-extension-model/SKILL.md index 2ae05bb6..5d7fbdeb 100644 --- a/.claude/skills/swamp-extension-model/SKILL.md +++ b/.claude/skills/swamp-extension-model/SKILL.md @@ -461,14 +461,15 @@ swamp model type describe @myorg/my-model --json # Check schema ## When to Use Other Skills -| Need | Use Skill | -| ------------------------- | ---------------- | -| Use existing models | `swamp-model` | -| Create/run workflows | `swamp-workflow` | -| Manage secrets for models | `swamp-vault` | -| Repository structure | `swamp-repo` | -| Manage model data | `swamp-data` | -| Create reports for models | `swamp-report` | +| Need | Use Skill | +| -------------------------- | ----------------------- | +| Use existing models | `swamp-model` | +| Create/run workflows | `swamp-workflow` | +| Manage secrets for models | `swamp-vault` | +| Repository structure | `swamp-repo` | +| Manage model data | `swamp-data` | +| Create reports for models | `swamp-report` | +| Understand swamp internals | `swamp-troubleshooting` | ## References diff --git a/.claude/skills/swamp-extension-vault/SKILL.md b/.claude/skills/swamp-extension-vault/SKILL.md index 1c300b26..7ce7a345 100644 --- a/.claude/skills/swamp-extension-vault/SKILL.md +++ b/.claude/skills/swamp-extension-vault/SKILL.md @@ -211,6 +211,7 @@ swamp vault status --json | Create custom datastores | `swamp-extension-datastore` | | Create custom execution drivers | `swamp-extension-driver` | | Repository setup and configuration | `swamp-repo` | +| Understand swamp internals | `swamp-troubleshooting` | ## References diff --git a/.claude/skills/swamp-model/SKILL.md b/.claude/skills/swamp-model/SKILL.md index 4c51ca03..4b69d851 100644 --- a/.claude/skills/swamp-model/SKILL.md +++ b/.claude/skills/swamp-model/SKILL.md @@ -428,96 +428,9 @@ variables are correct for the intended target. See ## Model Outputs -### Search Outputs - -Find method execution outputs. - -```bash -swamp model output search --json -swamp model output search "my-shell" --json -``` - -**Output shape:** - -```json -{ - "query": "", - "results": [ - { - "outputId": "d1e2f3a4-b5c6-4d7e-f8a9-b0c1d2e3f4a5", - "modelName": "my-shell", - "method": "execute", - "status": "succeeded", - "createdAt": "2025-01-15T10:30:00Z" - } - ] -} -``` - -### Get Output Details - -Get full details of a specific output or latest output for a model. - -```bash -swamp model output get d1e2f3a4-b5c6-4d7e-f8a9-b0c1d2e3f4a5 --json -swamp model output get my-shell --json # Latest output for model -``` - -**Output shape:** - -```json -{ - "outputId": "d1e2f3a4-b5c6-4d7e-f8a9-b0c1d2e3f4a5", - "modelId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", - "modelName": "my-shell", - "type": "command/shell", - "method": "execute", - "status": "succeeded", - "startedAt": "2025-01-15T10:30:00Z", - "completedAt": "2025-01-15T10:30:00.150Z", - "artifacts": [ - { "type": "resource", "path": "..." } - ] -} -``` - -### View Output Logs - -Get log content from a method execution. - -```bash -swamp model output logs d1e2f3a4-b5c6-4d7e-f8a9-b0c1d2e3f4a5 --json -``` - -**Output shape:** - -```json -{ - "outputId": "d1e2f3a4-b5c6-4d7e-f8a9-b0c1d2e3f4a5", - "logs": "Executing shell command...\nHello, world!\nCommand completed successfully." -} -``` - -### View Output Data - -Get data artifact content from a method execution. - -```bash -swamp model output data d1e2f3a4-b5c6-4d7e-f8a9-b0c1d2e3f4a5 --json -``` - -**Output shape:** - -```json -{ - "outputId": "d1e2f3a4-b5c6-4d7e-f8a9-b0c1d2e3f4a5", - "data": { - "exitCode": 0, - "command": "echo 'Hello, world!'", - "executedAt": "2025-01-15T10:30:00Z" - } -} -``` +Use `swamp model output search`, `output get`, `output logs`, and `output data` +to inspect method execution results. See +[references/outputs.md](references/outputs.md) for commands and output shapes. ## Workflow Example @@ -562,9 +475,12 @@ validation. | Manage data lifecycle | `swamp-data` | | Create custom TypeScript models | `swamp-extension-model` | | Create reports for models | `swamp-report` | +| Understand swamp internals | `swamp-troubleshooting` | ## References +- **Outputs**: See [references/outputs.md](references/outputs.md) for output + search, get, logs, and data commands with output shapes - **Examples**: See [references/examples.md](references/examples.md) for complete model workflows and CEL expression reference - **Troubleshooting**: See diff --git a/.claude/skills/swamp-model/references/outputs.md b/.claude/skills/swamp-model/references/outputs.md new file mode 100644 index 00000000..6acfb02b --- /dev/null +++ b/.claude/skills/swamp-model/references/outputs.md @@ -0,0 +1,92 @@ +# Model Outputs Reference + +## Search Outputs + +Find method execution outputs. + +```bash +swamp model output search --json +swamp model output search "my-shell" --json +``` + +**Output shape:** + +```json +{ + "query": "", + "results": [ + { + "outputId": "d1e2f3a4-b5c6-4d7e-f8a9-b0c1d2e3f4a5", + "modelName": "my-shell", + "method": "execute", + "status": "succeeded", + "createdAt": "2025-01-15T10:30:00Z" + } + ] +} +``` + +## Get Output Details + +Get full details of a specific output or latest output for a model. + +```bash +swamp model output get d1e2f3a4-b5c6-4d7e-f8a9-b0c1d2e3f4a5 --json +swamp model output get my-shell --json # Latest output for model +``` + +**Output shape:** + +```json +{ + "outputId": "d1e2f3a4-b5c6-4d7e-f8a9-b0c1d2e3f4a5", + "modelId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", + "modelName": "my-shell", + "type": "command/shell", + "method": "execute", + "status": "succeeded", + "startedAt": "2025-01-15T10:30:00Z", + "completedAt": "2025-01-15T10:30:00.150Z", + "artifacts": [ + { "type": "resource", "path": "..." } + ] +} +``` + +## View Output Logs + +Get log content from a method execution. + +```bash +swamp model output logs d1e2f3a4-b5c6-4d7e-f8a9-b0c1d2e3f4a5 --json +``` + +**Output shape:** + +```json +{ + "outputId": "d1e2f3a4-b5c6-4d7e-f8a9-b0c1d2e3f4a5", + "logs": "Executing shell command...\nHello, world!\nCommand completed successfully." +} +``` + +## View Output Data + +Get data artifact content from a method execution. + +```bash +swamp model output data d1e2f3a4-b5c6-4d7e-f8a9-b0c1d2e3f4a5 --json +``` + +**Output shape:** + +```json +{ + "outputId": "d1e2f3a4-b5c6-4d7e-f8a9-b0c1d2e3f4a5", + "data": { + "exitCode": 0, + "command": "echo 'Hello, world!'", + "executedAt": "2025-01-15T10:30:00Z" + } +} +``` diff --git a/.claude/skills/swamp-repo/SKILL.md b/.claude/skills/swamp-repo/SKILL.md index 907ef318..d8963dca 100644 --- a/.claude/skills/swamp-repo/SKILL.md +++ b/.claude/skills/swamp-repo/SKILL.md @@ -268,6 +268,7 @@ export SWAMP_DATASTORE='@myorg/my-store:{"key":"val"}' | Create custom TypeScript models | `swamp-extension-model` | | Create custom datastores | `swamp-extension-datastore` | | Create custom drivers | `swamp-extension-driver` | +| Understand swamp internals | `swamp-troubleshooting` | ## References diff --git a/.claude/skills/swamp-report/SKILL.md b/.claude/skills/swamp-report/SKILL.md index 913b8032..65b14c2c 100644 --- a/.claude/skills/swamp-report/SKILL.md +++ b/.claude/skills/swamp-report/SKILL.md @@ -286,6 +286,7 @@ Failed reports appear as `{ "_error": "error message" }`. | Extend model with new method | `swamp-extension-model` | | Manage model data | `swamp-data` | | Repository structure | `swamp-repo` | +| Understand swamp internals | `swamp-troubleshooting` | ## References diff --git a/.claude/skills/swamp-troubleshooting/SKILL.md b/.claude/skills/swamp-troubleshooting/SKILL.md index cd600313..d95ee044 100644 --- a/.claude/skills/swamp-troubleshooting/SKILL.md +++ b/.claude/skills/swamp-troubleshooting/SKILL.md @@ -1,23 +1,23 @@ --- name: swamp-troubleshooting description: > - Fetch and read swamp source code to debug, diagnose, and fix swamp issues. - IMPORTANT: Use this skill — not swamp-model, swamp-workflow, swamp-vault, - swamp-data, or swamp-repo — whenever the user's query signals something is - broken or wrong. Error signals include: "error", "failing", "failed", "broken", - "not working", "crash", "hang", "timeout", "unexpected", "strange", "wrong", - "issue", "problem", "bug", "fix", "debug", "diagnose", "troubleshoot", "trace", - "root cause", "stack trace", "error message", "error log", "isn't being - resolved", "isn't being found", "not reading", "giving me an error". This skill - applies even when the error mentions a specific domain (e.g., "vault expressions - aren't resolving" or "my model isn't being found") — the troubleshooting skill - fetches swamp source to trace the root cause. + Navigate swamp source code to trace error origins, identify execution + flows, inspect internal data structures, and understand CLI behavior when + --help is insufficient. Use this skill whenever something is broken + ("error", "failing", "not working", "crash", "timeout", "bug", "fix", + "debug", "troubleshoot", "root cause", "stack trace", "isn't being found", + "giving me an error") OR when you need to understand how swamp works + internally ("how does", "what happens when", "where is", "internals", + "under the hood"). Applies even when the query mentions a specific domain + (e.g., "vault expressions aren't resolving" or "how does extension push + work") — fetch swamp source to find the answer. --- # Swamp Troubleshooting Skill -Diagnose and troubleshoot swamp issues by fetching and reading the swamp source -code. All commands support `--json` for machine-readable output. +Diagnose and troubleshoot swamp issues, or understand swamp internals, by +fetching and reading the swamp source code. All commands support `--json` for +machine-readable output. **Verify CLI syntax:** If unsure about exact flags or subcommands, run `swamp help source` for the complete, up-to-date CLI schema. @@ -32,6 +32,26 @@ code. All commands support `--json` for machine-readable output. | Fetch main branch | `swamp source fetch --version main --json` | | Clean source | `swamp source clean --json` | +## When CLI Help Isn't Enough + +If `swamp --help` doesn't fully answer a question about how something +works, fetch the source and read the implementation. Common areas where source +context is needed: + +- **Auth**: How credentials are stored (`~/.config/swamp/auth.json`), API key + format (`swamp_` prefix), headless/CI setup — check `src/infrastructure/auth/` +- **Extension push**: What the push flow does internally, how bundles are + packaged, registry interaction — check `src/cli/commands/extension*.ts` and + `src/domain/extensions/` +- **Init**: What files and directories `swamp repo init` creates and why — check + `src/cli/commands/repo*.ts` and `src/domain/repo/` +- **Data persistence**: How data is stored, versioned, and garbage collected — + check `src/infrastructure/persistence/` + +**General rule:** When a skill's CLI commands and documentation don't provide +enough detail, use `swamp source fetch` to get the source and read the relevant +files directly. + ## Troubleshooting Workflow When a user reports a swamp issue: @@ -122,68 +142,9 @@ Based on the error message or symptoms: 4. **Vault/secret issues**: Check `src/domain/vaults/` 5. **Data persistence issues**: Check `src/infrastructure/persistence/` 6. **Output formatting issues**: Check `src/presentation/output/` -7. **Pre-flight check failures**: See below - -#### Pre-flight Check Failures - -When a method fails with a check-related error (e.g., "Pre-flight check failed: -..."): - -- Read the error messages returned by the failing check — they describe exactly - what condition was not met. -- To identify which check failed, look at the check name in the error output. -- To skip a specific check temporarily: - ```bash - swamp model method run --skip-check --json - ``` -- To skip all checks (e.g., in an offline environment where live API checks - can't run): - ```bash - swamp model method run --skip-checks --json - ``` -- To skip all checks with a given label (e.g., `live` checks): - ```bash - swamp model method run --skip-check-label live --json - ``` -- To run only the checks (without running the method) to diagnose: - ```bash - swamp model validate --method --json - ``` -- To run only checks with a specific label: - ```bash - swamp model validate --label offline --json - ``` -- Check source at `src/domain/models/` for the check's `execute` function to - understand what it validates. - -#### Check Selection Errors - -When `model validate` reports `Check selection` failed: - -- **"Required check X not found on model type Y"** — the definition's - `checks.require` references a check name that doesn't exist on the model type. - Fix: run `swamp model type describe ` to see available checks, then - correct the name in the YAML definition. -- **"Skipped check X not found on model type Y"** — same issue but for - `checks.skip`. The check was removed or renamed in the extension. -- **"Check X is in both require and skip lists"** — the definition lists the - same check in both `require` and `skip`. `skip` wins, but this is likely - unintentional. Remove it from one list. - -#### Extension Check Conflicts - -When an extension fails to load with "Check 'X' already exists on model type -'Y'": - -- Two extensions define the same check name for the same model type. -- Fix: rename one of the checks in the extension's `checks` array. - -#### Required Check Won't Skip - -If `--skip-checks` or `--skip-check ` doesn't skip a check, the -definition's `checks.require` list includes it. Required checks are immune to -CLI skip flags. To override: edit the YAML definition and remove the check from -`require`, or add it to `skip` (which always wins). +7. **Pre-flight check failures**: See + [references/checks.md](references/checks.md) for skip flags, check selection + errors, extension conflicts, and required check behavior ### 5. Explain and Suggest Fixes diff --git a/.claude/skills/swamp-troubleshooting/references/checks.md b/.claude/skills/swamp-troubleshooting/references/checks.md new file mode 100644 index 00000000..608f8af5 --- /dev/null +++ b/.claude/skills/swamp-troubleshooting/references/checks.md @@ -0,0 +1,62 @@ +# Pre-flight Check Troubleshooting + +## Pre-flight Check Failures + +When a method fails with a check-related error (e.g., "Pre-flight check failed: +..."): + +- Read the error messages returned by the failing check — they describe exactly + what condition was not met. +- To identify which check failed, look at the check name in the error output. +- To skip a specific check temporarily: + ```bash + swamp model method run --skip-check --json + ``` +- To skip all checks (e.g., in an offline environment where live API checks + can't run): + ```bash + swamp model method run --skip-checks --json + ``` +- To skip all checks with a given label (e.g., `live` checks): + ```bash + swamp model method run --skip-check-label live --json + ``` +- To run only the checks (without running the method) to diagnose: + ```bash + swamp model validate --method --json + ``` +- To run only checks with a specific label: + ```bash + swamp model validate --label offline --json + ``` +- Check source at `src/domain/models/` for the check's `execute` function to + understand what it validates. + +## Check Selection Errors + +When `model validate` reports `Check selection` failed: + +- **"Required check X not found on model type Y"** — the definition's + `checks.require` references a check name that doesn't exist on the model type. + Fix: run `swamp model type describe ` to see available checks, then + correct the name in the YAML definition. +- **"Skipped check X not found on model type Y"** — same issue but for + `checks.skip`. The check was removed or renamed in the extension. +- **"Check X is in both require and skip lists"** — the definition lists the + same check in both `require` and `skip`. `skip` wins, but this is likely + unintentional. Remove it from one list. + +## Extension Check Conflicts + +When an extension fails to load with "Check 'X' already exists on model type +'Y'": + +- Two extensions define the same check name for the same model type. +- Fix: rename one of the checks in the extension's `checks` array. + +## Required Check Won't Skip + +If `--skip-checks` or `--skip-check ` doesn't skip a check, the +definition's `checks.require` list includes it. Required checks are immune to +CLI skip flags. To override: edit the YAML definition and remove the check from +`require`, or add it to `skip` (which always wins). diff --git a/.claude/skills/swamp-vault/SKILL.md b/.claude/skills/swamp-vault/SKILL.md index 97876959..8ee4fa3d 100644 --- a/.claude/skills/swamp-vault/SKILL.md +++ b/.claude/skills/swamp-vault/SKILL.md @@ -268,13 +268,14 @@ See the **swamp-extension-model** skill for full schema examples. ## When to Use Other Skills -| Need | Use Skill | -| ------------------------- | ----------------------- | -| Vault usage in workflows | `swamp-workflow` | -| Create/run models | `swamp-model` | -| Create custom model types | `swamp-extension-model` | -| Repository structure | `swamp-repo` | -| Manage model data | `swamp-data` | +| Need | Use Skill | +| -------------------------- | ----------------------- | +| Vault usage in workflows | `swamp-workflow` | +| Create/run models | `swamp-model` | +| Create custom model types | `swamp-extension-model` | +| Repository structure | `swamp-repo` | +| Manage model data | `swamp-data` | +| Understand swamp internals | `swamp-troubleshooting` | ## References diff --git a/.claude/skills/swamp-workflow/SKILL.md b/.claude/skills/swamp-workflow/SKILL.md index 3ab3e3b3..0089ccca 100644 --- a/.claude/skills/swamp-workflow/SKILL.md +++ b/.claude/skills/swamp-workflow/SKILL.md @@ -457,13 +457,14 @@ End-to-end workflow creation: ## When to Use Other Skills -| Need | Use Skill | -| -------------------- | ----------------------- | -| Create/run models | `swamp-model` | -| Vault management | `swamp-vault` | -| Repository structure | `swamp-repo` | -| Manage model data | `swamp-data` | -| Create custom models | `swamp-extension-model` | +| Need | Use Skill | +| -------------------------- | ----------------------- | +| Create/run models | `swamp-model` | +| Vault management | `swamp-vault` | +| Repository structure | `swamp-repo` | +| Manage model data | `swamp-data` | +| Create custom models | `swamp-extension-model` | +| Understand swamp internals | `swamp-troubleshooting` | ## References diff --git a/src/infrastructure/assets/skill_assets.ts b/src/infrastructure/assets/skill_assets.ts index abbd03e0..49c0c512 100644 --- a/src/infrastructure/assets/skill_assets.ts +++ b/src/infrastructure/assets/skill_assets.ts @@ -75,6 +75,10 @@ const BUNDLED_SKILLS: SkillInfo[] = [ relativePath: "swamp-model/references/scenarios.md", name: "swamp-model", }, + { + relativePath: "swamp-model/references/outputs.md", + name: "swamp-model", + }, { relativePath: "swamp-repo/SKILL.md", name: "swamp-repo" }, { relativePath: "swamp-repo/references/structure.md", @@ -213,6 +217,10 @@ const BUNDLED_SKILLS: SkillInfo[] = [ relativePath: "swamp-troubleshooting/SKILL.md", name: "swamp-troubleshooting", }, + { + relativePath: "swamp-troubleshooting/references/checks.md", + name: "swamp-troubleshooting", + }, ]; /**