kastell 2.2.4 → 2.2.6

package/kastell-plugin/skills/kastell-research/SKILL.md

@@ -1,90 +1,90 @@
----
-name: kastell-research
-description: Read-only Kastell codebase exploration. Use when tracing a bug across files, mapping callsites before refactoring, or exploring unfamiliar subsystems. Runs in isolated context with Explore agent.
-context: fork
-agent: Explore
-allowed-tools: Read, Grep, Glob
-effort: medium
-memory: project
----
-
-# Kastell Research
-
-## Purpose
-
-Explore the Kastell codebase using read-only tools (Read, Grep, Glob). Runs in a forked Explore agent with Kastell architecture knowledge inlined.
-
-## When to Use
-
-- **Bug investigation:** Trace a bug from CLI command through core logic to adapters/providers. Start at the command file, follow imports to core, check utils and adapters.
-- **Feature mapping:** Map all callsites of a function, trace the import chain, understand how subsystems connect before making changes.
-- **Architecture question:** Understand how audit categories work, how the adapter dispatch flows, or how lock hardening steps are structured.
-
-## Live Codebase
-
-**Commands:**
-!`node -e "import('fs').then(f=>console.log(f.readdirSync('src/commands').filter(x=>x.endsWith('.ts')).map(x=>x.replace('.ts','')).join(', '))).catch(()=>console.log('commands dir not found'))"`
-**Provider registry:**
-!`node -e "import('fs').then(f=>{const c=f.readFileSync('src/constants.ts','utf8');const m=c.match(/PROVIDER_REGISTRY[\s\S]{0,200}/);console.log(m?m[0].split('\n').slice(0,4).join('\n'):'not found')}).catch(()=>console.log('constants.ts not found'))"`
-
-## Architecture Map
-
-```
-src/
-  commands/     # 31 thin CLI wrappers (parse args + delegate only)
-  core/         # Business logic (ALL computation here)
-    audit/      # 30 audit categories, 457+ checks
-    lock/       # 24-step server hardening
-  providers/    # Cloud API: hetzner, digitalocean, vultr, linode
-  adapters/     # Platform abstraction: coolify, dokploy
-    factory.ts  # getAdapter(platform) — entry point
-  mcp/
-    server.ts   # 13 tool registrations
-    tools/      # Handler files
-  utils/        # ssh, config, cloudInit, modeGuard
-  types/        # ServerMode, ServerRecord, Platform
-  constants.ts  # PROVIDER_REGISTRY
-```
-
-## Layer Flow
-
-Commands (parse args) --> Core (business logic) --> Providers (cloud API) / Adapters (platform ops). MCP tools also delegate to Core.
-
-## Research Workflows
-
-**Bug investigation:**
-1. Find the command file (`src/commands/<name>.ts`)
-2. Follow the core import (`src/core/<name>.ts`)
-3. Check adapter/provider calls
-4. Check utils (ssh, config)
-
-**Feature mapping:**
-1. Grep for the function name
-2. Follow import chain
-3. Map all callsites
-4. Check test coverage in `__tests__/`
-
-**Architecture question:**
-1. Read the Architecture Map above
-2. Read `kastell-plugin/skills/kastell-ops/SKILL.md` for full detail (adapter contract, provider registry, layer rules)
-3. Trace specific files
-
-## Debug by Symptom
-
-Common failure patterns and where to look first:
-
-| Symptom | Start Here | Then Check |
-|---------|-----------|------------|
-| SSH auth failure | `src/utils/ssh.ts` → `sshExec()` | `assertValidIp()`, server config `~/.kastell/servers.json`, banner parsing |
-| Provider API error | `src/providers/<name>.ts` | `withProviderErrorHandling()` in `src/utils/retry.ts`, API token config |
-| Audit check false positive | `src/core/audit/checks/<category>.ts` | SSH command output parsing, regex pattern, `sshExec` mock in test |
-| Fix rejected (SAFE tier) | `src/core/fix.ts` → `resolveTier()` | `FORBIDDEN_PATTERNS`, shell redirect/pipe in fixCommand string |
-| MCP tool error | `src/mcp/tools/<name>.ts` | Handler → core delegation, Zod schema validation, `result.content` format |
-| Lock step failure | `src/core/lock.ts` | Step's SSH command, `sshExec` stderr, cloud-init completion |
-| Config not found | `src/utils/config.ts` | `~/.kastell/` dir existence, `servers.json` format, migration from `~/.quicklify/` |
-
-**Known pitfalls:** See `kastell-plugin/skills/kastell-ops/references/pitfalls.md`
-
-## ARGUMENTS
-
-$ARGUMENTS
+---
+name: kastell-research
+description: Read-only Kastell codebase exploration. Use when tracing a bug across files, mapping callsites before refactoring, or exploring unfamiliar subsystems. Runs in isolated context with Explore agent.
+context: fork
+agent: Explore
+allowed-tools: Read, Grep, Glob
+effort: medium
+memory: project
+---
+
+# Kastell Research
+
+## Purpose
+
+Explore the Kastell codebase using read-only tools (Read, Grep, Glob). Runs in a forked Explore agent with Kastell architecture knowledge inlined.
+
+## When to Use
+
+- **Bug investigation:** Trace a bug from CLI command through core logic to adapters/providers. Start at the command file, follow imports to core, check utils and adapters.
+- **Feature mapping:** Map all callsites of a function, trace the import chain, understand how subsystems connect before making changes.
+- **Architecture question:** Understand how audit categories work, how the adapter dispatch flows, or how lock hardening steps are structured.
+
+## Live Codebase
+
+**Commands:**
+!`node -e "import('fs').then(f=>console.log(f.readdirSync('src/commands').filter(x=>x.endsWith('.ts')).map(x=>x.replace('.ts','')).join(', '))).catch(()=>console.log('commands dir not found'))"`
+**Provider registry:**
+!`node -e "import('fs').then(f=>{const c=f.readFileSync('src/constants.ts','utf8');const m=c.match(/PROVIDER_REGISTRY[\s\S]{0,200}/);console.log(m?m[0].split('\n').slice(0,4).join('\n'):'not found')}).catch(()=>console.log('constants.ts not found'))"`
+
+## Architecture Map
+
+```
+src/
+  commands/     # 31 thin CLI wrappers (parse args + delegate only)
+  core/         # Business logic (ALL computation here)
+    audit/      # 30 audit categories, 457+ checks
+    lock/       # 24-step server hardening
+  providers/    # Cloud API: hetzner, digitalocean, vultr, linode
+  adapters/     # Platform abstraction: coolify, dokploy
+    factory.ts  # getAdapter(platform) — entry point
+  mcp/
+    server.ts   # 13 tool registrations
+    tools/      # Handler files
+  utils/        # ssh, config, cloudInit, modeGuard
+  types/        # ServerMode, ServerRecord, Platform
+  constants.ts  # PROVIDER_REGISTRY
+```
+
+## Layer Flow
+
+Commands (parse args) --> Core (business logic) --> Providers (cloud API) / Adapters (platform ops). MCP tools also delegate to Core.
+
+## Research Workflows
+
+**Bug investigation:**
+1. Find the command file (`src/commands/<name>.ts`)
+2. Follow the core import (`src/core/<name>.ts`)
+3. Check adapter/provider calls
+4. Check utils (ssh, config)
+
+**Feature mapping:**
+1. Grep for the function name
+2. Follow import chain
+3. Map all callsites
+4. Check test coverage in `__tests__/`
+
+**Architecture question:**
+1. Read the Architecture Map above
+2. Read `kastell-plugin/skills/kastell-ops/SKILL.md` for full detail (adapter contract, provider registry, layer rules)
+3. Trace specific files
+
+## Debug by Symptom
+
+Common failure patterns and where to look first:
+
+| Symptom | Start Here | Then Check |
+|---------|-----------|------------|
+| SSH auth failure | `src/utils/ssh.ts` → `sshExec()` | `assertValidIp()`, server config `~/.kastell/servers.json`, banner parsing |
+| Provider API error | `src/providers/<name>.ts` | `withProviderErrorHandling()` in `src/utils/retry.ts`, API token config |
+| Audit check false positive | `src/core/audit/checks/<category>.ts` | SSH command output parsing, regex pattern, `sshExec` mock in test |
+| Fix rejected (SAFE tier) | `src/core/fix.ts` → `resolveTier()` | `FORBIDDEN_PATTERNS`, shell redirect/pipe in fixCommand string |
+| MCP tool error | `src/mcp/tools/<name>.ts` | Handler → core delegation, Zod schema validation, `result.content` format |
+| Lock step failure | `src/core/lock.ts` | Step's SSH command, `sshExec` stderr, cloud-init completion |
+| Config not found | `src/utils/config.ts` | `~/.kastell/` dir existence, `servers.json` format, migration from `~/.quicklify/` |
+
+**Known pitfalls:** See `kastell-plugin/skills/kastell-ops/references/pitfalls.md`
+
+## ARGUMENTS
+
+$ARGUMENTS

package/kastell-plugin/skills/kastell-scaffold/SKILL.md

@@ -1,104 +1,104 @@
----
-name: kastell-scaffold
-description: Generate new Kastell components from templates. Creates boilerplate for CLI commands, audit checks, providers, and MCP tools following current architecture (commands thin, core fat, adapters dispatch).
-context: fork
-disable-model-invocation: true
-effort: medium
-allowed-tools: Read, Edit, Write, Bash, Glob, Grep
-argument-hint: "[check|command|provider|mcp-tool] [name]"
----
-
-# Kastell Scaffold
-
-## Purpose
-
-Generate boilerplate files for new Kastell components. Each template follows the post-P63/P64 architecture: commands are thin wrappers, business logic lives in core/, providers handle cloud API, adapters abstract platform ops.
-
-## Usage
-
-```
-/kastell:scaffold command server-migrate     # creates command + core + test files
-/kastell:scaffold check filesystem-perms     # creates audit check + catalog update
-/kastell:scaffold provider ovhcloud          # creates provider + registry entry + test
-/kastell:scaffold mcp-tool server_migrate    # creates MCP tool + registration + test
-```
-
-`$ARGUMENTS[0]` is the component type. `$ARGUMENTS[1]` is the component name.
-
-## Architecture Rules
-
-These rules apply in every generated file. The forked subagent does not automatically have kastell-ops context — enforce these rules explicitly.
-
-| Layer    | Path              | Rule                                                         |
-|----------|-------------------|--------------------------------------------------------------|
-| Commands | src/commands/     | Parse args + delegate. ZERO business logic.                  |
-| Core     | src/core/         | ALL business logic. No chalk/ora/UI imports.                 |
-| Providers| src/providers/    | Cloud API per provider. Extends BaseProvider.                |
-| Adapters | src/adapters/     | Platform ops via PlatformAdapter. Access via getAdapter().   |
-| MCP      | src/mcp/tools/    | Zod schema + handler. Delegates to core.                     |
-
-**Critical:** Never import CoolifyAdapter or DokployAdapter directly. Always use `getAdapter(platform)` from `src/adapters/factory.ts`.
-
-**ESM:** `"type": "module"` — use `import`, not `require`. All imports use `.js` extension.
-
-## Existing Components
-
-**Commands:**
-!`node -e "import('fs').then(f=>console.log(f.readdirSync('src/commands').filter(x=>x.endsWith('.ts')).map(x=>x.replace('.ts','')).join(', '))).catch(()=>console.log('commands dir not found'))"`
-**Providers:**
-!`node -e "import('fs').then(f=>console.log(f.readdirSync('src/providers').filter(x=>x.endsWith('.ts')&&x!=='base.ts').map(x=>x.replace('.ts','')).join(', '))).catch(()=>console.log('providers dir not found'))"`
-**MCP tools:**
-!`node -e "import('fs').then(f=>console.log(f.readdirSync('src/mcp/tools').filter(x=>x.endsWith('.ts')).map(x=>x.replace('.ts','')).join(', '))).catch(()=>console.log('mcp/tools dir not found'))"`
-**Audit categories:**
-!`node -e "import('fs').then(f=>console.log(f.readdirSync('src/core/audit',{withFileTypes:true}).filter(d=>d.isDirectory()).map(d=>d.name).join(', '))).catch(()=>console.log('audit dir not found'))"`
-
-## Script (Deterministic)
-
-Run the scaffold script to generate boilerplate files:
-
-```bash
-bash scripts/scaffold.sh $ARGUMENTS[0] $ARGUMENTS[1]
-```
-
-The script reads `.tpl` templates from `templates/`, replaces `__NAME__`/`__NAME_PASCAL__`/`__NAME_CAMEL__`/`__NAME_UPPER__` placeholders, and creates files in the project. Add `--dry-run` to preview without writing.
-
-**Files generated per type:**
-- `command` → 3 files: `src/commands/`, `src/core/`, `src/__tests__/core/`
-- `check` → 2 files: `src/core/audit/checks/`, `src/__tests__/core/audit/checks/`
-- `provider` → 2 files: `src/providers/`, `src/__tests__/providers/`
-- `mcp-tool` → 2 files: `src/mcp/tools/`, `src/__tests__/mcp/`
-
-## Template Reference (Context for LLM)
-
-After running the script, read the matching reference for registration details:
-
-| Type       | Reference File                                 |
-|------------|------------------------------------------------|
-| `command`  | references/template-command.md                 |
-| `check`    | references/template-audit-check.md             |
-| `provider` | references/template-provider.md                |
-| `mcp-tool` | references/template-mcp-tool.md                |
-
-## After Generation
-
-Perform these steps after creating the boilerplate files:
-
-- [ ] Write tests first (TDD preferred — test core, not command)
-- [ ] Register the component:
-  - Commands: add import in `src/index.ts`
-  - MCP tools: `registerTool()` in `src/mcp/server.ts`
-  - Providers: add to `PROVIDER_REGISTRY` in `src/constants.ts`
-  - Audit checks: add entry to `src/core/audit/catalog.ts`
-- [ ] Run `npm run build && npm test && npm run lint`
-- [ ] Update README.md
-
-## Skill/Agent Oluşturma Kuralları (Yeni skill/agent scaffold ediliyorsa)
-
-Yeni skill veya agent oluşturulurken aşağıdaki koşullar ZORUNLU:
-- [ ] **Ersin kriteri:** scripts/ klasörü oluştur — deterministik iş LLM'e bırakılmayacak
-- [ ] **Progressive disclosure:** SKILL.md < 500 satır, detaylar references/ klasöründe
-- [ ] **Frontmatter:** `effort` + `allowed-tools` ekle (minimum zorunlu)
-- [ ] **Yan etki varsa:** `disable-model-invocation: true` ekle
-- [ ] **Agent ise:** `maxTurns` belirle, `memory` scope tanımla
-- [ ] **Script dili:** Shell (sh/bash) tercih et — Node.js ekosistemiyle uyumlu
-- [ ] **Evaluation:** Gerçek task'ta test et, struggle noktalarını gözlemle
+---
+name: kastell-scaffold
+description: Generate new Kastell components from templates. Creates boilerplate for CLI commands, audit checks, providers, and MCP tools following current architecture (commands thin, core fat, adapters dispatch).
+context: fork
+disable-model-invocation: true
+effort: medium
+allowed-tools: Read, Edit, Write, Bash, Glob, Grep
+argument-hint: "[check|command|provider|mcp-tool] [name]"
+---
+
+# Kastell Scaffold
+
+## Purpose
+
+Generate boilerplate files for new Kastell components. Each template follows the post-P63/P64 architecture: commands are thin wrappers, business logic lives in core/, providers handle cloud API, adapters abstract platform ops.
+
+## Usage
+
+```
+/kastell:scaffold command server-migrate     # creates command + core + test files
+/kastell:scaffold check filesystem-perms     # creates audit check + catalog update
+/kastell:scaffold provider ovhcloud          # creates provider + registry entry + test
+/kastell:scaffold mcp-tool server_migrate    # creates MCP tool + registration + test
+```
+
+`$ARGUMENTS[0]` is the component type. `$ARGUMENTS[1]` is the component name.
+
+## Architecture Rules
+
+These rules apply in every generated file. The forked subagent does not automatically have kastell-ops context — enforce these rules explicitly.
+
+| Layer    | Path              | Rule                                                         |
+|----------|-------------------|--------------------------------------------------------------|
+| Commands | src/commands/     | Parse args + delegate. ZERO business logic.                  |
+| Core     | src/core/         | ALL business logic. No chalk/ora/UI imports.                 |
+| Providers| src/providers/    | Cloud API per provider. Extends BaseProvider.                |
+| Adapters | src/adapters/     | Platform ops via PlatformAdapter. Access via getAdapter().   |
+| MCP      | src/mcp/tools/    | Zod schema + handler. Delegates to core.                     |
+
+**Critical:** Never import CoolifyAdapter or DokployAdapter directly. Always use `getAdapter(platform)` from `src/adapters/factory.ts`.
+
+**ESM:** `"type": "module"` — use `import`, not `require`. All imports use `.js` extension.
+
+## Existing Components
+
+**Commands:**
+!`node -e "import('fs').then(f=>console.log(f.readdirSync('src/commands').filter(x=>x.endsWith('.ts')).map(x=>x.replace('.ts','')).join(', '))).catch(()=>console.log('commands dir not found'))"`
+**Providers:**
+!`node -e "import('fs').then(f=>console.log(f.readdirSync('src/providers').filter(x=>x.endsWith('.ts')&&x!=='base.ts').map(x=>x.replace('.ts','')).join(', '))).catch(()=>console.log('providers dir not found'))"`
+**MCP tools:**
+!`node -e "import('fs').then(f=>console.log(f.readdirSync('src/mcp/tools').filter(x=>x.endsWith('.ts')).map(x=>x.replace('.ts','')).join(', '))).catch(()=>console.log('mcp/tools dir not found'))"`
+**Audit categories:**
+!`node -e "import('fs').then(f=>console.log(f.readdirSync('src/core/audit',{withFileTypes:true}).filter(d=>d.isDirectory()).map(d=>d.name).join(', '))).catch(()=>console.log('audit dir not found'))"`
+
+## Script (Deterministic)
+
+Run the scaffold script to generate boilerplate files:
+
+```bash
+bash scripts/scaffold.sh $ARGUMENTS[0] $ARGUMENTS[1]
+```
+
+The script reads `.tpl` templates from `templates/`, replaces `__NAME__`/`__NAME_PASCAL__`/`__NAME_CAMEL__`/`__NAME_UPPER__` placeholders, and creates files in the project. Add `--dry-run` to preview without writing.
+
+**Files generated per type:**
+- `command` → 3 files: `src/commands/`, `src/core/`, `src/__tests__/core/`
+- `check` → 2 files: `src/core/audit/checks/`, `src/__tests__/core/audit/checks/`
+- `provider` → 2 files: `src/providers/`, `src/__tests__/providers/`
+- `mcp-tool` → 2 files: `src/mcp/tools/`, `src/__tests__/mcp/`
+
+## Template Reference (Context for LLM)
+
+After running the script, read the matching reference for registration details:
+
+| Type       | Reference File                                 |
+|------------|------------------------------------------------|
+| `command`  | references/template-command.md                 |
+| `check`    | references/template-audit-check.md             |
+| `provider` | references/template-provider.md                |
+| `mcp-tool` | references/template-mcp-tool.md                |
+
+## After Generation
+
+Perform these steps after creating the boilerplate files:
+
+- [ ] Write tests first (TDD preferred — test core, not command)
+- [ ] Register the component:
+  - Commands: add import in `src/index.ts`
+  - MCP tools: `registerTool()` in `src/mcp/server.ts`
+  - Providers: add to `PROVIDER_REGISTRY` in `src/constants.ts`
+  - Audit checks: add entry to `src/core/audit/catalog.ts`
+- [ ] Run `npm run build && npm test && npm run lint`
+- [ ] Update README.md
+
+## Skill/Agent Oluşturma Kuralları (Yeni skill/agent scaffold ediliyorsa)
+
+Yeni skill veya agent oluşturulurken aşağıdaki koşullar ZORUNLU:
+- [ ] **Ersin kriteri:** scripts/ klasörü oluştur — deterministik iş LLM'e bırakılmayacak
+- [ ] **Progressive disclosure:** SKILL.md < 500 satır, detaylar references/ klasöründe
+- [ ] **Frontmatter:** `effort` + `allowed-tools` ekle (minimum zorunlu)
+- [ ] **Yan etki varsa:** `disable-model-invocation: true` ekle
+- [ ] **Agent ise:** `maxTurns` belirle, `memory` scope tanımla
+- [ ] **Script dili:** Shell (sh/bash) tercih et — Node.js ekosistemiyle uyumlu
+- [ ] **Evaluation:** Gerçek task'ta test et, struggle noktalarını gözlemle