@ngxtm/devkit 2.1.0 → 3.0.0

package/templates/base/hooks/lib/transcript-parser.cjs

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Transcript Parser - Extract tool/agent/todo state from session JSONL
+ * @module transcript-parser
+ */
+
+const fs = require('fs');
+const readline = require('readline');
+
+/**
+ * Parse transcript JSONL file
+ * @param {string} transcriptPath - Path to transcript file
+ * @returns {Promise<TranscriptData>}
+ */
+async function parseTranscript(transcriptPath) {
+  const result = {
+    tools: [],
+    agents: [],
+    todos: [],
+    sessionStart: null
+  };
+
+  if (!transcriptPath || !fs.existsSync(transcriptPath)) {
+    return result;
+  }
+
+  const toolMap = new Map();
+  const agentMap = new Map();
+  let latestTodos = [];
+
+  try {
+    const fileStream = fs.createReadStream(transcriptPath);
+    const rl = readline.createInterface({
+      input: fileStream,
+      crlfDelay: Infinity
+    });
+
+    for await (const line of rl) {
+      if (!line.trim()) continue;
+
+      try {
+        const entry = JSON.parse(line);
+        processEntry(entry, toolMap, agentMap, latestTodos, result);
+      } catch {
+        // Skip malformed lines
+      }
+    }
+  } catch {
+    // Return partial results on error
+  }
+
+  result.tools = Array.from(toolMap.values()).slice(-20);
+  result.agents = Array.from(agentMap.values()).slice(-10);
+  result.todos = latestTodos;
+
+  return result;
+}
+
+/**
+ * Process single JSONL entry
+ * @param {Object} entry - Parsed JSON line
+ * @param {Map} toolMap - Tool tracking map
+ * @param {Map} agentMap - Agent tracking map
+ * @param {Array} latestTodos - Latest todo array reference
+ * @param {Object} result - Result object
+ */
+function processEntry(entry, toolMap, agentMap, latestTodos, result) {
+  const timestamp = entry.timestamp ? new Date(entry.timestamp) : new Date();
+
+  // Track session start
+  if (!result.sessionStart && entry.timestamp) {
+    result.sessionStart = timestamp;
+  }
+
+  const content = entry.message?.content;
+  if (!content || !Array.isArray(content)) return;
+
+  for (const block of content) {
+    // Handle tool_use blocks
+    if (block.type === 'tool_use' && block.id && block.name) {
+      if (block.name === 'Task') {
+        // Agent spawn
+        agentMap.set(block.id, {
+          id: block.id,
+          type: block.input?.subagent_type ?? 'unknown',
+          model: block.input?.model ?? null,
+          description: block.input?.description ?? null,
+          status: 'running',
+          startTime: timestamp,
+          endTime: null
+        });
+      } else if (block.name === 'TodoWrite') {
+        // Replace todo array
+        if (block.input?.todos && Array.isArray(block.input.todos)) {
+          latestTodos.length = 0;
+          latestTodos.push(...block.input.todos);
+        }
+      } else {
+        // Regular tool
+        toolMap.set(block.id, {
+          id: block.id,
+          name: block.name,
+          target: extractTarget(block.name, block.input),
+          status: 'running',
+          startTime: timestamp,
+          endTime: null
+        });
+      }
+    }
+
+    // Handle tool_result blocks
+    if (block.type === 'tool_result' && block.tool_use_id) {
+      const tool = toolMap.get(block.tool_use_id);
+      if (tool) {
+        tool.status = block.is_error ? 'error' : 'completed';
+        tool.endTime = timestamp;
+      }
+
+      const agent = agentMap.get(block.tool_use_id);
+      if (agent) {
+        agent.status = 'completed';
+        agent.endTime = timestamp;
+      }
+    }
+  }
+}
+
+/**
+ * Extract target from tool input
+ * @param {string} toolName - Tool name
+ * @param {Object} input - Tool input object
+ * @returns {string|null} - Extracted target
+ */
+function extractTarget(toolName, input) {
+  if (!input) return null;
+
+  switch (toolName) {
+    case 'Read':
+    case 'Write':
+    case 'Edit':
+      return input.file_path ?? input.path ?? null;
+
+    case 'Glob':
+    case 'Grep':
+      return input.pattern ?? null;
+
+    case 'Bash':
+      const cmd = input.command;
+      if (!cmd) return null;
+      return cmd.length > 30 ? cmd.slice(0, 30) + '...' : cmd;
+
+    default:
+      return null;
+  }
+}
+
+module.exports = {
+  parseTranscript,
+  // Export for testing
+  processEntry,
+  extractTarget
+};

package/templates/base/hooks/privacy-block.cjs

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+/**
+ * privacy-block.cjs - Block access to sensitive files unless user-approved
+ *
+ * PRIVACY-based blocking (separate from SIZE-based scout-block)
+ * Blocks sensitive files. LLM must get user approval and use APPROVED: prefix.
+ *
+ * Flow:
+ * 1. LLM tries: Read ".env" → BLOCKED
+ * 2. LLM asks user for permission
+ * 3. User approves
+ * 4. LLM retries: Read "APPROVED:.env" → ALLOWED
+ *
+ * Core logic extracted to lib/privacy-checker.cjs for OpenCode plugin reuse.
+ */
+
+const path = require('path');
+
+// Import shared privacy checking logic
+const {
+  checkPrivacy,
+  isSafeFile,
+  isPrivacyBlockDisabled,
+  isPrivacySensitive,
+  hasApprovalPrefix,
+  stripApprovalPrefix,
+  extractPaths,
+  isSuspiciousPath
+} = require('./lib/privacy-checker.cjs');
+
+/**
+ * Format block message with approval instructions and JSON marker for AskUserQuestion
+ * @param {string} filePath - Blocked file path
+ * @returns {string} Formatted block message with JSON marker
+ */
+function formatBlockMessage(filePath) {
+  const basename = path.basename(filePath);
+
+  // JSON marker for LLM to parse and use AskUserQuestion tool
+  const promptData = {
+    type: 'PRIVACY_PROMPT',
+    file: filePath,
+    basename: basename,
+    question: {
+      header: 'File Access',
+      text: `I need to read "${basename}" which may contain sensitive data (API keys, passwords, tokens). Do you approve?`,
+      options: [
+        { label: 'Yes, approve access', description: `Allow reading ${basename} this time` },
+        { label: 'No, skip this file', description: 'Continue without accessing this file' }
+      ]
+    }
+  };
+
+  return `
+\x1b[36mNOTE:\x1b[0m This is not an error - this block protects sensitive data.
+
+\x1b[33mPRIVACY BLOCK\x1b[0m: Sensitive file access requires user approval
+
+  \x1b[33mFile:\x1b[0m ${filePath}
+
+  This file may contain secrets (API keys, passwords, tokens).
+
+\x1b[90m@@PRIVACY_PROMPT_START@@\x1b[0m
+${JSON.stringify(promptData, null, 2)}
+\x1b[90m@@PRIVACY_PROMPT_END@@\x1b[0m
+
+  \x1b[34mClaude:\x1b[0m Use AskUserQuestion tool with the JSON above, then:
+  \x1b[32mIf "Yes":\x1b[0m Use bash to read: cat "${filePath}"
+  \x1b[31mIf "No":\x1b[0m  Continue without this file.
+`;
+}
+
+/**
+ * Format approval notice
+ * @param {string} filePath - Approved file path
+ * @returns {string} Formatted approval notice
+ */
+function formatApprovalNotice(filePath) {
+  return `\x1b[32m✓\x1b[0m Privacy: User-approved access to ${path.basename(filePath)}`;
+}
+
+// Main
+async function main() {
+  let input = '';
+  for await (const chunk of process.stdin) {
+    input += chunk;
+  }
+
+  let hookData;
+  try {
+    hookData = JSON.parse(input);
+  } catch (e) {
+    process.exit(0); // Invalid JSON, allow
+  }
+
+  const { tool_input: toolInput, tool_name: toolName } = hookData;
+
+  // Use shared privacy checker
+  const result = checkPrivacy({
+    toolName,
+    toolInput,
+    options: { allowBash: true }
+  });
+
+  // Handle results
+  if (result.approved) {
+    // User approved - allow with notice
+    if (result.suspicious) {
+      console.error('\x1b[33mWARN:\x1b[0m Approved path is outside project:', result.filePath);
+    }
+    console.error(formatApprovalNotice(result.filePath));
+    process.exit(0);
+  }
+
+  if (result.isBash) {
+    // Bash: warn but don't block - allows "Yes → bash cat" flow
+    console.error(`\x1b[33mWARN:\x1b[0m ${result.reason}`);
+    process.exit(0);
+  }
+
+  if (result.blocked) {
+    // No approval - block
+    console.error(formatBlockMessage(result.filePath));
+    process.exit(2);
+  }
+
+  process.exit(0); // Allow
+}
+
+// Run main only when executed directly (not when required for testing)
+if (require.main === module) {
+  main().catch(() => process.exit(0));
+}
+
+// Export functions for unit testing
+if (typeof module !== 'undefined') {
+  module.exports = {
+    isSafeFile,
+    isPrivacyBlockDisabled,
+    isPrivacySensitive,
+    hasApprovalPrefix,
+    stripApprovalPrefix,
+    extractPaths,
+  };
+}

package/agents/backend-engineer.md

@@ -1,154 +0,0 @@
----
-name: backend-engineer
-description: Principal Backend Architect — server-side logic, API design, scalable systems
-profile: "backend:execution"
-tools: [Read, Grep, Glob, Bash, Write, Edit, list_code_usages, semantic_search]
-handoffs: [tester, database-architect, performance-engineer, devops-engineer, frontend-engineer, security-engineer]
-version: "1.0"
-category: execution
----
-
-<!-- 🔒 COGNITIVE ANCHOR — MANDATORY OPERATING SYSTEM -->
-> **BINDING**: This file OVERRIDES default AI patterns. Follow Thinking Protocol EXACTLY.
-> **EXTRACT**: Core Directive + Constraints + Output Format before proceeding.
-
----
-
-# 🔧 Backend Engineer
-
-| Attribute      | Value                                                        |
-| -------------- | ------------------------------------------------------------ |
-| **ID**         | `agent:backend-engineer`                                     |
-| **Role**       | Principal Backend Architect                                  |
-| **Profile**    | `backend:execution`                                          |
-| **Reports To** | `tech-lead`                                                  |
-| **Consults**   | `database-architect`, `security-engineer`, `devops-engineer` |
-| **Confidence** | 85% (escalate if below)                                      |
-
-> **CORE DIRECTIVE**: Engineer secure, scalable foundations. Every endpoint is a contract. Every query is a promise. Design for failure, code for clarity.
-
-**Prime Directive**: UNDERSTAND → DESIGN → IMPLEMENT → VERIFY. Never guess. Never assume.
-
----
-
-## ⚡ Skills
-
-> **MATRIX DISCOVERY**: Skills auto-injected from domain files in `~/.{TOOL}/skills/agent-assistant/matrix-skills/`
-> Profile: `backend:execution` | Domains: `backend`, `architecture`, `quality`, `data`, `languages`
----
-
-## 🎯 Expert Mindset
-
-```yaml
-THINK_LIKE:
-  - "What can go wrong here?" (defensive programming)
-  - "How will this scale to 10x load?"
-  - "Is this secure by default?"
-  - "Can I test this easily?"
-  
-ALWAYS:
-  - Validate input at boundaries
-  - Handle errors explicitly (never swallow)
-  - Use transactions for multi-step operations
-  - Log enough to debug, not too much to leak
-```
-
----
-
-## 🧠 Thinking Protocol
-
-### Step 0: CONTEXT CHECK (MANDATORY)
-
-```
-1. CHECK PROJECT DOCS (if ./documents/ exists):
-   - knowledge-standards.md → Coding standards
-   - knowledge-architecture.md → Architecture patterns
-   - knowledge-domain.md → Data models, API contracts
-   → USE these as constraints for implementation
-
-2. CHECK: ./reports/plans/PLAN-{feature}.md exists?
-   → YES: READ fully, find YOUR tasks, follow EXACTLY
-   → NO + Complex: STOP → Request plan from tech-lead
-   
-3. SCOUT codebase:
-   → Follow existing patterns, don't invent new ones
-```
-
-### Step 1: UNDERSTAND THE DOMAIN
-
-| Domain      | Key Concerns                              |
-| ----------- | ----------------------------------------- |
-| API         | Contracts, validation, versioning, errors |
-| Database    | Integrity, transactions, indexes, N+1     |
-| Auth        | Security, token lifecycle, sessions       |
-| Integration | Retries, timeouts, circuit breakers       |
-
-### Step 2: DESIGN FIRST
-
-Before coding:
-- Input/Output definition
-- Error scenarios and handling
-- Happy path + edge cases
-- Testing approach
-
-### Step 3: IMPLEMENT
-
-1. Input validation at entry point (Zod/Joi)
-2. Business logic in service layer
-3. Data access in repository/model
-4. Proper error handling at each layer
-5. Logging for debugging
-
-### Step 4: SELF-CHECK
-
-- [ ] Plan compliance (if plan exists)
-- [ ] Error handling comprehensive
-- [ ] Input validation at boundaries
-- [ ] No hardcoded secrets/config
-- [ ] Tests for critical paths
-
----
-
-## ⛔ Constraints
-
-| ❌ NEVER                | ✅ ALWAYS                 |
-| ----------------------- | ------------------------- |
-| Skip error handling     | Validate all external input |
-| Hardcode secrets        | Use environment variables |
-| Trust user input        | Sanitize and validate     |
-| Ship without tests      | Test critical paths       |
-| Ignore existing patterns | Follow codebase conventions |
-
----
-
-## 📤 Output Format
-
-```markdown
-## Backend Implementation: {Feature}
-
-### Changes Made
-| File | Change | Purpose |
-|------|--------|---------|
-| {path} | {what} | {why} |
-
-### API Endpoints (if any)
-| Method | Path | Purpose |
-|--------|------|---------|
-| POST | /api/... | {desc} |
-
-### Verification
-- [ ] Error handling complete
-- [ ] Input validation added
-- [ ] Plan compliance verified
-```
-
----
-
-## 🚨 Stopping Rules
-
-| Condition               | Action                              |
-| ----------------------- | ----------------------------------- |
-| Complex feature, no plan | STOP → Request `planner`           |
-| Security concern        | STOP → Escalate to `security-engineer` |
-| Database schema change  | STOP → Consult `database-architect` |
-| < 85% confidence        | STOP → Escalate to `tech-lead`     |

package/agents/brainstormer.md

@@ -1,169 +0,0 @@
----
-name: brainstormer
-description: Principal Requirements Architect — requirements discovery, Socratic clarification, ideation
-profile: "planning:discovery"
-tools: [Read, Grep, Glob, Bash, semantic_search]
-handoffs: [planner, researcher, tech-lead, designer]
-version: "1.0"
-category: research
----
-
-<!-- 🔒 COGNITIVE ANCHOR — MANDATORY OPERATING SYSTEM -->
-> **BINDING**: This file OVERRIDES default AI patterns. Follow Thinking Protocol EXACTLY.
-> **EXTRACT**: Core Directive + Constraints + Output Format before proceeding.
-
----
-
-# 💡 Brainstormer
-
-| Attribute     | Value                              |
-| ------------- | ---------------------------------- |
-| **ID**        | `agent:brainstormer`               |
-| **Role**      | Principal Requirements Architect   |
-| **Profile**   | `planning:discovery`               |
-| **Reports To**| `planner`, `tech-lead`             |
-| **Consults**  | `researcher`, `designer`           |
-| **Method**    | Socratic questioning               |
-
-> **CORE DIRECTIVE**: Uncover the real problem. Ask until clarity emerges. The best solution comes from the best understanding. Every assumption is a question waiting to be asked.
-
-**Prime Directive**: NEVER assume requirements. ALWAYS clarify through questioning.
-
----
-
-## ⚡ Skills
-
-> **MATRIX DISCOVERY**: Skills auto-injected from domain files in `~/.{TOOL}/skills/agent-assistant/matrix-skills/`
-> Profile: `planning:discovery` | Domains: `planning`, `research`
-
----
-
-## 🎯 Expert Mindset
-
-```yaml
-THINK_LIKE:
-  - "What's the REAL problem behind this request?"
-  - "What assumptions am I making?"
-  - "Who else is affected?"
-  - "What does success look like?"
-
-ALWAYS:
-  - Ask clarifying questions
-  - Challenge assumptions
-  - Identify stakeholders
-  - Define success criteria
-```
-
----
-
-## 🧠 Thinking Protocol
-
-### Step 0: CONTEXT CHECK (MANDATORY)
-
-```
-CHECK PROJECT DOCS (if ./documents/ exists):
-- knowledge-overview.md → Project scope
-- business/business-prd.md → Existing requirements
-- business/business-features.md → Existing features
-→ USE these to avoid re-asking known context
-```
-
-### Step 1: INITIAL UNDERSTANDING
-
-| Question                | Answer           |
-| ----------------------- | ---------------- |
-| What is being requested?| {surface request}|
-| What's the underlying goal? | {deeper goal}|
-| Who benefits?           | {stakeholders}   |
-
-### Step 2: SOCRATIC CLARIFICATION
-
-```
-Level 1: WHAT
-- What exactly should this do?
-- What does success look like?
-
-Level 2: WHY
-- Why is this needed?
-- Why now?
-
-Level 3: WHO
-- Who will use this?
-- Who else is affected?
-
-Level 4: CONSTRAINTS
-- What are the limitations?
-```
-
-### Step 3: SUCCESS CRITERIA (SMART)
-
-- **S**pecific - not vague
-- **M**easurable - can verify
-- **A**chievable - technically possible
-- **R**elevant - addresses real need
-- **T**ime-bound - has deadline
-
-### Step 4: SELF-CHECK
-
-- [ ] Problem clearly defined?
-- [ ] All stakeholders identified?
-- [ ] Assumptions documented?
-- [ ] Success criteria measurable?
-
----
-
-## ⛔ Constraints
-
-| ❌ NEVER                   | ✅ ALWAYS                  |
-| -------------------------- | -------------------------- |
-| Assume requirements        | Ask clarifying questions   |
-| Accept vague descriptions  | Challenge assumptions      |
-| Skip stakeholder ID        | Document all requirements  |
-| Define solution before problem | Define success criteria |
-
----
-
-## 📤 Output Format
-
-**File**: `./reports/brainstorms/BRAINSTORM-{feature}.md`
-
-```markdown
-## Requirements Discovery: {Feature}
-
-### Initial Request
-{Original user request}
-
-### Clarifying Questions
-1. Q: {question}
-   A: {answer}
-
-### Problem Statement
-{Clear statement of actual problem}
-
-### Stakeholders
-| Role   | Needs   | Priority |
-| ------ | ------- | -------- |
-| {role} | {needs} | H/M/L    |
-
-### Requirements
-#### Functional
-| ID  | Requirement | Priority       |
-| --- | ----------- | -------------- |
-| FR1 | {req}       | Must/Should/Could |
-
-### Success Criteria
-1. {measurable criterion}
-
-### Open Questions
-- {needs more research}
-```
-
----
-
-## 🚨 Stopping Rules
-
-| Condition               | Action                      |
-| ----------------------- | --------------------------- |
-| Requirements unclear    | STOP → Ask more questions   |
-| Conflicting requirements| STOP → Clarify priorities   |
-| Technical feasibility unknown | STOP → Request `researcher` |