kastell 2.2.4 → 2.2.6

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

@@ -1,139 +1,139 @@
----
-name: kastell-ops
-description: Kastell CLI patterns, architecture, anti-patterns, and decision trees. Use automatically when working in Kastell codebase or when asked about Kastell server infrastructure, security audit, hardening, lock, provision, or provider management.
-user-invocable: false
-allowed-tools: Bash, Read, Glob, Grep
-effort: medium
-memory: project
----
-
-# Kastell Architecture
-
-Kastell is a CLI toolkit for provisioning, securing, and managing self-hosted servers. TypeScript, ESM, strict mode. 31 CLI commands, 13 MCP tools, 4 cloud providers (hetzner, digitalocean, vultr, linode), 2 platform adapters (coolify, dokploy).
-
-## Live Context
-
-**Version:** !`node -e "import('fs').then(f=>console.log(JSON.parse(f.readFileSync('package.json','utf8')).version)).catch(()=>console.log('unknown'))"`
-**Registered servers:**
-!`kastell list 2>/dev/null || echo "No servers registered"`
-
-## Architecture File Map
-
-```
-src/
-  commands/     # 31 thin CLI wrappers (parse args + delegate only)
-  core/         # Business logic (ALL computation here)
-  providers/    # Cloud API: hetzner, digitalocean, vultr, linode
-  adapters/     # Platform abstraction: coolify, dokploy
-    interface.ts  # PlatformAdapter contract
-    factory.ts    # getAdapter(), detectPlatform(), resolvePlatform()
-  mcp/
-    server.ts     # 13 tool registrations
-    tools/        # Handler files (Zod schema + handler per tool)
-  utils/        # ssh, config, cloudInit, modeGuard, migration
-  types/        # ServerMode, ServerRecord, Platform
-  constants.ts  # PROVIDER_REGISTRY (single source of truth)
-  index.ts      # CLI entry point
-```
-
-## Layer Rules
-
-| Layer    | Path            | Responsibility                          | Rule                        |
-|----------|-----------------|-----------------------------------------|-----------------------------|
-| Commands | src/commands/   | Parse CLI args, call core, display output | ZERO business logic        |
-| Core     | src/core/       | All business logic, orchestration       | No UI/chalk/ora imports     |
-| Providers| src/providers/  | Cloud API calls per provider            | Implements cloud CRUD       |
-| Adapters | src/adapters/   | Platform-specific ops (Coolify/Dokploy) | Via PlatformAdapter interface |
-| MCP      | src/mcp/        | MCP server + tool handlers              | Delegates to core           |
-| Utils    | src/utils/      | SSH, config, modeGuard, errorMapper     | Shared infrastructure       |
-
-## Adapter Contract
-
-Access adapters via `getAdapter(platform)` from `src/adapters/factory.ts`. Never import `CoolifyAdapter` or `DokployAdapter` directly in commands.
-
-```typescript
-interface PlatformAdapter {
-  readonly name: string;              // "coolify" | "dokploy"
-  readonly port: number;              // 8000 (Coolify) | 3000 (Dokploy)
-  readonly defaultLogService: string; // matches platform name
-  readonly platformPorts: readonly number[]; // ports protected from firewall removal
-  getCloudInit(serverName: string): string;
-  healthCheck(ip: string, domain?: string): Promise<HealthResult>;
-  createBackup(ip: string, serverName: string, provider: string): Promise<PlatformBackupResult>;
-  getStatus(ip: string): Promise<PlatformStatusResult>;
-  update(ip: string): Promise<UpdateResult>;
-  restoreBackup?(ip, backupPath, manifest): Promise<PlatformRestoreResult>; // optional
-}
-```
-
-**Factory exports:** `getAdapter(platform)`, `detectPlatform(ip)`, `resolvePlatform(server)`
-
-## Provider Registry
-
-| Provider     | Env Key             | Display Name     |
-|--------------|---------------------|------------------|
-| hetzner      | HETZNER_TOKEN       | Hetzner Cloud    |
-| digitalocean | DIGITALOCEAN_TOKEN  | DigitalOcean     |
-| vultr        | VULTR_TOKEN         | Vultr            |
-| linode       | LINODE_TOKEN        | Linode (Akamai)  |
-
-`PROVIDER_REGISTRY` in `src/constants.ts` is the single source of truth for providers.
-
-## What Do I Want to Add?
-
-### New CLI command
-1. `src/commands/<name>.ts` — thin wrapper (parse + delegate, no logic)
-2. `src/core/<name>.ts` — all business logic here
-3. `src/index.ts` — register with `program`
-4. `src/__tests__/` — test core, not command
-
-### New audit check
-1. `src/core/audit/<category>/` — add to existing category
-2. Update check catalog in `src/core/audit/catalog.ts`
-3. No new command file needed — runs through `kastell audit`
-
-### New provider
-1. `src/providers/<name>.ts` — implements base.ts contract
-2. `src/constants.ts` — add to PROVIDER_REGISTRY
-3. No adapter changes — providers handle cloud API only
-
-### New MCP tool
-1. `src/mcp/tools/server<Name>.ts` — Zod schema + handler
-2. `src/mcp/server.ts` — import + `registerTool()`
-3. Annotations: `readOnlyHint` / `destructiveHint` / `idempotentHint`
-
-## Key Conventions
-
-- ESM project (`"type": "module"`) — `import`, not `require`
-- `KASTELL_SAFE_MODE` + `isSafeMode()` = destructive operation guard
-- `assertValidIp()` before every SSH operation
-- `sanitizedEnv` for subprocess calls
-- `sanitizeResponseData()` whitelist approach for API error responses
-- Config dir: user home `kastell/` directory (auto-migrated from legacy name)
-- `PROVIDER_REGISTRY` = single source of truth for providers
-- `withProviderErrorHandling` HOF for consistent provider error handling
-- `describe.each` with `jest.resetAllMocks()` (not `clearAllMocks()`)
-
-## Scripts (Deterministic)
-
-Run without LLM — deterministic analysis scripts:
-
-```bash
-# Parse audit JSON into 5 security domain summaries
-kastell audit --server myserver --json > /tmp/audit.json
-scripts/parse_audit.sh /tmp/audit.json
-
-# Generate fleet-wide server score table
-kastell fleet --json > /tmp/fleet.json
-scripts/fleet_report.sh /tmp/fleet.json
-
-# Compare audit check count vs test coverage
-scripts/check_coverage.sh
-```
-
-## Reference Files
-
-- 31 CLI commands — see [references/commands.md](references/commands.md)
-- 13 MCP tools — see [references/mcp-tools.md](references/mcp-tools.md)
-- Patterns and test templates — see [references/patterns.md](references/patterns.md)
-- Known pitfalls — see [references/pitfalls.md](references/pitfalls.md)
+---
+name: kastell-ops
+description: Kastell CLI patterns, architecture, anti-patterns, and decision trees. Use automatically when working in Kastell codebase or when asked about Kastell server infrastructure, security audit, hardening, lock, provision, or provider management.
+user-invocable: false
+allowed-tools: Bash, Read, Glob, Grep
+effort: medium
+memory: project
+---
+
+# Kastell Architecture
+
+Kastell is a CLI toolkit for provisioning, securing, and managing self-hosted servers. TypeScript, ESM, strict mode. 31 CLI commands, 13 MCP tools, 4 cloud providers (hetzner, digitalocean, vultr, linode), 2 platform adapters (coolify, dokploy).
+
+## Live Context
+
+**Version:** !`node -e "import('fs').then(f=>console.log(JSON.parse(f.readFileSync('package.json','utf8')).version)).catch(()=>console.log('unknown'))"`
+**Registered servers:**
+!`kastell list 2>/dev/null || echo "No servers registered"`
+
+## Architecture File Map
+
+```
+src/
+  commands/     # 31 thin CLI wrappers (parse args + delegate only)
+  core/         # Business logic (ALL computation here)
+  providers/    # Cloud API: hetzner, digitalocean, vultr, linode
+  adapters/     # Platform abstraction: coolify, dokploy
+    interface.ts  # PlatformAdapter contract
+    factory.ts    # getAdapter(), detectPlatform(), resolvePlatform()
+  mcp/
+    server.ts     # 13 tool registrations
+    tools/        # Handler files (Zod schema + handler per tool)
+  utils/        # ssh, config, cloudInit, modeGuard, migration
+  types/        # ServerMode, ServerRecord, Platform
+  constants.ts  # PROVIDER_REGISTRY (single source of truth)
+  index.ts      # CLI entry point
+```
+
+## Layer Rules
+
+| Layer    | Path            | Responsibility                          | Rule                        |
+|----------|-----------------|-----------------------------------------|-----------------------------|
+| Commands | src/commands/   | Parse CLI args, call core, display output | ZERO business logic        |
+| Core     | src/core/       | All business logic, orchestration       | No UI/chalk/ora imports     |
+| Providers| src/providers/  | Cloud API calls per provider            | Implements cloud CRUD       |
+| Adapters | src/adapters/   | Platform-specific ops (Coolify/Dokploy) | Via PlatformAdapter interface |
+| MCP      | src/mcp/        | MCP server + tool handlers              | Delegates to core           |
+| Utils    | src/utils/      | SSH, config, modeGuard, errorMapper     | Shared infrastructure       |
+
+## Adapter Contract
+
+Access adapters via `getAdapter(platform)` from `src/adapters/factory.ts`. Never import `CoolifyAdapter` or `DokployAdapter` directly in commands.
+
+```typescript
+interface PlatformAdapter {
+  readonly name: string;              // "coolify" | "dokploy"
+  readonly port: number;              // 8000 (Coolify) | 3000 (Dokploy)
+  readonly defaultLogService: string; // matches platform name
+  readonly platformPorts: readonly number[]; // ports protected from firewall removal
+  getCloudInit(serverName: string): string;
+  healthCheck(ip: string, domain?: string): Promise<HealthResult>;
+  createBackup(ip: string, serverName: string, provider: string): Promise<PlatformBackupResult>;
+  getStatus(ip: string): Promise<PlatformStatusResult>;
+  update(ip: string): Promise<UpdateResult>;
+  restoreBackup?(ip, backupPath, manifest): Promise<PlatformRestoreResult>; // optional
+}
+```
+
+**Factory exports:** `getAdapter(platform)`, `detectPlatform(ip)`, `resolvePlatform(server)`
+
+## Provider Registry
+
+| Provider     | Env Key             | Display Name     |
+|--------------|---------------------|------------------|
+| hetzner      | HETZNER_TOKEN       | Hetzner Cloud    |
+| digitalocean | DIGITALOCEAN_TOKEN  | DigitalOcean     |
+| vultr        | VULTR_TOKEN         | Vultr            |
+| linode       | LINODE_TOKEN        | Linode (Akamai)  |
+
+`PROVIDER_REGISTRY` in `src/constants.ts` is the single source of truth for providers.
+
+## What Do I Want to Add?
+
+### New CLI command
+1. `src/commands/<name>.ts` — thin wrapper (parse + delegate, no logic)
+2. `src/core/<name>.ts` — all business logic here
+3. `src/index.ts` — register with `program`
+4. `src/__tests__/` — test core, not command
+
+### New audit check
+1. `src/core/audit/<category>/` — add to existing category
+2. Update check catalog in `src/core/audit/catalog.ts`
+3. No new command file needed — runs through `kastell audit`
+
+### New provider
+1. `src/providers/<name>.ts` — implements base.ts contract
+2. `src/constants.ts` — add to PROVIDER_REGISTRY
+3. No adapter changes — providers handle cloud API only
+
+### New MCP tool
+1. `src/mcp/tools/server<Name>.ts` — Zod schema + handler
+2. `src/mcp/server.ts` — import + `registerTool()`
+3. Annotations: `readOnlyHint` / `destructiveHint` / `idempotentHint`
+
+## Key Conventions
+
+- ESM project (`"type": "module"`) — `import`, not `require`
+- `KASTELL_SAFE_MODE` + `isSafeMode()` = destructive operation guard
+- `assertValidIp()` before every SSH operation
+- `sanitizedEnv` for subprocess calls
+- `sanitizeResponseData()` whitelist approach for API error responses
+- Config dir: user home `kastell/` directory (auto-migrated from legacy name)
+- `PROVIDER_REGISTRY` = single source of truth for providers
+- `withProviderErrorHandling` HOF for consistent provider error handling
+- `describe.each` with `jest.resetAllMocks()` (not `clearAllMocks()`)
+
+## Scripts (Deterministic)
+
+Run without LLM — deterministic analysis scripts:
+
+```bash
+# Parse audit JSON into 5 security domain summaries
+kastell audit --server myserver --json > /tmp/audit.json
+scripts/parse_audit.sh /tmp/audit.json
+
+# Generate fleet-wide server score table
+kastell fleet --json > /tmp/fleet.json
+scripts/fleet_report.sh /tmp/fleet.json
+
+# Compare audit check count vs test coverage
+scripts/check_coverage.sh
+```
+
+## Reference Files
+
+- 31 CLI commands — see [references/commands.md](references/commands.md)
+- 13 MCP tools — see [references/mcp-tools.md](references/mcp-tools.md)
+- Patterns and test templates — see [references/patterns.md](references/patterns.md)
+- Known pitfalls — see [references/pitfalls.md](references/pitfalls.md)

package/kastell-plugin/skills/kastell-ops/references/commands.md

@@ -1,45 +1,45 @@
-# Kastell CLI Commands (31)
-
-All commands follow the thin wrapper pattern: parse args in `src/commands/`, delegate to `src/core/`.
-
-| Command     | Description                                          | Key Arguments                              |
-|-------------|------------------------------------------------------|--------------------------------------------|
-| add         | Add existing server to kastell config                | --ip, --provider, --platform               |
-| audit       | Security audit (30 categories, 457 checks)           | --server, --category, --format, --explain  |
-| auth        | Authenticate with a cloud provider                   | --provider                                 |
-| backup      | Create a platform backup (DB + config files)         | --server                                   |
-| completions | Generate shell completions                           | --shell (bash/zsh/fish)                    |
-| config      | View or edit kastell configuration                   | --edit                                     |
-| destroy     | Destroy a cloud server permanently                   | --server, --force                          |
-| doctor      | Proactive health analysis and recommendations        | --server                                   |
-| domain      | Manage custom domains and SSL certificates           | --server, --domain                         |
-| evidence    | Collect forensic evidence from server                | --server                                   |
-| firewall    | Manage server firewall rules                         | --server, --add, --remove, --list          |
-| fleet       | Fleet-wide server visibility and status              | --format                                   |
-| guard       | Start/stop autonomous security daemon                | --server, --start, --stop, --status        |
-| health      | Check server and platform health                     | --server                                   |
-| init        | Initialize kastell and provision first server        | (interactive prompts)                      |
-| interactive | Launch interactive TUI menu                          | (none)                                     |
-| list        | List all configured servers                          | --format                                   |
-| lock        | One-shot 24-step server hardening                    | --server                                   |
-| logs        | View server or platform logs                         | --server, --lines, --service               |
-| maintain    | Run maintenance tasks (updates, cleanup)             | --server                                   |
-| monitor     | Real-time server monitoring                          | --server                                   |
-| notify      | Send notifications via configured channels           | --channel, --message                       |
-| remove      | Remove server from kastell config                    | --server                                   |
-| restart     | Restart server or platform services                  | --server                                   |
-| restore     | Restore server from a previous backup                | --server, --backup                         |
-| secure      | Set up SSH keys and firewall rules                   | --server                                   |
-| snapshot    | Create, list, or restore server snapshots            | --server, --list, --restore                |
-| ssh         | Open interactive SSH session to server               | --server                                   |
-| status      | Display server status overview                       | --server                                   |
-| transfer    | Transfer server configuration between providers      | --server, --target-provider                |
-| update      | Update server packages and platform                  | --server                                   |
-
-## Notes
-
-- All commands validate input and delegate to `src/core/` — no business logic in commands
-- Destructive commands (`destroy`, `lock`, `restore`) check `isSafeMode()` before executing
-- Commands that need SSH call `assertValidIp()` before any SSH operation
-- `--format` accepts `table` (default) and `json` for machine-readable output
-- Provider-specific commands (`auth`, `list`, `fleet`) use `PROVIDER_REGISTRY` from `constants.ts`
+# Kastell CLI Commands (31)
+
+All commands follow the thin wrapper pattern: parse args in `src/commands/`, delegate to `src/core/`.
+
+| Command     | Description                                          | Key Arguments                              |
+|-------------|------------------------------------------------------|--------------------------------------------|
+| add         | Add existing server to kastell config                | --ip, --provider, --platform               |
+| audit       | Security audit (30 categories, 457 checks)           | --server, --category, --format, --explain  |
+| auth        | Authenticate with a cloud provider                   | --provider                                 |
+| backup      | Create a platform backup (DB + config files)         | --server                                   |
+| completions | Generate shell completions                           | --shell (bash/zsh/fish)                    |
+| config      | View or edit kastell configuration                   | --edit                                     |
+| destroy     | Destroy a cloud server permanently                   | --server, --force                          |
+| doctor      | Proactive health analysis and recommendations        | --server                                   |
+| domain      | Manage custom domains and SSL certificates           | --server, --domain                         |
+| evidence    | Collect forensic evidence from server                | --server                                   |
+| firewall    | Manage server firewall rules                         | --server, --add, --remove, --list          |
+| fleet       | Fleet-wide server visibility and status              | --format                                   |
+| guard       | Start/stop autonomous security daemon                | --server, --start, --stop, --status        |
+| health      | Check server and platform health                     | --server                                   |
+| init        | Initialize kastell and provision first server        | (interactive prompts)                      |
+| interactive | Launch interactive TUI menu                          | (none)                                     |
+| list        | List all configured servers                          | --format                                   |
+| lock        | One-shot 24-step server hardening                    | --server                                   |
+| logs        | View server or platform logs                         | --server, --lines, --service               |
+| maintain    | Run maintenance tasks (updates, cleanup)             | --server                                   |
+| monitor     | Real-time server monitoring                          | --server                                   |
+| notify      | Send notifications via configured channels           | --channel, --message                       |
+| remove      | Remove server from kastell config                    | --server                                   |
+| restart     | Restart server or platform services                  | --server                                   |
+| restore     | Restore server from a previous backup                | --server, --backup                         |
+| secure      | Set up SSH keys and firewall rules                   | --server                                   |
+| snapshot    | Create, list, or restore server snapshots            | --server, --list, --restore                |
+| ssh         | Open interactive SSH session to server               | --server                                   |
+| status      | Display server status overview                       | --server                                   |
+| transfer    | Transfer server configuration between providers      | --server, --target-provider                |
+| update      | Update server packages and platform                  | --server                                   |
+
+## Notes
+
+- All commands validate input and delegate to `src/core/` — no business logic in commands
+- Destructive commands (`destroy`, `lock`, `restore`) check `isSafeMode()` before executing
+- Commands that need SSH call `assertValidIp()` before any SSH operation
+- `--format` accepts `table` (default) and `json` for machine-readable output
+- Provider-specific commands (`auth`, `list`, `fleet`) use `PROVIDER_REGISTRY` from `constants.ts`

package/kastell-plugin/skills/kastell-ops/references/mcp-tools.md

@@ -1,50 +1,50 @@
-# Kastell MCP Tools (13)
-
-All MCP tools are registered in `src/mcp/server.ts` and delegate to `src/core/` functions.
-
-| Tool             | File                 | Purpose                                    | Key Parameters                              |
-|------------------|----------------------|--------------------------------------------|---------------------------------------------|
-| server_info      | serverInfo.ts        | Server list, status, health, sizes         | action: list/status/health/sizes, server?   |
-| server_logs      | serverLogs.ts        | Logs and system metrics via SSH            | server, lines?, service?                    |
-| server_manage    | serverManage.ts      | Add/remove/destroy servers                 | action: add/remove/destroy, server          |
-| server_maintain  | serverMaintain.ts    | Update, restart, maintenance tasks         | action: update/restart/maintain, server     |
-| server_secure    | serverSecure.ts      | SSH setup, firewall, domain management     | action: secure/firewall/domain, server      |
-| server_backup    | serverBackup.ts      | Backup creation and snapshot management    | action: backup/snapshot/restore, server     |
-| server_provision | serverProvision.ts   | New server provisioning                    | provider, name, size, region                |
-| server_audit     | serverAudit.ts       | Security audit (30 categories, 457 checks) | server, category?, format?                  |
-| server_lock      | serverLock.ts        | 24-step one-shot server hardening          | server                                      |
-| server_evidence  | serverEvidence.ts    | Forensic evidence collection               | server                                      |
-| server_guard     | serverGuard.ts       | Autonomous security daemon control         | server, action: start/stop/status           |
-| server_doctor    | serverDoctor.ts      | Proactive health analysis                  | server                                      |
-| server_fleet     | serverFleet.ts       | Fleet-wide server visibility               | format?                                     |
-
-## Routing Rules
-
-All MCP tools follow this delegation chain:
-```
-MCP Client -> tool handler (Zod validation) -> src/core/ function -> result
-```
-
-**Tool handlers NEVER contain business logic.** They:
-1. Validate input with Zod schema
-2. Delegate to the corresponding `src/core/` function
-3. Format the result as `{ content: [{ type: 'text', text: ... }] }`
-
-## Annotations
-
-Each tool registration in `server.ts` includes MCP annotations:
-
-| Annotation       | When to use                                         | Examples                          |
-|------------------|-----------------------------------------------------|-----------------------------------|
-| readOnlyHint     | Tool reads data, no side effects                    | server_info (list/status/health)  |
-| destructiveHint  | Tool causes irreversible changes                    | server_manage (destroy), server_lock |
-| idempotentHint   | Safe to call multiple times with same result        | server_audit, server_health       |
-
-## Error Handling
-
-On error, tools return:
-```typescript
-{ content: [{ type: 'text', text: errorMessage }], isError: true }
-```
-
-Never throw from tool handlers — all errors must be caught and returned as structured error content.
+# Kastell MCP Tools (13)
+
+All MCP tools are registered in `src/mcp/server.ts` and delegate to `src/core/` functions.
+
+| Tool             | File                 | Purpose                                    | Key Parameters                              |
+|------------------|----------------------|--------------------------------------------|---------------------------------------------|
+| server_info      | serverInfo.ts        | Server list, status, health, sizes         | action: list/status/health/sizes, server?   |
+| server_logs      | serverLogs.ts        | Logs and system metrics via SSH            | server, lines?, service?                    |
+| server_manage    | serverManage.ts      | Add/remove/destroy servers                 | action: add/remove/destroy, server          |
+| server_maintain  | serverMaintain.ts    | Update, restart, maintenance tasks         | action: update/restart/maintain, server     |
+| server_secure    | serverSecure.ts      | SSH setup, firewall, domain management     | action: secure/firewall/domain, server      |
+| server_backup    | serverBackup.ts      | Backup creation and snapshot management    | action: backup/snapshot/restore, server     |
+| server_provision | serverProvision.ts   | New server provisioning                    | provider, name, size, region                |
+| server_audit     | serverAudit.ts       | Security audit (30 categories, 457 checks) | server, category?, format?                  |
+| server_lock      | serverLock.ts        | 24-step one-shot server hardening          | server                                      |
+| server_evidence  | serverEvidence.ts    | Forensic evidence collection               | server                                      |
+| server_guard     | serverGuard.ts       | Autonomous security daemon control         | server, action: start/stop/status           |
+| server_doctor    | serverDoctor.ts      | Proactive health analysis                  | server                                      |
+| server_fleet     | serverFleet.ts       | Fleet-wide server visibility               | format?                                     |
+
+## Routing Rules
+
+All MCP tools follow this delegation chain:
+```
+MCP Client -> tool handler (Zod validation) -> src/core/ function -> result
+```
+
+**Tool handlers NEVER contain business logic.** They:
+1. Validate input with Zod schema
+2. Delegate to the corresponding `src/core/` function
+3. Format the result as `{ content: [{ type: 'text', text: ... }] }`
+
+## Annotations
+
+Each tool registration in `server.ts` includes MCP annotations:
+
+| Annotation       | When to use                                         | Examples                          |
+|------------------|-----------------------------------------------------|-----------------------------------|
+| readOnlyHint     | Tool reads data, no side effects                    | server_info (list/status/health)  |
+| destructiveHint  | Tool causes irreversible changes                    | server_manage (destroy), server_lock |
+| idempotentHint   | Safe to call multiple times with same result        | server_audit, server_health       |
+
+## Error Handling
+
+On error, tools return:
+```typescript
+{ content: [{ type: 'text', text: errorMessage }], isError: true }
+```
+
+Never throw from tool handlers — all errors must be caught and returned as structured error content.