kastell 2.2.4 → 2.2.6

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

@@ -1,150 +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'`
+# 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

@@ -1,80 +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
+# 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

@@ -1,72 +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
+# 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