kastell 2.1.0 → 2.2.1

package/kastell-plugin/skills/kastell-scaffold/references/template-audit-check.md

@@ -0,0 +1,150 @@
+# Template: Audit Check — $1
+
+## Files to Create/Modify
+
+1. `src/core/audit/checks/$1.ts` — check definitions + parser
+2. `src/core/audit/commands.ts` — SSH batch section
+3. `src/core/audit/checks/index.ts` — registry entry
+4. `src/core/audit/compliance/mapper.ts` — compliance mapping (optional)
+5. `src/__tests__/core/audit/checks/$1.test.ts` — test file
+
+## Step 1: Check File
+
+```typescript
+// src/core/audit/checks/$1.ts
+import type { AuditCheck, CheckParser } from "../../types.js";
+
+interface $1CheckDef {
+  id: string;           // "CATEGORY-CHECK-NAME" (uppercase, hyphen-separated)
+  name: string;         // Human-readable description
+  severity: "critical" | "warning" | "info";
+  check: (output: string) => { passed: boolean; currentValue: string };
+  expectedValue: string;
+  fixCommand: string;
+  explain: string;
+}
+
+const $1_CHECKS: $1CheckDef[] = [
+  {
+    id: "CAT-CHECK-ONE",
+    name: "Check description",
+    severity: "warning",
+    check: (output) => {
+      const match = output.includes("SENTINEL_PASS");
+      return { passed: match, currentValue: match ? "configured" : "not found" };
+    },
+    expectedValue: "configured",
+    fixCommand: "command to fix",
+    explain: "Why this matters and what the fix does.",
+  },
+];
+
+export const parse$1Checks: CheckParser = (
+  sectionOutput: string,
+  _platform: string,
+): AuditCheck[] => {
+  // Conditional category: return [] if not applicable (excluded from score)
+  if (!sectionOutput || sectionOutput.includes("SKIP_MARKER")) {
+    return [];
+  }
+
+  return $1_CHECKS.map((def) => {
+    const { passed, currentValue } = def.check(sectionOutput);
+    return {
+      id: def.id,
+      category: "Category Name",  // MUST match CHECK_REGISTRY.name exactly
+      name: def.name,
+      severity: def.severity,
+      passed,
+      currentValue,
+      expectedValue: def.expectedValue,
+      fixCommand: def.fixCommand,
+      explain: def.explain,
+    };
+  });
+};
+```
+
+## Step 2: SSH Batch Section
+
+`src/core/audit/commands.ts` — add bash commands that run on the server.
+
+```typescript
+function new$1Section(): string {
+  return [
+    NAMED_SEP("$1UPPER"),  // MUST match CHECK_REGISTRY.sectionName exactly
+    `command1 || echo 'N/A'`,
+    `command2 || echo 'N/A'`,
+  ].join("\n");
+}
+```
+
+Add to the correct batch array:
+- `BATCH_FAST` — fast commands (<1s)
+- `BATCH_MEDIUM` — medium commands (1-5s)
+- `BATCH_SLOW` — slow commands (5s+, e.g., `nginx -T`)
+
+**Sentinel matching is critical:** `NAMED_SEP("FOO")` produces `---SECTION:FOO---`. This string MUST match `CHECK_REGISTRY.sectionName` exactly.
+
+For conditional categories, add a skip marker as first command:
+```bash
+command -v nginx >/dev/null 2>&1 || echo 'NGINX_NOT_INSTALLED'
+```
+
+## Step 3: Registry
+
+```typescript
+// src/core/audit/checks/index.ts
+import { parse$1Checks } from "./$1.js";
+
+export const CHECK_REGISTRY: CategoryEntry[] = [
+  // ... existing categories ...
+  { name: "Category Name", sectionName: "$1UPPER", parser: parse$1Checks },
+];
+```
+
+**Triple-check:**
+- [ ] `sectionName` === `NAMED_SEP()` parameter
+- [ ] `name` === check file's `category` string
+- [ ] Import path has `.js` extension (ESM)
+
+## Step 4: Compliance Mapping (Optional)
+
+```typescript
+// src/core/audit/compliance/mapper.ts
+export const COMPLIANCE_MAP: Record<string, ComplianceRef[]> = {
+  // ─── $1 ────────────────────────────────────────
+  "CAT-CHECK-ONE": [
+    cis("5.x.x", "Control description", "full"),
+    pci("x.x.x", "PCI control", "partial"),
+  ],
+};
+```
+
+Helpers: `cis()`, `pci()`, `hipaa()`. Coverage: `"full"` or `"partial"`.
+
+## Severity Guide
+
+| Severity | When | Score weight |
+|----------|------|-------------|
+| `critical` | Exploitable, immediate fix required | 3x |
+| `warning` | Risk exists but not urgent | 2x |
+| `info` | Best practice, informational | 1x |
+
+## Anti-Patterns
+
+- **DON'T:** Typo in sentinel strings — parser silently returns empty array, no error
+- **DON'T:** Throw exceptions in `check()` — no try/catch wrapper, entire category breaks
+- **DON'T:** Reuse check ID across categories — compliance mapping will conflict
+- **DON'T:** Multi-step scripts in `fixCommand` — keep it one-line, reference `kastell` command if needed
+- **DON'T:** Forget `|| echo 'N/A'` fallback in SSH commands — parser breaks if command missing
+
+## Next Steps
+
+- [ ] Choose correct audit category (30 categories exist)
+- [ ] Assign unique check key: `<CATEGORY>-NN` pattern
+- [ ] Verify `passed` logic matches `currentValue` evaluation
+- [ ] Add SSH command to category batch (avoid extra SSH round-trips)
+- [ ] Write test: mock SSH output, verify correct passed/failed
+- [ ] Run: `npm test -- --testPathPattern=audit`
+- [ ] Verify check count: `kastell audit --json | jq '.summary.totalChecks'`

package/kastell-plugin/skills/kastell-scaffold/references/template-command.md

@@ -0,0 +1,80 @@
+# Template: CLI Command — $1
+
+## Files to Create
+
+1. `src/commands/$1.ts` — thin wrapper (parse args, call core, display result)
+2. `src/core/$1.ts` — all business logic (no UI imports)
+3. `src/__tests__/core/$1.test.ts` — test the core function, not the command
+
+## Command File (thin wrapper)
+
+```typescript
+// src/commands/$1.ts
+import { program } from 'commander';
+import chalk from 'chalk';
+import ora from 'ora';
+import { $1Core } from '../core/$1.js';
+
+program
+  .command('$1')
+  .description('TODO: describe what this command does')
+  .option('--server <name>', 'Target server name or IP')
+  .option('--json', 'Output as JSON')
+  .action(async (options) => {
+    const spinner = ora('Running $1...').start();
+    try {
+      const result = await $1Core(options);
+      spinner.succeed('Done');
+      if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(chalk.green(result.message));
+      }
+    } catch (error) {
+      spinner.fail(error instanceof Error ? error.message : 'Unknown error');
+      process.exitCode = 1;
+    }
+  });
+```
+
+## Core File (all logic here)
+
+```typescript
+// src/core/$1.ts
+export interface $1Options { server?: string; json?: boolean; }
+export interface $1Result { success: boolean; message: string; }
+
+export async function $1Core(options: $1Options): Promise<$1Result> {
+  // ALL business logic here. NO chalk/ora/UI imports.
+  // assertValidIp() before SSH. getAdapter(platform) for platform ops.
+  // withProviderErrorHandling() for provider calls.
+  throw new Error('Not implemented');
+}
+```
+
+## Test File
+
+```typescript
+// src/__tests__/core/$1.test.ts
+import { $1Core } from '../../core/$1.js';
+jest.mock('../../utils/ssh.js');
+
+describe('$1Core', () => {
+  beforeEach(() => jest.resetAllMocks());
+
+  it('should TODO: describe expected behavior', async () => {
+    const result = await $1Core({ server: 'test-server' });
+    expect(result.success).toBe(true);
+  });
+});
+```
+
+## Next Steps
+
+- [ ] Register command in `src/index.ts`
+- [ ] Write tests first (TDD: test core function, not command)
+- [ ] Add `isSafeMode()` check if operation is destructive
+- [ ] Add `assertValidIp()` before any SSH operation
+- [ ] Use `getAdapter(platform)` for platform-specific operations (never import adapters directly)
+- [ ] Run `npm run build && npm test && npm run lint`
+- [ ] Update README.md command table

package/kastell-plugin/skills/kastell-scaffold/references/template-mcp-tool.md

@@ -0,0 +1,72 @@
+# Template: MCP Tool — $1
+
+## Files to Create
+
+1. `src/mcp/tools/$1.ts` — Zod schema + handler
+2. Update `src/mcp/server.ts` — import + registerTool()
+3. `src/__tests__/mcp/$1.test.ts` — test handler function
+
+## Tool File (Zod schema + handler)
+
+```typescript
+// src/mcp/tools/$1.ts
+import { z } from 'zod';
+import type { McpResponse } from '../types.js';
+
+// IMPORTANT: Schema is a flat object, NOT wrapped in z.object()
+// The SDK wraps it automatically
+export const $1Schema = {
+  server: z.string().optional().describe('Server name or IP. Auto-selected if only one server exists.'),
+  action: z.enum(['TODO']).describe('TODO: describe actions'),
+};
+
+export async function handle$1(params: {
+  server?: string;
+  action: string;
+}): Promise<McpResponse> {
+  // Delegate to core function (NOT direct SSH/provider calls)
+  // Example: const result = await someCoreFunction(params);
+
+  return {
+    content: [
+      {
+        type: 'text' as const,
+        text: JSON.stringify({ success: true }, null, 2),
+      },
+    ],
+  };
+}
+```
+
+## Server Registration
+
+```typescript
+// In src/mcp/server.ts
+import { $1Schema, handle$1 } from './tools/$1.js';
+
+server.registerTool('$1', {
+  description: 'TODO: 50-150 tokens. What it does. Actions. Constraints. Requirements.',
+  inputSchema: $1Schema,
+  annotations: {
+    title: 'TODO: Human-readable title',
+    readOnlyHint: false,    // true if read-only
+    destructiveHint: false, // true if destructive
+    idempotentHint: false,  // true if idempotent
+    openWorldHint: true,
+  },
+}, async (params) => {
+  return handle$1(params);
+});
+```
+
+## Next Steps
+
+- [ ] Define Zod schema as flat object (NOT z.object() wrapper)
+- [ ] Handler delegates to core/ functions (not direct SSH/provider)
+- [ ] Add `server` param as `.optional()` with standard description
+- [ ] Set annotations correctly (readOnlyHint, destructiveHint)
+- [ ] Write description: "What it does. Actions: 'x' does Y. Constraints. For Z, use other_tool instead."
+- [ ] Add SAFE_MODE check if destructive: `if (isSafeMode()) throw ...`
+- [ ] Write test: call handler directly with mock params
+- [ ] Run `npm run build && npm test && npm run lint`
+- [ ] Update README.md MCP tools table

package/kastell-plugin/skills/kastell-scaffold/references/template-provider.md

@@ -0,0 +1,67 @@
+# Template: Provider — $1
+
+## Files to Create
+
+1. `src/providers/$1.ts` — provider implementation (extends BaseProvider)
+2. Update `src/constants.ts` — add to PROVIDER_REGISTRY
+3. `src/__tests__/providers/$1.test.ts` — test with mocked API calls
+
+## Provider Implementation
+
+```typescript
+// src/providers/$1.ts
+import {
+  BaseProvider,
+  type ProviderServer,
+  type CreateServerParams,
+  type ProviderResponse,
+} from './base.js';
+
+export class $1Provider extends BaseProvider {
+  constructor(token: string) {
+    super(token, 'https://api.$1.com/v1'); // adjust API base URL
+  }
+
+  async listServers(): Promise<ProviderResponse<ProviderServer[]>> {
+    return this.request<ProviderServer[]>('GET', '/servers');
+  }
+
+  async createServer(params: CreateServerParams): Promise<ProviderResponse<ProviderServer>> {
+    return this.request<ProviderServer>('POST', '/servers', { body: params });
+  }
+
+  async deleteServer(serverId: string): Promise<ProviderResponse<void>> {
+    return this.request<void>('DELETE', `/servers/${serverId}`);
+  }
+
+  async getServer(serverId: string): Promise<ProviderResponse<ProviderServer>> {
+    return this.request<ProviderServer>('GET', `/servers/${serverId}`);
+  }
+}
+```
+
+## PROVIDER_REGISTRY Entry
+
+```typescript
+// In src/constants.ts — add to PROVIDER_REGISTRY (single source of truth)
+import { $1Provider } from './providers/$1.js';
+
+export const PROVIDER_REGISTRY = {
+  // ... existing providers
+  $1: {
+    name: '$1',
+    envKey: '$1_TOKEN', // e.g., 'OVHCLOUD_TOKEN'
+    class: $1Provider,
+  },
+};
+```
+
+## Next Steps
+
+- [ ] Register in `PROVIDER_REGISTRY` (src/constants.ts) — single source of truth
+- [ ] Implement `stripSensitiveData()` to remove API tokens from error responses
+- [ ] Use `assertValidIp()` before any SSH operation
+- [ ] Use `withProviderErrorHandling()` HOF for API error consistency
+- [ ] Write tests with mocked axios (mock `axios.create()` → `jest.fn(() => axios)`)
+- [ ] Add "Getting Your API Token" section to README.md
+- [ ] Run `npm run build && npm test && npm run lint`

package/kastell-plugin/skills/kastell-scaffold/scripts/scaffold.sh

@@ -0,0 +1,180 @@
+#!/usr/bin/env bash
+# scaffold.sh — Generate Kastell component boilerplate from templates.
+# Usage: scaffold.sh <type> <name> [--dry-run]
+#   type: command | check | provider | mcp-tool
+#   name: kebab-case component name (e.g., server-migrate, filesystem-perms)
+#
+# Ersin criterion: This script runs without an LLM. Deterministic file generation.
+
+set -euo pipefail
+
+# ── Resolve script directory (works in symlink/Git Bash/etc) ──
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TEMPLATE_DIR="$SCRIPT_DIR/../templates"
+PROJECT_ROOT="${PROJECT_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+
+# ── Colors ──
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+CYAN='\033[0;36m'
+NC='\033[0m' # No Color
+
+info()  { echo -e "${CYAN}ℹ${NC} $*"; }
+ok()    { echo -e "${GREEN}✓${NC} $*"; }
+warn()  { echo -e "${YELLOW}⚠${NC} $*"; }
+err()   { echo -e "${RED}✗${NC} $*" >&2; }
+
+# ── Args ──
+TYPE="${1:-}"
+NAME="${2:-}"
+DRY_RUN=false
+for arg in "$@"; do [[ "$arg" == "--dry-run" ]] && DRY_RUN=true; done
+
+if [[ -z "$TYPE" || -z "$NAME" ]]; then
+  echo "Usage: scaffold.sh <type> <name> [--dry-run]"
+  echo "  type: command | check | provider | mcp-tool"
+  echo "  name: kebab-case (e.g., server-migrate)"
+  exit 1
+fi
+
+# Validate type
+case "$TYPE" in
+  command|check|provider|mcp-tool) ;;
+  *) err "Unknown type: $TYPE (valid: command, check, provider, mcp-tool)"; exit 1 ;;
+esac
+
+# Validate name (kebab-case or snake_case, lowercase)
+if [[ ! "$NAME" =~ ^[a-z][a-z0-9_-]*$ ]]; then
+  err "Invalid name: $NAME (must be lowercase kebab-case or snake_case)"
+  exit 1
+fi
+
+# ── Name transformations ──
+to_pascal() {
+  echo "$1" | sed 's/[-_]/ /g' | awk '{for(i=1;i<=NF;i++) $i=toupper(substr($i,1,1)) substr($i,2)}1' | tr -d ' '
+}
+
+to_camel() {
+  local pascal
+  pascal=$(to_pascal "$1")
+  echo "$(echo "${pascal:0:1}" | tr 'A-Z' 'a-z')${pascal:1}"
+}
+
+to_upper() {
+  echo "$1" | tr '[:lower:]' '[:upper:]' | tr '-' '_'
+}
+
+NAME_PASCAL=$(to_pascal "$NAME")
+NAME_CAMEL=$(to_camel "$NAME")
+NAME_UPPER=$(to_upper "$NAME")
+
+info "Scaffolding $TYPE: $NAME"
+info "  PascalCase: $NAME_PASCAL"
+info "  camelCase:  $NAME_CAMEL"
+info "  UPPER:      $NAME_UPPER"
+echo ""
+
+# ── Template processing ──
+process_template() {
+  local tpl_file="$1"
+  local output_file="$2"
+
+  if [[ ! -f "$tpl_file" ]]; then
+    err "Template not found: $tpl_file"
+    return 1
+  fi
+
+  if [[ -f "$output_file" ]] && [[ "$DRY_RUN" == false ]]; then
+    err "File already exists: $output_file (won't overwrite)"
+    return 1
+  fi
+
+  local content
+  content=$(sed \
+    -e "s/__NAME__/$NAME/g" \
+    -e "s/__NAME_PASCAL__/$NAME_PASCAL/g" \
+    -e "s/__NAME_CAMEL__/$NAME_CAMEL/g" \
+    -e "s/__NAME_UPPER__/$NAME_UPPER/g" \
+    "$tpl_file")
+
+  if [[ "$DRY_RUN" == true ]]; then
+    warn "[dry-run] Would create: $output_file"
+    echo "$content"
+    echo "---"
+  else
+    mkdir -p "$(dirname "$output_file")"
+    echo "$content" > "$output_file"
+    ok "Created: $output_file"
+  fi
+}
+
+# ── File mapping per type ──
+CREATED=0
+
+case "$TYPE" in
+  command)
+    process_template "$TEMPLATE_DIR/command.ts.tpl"      "$PROJECT_ROOT/src/commands/$NAME.ts"         && ((CREATED++)) || true
+    process_template "$TEMPLATE_DIR/command-core.ts.tpl"  "$PROJECT_ROOT/src/core/$NAME.ts"             && ((CREATED++)) || true
+    process_template "$TEMPLATE_DIR/command-test.ts.tpl"  "$PROJECT_ROOT/src/__tests__/core/$NAME.test.ts" && ((CREATED++)) || true
+
+    echo ""
+    warn "Next steps:"
+    echo "  1. Register command in src/index.ts"
+    echo "  2. Implement core logic in src/core/$NAME.ts"
+    echo "  3. Add isSafeMode() check if destructive"
+    echo "  4. Run: npm run build && npm test && npm run lint"
+    echo "  5. Update README.md command table"
+    ;;
+
+  check)
+    process_template "$TEMPLATE_DIR/check.ts.tpl"         "$PROJECT_ROOT/src/core/audit/checks/$NAME.ts"         && ((CREATED++)) || true
+    process_template "$TEMPLATE_DIR/check-test.ts.tpl"    "$PROJECT_ROOT/src/__tests__/core/audit/checks/$NAME.test.ts" && ((CREATED++)) || true
+
+    echo ""
+    warn "Next steps:"
+    echo "  1. Add SSH section in src/core/audit/commands.ts:"
+    echo "     NAMED_SEP(\"${NAME_UPPER}\") + bash commands"
+    echo "  2. Register in src/core/audit/checks/index.ts:"
+    echo "     { name: \"$NAME_PASCAL\", sectionName: \"$NAME_UPPER\", parser: parse${NAME_PASCAL}Checks }"
+    echo "  3. Add compliance mapping in src/core/audit/compliance/mapper.ts (optional)"
+    echo "  4. Run: npm run build && npm test && npm run lint"
+    echo "  5. Test: kastell audit --list-checks | grep $NAME_UPPER"
+    ;;
+
+  provider)
+    process_template "$TEMPLATE_DIR/provider.ts.tpl"      "$PROJECT_ROOT/src/providers/$NAME.ts"         && ((CREATED++)) || true
+    process_template "$TEMPLATE_DIR/provider-test.ts.tpl"  "$PROJECT_ROOT/src/__tests__/providers/$NAME.test.ts" && ((CREATED++)) || true
+
+    echo ""
+    warn "Next steps:"
+    echo "  1. Add to PROVIDER_REGISTRY in src/constants.ts:"
+    echo "     $NAME: { name: \"$NAME_PASCAL\", envKey: \"${NAME_UPPER}_TOKEN\", class: ${NAME_PASCAL}Provider }"
+    echo "  2. Implement API methods (adjust base URL)"
+    echo "  3. Add stripSensitiveData() token cleanup"
+    echo "  4. Run: npm run build && npm test && npm run lint"
+    echo "  5. Add 'Getting Your API Token' to README.md"
+    ;;
+
+  mcp-tool)
+    process_template "$TEMPLATE_DIR/mcp-tool.ts.tpl"      "$PROJECT_ROOT/src/mcp/tools/$NAME.ts"         && ((CREATED++)) || true
+    process_template "$TEMPLATE_DIR/mcp-tool-test.ts.tpl"  "$PROJECT_ROOT/src/__tests__/mcp/$NAME.test.ts" && ((CREATED++)) || true
+
+    echo ""
+    warn "Next steps:"
+    echo "  1. Register in src/mcp/server.ts:"
+    echo "     registerTool('$NAME', { schema: ${NAME_CAMEL}Schema, handler: handle${NAME_PASCAL} })"
+    echo "  2. Define Zod schema (flat object, NOT z.object() wrapper)"
+    echo "  3. Handler delegates to core/ (NOT direct SSH/provider)"
+    echo "  4. Add SAFE_MODE check if destructive"
+    echo "  5. Run: npm run build && npm test && npm run lint"
+    echo "  6. Update README.md MCP tools table"
+    ;;
+esac
+
+echo ""
+if [[ "$DRY_RUN" == true ]]; then
+  info "[dry-run] No files were created."
+else
+  ok "Scaffolded $CREATED file(s) for $TYPE: $NAME"
+fi

package/kastell-plugin/skills/kastell-scaffold/templates/check-test.ts.tpl

@@ -0,0 +1,27 @@
+import { parse__NAME_PASCAL__Checks } from "../../core/audit/checks/__NAME__.js";
+
+describe("parse__NAME_PASCAL__Checks", () => {
+  beforeEach(() => jest.resetAllMocks());
+
+  it("returns checks when section output is valid", () => {
+    const result = parse__NAME_PASCAL__Checks("TODO_SENTINEL present", "linux");
+    expect(result.length).toBeGreaterThan(0);
+    expect(result[0].passed).toBe(true);
+  });
+
+  it("returns empty array when section output is empty", () => {
+    const result = parse__NAME_PASCAL__Checks("", "linux");
+    expect(result).toEqual([]);
+  });
+
+  it("returns empty array when skip marker present", () => {
+    const result = parse__NAME_PASCAL__Checks("SKIP_MARKER", "linux");
+    expect(result).toEqual([]);
+  });
+
+  it("returns failed check when sentinel missing", () => {
+    const result = parse__NAME_PASCAL__Checks("some other output", "linux");
+    expect(result.length).toBeGreaterThan(0);
+    expect(result[0].passed).toBe(false);
+  });
+});

package/kastell-plugin/skills/kastell-scaffold/templates/check.ts.tpl

@@ -0,0 +1,50 @@
+import type { AuditCheck, CheckParser } from "../../types.js";
+
+interface __NAME_PASCAL__CheckDef {
+  id: string;
+  name: string;
+  severity: "critical" | "warning" | "info";
+  check: (output: string) => { passed: boolean; currentValue: string };
+  expectedValue: string;
+  fixCommand: string;
+  explain: string;
+}
+
+const __NAME_UPPER___CHECKS: __NAME_PASCAL__CheckDef[] = [
+  {
+    id: "__NAME_UPPER__-01",
+    name: "TODO: check description",
+    severity: "warning",
+    check: (output) => {
+      const match = output.includes("TODO_SENTINEL");
+      return { passed: match, currentValue: match ? "configured" : "not found" };
+    },
+    expectedValue: "configured",
+    fixCommand: "TODO: fix command",
+    explain: "TODO: why this matters",
+  },
+];
+
+export const parse__NAME_PASCAL__Checks: CheckParser = (
+  sectionOutput: string,
+  _platform: string,
+): AuditCheck[] => {
+  if (!sectionOutput || sectionOutput.includes("SKIP_MARKER")) {
+    return [];
+  }
+
+  return __NAME_UPPER___CHECKS.map((def) => {
+    const { passed, currentValue } = def.check(sectionOutput);
+    return {
+      id: def.id,
+      category: "__NAME_PASCAL__",
+      name: def.name,
+      severity: def.severity,
+      passed,
+      currentValue,
+      expectedValue: def.expectedValue,
+      fixCommand: def.fixCommand,
+      explain: def.explain,
+    };
+  });
+};

package/kastell-plugin/skills/kastell-scaffold/templates/command-core.ts.tpl

@@ -0,0 +1,18 @@
+export interface __NAME_PASCAL__Options {
+  server?: string;
+  json?: boolean;
+}
+
+export interface __NAME_PASCAL__Result {
+  success: boolean;
+  message: string;
+}
+
+export async function __NAME_CAMEL__Core(
+  options: __NAME_PASCAL__Options,
+): Promise<__NAME_PASCAL__Result> {
+  // ALL business logic here. NO chalk/ora/UI imports.
+  // assertValidIp() before SSH. getAdapter(platform) for platform ops.
+  // withProviderErrorHandling() for provider calls.
+  throw new Error("Not implemented");
+}

package/kastell-plugin/skills/kastell-scaffold/templates/command-test.ts.tpl

@@ -0,0 +1,17 @@
+import { __NAME_CAMEL__Core } from "../../core/__NAME__.js";
+
+jest.mock("../../utils/ssh.js");
+
+describe("__NAME_CAMEL__Core", () => {
+  beforeEach(() => jest.resetAllMocks());
+
+  it("should TODO: describe expected behavior", async () => {
+    const result = await __NAME_CAMEL__Core({ server: "test-server" });
+    expect(result.success).toBe(true);
+  });
+
+  it("should handle missing server gracefully", async () => {
+    const result = await __NAME_CAMEL__Core({});
+    expect(result.success).toBe(false);
+  });
+});