@mandujs/skills 1.0.0

package/skills/mandu-slot/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: mandu-slot
+description: |
+  Filling API 레퍼런스. ctx 메서드, 라이프사이클 훅, 미들웨어 체인.
+  Mandu.filling(), ctx.ok(), .guard(), slot 파일 작업 시 자동 호출.
+---
+
+# Mandu Slot (Filling API)
+
+Slot은 비즈니스 로직을 작성하는 파일입니다. `Mandu.filling()` API를 사용하여
+API 핸들러, 인증 가드, 라이프사이클 훅을 구현합니다.
+
+## Filling Chain API
+
+### Basic Route Handler
+
+```typescript
+// app/api/users/route.ts
+import { Mandu } from "@mandujs/core";
+
+export default Mandu.filling()
+  .get((ctx) => ctx.ok({ users: [] }))
+  .post(async (ctx) => {
+    const body = await ctx.body<{ name: string }>();
+    return ctx.created({ user: { id: "1", ...body } });
+  })
+  .patch(async (ctx) => {
+    const body = await ctx.body<{ name: string }>();
+    return ctx.ok({ user: { id: ctx.params.id, ...body } });
+  })
+  .delete((ctx) => ctx.noContent());
+```
+
+CRITICAL: Always use `Mandu.filling()` chain as default export. Never export raw functions.
+
+## Context Methods (ctx)
+
+### Response Methods
+
+| Method | Status | Usage |
+|--------|--------|-------|
+| `ctx.ok(data)` | 200 | Success response |
+| `ctx.created(data)` | 201 | Resource created |
+| `ctx.noContent()` | 204 | Deleted/no body |
+| `ctx.error(status, msg)` | 4xx/5xx | Error response |
+
+### Request Methods
+
+```typescript
+const body = await ctx.body<T>();       // Parse JSON body (MUST await)
+const { id } = ctx.params;             // URL params (/users/[id])
+const { page, limit } = ctx.query;     // Query string (?page=1&limit=10)
+const auth = ctx.headers.get("authorization");  // Request header
+```
+
+### Store (cross-middleware state)
+
+```typescript
+ctx.set("user", authenticatedUser);    // Set value
+const user = ctx.get("user");          // Get value
+```
+
+## Guard (Authentication/Authorization)
+
+```typescript
+export default Mandu.filling()
+  .guard(async (ctx) => {
+    const token = ctx.headers.get("authorization");
+    if (!token) return ctx.error(401, "Unauthorized");
+    const user = await verifyToken(token);
+    ctx.set("user", user);
+    // Return void to continue, return Response to block
+  })
+  .get((ctx) => ctx.ok({ user: ctx.get("user") }));
+```
+
+Multiple guards run in order. First one to return a Response blocks the chain.
+
+## Lifecycle Hooks
+
+```typescript
+export default Mandu.filling()
+  .onRequest((ctx) => {
+    ctx.set("startTime", Date.now());       // Before handler
+  })
+  .get((ctx) => ctx.ok({ data: "hello" }))
+  .afterHandle((ctx, response) => {
+    const ms = Date.now() - ctx.get("startTime");
+    console.log(`${ctx.method} ${ctx.path} ${ms}ms`);
+    return response;                        // After handler
+  });
+```
+
+## Slot File Locations
+
+| File | Location | Purpose |
+|------|----------|---------|
+| API route | `app/api/{name}/route.ts` | HTTP endpoint handler |
+| Data loader | `spec/slots/{name}.slot.ts` | Server-side data fetch (before render) |
+| Client logic | `spec/slots/{name}.client.ts` | Client-side island logic |
+
+Slot files (`.slot.ts`) run on the server before page rendering.
+Data they return is available to Islands via `useServerData()`.
+
+## Middleware Pattern
+
+```typescript
+// Reusable middleware
+const withAuth = (ctx) => {
+  const token = ctx.headers.get("authorization");
+  if (!token) return ctx.error(401, "Unauthorized");
+  ctx.set("user", decodeToken(token));
+};
+
+const withRateLimit = (ctx) => {
+  // rate limit logic
+};
+
+// Compose
+export default Mandu.filling()
+  .guard(withRateLimit)
+  .guard(withAuth)
+  .get((ctx) => ctx.ok({ user: ctx.get("user") }));
+```
+
+## Common Mistakes
+
+- Exporting raw handler functions instead of `Mandu.filling()` chain
+- Placing slot files outside `spec/slots/` directory
+- Forgetting to `await ctx.body()`
+- Using inline auth checks instead of `.guard()`
+- Not returning `void` from guard when request should continue

package/src/cli.ts

@@ -0,0 +1,125 @@
+#!/usr/bin/env bun
+/**
+ * @mandujs/skills CLI
+ *
+ * Usage:
+ *   bunx mandu-skills install [options]
+ *   bunx mandu-skills install --force
+ *   bunx mandu-skills install --dry-run
+ *   bunx mandu-skills list
+ */
+
+import { installSkills, listSkillIds, type SkillId } from "./index.js";
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+function printUsage(): void {
+  console.log(`
+@mandujs/skills - Claude Code Plugin for Mandu Framework
+
+Usage:
+  mandu-skills install [options]    Install skills into current project
+  mandu-skills list                 List available skills
+  mandu-skills help                 Show this help
+
+Install Options:
+  --force              Overwrite existing files
+  --dry-run            Report what would be done without writing
+  --target <dir>       Target directory (default: cwd)
+  --skills <ids>       Comma-separated skill IDs to install
+  --skip-mcp           Skip .mcp.json setup
+  --skip-settings      Skip .claude/settings.json setup
+`);
+}
+
+function parseFlag(flag: string): boolean {
+  return args.includes(flag);
+}
+
+function parseFlagValue(flag: string): string | undefined {
+  const idx = args.indexOf(flag);
+  if (idx === -1 || idx + 1 >= args.length) return undefined;
+  return args[idx + 1];
+}
+
+async function main(): Promise<void> {
+  if (!command || command === "help" || command === "--help" || command === "-h") {
+    printUsage();
+    process.exit(0);
+  }
+
+  if (command === "list") {
+    console.log("\nAvailable Mandu Skills:\n");
+    const skills = listSkillIds();
+    for (const id of skills) {
+      console.log(`  - ${id}`);
+    }
+    console.log(`\nTotal: ${skills.length} skills\n`);
+    process.exit(0);
+  }
+
+  if (command === "install") {
+    const force = parseFlag("--force");
+    const dryRun = parseFlag("--dry-run");
+    const targetDir = parseFlagValue("--target") || process.cwd();
+    const skipMcp = parseFlag("--skip-mcp");
+    const skipSettings = parseFlag("--skip-settings");
+    const skillsRaw = parseFlagValue("--skills");
+    const skills = skillsRaw
+      ? (skillsRaw.split(",").map((s) => s.trim()) as SkillId[])
+      : undefined;
+
+    console.log(`\n  Mandu Skills Installer${dryRun ? " (dry-run)" : ""}\n`);
+    console.log(`  Target: ${targetDir}`);
+    if (force) console.log("  Mode: force (overwrite existing)");
+    console.log();
+
+    const result = await installSkills({
+      targetDir,
+      force,
+      dryRun,
+      skills,
+      skipMcp,
+      skipSettings,
+    });
+
+    if (result.installed.length > 0) {
+      console.log("  Installed:");
+      for (const file of result.installed) {
+        console.log(`    + ${file}`);
+      }
+    }
+
+    if (result.skipped.length > 0) {
+      console.log("  Skipped:");
+      for (const file of result.skipped) {
+        console.log(`    - ${file}`);
+      }
+    }
+
+    if (result.errors.length > 0) {
+      console.log("  Errors:");
+      for (const err of result.errors) {
+        console.log(`    ! ${err}`);
+      }
+    }
+
+    const total = result.installed.length + result.skipped.length;
+    console.log(`\n  Done. ${result.installed.length}/${total} files written.\n`);
+
+    if (result.errors.length > 0) {
+      process.exit(1);
+    }
+    process.exit(0);
+  }
+
+  console.error(`Unknown command: ${command}`);
+  printUsage();
+  process.exit(1);
+}
+
+main().catch((err) => {
+  console.error("Fatal error:", err);
+  process.exit(1);
+});

package/src/index.ts

@@ -0,0 +1,239 @@
+/**
+ * @mandujs/skills - Claude Code Plugin for Mandu Framework
+ *
+ * Programmatic API for installing and managing Mandu skills
+ * in Claude Code projects.
+ */
+
+import { readdir, readFile, writeFile, mkdir, access, copyFile } from "fs/promises";
+import { join, dirname, resolve } from "path";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/** Root of the @mandujs/skills package */
+const PACKAGE_ROOT = resolve(__dirname, "..");
+
+/** Available skill IDs (9 skills) */
+export const SKILL_IDS = [
+  "mandu-create-feature",
+  "mandu-create-api",
+  "mandu-debug",
+  "mandu-explain",
+  "mandu-guard-guide",
+  "mandu-deploy",
+  "mandu-slot",
+  "mandu-fs-routes",
+  "mandu-hydration",
+] as const;
+
+export type SkillId = (typeof SKILL_IDS)[number];
+
+export interface InstallOptions {
+  /** Target project directory (defaults to cwd) */
+  targetDir?: string;
+  /** Overwrite existing files */
+  force?: boolean;
+  /** Only install specific skills */
+  skills?: SkillId[];
+  /** Skip MCP config setup */
+  skipMcp?: boolean;
+  /** Skip Claude settings setup */
+  skipSettings?: boolean;
+  /** Dry run - report what would be done without writing files */
+  dryRun?: boolean;
+}
+
+export interface InstallResult {
+  installed: string[];
+  skipped: string[];
+  errors: string[];
+}
+
+async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Deep-merge two JSON objects. Arrays are replaced, not merged.
+ */
+function deepMerge(target: Record<string, unknown>, source: Record<string, unknown>): Record<string, unknown> {
+  const result = { ...target };
+
+  for (const key of Object.keys(source)) {
+    const srcVal = source[key];
+    const tgtVal = target[key];
+
+    if (
+      srcVal !== null &&
+      typeof srcVal === "object" &&
+      !Array.isArray(srcVal) &&
+      tgtVal !== null &&
+      typeof tgtVal === "object" &&
+      !Array.isArray(tgtVal)
+    ) {
+      result[key] = deepMerge(
+        tgtVal as Record<string, unknown>,
+        srcVal as Record<string, unknown>
+      );
+    } else {
+      result[key] = srcVal;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Install Mandu skills into a project.
+ *
+ * Copies skill SKILL.md files from `skills/<id>/SKILL.md` to
+ * `<targetDir>/.claude/skills/<id>.md`.
+ */
+export async function installSkills(options: InstallOptions = {}): Promise<InstallResult> {
+  const targetDir = options.targetDir || process.cwd();
+  const force = options.force ?? false;
+  const skillIds = options.skills ?? [...SKILL_IDS];
+  const dryRun = options.dryRun ?? false;
+
+  const result: InstallResult = {
+    installed: [],
+    skipped: [],
+    errors: [],
+  };
+
+  // 1. Install skill files to .claude/skills/
+  const skillsDir = join(targetDir, ".claude", "skills");
+  if (!dryRun) {
+    await mkdir(skillsDir, { recursive: true });
+  }
+
+  for (const skillId of skillIds) {
+    const srcPath = join(PACKAGE_ROOT, "skills", skillId, "SKILL.md");
+    const destPath = join(skillsDir, `${skillId}.md`);
+
+    try {
+      if (!force && (await fileExists(destPath))) {
+        result.skipped.push(`skills/${skillId}.md (exists)`);
+        continue;
+      }
+
+      if (dryRun) {
+        result.installed.push(`skills/${skillId}.md (dry-run)`);
+        continue;
+      }
+
+      await copyFile(srcPath, destPath);
+      result.installed.push(`skills/${skillId}.md`);
+    } catch (err) {
+      result.errors.push(`skills/${skillId}.md: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  // 2. Setup .mcp.json (merge, don't overwrite)
+  if (!options.skipMcp) {
+    const mcpPath = join(targetDir, ".mcp.json");
+    try {
+      const templateContent = await readFile(
+        join(PACKAGE_ROOT, "templates", ".mcp.json"),
+        "utf-8"
+      );
+      const templateConfig = JSON.parse(templateContent);
+
+      if (await fileExists(mcpPath)) {
+        if (force) {
+          if (!dryRun) {
+            const existing = JSON.parse(await readFile(mcpPath, "utf-8"));
+            const merged = deepMerge(existing, templateConfig);
+            await writeFile(mcpPath, JSON.stringify(merged, null, 2) + "\n");
+          }
+          result.installed.push(".mcp.json (merged)");
+        } else {
+          // Check if mandu server already configured
+          const existing = JSON.parse(await readFile(mcpPath, "utf-8"));
+          if (existing.mcpServers?.mandu) {
+            result.skipped.push(".mcp.json (mandu server exists)");
+          } else {
+            if (!dryRun) {
+              const merged = deepMerge(existing, templateConfig);
+              await writeFile(mcpPath, JSON.stringify(merged, null, 2) + "\n");
+            }
+            result.installed.push(".mcp.json (mandu server added)");
+          }
+        }
+      } else {
+        if (!dryRun) {
+          await writeFile(mcpPath, JSON.stringify(templateConfig, null, 2) + "\n");
+        }
+        result.installed.push(".mcp.json (created)");
+      }
+    } catch (err) {
+      result.errors.push(`.mcp.json: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  // 3. Setup .claude/settings.json (merge hooks and permissions)
+  if (!options.skipSettings) {
+    const settingsPath = join(targetDir, ".claude", "settings.json");
+    try {
+      const templateContent = await readFile(
+        join(PACKAGE_ROOT, "templates", ".claude", "settings.json"),
+        "utf-8"
+      );
+      const templateSettings = JSON.parse(templateContent);
+
+      if (!dryRun) {
+        await mkdir(join(targetDir, ".claude"), { recursive: true });
+      }
+
+      if (await fileExists(settingsPath)) {
+        if (force) {
+          if (!dryRun) {
+            const existing = JSON.parse(await readFile(settingsPath, "utf-8"));
+            const merged = deepMerge(existing, templateSettings);
+            await writeFile(settingsPath, JSON.stringify(merged, null, 2) + "\n");
+          }
+          result.installed.push(".claude/settings.json (merged)");
+        } else {
+          result.skipped.push(".claude/settings.json (exists, use --force to merge)");
+        }
+      } else {
+        if (!dryRun) {
+          await writeFile(settingsPath, JSON.stringify(templateSettings, null, 2) + "\n");
+        }
+        result.installed.push(".claude/settings.json (created)");
+      }
+    } catch (err) {
+      result.errors.push(`.claude/settings.json: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Get the path to a skill SKILL.md file in the package
+ */
+export function getSkillPath(skillId: SkillId): string {
+  return join(PACKAGE_ROOT, "skills", skillId, "SKILL.md");
+}
+
+/**
+ * Get the path to a template file in the package
+ */
+export function getTemplatePath(relativePath: string): string {
+  return join(PACKAGE_ROOT, "templates", relativePath);
+}
+
+/**
+ * List all available skill IDs
+ */
+export function listSkillIds(): readonly SkillId[] {
+  return SKILL_IDS;
+}

package/src/init-integration.ts

@@ -0,0 +1,106 @@
+/**
+ * Integration module for `mandu init`
+ *
+ * Called by packages/cli/src/commands/init.ts during project scaffolding.
+ * Copies skills, settings, and configures the Claude Code environment.
+ *
+ * Usage from init.ts:
+ *   import { setupClaudeSkills } from "@mandujs/skills/init-integration";
+ *   await setupClaudeSkills(targetDir);
+ */
+
+import { readFile, writeFile, mkdir, copyFile } from "fs/promises";
+import { join, dirname, resolve } from "path";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const PACKAGE_ROOT = resolve(__dirname, "..");
+
+/** Skill directories containing SKILL.md files */
+const SKILL_DIRS = [
+  "mandu-create-feature",
+  "mandu-create-api",
+  "mandu-debug",
+  "mandu-explain",
+  "mandu-guard-guide",
+  "mandu-deploy",
+  "mandu-slot",
+  "mandu-fs-routes",
+  "mandu-hydration",
+];
+
+export interface SetupResult {
+  skillsInstalled: number;
+  settingsCreated: boolean;
+  errors: string[];
+}
+
+/**
+ * Install Claude Code skills and settings into a new project.
+ * Called by `mandu init` during project creation.
+ *
+ * This function:
+ * 1. Creates .claude/skills/ directory
+ * 2. Copies all 9 skill markdown files (from skills/<id>/SKILL.md -> .claude/skills/<id>.md)
+ * 3. Creates .claude/settings.json with hooks and permissions
+ *
+ * NOTE: .mcp.json is handled separately by init.ts's setupMcpConfig()
+ * to support merge logic for Claude, Gemini, and other agent configs.
+ */
+export async function setupClaudeSkills(targetDir: string): Promise<SetupResult> {
+  const result: SetupResult = {
+    skillsInstalled: 0,
+    settingsCreated: false,
+    errors: [],
+  };
+
+  // 1. Create .claude/skills/ directory
+  const skillsDir = join(targetDir, ".claude", "skills");
+  try {
+    await mkdir(skillsDir, { recursive: true });
+  } catch (err) {
+    result.errors.push(`mkdir .claude/skills: ${err instanceof Error ? err.message : String(err)}`);
+    return result;
+  }
+
+  // 2. Copy skill files (skills/<id>/SKILL.md -> .claude/skills/<id>.md)
+  for (const skillDir of SKILL_DIRS) {
+    const srcPath = join(PACKAGE_ROOT, "skills", skillDir, "SKILL.md");
+    const destPath = join(skillsDir, `${skillDir}.md`);
+
+    try {
+      await copyFile(srcPath, destPath);
+      result.skillsInstalled++;
+    } catch (err) {
+      result.errors.push(`copy ${skillDir}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  // 3. Create .claude/settings.json
+  try {
+    const templatePath = join(PACKAGE_ROOT, "templates", ".claude", "settings.json");
+    const templateContent = await readFile(templatePath, "utf-8");
+    const settingsPath = join(targetDir, ".claude", "settings.json");
+    await writeFile(settingsPath, templateContent);
+    result.settingsCreated = true;
+  } catch (err) {
+    result.errors.push(`settings.json: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  return result;
+}
+
+/**
+ * Get the count of available skills (for display in init output)
+ */
+export function getSkillCount(): number {
+  return SKILL_DIRS.length;
+}
+
+/**
+ * Get skill names (for display in init output)
+ */
+export function getSkillNames(): string[] {
+  return [...SKILL_DIRS];
+}

package/templates/.claude/settings.json

@@ -0,0 +1,37 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(bun *)",
+      "Bash(bunx mandu *)",
+      "Bash(bunx @mandujs/*)",
+      "mcp__mandu__mandu_*"
+    ],
+    "deny": []
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bunx mandu guard check-file \"$FILE_PATH\" --json --severity error 2>/dev/null || true"
+          }
+        ],
+        "description": "Run architecture guard validation before modifying source files"
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"const p=process.env.FILE_PATH||'';if(p.includes('spec/contracts/')){process.stdout.write('Contract modified. Run: bunx mandu guard contract --validate')}\" 2>/dev/null || true"
+          }
+        ],
+        "description": "Notify when contract files are modified"
+      }
+    ]
+  }
+}

package/templates/.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "mandu": {
+      "command": "bunx",
+      "args": ["@mandujs/mcp"],
+      "cwd": "."
+    }
+  }
+}