@haposoft/cafekit 0.13.4 → 0.14.1

package/src/opencode/plugins/spec-state.ts

@@ -0,0 +1,244 @@
+/**
+ * Copyright (c) 2026 Haposoft. MIT License.
+ *
+ * OpenCode Plugin — spec-state.ts
+ *
+ * Port of .claude/hooks/spec-state.cjs to OpenCode plugin protocol.
+ *
+ * Behavior:
+ * - On chat.message (before the model processes the user turn), scan
+ *   project specs dirs for the first in_progress / in-progress spec.json.
+ * - Inject a tollgate reminder into the turn by pushing a text part onto
+ *   output.parts (OpenCode equivalent of Claude UserPromptSubmit stdout inject).
+ * - State-change gate: fingerprint phase|done/total in plugins/.logs/tollgate-last.txt;
+ *   unchanged -> one-line reminder; changed -> full URGENT block + refresh fingerprint.
+ *
+ * Disable via `.opencode/runtime.json` { "spec": { "tollgate": false } }.
+ * Fail-open: never throw — a tollgate crash must not break the turn.
+ */
+
+import type { Plugin } from "@opencode-ai/plugin";
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  appendFileSync,
+  readdirSync,
+} from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PLUGIN_DIR = dirname(fileURLToPath(import.meta.url));
+const CACHE_FILE = join(PLUGIN_DIR, ".logs", "tollgate-last.txt");
+
+type SpecJson = {
+  status?: string;
+  current_phase?: string;
+  phase?: string;
+  task_registry?: Record<
+    string,
+    {
+      status?: string;
+      dependencies?: string[];
+    }
+  >;
+};
+
+function readRuntime(cwd: string): Record<string, unknown> {
+  try {
+    const file = join(cwd, ".opencode", "runtime.json");
+    return existsSync(file) ? JSON.parse(readFileSync(file, "utf8")) : {};
+  } catch {
+    return {};
+  }
+}
+
+function logCrash(error: unknown): void {
+  try {
+    const logDir = join(PLUGIN_DIR, ".logs");
+    if (!existsSync(logDir)) mkdirSync(logDir, { recursive: true });
+    appendFileSync(
+      join(logDir, "hook-log.jsonl"),
+      JSON.stringify({
+        ts: new Date().toISOString(),
+        hook: "spec-state",
+        status: "crash",
+        error: error instanceof Error ? error.message : String(error),
+      }) + "\n",
+    );
+  } catch {
+    // fail-open
+  }
+}
+
+function findActiveSpec(
+  specsPath: string,
+): { featureName: string; activeSpec: SpecJson } | null {
+  if (!existsSync(specsPath)) return null;
+
+  let entries;
+  try {
+    entries = readdirSync(specsPath, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const specFile = join(specsPath, entry.name, "spec.json");
+    if (!existsSync(specFile)) continue;
+    try {
+      const specData = JSON.parse(readFileSync(specFile, "utf8")) as SpecJson;
+      if (specData.status === "in_progress" || specData.status === "in-progress") {
+        return { featureName: entry.name, activeSpec: specData };
+      }
+    } catch {
+      // skip bad JSON
+    }
+  }
+  return null;
+}
+
+function buildTollgateText(
+  featureName: string,
+  activeSpec: SpecJson,
+): { stateKey: string; fullBlock: string; reminder: string } {
+  const phase = activeSpec.current_phase || activeSpec.phase || "unknown";
+  const taskRegistry = activeSpec.task_registry || {};
+  const taskEntries = Object.entries(taskRegistry);
+  const taskCounts = taskEntries.reduce<Record<string, number>>((acc, [, task]) => {
+    const status = task?.status || "pending";
+    acc[status] = (acc[status] || 0) + 1;
+    return acc;
+  }, {});
+  const taskStatusByPath = new Map(
+    taskEntries.map(([taskPath, task]) => [taskPath, task?.status || "pending"]),
+  );
+  const nextUnblocked = taskEntries.find(([, task]) => {
+    const status = task?.status || "pending";
+    const deps = Array.isArray(task?.dependencies) ? task.dependencies : [];
+    return status === "pending" && deps.every((dep) => taskStatusByPath.get(dep) === "done");
+  });
+
+  const done = taskCounts.done || 0;
+  const total = taskEntries.length;
+  const stateKey = `${phase}|${done}/${total}`;
+
+  const reminder =
+    `\n> 🔵 Spec \`${featureName}\` @ \`${phase}\` (${done}/${total} tasks done). ` +
+    "Tollgate active — sync `spec.json` when state changes.\n";
+
+  const lines: string[] = [
+    "",
+    "### 🔴 URGENT SYSTEM TOLLGATE (STATE SYNC) 🔴",
+    `- **Active Feature:** \`${featureName}\``,
+    `- **Current Phase:** \`${phase}\``,
+  ];
+  if (total > 0) {
+    lines.push(
+      `- **Task Registry:** \`${total} total | ${done} done | ${taskCounts.in_progress || 0} in_progress | ${taskCounts.blocked || 0} blocked | ${taskCounts.pending || 0} pending\``,
+    );
+    if (nextUnblocked) {
+      lines.push(`- **Next Unblocked Task:** \`${nextUnblocked[0]}\``);
+    }
+  }
+  lines.push("");
+  lines.push(
+    "> BẮT BUỘC (MANDATORY): Nếu bạn vừa hoàn thành một bước, bạn KHÔNG ĐƯỢC báo cáo \"Đã xong\" ngay.",
+  );
+  lines.push(
+    "> Bạn PHẢI sử dụng công cụ Edit để cập nhật trạng thái vật lý sau khi đã có bằng chứng verify thật (build/test/runtime/artifact), không phải chỉ vì code đã viết xong.",
+  );
+  lines.push(
+    "> 1. Sửa file `spec.json` (status, phase/current_phase, timestamps, `task_files`, `task_registry`, validation state nếu có thay đổi).",
+  );
+  lines.push(
+    "> 2. Chỉ khi verify xong mới sửa file `tasks/task-*.md` (status + tick '[x]' các sub-task và completion criteria liên quan).",
+  );
+  lines.push(
+    `> 3. Trước khi set \`ready_for_implementation = true\`, PHẢI chạy \`node .opencode/scripts/validate-spec-output.cjs specs/${featureName}\` và sửa mọi lỗi.`,
+  );
+  lines.push(
+    "> 4. NẾU VỪA HOÀN THÀNH 1 TASK CÓ SỬA SOURCE CODE, BẮT BUỘC cập nhật ngay tài liệu trong `docs/` (`system-architecture.md` hoặc Changelog) cho đồng bộ.",
+  );
+  lines.push(
+    "> CẤM VI PHẠM LUẬT TOLLGATE NÀY NHẰM ĐẢM BẢO TÍNH ĐỒNG BỘ CỦA HỆ THỐNG.",
+  );
+  lines.push("");
+
+  return { stateKey, fullBlock: lines.join("\n"), reminder };
+}
+
+type MessageRef = { id?: string; sessionID?: string };
+
+function injectText(
+  output: { message?: MessageRef; parts?: unknown[] },
+  text: string,
+): void {
+  // OpenCode persists user parts and validates their schema: a part MUST carry
+  // id + sessionID + messageID or the whole turn fails with
+  // "invalid user part before save" (verified on opencode 1.17.15).
+  const message = output.message ?? {};
+  if (!Array.isArray(output.parts)) {
+    (output as { parts: unknown[] }).parts = [];
+  }
+  output.parts!.push({
+    id: `prt_ck${Date.now().toString(36)}${Math.random().toString(36).slice(2, 10)}`,
+    sessionID: message.sessionID ?? "",
+    messageID: message.id ?? "",
+    type: "text",
+    text,
+    synthetic: true,
+  });
+}
+
+export const SpecState: Plugin = async ({ directory }) => ({
+  "chat.message": async (_input, output) => {
+    try {
+      const runtime = readRuntime(directory);
+      const spec = runtime.spec as Record<string, unknown> | undefined;
+      if (spec?.tollgate === false) return;
+
+      const paths = runtime.paths as Record<string, unknown> | undefined;
+      const specsRel =
+        typeof paths?.specs === "string" && paths.specs.trim()
+          ? paths.specs.trim()
+          : "specs";
+      const specsPath = join(directory, specsRel);
+
+      const found = findActiveSpec(specsPath);
+      if (!found) return;
+
+      const { featureName, activeSpec } = found;
+      const { stateKey, fullBlock, reminder } = buildTollgateText(
+        featureName,
+        activeSpec,
+      );
+
+      let lastKey = "";
+      try {
+        lastKey = readFileSync(CACHE_FILE, "utf8").trim();
+      } catch {
+        // first run
+      }
+
+      if (lastKey === stateKey) {
+        injectText(output as { message?: MessageRef; parts?: unknown[] }, reminder);
+        return;
+      }
+
+      try {
+        mkdirSync(dirname(CACHE_FILE), { recursive: true });
+        writeFileSync(CACHE_FILE, stateKey);
+      } catch {
+        // fail-open: still inject full block
+      }
+
+      injectText(output as { message?: MessageRef; parts?: unknown[] }, fullBlock);
+    } catch (error) {
+      logCrash(error);
+      // never throw — tollgate must not break the turn
+    }
+  },
+});

package/src/opencode/plugins/task-scaffold-guard.ts

@@ -0,0 +1,161 @@
+/**
+ * Copyright (c) 2026 Haposoft. MIT License.
+ *
+ * OpenCode Plugin — task-scaffold-guard.ts
+ *
+ * Port of .claude/hooks/task-scaffold-guard.cjs to OpenCode plugin protocol.
+ * Also covers the OpenCode-only `apply_patch` file-creation vector
+ * (`*** Add File: <path>` in `output.args.patchText`).
+ *
+ * Behavior:
+ * - Block `write` and `apply_patch` that create `specs/<feature>/tasks/task-*.md`.
+ * - Task files must be generated via `spec-scaffold.cjs`, then Edit-filled.
+ *
+ * Safety valves:
+ *   1. Escape hatch: `.opencode/runtime.json` `{ "spec": { "scaffold_guard": false } }`
+ *      (fail-closed: missing/broken runtime keeps the guard ON).
+ *   2. Fail-open if `.opencode/scripts/spec-scaffold.cjs` is absent.
+ *   3. Actionable block message with the exact scaffold command.
+ */
+
+import type { Plugin } from "@opencode-ai/plugin";
+import { existsSync, readFileSync, mkdirSync, appendFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const TASK_FILE_RE = /(^|\/)specs\/[^/]+\/tasks\/task-[^/]+\.md$/;
+const TASK_FILE_REL_RE = /(?:^|\/)(specs\/[^/]+\/tasks\/task-[^/]+\.md)$/;
+const FEATURE_RE = /(^|\/)specs\/([^/]+)\/tasks\//;
+const ADD_FILE_RE = /^\*\*\* Add File:\s*(.+?)\s*$/gm;
+
+const PLUGIN_DIR = dirname(fileURLToPath(import.meta.url));
+
+function readRuntime(cwd: string): Record<string, unknown> {
+  try {
+    const file = join(cwd, ".opencode", "runtime.json");
+    return existsSync(file) ? JSON.parse(readFileSync(file, "utf8")) : {};
+  } catch {
+    return {};
+  }
+}
+
+function isTaskFile(filePath: string): boolean {
+  const norm = filePath.replace(/\\/g, "/");
+  return TASK_FILE_RE.test(norm);
+}
+
+function extractFeature(filePath: string): string {
+  const norm = filePath.replace(/\\/g, "/");
+  const m = norm.match(FEATURE_RE);
+  return m ? m[2] : "<feature>";
+}
+
+function pathsFromApplyPatch(patchText: string): string[] {
+  const paths: string[] = [];
+  let match: RegExpExecArray | null;
+  const re = new RegExp(ADD_FILE_RE.source, ADD_FILE_RE.flags);
+  while ((match = re.exec(patchText)) !== null) {
+    const p = match[1]?.trim();
+    if (p) paths.push(p);
+  }
+  return paths;
+}
+
+function collectTargetPaths(tool: string, args: Record<string, unknown>): string[] {
+  if (tool === "write") {
+    const filePath = typeof args.filePath === "string" ? args.filePath.trim() : "";
+    return filePath ? [filePath] : [];
+  }
+  if (tool === "apply_patch") {
+    const patchText = typeof args.patchText === "string" ? args.patchText : "";
+    return patchText ? pathsFromApplyPatch(patchText) : [];
+  }
+  return [];
+}
+
+/**
+ * Resolve a (possibly sandbox-virtual) tool path to the real on-disk task file.
+ * OpenCode may present paths like /home/user/specs/... to the model; the
+ * project-relative `specs/...` suffix joined onto the plugin `directory` is
+ * the reliable location for existence checks.
+ */
+function resolveTaskFile(directory: string, filePath: string): string {
+  const norm = filePath.replace(/\\/g, "/");
+  const m = norm.match(TASK_FILE_REL_RE);
+  return m ? join(directory, m[1]) : filePath;
+}
+
+function formatBlockMessage(filePath: string): string {
+  const feature = extractFeature(filePath);
+  // NOTE: deliberately does NOT mention the runtime.json escape hatch.
+  // Smoke-tested on opencode 1.17.15: when the block message advertised the
+  // override, the model simply wrote runtime.json and disabled the guard.
+  // The hatch stays functional for humans; it is documented in the docs only.
+  return [
+    "TASK SCAFFOLD REQUIRED: task files must be generated, not hand-written.",
+    `Blocked Write: ${filePath}`,
+    "",
+    "Generate the stub(s), then Edit-fill the {{...}} placeholders:",
+    `  node .opencode/scripts/spec-scaffold.cjs ${feature} --tasks "R0-01-slug,R1-01-slug,..." --tasks-only`,
+    "Then use Edit (not Write) on each tasks/task-*.md stub.",
+  ].join("\n");
+}
+
+function logCrash(error: unknown): void {
+  try {
+    const logDir = join(PLUGIN_DIR, ".logs");
+    if (!existsSync(logDir)) mkdirSync(logDir, { recursive: true });
+    appendFileSync(
+      join(logDir, "hook-log.jsonl"),
+      JSON.stringify({
+        ts: new Date().toISOString(),
+        hook: "task-scaffold-guard",
+        status: "crash",
+        error: error instanceof Error ? error.message : String(error),
+      }) + "\n",
+    );
+  } catch {
+    // fail-open
+  }
+}
+
+export const TaskScaffoldGuard: Plugin = async ({ directory }) => ({
+  "tool.execute.before": async (input, output) => {
+    try {
+      if (input.tool !== "write" && input.tool !== "apply_patch" && input.tool !== "edit") return;
+
+      const runtime = readRuntime(directory);
+      const spec = runtime.spec as Record<string, unknown> | undefined;
+      if (spec?.scaffold_guard === false) return;
+
+      const scaffold = join(directory, ".opencode", "scripts", "spec-scaffold.cjs");
+      if (!existsSync(scaffold)) return;
+
+      const args = (output.args ?? {}) as Record<string, unknown>;
+
+      // OpenCode's `edit` CAN create new files (unlike Claude's Edit, which
+      // requires an existing file — the original guard's design premise).
+      // Verified on opencode 1.17.15. Gate: edit on a NON-existent task file
+      // is creation (block); edit on an existing stub is legitimate filling.
+      if (input.tool === "edit") {
+        const filePath = typeof args.filePath === "string" ? args.filePath.trim() : "";
+        if (filePath && isTaskFile(filePath) && !existsSync(resolveTaskFile(directory, filePath))) {
+          throw new Error(formatBlockMessage(filePath));
+        }
+        return;
+      }
+
+      const paths = collectTargetPaths(input.tool, args);
+      for (const filePath of paths) {
+        if (!isTaskFile(filePath)) continue;
+        throw new Error(formatBlockMessage(filePath));
+      }
+    } catch (error) {
+      // Re-throw intentional scaffold blocks; swallow programming errors.
+      if (error instanceof Error && error.message.includes("TASK SCAFFOLD REQUIRED")) {
+        throw error;
+      }
+      logCrash(error);
+    }
+  },
+});

package/src/claude/scripts/browser-tool.cjs

@@ -1,138 +0,0 @@
-#!/usr/bin/env node
-/**
- * Hapo Native Browser Multi-Tool (Puppeteer Bundler)
- * Gồm: screenshot, aria-snapshot, và console logs. Gọn gàng nén trong 1 script.
- * 
- * Usage:
- *   node browser-tool.cjs --action screenshot --url http://localhost:3000 --output ./shot.png
- *   node browser-tool.cjs --action console --url http://localhost:3000
- *   node browser-tool.cjs --action aria --url http://localhost:3000
- */
-
-const fs = require('fs');
-const path = require('path');
-
-let puppeteer;
-try {
-  puppeteer = require('puppeteer-core');
-} catch (e) {
-  try {
-    puppeteer = require('puppeteer');
-  } catch (err) {
-    console.error('\n[LỖI] Hapo Browser Tool yêu cầu gói thư viện Puppeteer!');
-    console.error('Do tôn trọng dung lượng nhẹ (Clean-room), Hapo không tự nhồi nhét Puppeteer vào dự án.');
-    console.error('-> HÃY BẢO LLM (hoặc Dev) CHẠY LỆNH: `npm i -D puppeteer` TRONG PROJECT TRƯỚC KHI DÙNG CÔNG CỤ NÀY!\n');
-    process.exit(1);
-  }
-}
-
-// Hàm phân tích Argument đơn giản
-function parseArgs() {
-  const args = process.argv.slice(2);
-  const config = { action: 'screenshot', url: '', output: './hapo-debug.png' };
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === '--action') config.action = args[++i];
-    if (args[i] === '--url') config.url = args[++i];
-    if (args[i] === '--output') config.output = args[++i];
-  }
-  return config;
-}
-
-async function getBrowser() {
-  // Ưu tiên nỗ lực dùng Chromium của máy nếu xài puppeteer-core (Edge / Chrome)
-  let executablePath = process.env.CHROME_BIN || process.env.PUPPETEER_EXECUTABLE_PATH;
-  
-  if (!executablePath && puppeteer.executablePath) {
-    try {
-      executablePath = puppeteer.executablePath();
-    } catch(e) {}
-  }
-
-  // Fallback map cơ bản cho Mac/Linux
-  if (!executablePath) {
-    if (process.platform === 'darwin') executablePath = '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome';
-    else if (process.platform === 'linux') executablePath = '/usr/bin/google-chrome';
-    else if (process.platform === 'win32') executablePath = 'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe';
-  }
-
-  console.log(`[Hapo Browser] Khởi tạo trình duyệt tại: ${executablePath}`);
-  
-  return puppeteer.launch({
-    executablePath: executablePath || undefined,
-    headless: "new",
-    args: ['--no-sandbox', '--disable-setuid-sandbox']
-  });
-}
-
-async function takeScreenshot(page, output) {
-  console.log(`[Hapo Browser] Đang chụp hình dồn vào file: ${output}`);
-  await fs.promises.mkdir(path.dirname(path.resolve(output)), { recursive: true });
-  await page.screenshot({ path: output, fullPage: true });
-  console.log(`✅ [THÀNH CÔNG] Ảnh chụp full-page đã được nướng chín! LLM hãy gửi cho User lệnh mở ảnh nhé.`);
-}
-
-async function captureConsole(page) {
-  console.log(`[Hapo Browser] Đang rình Console Log trong 5 giây...`);
-  const logs = [];
-  page.on('console', msg => {
-    if (msg.type() === 'error' || msg.type() === 'warning') {
-      logs.push(`[${msg.type().toUpperCase()}] ${msg.text()}`);
-    }
-  });
-  // Gài thêm bẫy vớt lỗi Page Error (JS Crash)
-  page.on('pageerror', err => logs.push(`[CRASH] ${err.message}`));
-
-  // Cho thời gian sống 5 giấy để lắng nghe event
-  await new Promise(r => setTimeout(r, 5000));
-  
-  console.log('\n=== KẾT QUẢ RÌNH RẬP DÀNH CHO LLM ===');
-  if (logs.length === 0) console.log('Sạch bóng quân thù! Không có Warning hay Error nào gào thét trên Console cả.');
-  else logs.forEach(l => console.log(l));
-  console.log('=====================================\n');
-}
-
-async function captureAria(page) {
-  console.log(`[Hapo Browser] Đang quét cấu trúc xẻ thịt HTML (ARIA DOM)...`);
-  // Truy xuất cây Accessibility đơn giản
-  const snapshot = await page.accessibility.snapshot();
-  console.log('\n=== CẤU TRÚC DOM ẨN DƯỚI GÓC NHÌN ARIA ===');
-  console.log(JSON.stringify(snapshot, null, 2));
-  console.log('=============================================\n');
-}
-
-async function main() {
-  const config = parseArgs();
-  if (!config.url || !config.url.startsWith('http')) {
-    console.error('[LỖI] Thiếu --url hợp lệ (Ví dụ: --url http://localhost:3000)');
-    process.exit(1);
-  }
-
-  let browser;
-  try {
-    browser = await getBrowser();
-    const page = await browser.newPage();
-    
-    // Set viewport như Macbook Pro
-    await page.setViewport({ width: 1440, height: 900 });
-    
-    console.log(`[Hapo Browser] Định vị tọa độ: ${config.url}`);
-    await page.goto(config.url, { waitUntil: 'networkidle2', timeout: 15000 });
-
-    if (config.action === 'screenshot') {
-      await takeScreenshot(page, config.output);
-    } else if (config.action === 'console') {
-      await captureConsole(page);
-    } else if (config.action === 'aria') {
-      await captureAria(page);
-    } else {
-      console.error(`[LỖI] Không tồn tại Action tên là: ${config.action}`);
-    }
-
-  } catch (error) {
-    console.error('\n[LỖI SẬP NGUỒN]', error.message);
-  } finally {
-    if (browser) await browser.close();
-  }
-}
-
-main();

package/src/claude/skills/generate-graph/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 fireworks-tech-graph contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.