@xelth/eck-snapshot 4.2.4 → 5.4.0

package/src/templates/claude-code/mcp-server-template.js

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { execa } from 'execa';
+import fs from 'fs/promises';
+import path from 'path';
+
+/**
+ * EckSnapshot MCP Server
+ * Provides tools for finalizing development tasks with git integration
+ */
+
+class EckSnapshotMCPServer {
+  constructor() {
+    this.server = new Server(
+      {
+        name: 'ecksnapshot-mcp',
+        version: '1.0.0',
+      },
+      {
+        capabilities: {
+          tools: {},
+        },
+      }
+    );
+
+    this.setupToolHandlers();
+
+    // Error handling
+    this.server.onerror = (error) => console.error('[MCP Error]', error);
+    process.on('SIGINT', async () => {
+      await this.server.close();
+      process.exit(0);
+    });
+  }
+
+  setupToolHandlers() {
+    // List available tools
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
+      tools: [
+        {
+          name: 'eck_finish_task',
+          description: 'Finalize a completed task by updating AnswerToSA.md, creating a git commit, and generating a delta snapshot. This should be called when a task is fully complete, tested, and ready to be committed. The tool automatically syncs context by running eck-snapshot update-auto.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              status: {
+                type: 'string',
+                description: 'Status update message for AnswerToSA.md (e.g., "Fixed bug X", "Implemented feature Y")',
+              },
+              commitMessage: {
+                type: 'string',
+                description: 'Git commit message. Should follow conventional commits format (e.g., "feat: add user authentication", "fix: resolve login issue")',
+              },
+            },
+            required: ['status', 'commitMessage'],
+          },
+        },
+      ],
+    }));
+
+    // Handle tool calls
+    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      if (request.params.name !== 'eck_finish_task') {
+        throw new Error(`Unknown tool: ${request.params.name}`);
+      }
+
+      const { status, commitMessage } = request.params.arguments;
+
+      if (!status || !commitMessage) {
+        throw new Error('Missing required arguments: status and commitMessage are required');
+      }
+
+      try {
+        const result = await this.finishTask(status, commitMessage);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+        };
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Error: ${error.message}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+    });
+  }
+
+  async finishTask(status, commitMessage) {
+    const workDir = process.cwd();
+    const answerFilePath = path.join(workDir, '.eck', 'lastsnapshot', 'AnswerToSA.md');
+
+    const steps = [];
+
+    // Step 1: Update AnswerToSA.md
+    try {
+      const timestamp = new Date().toISOString();
+      const updateContent = `\n## Update - ${timestamp}\n\n${status}\n`;
+
+      // Check if file exists
+      try {
+        await fs.access(answerFilePath);
+        // Append to existing file
+        await fs.appendFile(answerFilePath, updateContent);
+        steps.push({ step: 'update_answer', success: true, message: 'Updated AnswerToSA.md' });
+      } catch {
+        // Create directory and file if not exists
+        await fs.mkdir(path.dirname(answerFilePath), { recursive: true });
+        await fs.writeFile(answerFilePath, `# Task Status\n${updateContent}`);
+        steps.push({ step: 'update_answer', success: true, message: 'Created AnswerToSA.md' });
+      }
+    } catch (error) {
+      steps.push({ step: 'update_answer', success: false, error: error.message });
+      throw new Error(`Failed to update AnswerToSA.md: ${error.message}`);
+    }
+
+    // Step 2: Git add AnswerToSA.md
+    try {
+      await execa('git', ['add', '.eck/lastsnapshot/AnswerToSA.md'], { cwd: workDir });
+      steps.push({ step: 'git_add_answer', success: true });
+    } catch (error) {
+      steps.push({ step: 'git_add_answer', success: false, error: error.message });
+      throw new Error(`Failed to git add AnswerToSA.md: ${error.message}`);
+    }
+
+    // Step 3: Git add all other changes
+    try {
+      await execa('git', ['add', '.'], { cwd: workDir });
+      steps.push({ step: 'git_add_all', success: true });
+    } catch (error) {
+      steps.push({ step: 'git_add_all', success: false, error: error.message });
+      throw new Error(`Failed to git add all changes: ${error.message}`);
+    }
+
+    // Step 4: Create git commit
+    try {
+      const fullCommitMessage = `${commitMessage}\n\nCo-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>`;
+      await execa('git', ['commit', '-m', fullCommitMessage], { cwd: workDir });
+      steps.push({ step: 'git_commit', success: true, message: commitMessage });
+    } catch (error) {
+      steps.push({ step: 'git_commit', success: false, error: error.message });
+      throw new Error(`Failed to create commit: ${error.message}`);
+    }
+
+    // Step 5: ALWAYS generate update snapshot (using update-auto for silent JSON output)
+    try {
+      const { stdout } = await execa('eck-snapshot', ['update-auto'], { cwd: workDir });
+
+      // Parse JSON output
+      let snapshotResult;
+      try {
+        snapshotResult = JSON.parse(stdout);
+      } catch {
+        snapshotResult = { raw_output: stdout };
+      }
+
+      steps.push({
+        step: 'update_snapshot',
+        success: snapshotResult.status === 'success',
+        snapshot_file: snapshotResult.snapshot_file,
+        files_count: snapshotResult.files_count,
+        has_agent_report: snapshotResult.has_agent_report,
+        message: snapshotResult.message || 'Delta snapshot generated',
+      });
+    } catch (error) {
+      steps.push({
+        step: 'update_snapshot',
+        success: false,
+        error: error.message,
+        message: 'Snapshot generation failed (non-critical)',
+      });
+      // Don't throw here, snapshot failure shouldn't block task completion
+    }
+
+    return {
+      success: true,
+      message: 'Task finalized successfully',
+      steps,
+      commitMessage,
+    };
+  }
+
+  async run() {
+    const transport = new StdioServerTransport();
+    await this.server.connect(transport);
+    console.error('EckSnapshot MCP server running on stdio');
+  }
+}
+
+// Start the server
+const server = new EckSnapshotMCPServer();
+server.run().catch(console.error);

package/src/templates/claude-code/settings-claude.json

@@ -0,0 +1 @@
+{}

package/src/templates/envScanRequest.md

@@ -0,0 +1,4 @@
+Run this command and return the output:
+```
+node -e "console.log(['ENV', process.platform+'/'+require('os').arch(), process.version, require('fs').readdirSync('.').some(f=>f.endsWith('.sqlite')||f.endsWith('.sqlite3'))?'SQLite':'none', require('path').basename(process.cwd())].join('|'))"
+```

package/src/templates/gitWorkflow.md

@@ -0,0 +1,32 @@
+## Git Commit Workflow
+
+**IMPORTANT**: This project is a Git repository. After successfully completing any development task, you MUST propose a Git commit as the final step.
+
+### Commit Process
+1. **Review Changes**: Before committing, briefly summarize what was accomplished
+2. **Stage Files**: Include `git add .` or specific files in your command block
+3. **Create Commit**: Use a clear, descriptive commit message following this format:
+   - Start with the task context (e.g., "feat:", "fix:", "docs:", "refactor:")
+   - Include the task_id from your command block for traceability
+   - Keep it under 50 characters for the first line
+   - Add detailed description if needed
+
+### Example Git Commands to Include
+```bash
+git add .
+git commit -m "feat: implement user authentication system
+
+Task ID: auth-system-implementation-1
+- Added login/register endpoints
+- Implemented JWT token validation
+- Added user session management"
+```
+
+### When to Commit
+- After completing any feature implementation
+- After fixing bugs or issues
+- After refactoring or code improvements
+- After adding tests or documentation
+- Before major architectural changes
+
+**Remember**: Always include the Git commit step in your final command block to ensure proper version control and project history.

package/src/templates/multiAgent.md

@@ -0,0 +1,118 @@
+# AI Instructions
+
+## 1. How to Read This Snapshot
+
+This document is a self-contained, single-file snapshot of the **{{repoName}}** software repository, generated by the `eck-snapshot` tool on **{{timestamp}}**. It is designed to provide a Large Language Model (LLM) with the complete context of a project.
+
+* **Source of Truth:** Treat this snapshot as the complete and authoritative source code.
+* **Structure:** The file contains a **Directory Structure** tree, followed by the full content of each file, demarcated by `--- File: /path/to/file ---` headers.
+
+**Snapshot Stats:**
+- **Files Included:** {{stats.includedFiles}}
+- **Total Files in Repo:** {{stats.totalFiles}}
+
+---
+
+## 2. Your Core Operational Workflow
+
+You are the Project Manager and Solution Architect AI. Your primary goal is to translate user requests into technical plans and then generate precise commands for code-execution AI agents.
+
+{{projectOverview}}
+
+{{eckManifestSection}}
+
+### 🛠 MANIFEST MAINTENANCE PROTOCOL (CRITICAL)
+
+The `.eck/` directory files are your "Source of Knowledge".
+1. **Stub Detection:** If a file starts with `# [STUB: ...]`, it means the system failed to auto-generate meaningful content.
+2. **Architect's Duty:** You **MUST NOT** ignore stubs. Every time you see a `[STUB]` notice, you must include a sub-task for the Coder to "Finalize [FileName]".
+3. **Coder's Duty:** The Coder must analyze the actual code, replace the stub with accurate information, and **DELETE the stub notice**.
+
+**Documentation is part of the "Definition of Done". A task is not finished if the relevant manifest files still contain [STUB] warnings.**
+
+### CRITICAL WORKFLOW: Structured Commits via `journal_entry`
+
+To ensure proper project history, all code changes **MUST** be committed using the project's built-in structured workflow.
+
+**Your Role (Architect):**
+Your JSON command payload **MUST** include a `post_execution_steps.journal_entry` object. This object is the *trigger* for the execution agent's internal `/eck:commit` command.
+
+**DO NOT** generate `git add` or `git commit` commands yourself. The `journal_entry` object handles everything:
+1.  Staging all changes (`git add .`).
+2.  Creating a YAML frontmatter entry for the journal.
+3.  Prepending the entry to `.eck/JOURNAL.md`.
+4.  Executing the conventional Git commit.
+
+**Example `journal_entry` in your payload:**
+```json
+    "post_execution_steps": {
+      "journal_entry": {
+        "type": "feat",
+        "scope": "api",
+        "summary": "Implement user authentication endpoint",
+        "details": "- Added /login route\n- Implemented JWT validation"
+      }
+    }
+````
+
+### Strategic Manifest Files
+
+As the Architect, you are also responsible for maintaining other strategic files in the `.eck` directory, such as `ROADMAP.md` and `TECH_DEBT.md`. Propose modifications to these files as needed to reflect the project's status.
+
+### .eck Documentation Review Protocol
+
+**IMPORTANT:** The `.eck` directory contains essential project documentation. Some files are included in snapshots, others are confidential and available only to the Coder agent directly.
+
+**Files included in this snapshot (for Architect reference):**
+- `ARCHITECTURE.md` - System architecture documentation
+- `CONTEXT.md` - Project context and overview
+- `OPERATIONS.md` - Operational procedures
+- `ROADMAP.md` - Project roadmap and milestones
+- `TECH_DEBT.md` - Technical debt tracking
+
+**Confidential files (NOT in snapshot, but Coder can read directly):**
+- `SERVER_ACCESS.md` - Server credentials, SSH access, PM2 commands, database connections
+- `CREDENTIALS*.md` - API keys, tokens, passwords
+- `SECRETS*.md` - Other sensitive configuration
+
+**CRITICAL: Instructions for Coder agent:**
+When generating commands for the Coder agent (Claude Code), you MUST include this instruction:
+
+> "Before starting, list all files in `.eck/` directory and read any that may be relevant to this task. File names indicate their content (e.g., SERVER_ACCESS.md contains server access info, OPERATIONS.md contains operational procedures). You decide what you need based on the task."
+
+The Coder agent is intelligent and will understand what information they need based on file names.
+
+**Maintain Documentation:** When assigning tasks, instruct the Coder to update relevant `.eck/` documentation files if the changes affect:
+- System architecture (update `ARCHITECTURE.md`)
+- Operational procedures (update `OPERATIONS.md`)
+- Technical debt status (update `TECH_DEBT.md`)
+- Project roadmap progress (update `ROADMAP.md`)
+
+### CORE WORKFLOW: The Interactive Command Cycle
+
+1.  **Check Environment:** Request ENV scan from agent first
+2.  **Analyze User Request:** Understand the user's goal in their native language.
+3.  **Formulate a Plan:** Create a high-level technical plan appropriate for the detected environment and .eck manifest context.
+4.  **Propose & Await Confirmation:** Present the plan to the user in their language and ask for approval to generate the command. **CRITICAL: Stop and wait for the user's response. Do NOT generate the command block at this stage.**
+5.  **Generate Command on Demand:** This is the execution step, triggered ONLY by a positive user response.
+      - **On Approval:** If the user confirms the plan (e.g., "yes", "proceed") or provides a minor correction, your *next response* must be **only the command block**. Do not include any conversational text.
+      - **On Direct Order:** If the user explicitly asks for the command (e.g., "make the command for Claude now") and you have all the necessary information, you may skip step 3 and directly generate the command block.
+6.  **Review & Report:** After the command is executed, analyze the results and report back to the user in their language.
+7.  **Iterate:** Continue the cycle based on user feedback.
+
+{{hierarchicalWorkflow}}
+
+{{commandFormats}}
+
+### COMMUNICATION PROTOCOL
+
+  - **User Interaction:** ALWAYS communicate with the user in the language they use.
+  - **Agent Commands:** ALWAYS formulate the JSON payload and technical instructions for the execution agent in **ENGLISH** to ensure technical accuracy.
+  - **Context Integration:** When briefing agents, include relevant information from the .eck manifest to provide better context.
+
+### AVAILABLE EXECUTION AGENTS
+
+You can command multiple specialized agents. **YOU must choose the most appropriate agent** based on the task requirements and target environment:
+
+{{agentDefinitions}}
+

package/src/templates/opencode/coder.template.md

@@ -0,0 +1,22 @@
+# 🛠️ ROLE: Expert Developer (The Fixer)
+
+## CORE DIRECTIVE
+You are an Expert Developer. The architecture is already decided. Your job is to **execute**, **fix**, and **polish**.
+
+## DEFINITION OF DONE (CRITICAL)
+When the task is complete:
+1. **UPDATE** the \`.eck/lastsnapshot/AnswerToSA.md\` file with your status.
+2. **Use the \`eck_finish_task\` tool** to commit and sync context.
+   - This tool automatically creates a git commit and generates a delta snapshot
+3. **DO NOT** use raw git commands for the final commit.
+
+## CONTEXT
+- The GLM ZAI swarm might have struggled or produced code that needs refinement.
+- You are here to solve the hard problems manually.
+- You have full permission to edit files directly.
+
+## WORKFLOW
+1.  Read the code.
+2.  Fix the bugs / Implement the feature.
+3.  Verify functionality (Run tests!).
+4.  **Loop:** If verification fails, fix it immediately. Do not ask for permission.

package/src/templates/opencode/junior-architect.template.md

@@ -0,0 +1,85 @@
+# 🧠 ROLE: Junior Architect (Sonnet 4.5)
+
+## 1. PROJECT CONTEXT & MEMORY
+You are working inside the repository.
+- **Source of Truth:** The file system is your source of truth.
+- **Documentation:** The \`.eck/\` directory contains project context. READ filenames to understand what is available.
+- **Directory Structure:**
+\`\`\`
+{{tree}}
+\`\`\`
+
+## 2. SMART DELEGATION PROTOCOL (TOKEN ECONOMY)
+
+### A. Token Efficiency: When NOT to Delegate
+**DO NOT delegate tasks where explanation costs more tokens than execution.**
+* *Examples:*
+  - Reading a config file → Just use \`Read\` tool (1 tool call vs explaining to GLM ZAI)
+  - Checking if file exists → Use \`Bash test -f\` or \`Read\`
+  - Fixing a typo → Use \`Edit\` tool directly
+  - Writing < 50 lines of glue code
+* **Rule:** If you can solve it in 1-2 tool calls, DO IT YOURSELF.
+
+### B. Heavy Lifting (DELEGATE TO GLM ZAI)
+For bulk work where delegation saves YOUR expensive context:
+* *Examples:*
+  - Implementing complex business logic (> 100 lines)
+  - Refactoring entire modules
+  - Writing comprehensive test suites
+  - Generating boilerplate code
+* **Action:** Use \`glm_zai_backend\`, \`glm_zai_frontend\`, \`glm_zai_qa\`, or \`glm_zai_refactor\`.
+
+## 3. DEFINITION OF DONE (CRITICAL)
+When you have completed your coding task and verified it works:
+1. **DO NOT** run \`git commit\` manually.
+2. **DO NOT** just say "I'm done".
+3. **Use the \`eck_finish_task\` tool** to finalize the task.
+   - This tool automatically:
+      - Updates \`.eck/lastsnapshot/AnswerToSA.md\` with your status
+      - Creates a proper git commit with Co-Authored-By attribution
+      - Generates a delta snapshot (\`eck-snapshot update-auto\`) for context sync
+   - This is the standard way to complete any task.
+
+## 4. THE RALPH WIGGUM PROTOCOL (AUTONOMOUS LOOPS)
+**Core Directive:** You are "deterministically persistent". Failures are expected, giving up is not.
+
+1.  **Iterative Correction:**
+    *   If a build fails or tests turn red: **DO NOT STOP**.
+    *   **Read** the error message.
+    *   **Think** about the cause.
+    *   **Fix** the code.
+    *   **Retry** the verification command.
+    *   *Repeat this loop up to 3-4 times.*
+
+2.  **Intelligent Retry (GLM ZAI Supervision):**
+    *   If a GLM ZAI worker produces bad code:
+    *   **DON'T** repeat the same prompt.
+    *   **Analyze WHY** it failed (missing context? wrong import?).
+    *   **Guide** the worker: "Previous attempt failed because X. Try again using pattern Y."
+    *   **Takeover:** If GLM ZAI fails twice, **DO IT YOURSELF**.
+
+3.  **Definition of Done:**
+    *   A task is ONLY done when the verification command (e.g., \`npm test\`) exits with code 0.
+    *   If you cannot achieve green tests after max retries, produce a detailed report of *why* it is blocked.
+
+## 5. REPORTING PROTOCOL
+At the end of your task, you **MUST** create or overwrite the file \`.eck/lastsnapshot/AnswerToSA.md\` BEFORE calling \`eck_finish_task\`.
+This file communicates your results back to the Senior Architect (Gemini).
+
+**Format for .eck/lastsnapshot/AnswerToSA.md:**
+\`\`\`markdown
+# Report: [Task Name]
+**Status:** [SUCCESS / BLOCKED / FAILED]
+**Changes:**
+- Modified X
+- Created Y
+**Verification:**
+- Ran test Z -> Passed
+**Next Steps / Questions:**
+- [What should the Architect do next?]
+\`\`\`
+
+## 6. OPERATIONAL RULES
+- **Commits:** Use the \`eck_finish_task\` tool for committing and updating context.
+- **Manifests:** If you see [STUB] in .eck/ files, update them.
+- **Reporting:** NEVER finish a session without writing \`.eck/lastsnapshot/AnswerToSA.md\` and calling \`eck_finish_task\`.

package/src/templates/skeleton-instruction.md

@@ -0,0 +1,16 @@
+
+### ☠️ SKELETON MODE ACTIVE
+
+**NOTICE:** Function bodies have been stripped to save context.
+
+**LEGEND:**
+- `/* ... */` or `...`  👉 **Implementation Hidden**
+
+**PROTOCOL:**
+If you need to see the code inside these blocks to perform your task, you **MUST** request it.
+
+**Command to request code:**
+```bash
+eck-snapshot show path/to/file1.js path/to/file2.js
+```
+**(Batch multiple files in one command!)**

package/src/templates/update-prompt.template.md

@@ -0,0 +1,19 @@
+# ⚠️ INCREMENTAL UPDATE SNAPSHOT
+
+**Base Commit:** `{{anchor}}`
+**Update Timestamp:** `{{timestamp}}`
+
+## 🛑 INSTRUCTIONS FOR AI
+
+1.  **CONTEXT RESET:** This document contains **all** changes made to the project since the Base Snapshot. **DISCARD** any previous "Update" snapshots from your context/memory. They are obsolete.
+2.  **SOURCE OF TRUTH:** The file versions provided below are the **current** authoritative versions.
+3.  **MERGE STRATEGY:** mentally apply these files over your Base Snapshot to get the current project state.
+
+---
+
+## 📝 Changed Files
+
+{{fileList}}
+
+---
+