@kkelly-offical/kkcode 0.1.2

package/src/session/usability-gates.mjs

@@ -0,0 +1,379 @@
+import path from "node:path"
+import { access, readFile, writeFile, mkdir } from "node:fs/promises"
+import { homedir } from "node:os"
+import { spawn } from "node:child_process"
+import { readReviewState } from "../review/review-store.mjs"
+import { fsckSessionStore, getSession } from "./store.mjs"
+import { EventBus } from "../core/events.mjs"
+import { EVENT_TYPES } from "../core/constants.mjs"
+
+const DEFAULT_GATE_TIMEOUT_MS = 15 * 60 * 1000
+const GATE_PREFS_FILE = path.join(homedir(), ".kkcode", "gate-preferences.json")
+
+// --- Gate result cache (5-min TTL, only caches passing results) ---
+const gateCache = new Map()
+const GATE_CACHE_TTL_MS = 5 * 60 * 1000
+
+function getCachedGate(key) {
+  const entry = gateCache.get(key)
+  if (!entry) return null
+  if (Date.now() - entry.ts > GATE_CACHE_TTL_MS) { gateCache.delete(key); return null }
+  return entry.result
+}
+
+function setCachedGate(key, result) {
+  if (result.status === "pass" || result.status === "not_applicable") {
+    gateCache.set(key, { result, ts: Date.now() })
+  }
+}
+
+export function clearGateCache() { gateCache.clear() }
+
+// --- Gate preference persistence ---
+let cachedPrefs = null
+
+async function loadGatePreferences() {
+  if (cachedPrefs) return cachedPrefs
+  try {
+    const raw = await readFile(GATE_PREFS_FILE, "utf8")
+    cachedPrefs = JSON.parse(raw)
+    return cachedPrefs
+  } catch {
+    return null
+  }
+}
+
+export async function saveGatePreferences(prefs) {
+  cachedPrefs = prefs
+  await mkdir(path.dirname(GATE_PREFS_FILE), { recursive: true })
+  await writeFile(GATE_PREFS_FILE, JSON.stringify(prefs, null, 2), "utf8")
+}
+
+export async function hasGatePreferences() {
+  const prefs = await loadGatePreferences()
+  return prefs !== null
+}
+
+export async function getGatePreferences() {
+  return loadGatePreferences()
+}
+
+export function buildGatePromptText() {
+  return [
+    "[SYSTEM] LongAgent 质量门控配置",
+    "",
+    "LongAgent 完成后会运行以下质量检查门控，通过后才标记为完成：",
+    "  1. build  — 运行 npm run build 检查构建是否通过",
+    "  2. test   — 运行测试套件确保无回归",
+    "  3. review — 检查代码审查状态",
+    "  4. health — 检查会话存储健康状态",
+    "  5. budget — 检查 token 预算是否超限",
+    "",
+    "请选择要启用的门控（用逗号分隔，或输入 all/none）：",
+    "例如: build,test 或 all 或 none",
+    "",
+    "提示：门控可以在配置文件中随时修改 (agent.longagent.usability_gates)"
+  ].join("\n")
+}
+
+export function parseGateSelection(answer) {
+  const text = String(answer || "").toLowerCase().trim()
+  const gates = ["build", "test", "review", "health", "budget"]
+  if (text === "all" || text === "全部" || text === "所有") {
+    return Object.fromEntries(gates.map(g => [g, true]))
+  }
+  if (text === "none" || text === "无" || text === "不需要" || text === "跳过") {
+    return Object.fromEntries(gates.map(g => [g, false]))
+  }
+  const selected = new Set(
+    text.split(/[,，\s]+/).map(s => s.trim()).filter(Boolean)
+  )
+  return Object.fromEntries(gates.map(g => [g, selected.has(g)]))
+}
+
+function isEnabled(config, gateName) {
+  return config?.agent?.longagent?.usability_gates?.[gateName]?.enabled !== false
+}
+
+async function fileExists(file) {
+  try {
+    await access(file)
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function readPackageScripts(cwd) {
+  const pkgPath = path.join(cwd, "package.json")
+  const raw = await readFile(pkgPath, "utf8").catch(() => null)
+  if (!raw) return null
+  try {
+    const parsed = JSON.parse(raw)
+    return parsed?.scripts && typeof parsed.scripts === "object" ? parsed.scripts : {}
+  } catch {
+    return null
+  }
+}
+
+function npmBin() {
+  return process.platform === "win32" ? "npm.cmd" : "npm"
+}
+
+function outputSnippet(result) {
+  const lines = `${result.stdout || ""}\n${result.stderr || ""}`
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+  return lines.slice(-12).join(" | ")
+}
+
+async function runCommand({ command, args, cwd, timeoutMs = DEFAULT_GATE_TIMEOUT_MS }) {
+  return new Promise((resolve) => {
+    let done = false
+    let stdout = ""
+    let stderr = ""
+    let timedOut = false
+
+    const child = spawn(command, args, {
+      cwd,
+      windowsHide: true,
+      stdio: ["ignore", "pipe", "pipe"]
+    })
+
+    const timer = setTimeout(() => {
+      timedOut = true
+      child.kill()
+    }, timeoutMs)
+
+    child.stdout.on("data", (buf) => {
+      stdout += String(buf)
+    })
+    child.stderr.on("data", (buf) => {
+      stderr += String(buf)
+    })
+
+    child.on("error", (error) => {
+      if (done) return
+      done = true
+      clearTimeout(timer)
+      resolve({
+        ok: false,
+        code: null,
+        stdout,
+        stderr: `${stderr}\n${error.message}`.trim(),
+        timedOut: false
+      })
+    })
+
+    child.on("close", (code) => {
+      if (done) return
+      done = true
+      clearTimeout(timer)
+      resolve({
+        ok: !timedOut && code === 0,
+        code,
+        stdout,
+        stderr,
+        timedOut
+      })
+    })
+  })
+}
+
+async function checkBuildGate({ cwd, config }) {
+  const cached = getCachedGate("build"); if (cached) return cached
+  if (!isEnabled(config, "build")) {
+    return { enabled: false, status: "disabled", reason: "build gate disabled" }
+  }
+  const scripts = await readPackageScripts(cwd)
+  if (!scripts) {
+    return { enabled: true, status: "not_applicable", reason: "package.json not found" }
+  }
+  if (!scripts.build) {
+    return { enabled: true, status: "not_applicable", reason: "build script not found" }
+  }
+  const result = await runCommand({
+    command: npmBin(),
+    args: ["run", "build", "--silent"],
+    cwd
+  })
+  if (result.ok) {
+    const r = { enabled: true, status: "pass", reason: "build succeeded" }
+    setCachedGate("build", r); return r
+  }
+  return {
+    enabled: true,
+    status: "fail",
+    reason: result.timedOut ? "build timed out" : `build failed with code ${result.code}`,
+    output: outputSnippet(result)
+  }
+}
+
+async function checkTestGate({ cwd, config }) {
+  const cached = getCachedGate("test"); if (cached) return cached
+  if (!isEnabled(config, "test")) {
+    return { enabled: false, status: "disabled", reason: "test gate disabled" }
+  }
+  const scripts = await readPackageScripts(cwd)
+  const hasTestDir = await fileExists(path.join(cwd, "test"))
+  const hasNodeTestDir = await fileExists(path.join(cwd, "tests"))
+
+  if (!scripts && !hasTestDir && !hasNodeTestDir) {
+    return { enabled: true, status: "not_applicable", reason: "no package.json or test directory" }
+  }
+
+  let result
+  if (scripts?.test) {
+    result = await runCommand({
+      command: npmBin(),
+      args: ["run", "test", "--silent"],
+      cwd
+    })
+  } else if (hasTestDir || hasNodeTestDir) {
+    result = await runCommand({
+      command: process.execPath,
+      args: ["--test"],
+      cwd
+    })
+  } else {
+    return { enabled: true, status: "not_applicable", reason: "test script not found" }
+  }
+
+  if (result.ok) {
+    const r = { enabled: true, status: "pass", reason: "tests succeeded" }
+    setCachedGate("test", r); return r
+  }
+  return {
+    enabled: true,
+    status: "fail",
+    reason: result.timedOut ? "tests timed out" : `tests failed with code ${result.code}`,
+    output: outputSnippet(result)
+  }
+}
+
+async function checkReviewGate({ cwd, config, sessionId }) {
+  const cached = getCachedGate("review"); if (cached) return cached
+  if (!isEnabled(config, "review")) {
+    return { enabled: false, status: "disabled", reason: "review gate disabled" }
+  }
+  const state = await readReviewState(cwd)
+  if (!state.files.length) {
+    return { enabled: true, status: "not_applicable", reason: "no review file state" }
+  }
+  if (state.sessionId && sessionId && state.sessionId !== sessionId) {
+    return {
+      enabled: true,
+      status: "not_applicable",
+      reason: `review state belongs to other session (${state.sessionId})`
+    }
+  }
+  const pending = state.files.filter((file) => file.status !== "approved")
+  if (pending.length > 0) {
+    return {
+      enabled: true,
+      status: "fail",
+      reason: `${pending.length} review item(s) not approved`,
+      output: pending.slice(0, 5).map((item) => item.path).join(", ")
+    }
+  }
+  const r = { enabled: true, status: "pass", reason: "all review items approved" }
+  setCachedGate("review", r); return r
+}
+
+async function checkHealthGate({ config }) {
+  const cached = getCachedGate("health"); if (cached) return cached
+  if (!isEnabled(config, "health")) {
+    return { enabled: false, status: "disabled", reason: "health gate disabled" }
+  }
+  const report = await fsckSessionStore()
+  if (report.ok) {
+    const r = { enabled: true, status: "pass", reason: "session fsck passed" }
+    setCachedGate("health", r); return r
+  }
+  return {
+    enabled: true,
+    status: "fail",
+    reason: "session fsck failed",
+    output: report.suggestions.join(" | ")
+  }
+}
+
+async function checkBudgetGate({ config, sessionId }) {
+  const cached = getCachedGate("budget"); if (cached) return cached
+  if (!isEnabled(config, "budget")) {
+    return { enabled: false, status: "disabled", reason: "budget gate disabled" }
+  }
+  const sessionData = await getSession(sessionId)
+  const budgetState = sessionData?.session?.budgetState || null
+  if (!budgetState) {
+    return { enabled: true, status: "pass", reason: "no budget restriction state" }
+  }
+  const strategy = config?.usage?.budget?.strategy || "warn"
+  if (budgetState.exceeded && strategy === "block") {
+    return {
+      enabled: true,
+      status: "fail",
+      reason: "budget exceeded with strategy=block",
+      output: (budgetState.warnings || []).join(" | ")
+    }
+  }
+  if ((budgetState.warnings || []).length > 0) {
+    return {
+      enabled: true,
+      status: "warn",
+      reason: "budget warning",
+      output: budgetState.warnings.join(" | ")
+    }
+  }
+  const r = { enabled: true, status: "pass", reason: "budget gate passed" }
+  setCachedGate("budget", r); return r
+}
+
+function isPassingStatus(status) {
+  return status === "pass" || status === "not_applicable"
+}
+
+export async function runUsabilityGates({
+  sessionId,
+  config,
+  cwd = process.cwd(),
+  iteration = 0
+}) {
+  const [build, test, review, health, budget] = await Promise.all([
+    checkBuildGate({ cwd, config }),
+    checkTestGate({ cwd, config }),
+    checkReviewGate({ cwd, config, sessionId }),
+    checkHealthGate({ config }),
+    checkBudgetGate({ config, sessionId })
+  ])
+  const checks = { build, test, review, health, budget }
+
+  for (const [gate, result] of Object.entries(checks)) {
+    await EventBus.emit({
+      type: EVENT_TYPES.LONGAGENT_GATE_CHECKED,
+      sessionId,
+      payload: {
+        gate,
+        status: result.status,
+        reason: result.reason,
+        iteration
+      }
+    })
+  }
+
+  const failures = Object.entries(checks)
+    .filter(([, result]) => result.enabled !== false && !isPassingStatus(result.status))
+    .map(([gate, result]) => ({
+      gate,
+      status: result.status,
+      reason: result.reason,
+      output: result.output || ""
+    }))
+
+  return {
+    allPass: failures.length === 0,
+    gates: checks,
+    failures
+  }
+}

package/src/skill/builtin/backend-patterns.mjs

@@ -0,0 +1,123 @@
+export const name = "backend-patterns"
+export const description = "Backend development patterns reference: API design, repository pattern, middleware, error handling, authentication"
+
+export async function run(ctx) {
+  const topic = (ctx.args || "").trim().toLowerCase()
+
+  const sections = {
+    api: `## API Design Patterns
+
+### RESTful Conventions
+- GET /resources — list (with pagination: ?page=1&limit=20)
+- GET /resources/:id — get single
+- POST /resources — create (return 201 + Location header)
+- PUT /resources/:id — full replace
+- PATCH /resources/:id — partial update
+- DELETE /resources/:id — remove (return 204)
+
+### Response Format
+\`\`\`json
+{
+  "data": { ... },
+  "meta": { "page": 1, "total": 42, "limit": 20 },
+  "error": null
+}
+\`\`\`
+
+### Error Responses
+\`\`\`json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Email is required",
+    "details": [{ "field": "email", "rule": "required" }]
+  }
+}
+\`\`\`
+Status codes: 400 validation, 401 unauthenticated, 403 unauthorized, 404 not found, 409 conflict, 422 unprocessable, 429 rate limited, 500 server error`,
+
+    repository: `## Repository Pattern
+
+Separate data access from business logic:
+\`\`\`
+Controller → Service → Repository → Database
+\`\`\`
+
+- **Repository**: handles queries, CRUD, caching. Returns domain objects.
+- **Service**: business rules, validation, orchestration. Calls repositories.
+- **Controller**: HTTP concerns only. Parses request, calls service, formats response.
+
+Benefits: testable (mock repository in service tests), swappable storage, clear boundaries.`,
+
+    middleware: `## Middleware Patterns
+
+Execution order matters. Typical chain:
+1. **CORS** — set access headers
+2. **Request ID** — assign unique ID for tracing
+3. **Logger** — log method, path, duration, status
+4. **Rate limiter** — throttle by IP or API key
+5. **Auth** — verify JWT/session, attach user to request
+6. **Validation** — validate request body/params against schema
+7. **Handler** — actual business logic
+8. **Error handler** — catch errors, format response (always LAST)`,
+
+    auth: `## Authentication Patterns
+
+### JWT (Stateless)
+- Access token (short-lived: 15min) + Refresh token (long-lived: 7d)
+- Store refresh in httpOnly cookie, access in memory (NOT localStorage)
+- Rotate refresh tokens on use (one-time use)
+
+### Session (Stateful)
+- Server-side session store (Redis for multi-server)
+- Session ID in httpOnly, Secure, SameSite=Strict cookie
+- Regenerate session ID after login (prevent fixation)
+
+### OAuth 2.0
+- Always validate \`state\` parameter (CSRF protection)
+- Use PKCE for public clients (SPAs, mobile)
+- Exchange code for tokens server-side (never client-side)`,
+
+    error: `## Error Handling
+
+### Layered Error Strategy
+- **Repository**: throw typed errors (NotFoundError, ConflictError)
+- **Service**: catch repo errors, add business context, re-throw
+- **Controller/Middleware**: catch all, map to HTTP status, log, respond
+
+### Custom Error Classes
+\`\`\`javascript
+class AppError extends Error {
+  constructor(message, code, statusCode = 500) {
+    super(message)
+    this.code = code
+    this.statusCode = statusCode
+  }
+}
+class NotFoundError extends AppError {
+  constructor(resource, id) {
+    super(\`\${resource} \${id} not found\`, "NOT_FOUND", 404)
+  }
+}
+\`\`\`
+
+### Never expose internals
+- Log full stack trace server-side
+- Return sanitized message to client
+- Never leak database errors, file paths, or config values`
+  }
+
+  if (topic && sections[topic]) {
+    return sections[topic]
+  }
+
+  // Return overview with all sections
+  const overview = Object.values(sections).join("\n\n---\n\n")
+  return `# Backend Development Patterns
+
+Use \`/backend-patterns <topic>\` for a specific section: api, repository, middleware, auth, error
+
+---
+
+${overview}`
+}

package/src/skill/builtin/commit.mjs

@@ -0,0 +1,64 @@
+export const name = "commit"
+export const description = "Stage changes and create a git commit with a descriptive message using AI-powered git automation"
+
+export async function run(args, context = {}) {
+  const hasGitAuto = context.config?.git_auto?.enabled !== false
+  
+  return `Review the current git status and create a well-structured commit.
+
+${hasGitAuto ? `🚀 Git Auto Mode Enabled
+The AI can now use ghost commits (temporary snapshots) to safely manage changes before you finalize them.
+` : `⚙️ Standard Mode
+Consider enabling git_auto in your config for enhanced safety features.
+`}
+
+Steps:
+1. Run \`git_info\` to understand the repository context.
+2. Run \`git_status\` to see all changed, staged, and untracked files.
+3. Review the changes to understand what needs to be committed.
+
+${hasGitAuto ? `4. **IMPORTANT**: Before making any edits, create a ghost commit snapshot:
+   \`git_snapshot\` - Creates a temporary snapshot you can restore later
+   
+5. After reviewing, if you need to make changes, the AI will:
+   - First create an automatic snapshot (if git_auto.auto_snapshot is enabled)
+   - Apply changes using \`edit\`, \`write\`, or \`git_apply_patch\`
+   
+6. If you're not satisfied with the changes:
+   - Use \`git_list_snapshots\` to see available snapshots
+   - Use \`git_restore\` with the snapshot_id to revert
+   
+7. When satisfied with the changes, guide the user to manually run:
+   \`bash: git add <files> && git commit -m "<message>"\`
+   Note: AI is forbidden from running git commit directly for security.` 
+   
+: `4. Stage the relevant files with manual git commands (AI cannot run git commit):
+   - AI can suggest: \`bash: git add <files>\`
+   - But user must manually run: \`git commit -m "<message>"\`
+   
+5. Note: AI is forbidden from executing git commit/push for security reasons.`}
+
+Commit Message Format (Conventional Commits):
+- feat: new feature or capability
+- fix: bug fix
+- refactor: code restructuring without behavior change
+- docs: documentation changes
+- style: formatting, whitespace, semicolons
+- test: adding or updating tests
+- chore: build process, dependencies, tooling
+
+Format: <type>(<optional scope>): <short description>
+Example: feat(auth): add JWT token refresh logic
+
+Important:
+- Keep the commit focused on a single logical change.
+- If there are unrelated changes, create separate commits.
+- The commit message subject should be under 72 characters.
+- Use imperative mood: "add feature" not "added feature".
+
+${hasGitAuto ? `Safety Features:
+- Ghost commits are stored for 7 days then auto-cleaned
+- Maximum 50 snapshots per repository
+- Snapshots don't interfere with your normal git workflow
+- Use \`git_cleanup\` to manually clean up expired snapshots` : ""}`
+}

package/src/skill/builtin/debug.mjs

@@ -0,0 +1,45 @@
+export const name = "debug"
+export const description = "Diagnose and fix a bug or error (usage: /debug <error description or message>)"
+
+export async function run(ctx) {
+  const issue = (ctx.args || "").trim()
+
+  if (!issue) {
+    return `Please describe the bug or paste the error message.
+
+Usage:
+  /debug TypeError: Cannot read properties of undefined
+  /debug the login page shows a blank screen after submit
+  /debug test suite fails on CI but passes locally`
+  }
+
+  return `Debug this issue: ${issue}
+
+Follow this systematic approach:
+
+1. **Reproduce**
+   - Identify the minimal steps or command to trigger the issue.
+   - If an error message was given, search the codebase for the source: \`grep -r "<key phrase>" src/\`
+   - If a test fails, run it in isolation to confirm.
+
+2. **Locate root cause**
+   - Trace the execution path from the error location backward.
+   - Read the relevant source files to understand the logic.
+   - Check recent changes: \`git log --oneline -10\` and \`git diff HEAD~3\` for potential regressions.
+   - Add diagnostic logging or assertions if the cause isn't obvious.
+
+3. **Fix**
+   - Apply the minimal change that addresses the root cause.
+   - Do NOT refactor surrounding code or fix unrelated issues.
+   - Preserve existing behavior for all other code paths.
+
+4. **Verify**
+   - Run the reproduction steps again to confirm the fix.
+   - Run related tests if they exist.
+   - Check for regressions in adjacent functionality.
+
+5. **Output**
+   - State the root cause in one sentence.
+   - Show the exact change made (file, line, before/after).
+   - List verification steps performed.`
+}