opencode-code-archaeology 2.0.2 → 2.2.0

package/hooks/opencode/revert-phase.sh

@@ -1,4 +1,4 @@
-# Revert changes in the current working tree back to the last commit.
+# Move current working tree changes into a recoverable stash.
 # Usage: revert-phase.sh [phase-name]
 
 set -euo pipefail
@@ -7,11 +7,6 @@ PHASE="${1:-unknown}"
 
 echo "[$PHASE] ⚠️ Reverting changes due to failure..."
 
-# Stash any changes and drop them
-git stash push -m "code-archaeology-revert-$PHASE" --include-untracked 2>/dev/null || true
-git stash drop 2>/dev/null || true
+git stash push -m "code-archaeology-revert-$PHASE" --include-untracked >/dev/null 2>&1 || true
 
-# Reset to HEAD
-git reset --hard HEAD
-
-echo "[$PHASE] ✅ Reverted to last commit"
+echo "[$PHASE] ✅ Changes preserved in git stash"

package/hooks/opencode/update-expedition.ps1

@@ -0,0 +1,51 @@
+# Update expedition status in session.json
+# Usage: update-expedition.ps1 <phase> <status> [findings_count] [error_message]
+
+$ErrorActionPreference = 'Stop'
+
+$PHASE = $args[0]
+$STATUS = $args[1]
+$FINDINGS = if ($args[2]) { [int]$args[2] } else { 0 }
+$ERROR_MSG = if ($args[3]) { $args[3] } else { "" }
+
+$ARCHAEOLOGY_DIR = ".archaeology"
+$SESSION_FILE = "$ARCHAEOLOGY_DIR/session.json"
+
+if (!(Test-Path "$SESSION_FILE")) {
+    Write-Error "Error: session.json not found. Run init.ps1 first."
+    exit 1
+}
+
+$NOW = (Get-Date).ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ssZ")
+
+$session = Get-Content "$SESSION_FILE" -Raw | ConvertFrom-Json
+
+foreach ($expedition in $session.expeditions) {
+    if ($expedition.phase -eq $PHASE) {
+        $expedition.status = $STATUS
+        $expedition.findings_count = $FINDINGS
+        if ($STATUS -eq "completed" -or $STATUS -eq "done") {
+            $expedition | Add-Member -MemberType NoteProperty -Name "completed_at" -Value $NOW -Force
+        }
+        if ($ERROR_MSG) {
+            $expedition | Add-Member -MemberType NoteProperty -Name "error" -Value $ERROR_MSG -Force
+        } else {
+            if ($expedition.PSObject.Properties["error"]) {
+                $expedition.PSObject.Properties.Remove("error")
+            }
+        }
+    }
+}
+
+$session.updated_at = $NOW
+
+# Update total findings
+$total = 0
+foreach ($expedition in $session.expeditions) {
+    $total += $expedition.findings_count
+}
+$session.total_findings = $total
+
+$session | ConvertTo-Json -Depth 10 | Set-Content "$SESSION_FILE" -Encoding UTF8
+
+Write-Host "[$PHASE] Updated status: $STATUS (findings: $FINDINGS)"

package/hooks/opencode/verify-package.sh

@@ -19,6 +19,7 @@ const requiredFiles = [
   'hooks/opencode/verify-package.sh',
   'prompts/discovery.md',
   'schema/expedition-report.json',
+  'docs/index.html',
   'docs/README.md',
   'wiki/Home.md',
   'assets/code-archaeology-banner.svg',

package/hooks/opencode/verify-phase.ps1

@@ -0,0 +1,35 @@
+# Verify that tests pass and typecheck succeeds.
+# Usage: verify-phase.ps1 [phase-name]
+
+$ErrorActionPreference = 'Stop'
+
+$PHASE = if ($args[0]) { $args[0] } else { "unknown" }
+$ARCHAEOLOGY_DIR = ".archaeology"
+$SESSION_FILE = "$ARCHAEOLOGY_DIR/session.json"
+$SCRIPT_DIR = Split-Path -Parent $MyInvocation.MyCommand.Path
+. (Join-Path $SCRIPT_DIR "../shared/command-utils.ps1")
+
+# Verification commands must not be read from repository-local state.
+# A malicious repository can pre-seed .archaeology/session.json; executing commands
+# from that file would cross the repository-to-workstation trust boundary.
+# Operators who intentionally need custom commands can approve them explicitly via
+# environment variables for the current process.
+$TEST_CMD = if ($env:CODE_ARCHAEOLOGY_TEST_COMMAND) { $env:CODE_ARCHAEOLOGY_TEST_COMMAND } else { "npm test" }
+$TYPECHECK_CMD = if ($env:CODE_ARCHAEOLOGY_TYPECHECK_COMMAND) { $env:CODE_ARCHAEOLOGY_TYPECHECK_COMMAND } else { "npx tsc --noEmit" }
+
+Write-Host "[$PHASE] Running test command: $TEST_CMD"
+try {
+    Invoke-CheckedCommand -CommandLine $TEST_CMD | Out-Default
+} catch {
+    Write-Error "[$PHASE] Tests FAILED"
+    exit 1
+}
+
+Write-Host "[$PHASE] Running typecheck: $TYPECHECK_CMD"
+try {
+    Invoke-CheckedCommand -CommandLine $TYPECHECK_CMD 2>$null | Out-Default
+} catch {
+    Write-Warning "[$PHASE] Typecheck reported errors (non-blocking for some languages)"
+}
+
+Write-Host "[$PHASE] Verification passed"

package/hooks/opencode/verify-phase.sh

@@ -9,13 +9,13 @@ SESSION_FILE="$ARCHAEOLOGY_DIR/session.json"
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 
-# Source config from session file if jq is available
-TEST_CMD="npm test"
-TYPECHECK_CMD="npx tsc --noEmit"
-if command -v jq >/dev/null 2>&1 && [[ -f "$SESSION_FILE" ]]; then
-  TEST_CMD=$(jq -r '.config.test_command // "npm test"' "$SESSION_FILE")
-  TYPECHECK_CMD=$(jq -r '.config.typecheck_command // "npx tsc --noEmit"' "$SESSION_FILE")
-fi
+# Verification commands must not be read from repository-local state.
+# A malicious repository can pre-seed .archaeology/session.json; executing commands
+# from that file would cross the repository-to-workstation trust boundary.
+# Operators who intentionally need custom commands can approve them explicitly via
+# environment variables for the current process.
+TEST_CMD="${CODE_ARCHAEOLOGY_TEST_COMMAND:-npm test}"
+TYPECHECK_CMD="${CODE_ARCHAEOLOGY_TYPECHECK_COMMAND:-npx tsc --noEmit}"
 
 echo "[$PHASE] Running test command: $TEST_CMD"
 if ! bash -c "$TEST_CMD"; then

package/hooks/shared/command-utils.ps1

@@ -0,0 +1,100 @@
+# Shared PowerShell command parsing and execution helpers for verification hooks.
+
+function Convert-CommandElementToArgument {
+    param(
+        [Parameter(Mandatory=$true)]
+        [System.Management.Automation.Language.CommandElementAst]$Element,
+
+        [Parameter(Mandatory=$true)]
+        [string]$CommandLine
+    )
+
+    if ($Element -is [System.Management.Automation.Language.StringConstantExpressionAst]) {
+        return $Element.Value
+    }
+
+    if ($Element -is [System.Management.Automation.Language.ExpandableStringExpressionAst]) {
+        return $Element.Value
+    }
+
+    if ($Element -is [System.Management.Automation.Language.CommandParameterAst]) {
+        if ($null -ne $Element.Argument) {
+            $argumentValue = Convert-CommandElementToArgument -Element $Element.Argument -CommandLine $CommandLine
+            return "-$($Element.ParameterName):$argumentValue"
+        }
+
+        return "-$($Element.ParameterName)"
+    }
+
+    throw "Unsupported command syntax in command: $CommandLine"
+}
+
+function Split-CommandLine {
+    param([Parameter(Mandatory=$true)][string]$CommandLine)
+
+    [System.Management.Automation.Language.Token[]]$tokens = @()
+    [System.Management.Automation.Language.ParseError[]]$parseErrors = @()
+    $ast = [System.Management.Automation.Language.Parser]::ParseInput($CommandLine, [ref]$tokens, [ref]$parseErrors)
+
+    if ($parseErrors.Count -gt 0) {
+        $message = ($parseErrors | ForEach-Object { $_.Message }) -join "; "
+        throw "Invalid command syntax: $CommandLine. $message"
+    }
+
+    $statements = @($ast.EndBlock.Statements)
+    if ($statements.Count -ne 1 -or $statements[0] -isnot [System.Management.Automation.Language.PipelineAst]) {
+        throw "Only a single simple command is supported: $CommandLine"
+    }
+
+    $pipeline = [System.Management.Automation.Language.PipelineAst]$statements[0]
+    if ($pipeline.PipelineElements.Count -ne 1 -or $pipeline.PipelineElements[0] -isnot [System.Management.Automation.Language.CommandAst]) {
+        throw "Only a single simple command is supported: $CommandLine"
+    }
+
+    $commandAst = [System.Management.Automation.Language.CommandAst]$pipeline.PipelineElements[0]
+    if ($commandAst.Redirections.Count -gt 0) {
+        throw "Command must not contain redirections: $CommandLine"
+    }
+
+    $parts = [System.Collections.Generic.List[string]]::new()
+    foreach ($element in $commandAst.CommandElements) {
+        $parts.Add((Convert-CommandElementToArgument -Element $element -CommandLine $CommandLine))
+    }
+
+    return $parts.ToArray()
+}
+
+function Invoke-CheckedCommand {
+    param([Parameter(Mandatory=$true)][string]$CommandLine)
+
+    [string[]]$parts = @(Split-CommandLine -CommandLine $CommandLine)
+    if ($parts.Count -eq 0) {
+        throw "Empty command"
+    }
+
+    $command = $parts[0]
+    $arguments = @()
+    if ($parts.Count -gt 1) {
+        $arguments = $parts[1..($parts.Count - 1)]
+    }
+
+    $resolvedCommand = Get-Command -Name $command -ErrorAction Stop | Select-Object -First 1
+    $isExternalApplication = $resolvedCommand.CommandType -eq [System.Management.Automation.CommandTypes]::Application
+    if ($isExternalApplication) {
+        $global:LASTEXITCODE = 0
+    }
+
+    & $command @arguments
+
+    if ($isExternalApplication) {
+        $exitCode = $LASTEXITCODE
+        if ($exitCode -ne 0) {
+            throw "Command failed with exit code $exitCode: $CommandLine"
+        }
+        return
+    }
+
+    if (-not $?) {
+        throw "Command failed: $CommandLine"
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-code-archaeology",
-  "version": "2.0.2",
+  "version": "2.2.0",
   "description": "Excavate, catalog, and restore a codebase by removing accumulated sediment—dead code, legacy fallbacks, circular dependencies, weak types, and defensive programming slop.",
   "type": "module",
   "main": "./dist/index.js",
@@ -16,6 +16,10 @@
     "./plugin": {
       "types": "./dist/plugin.d.ts",
       "default": "./dist/plugin.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "default": "./dist/types.js"
     }
   },
   "files": [
@@ -23,10 +27,10 @@
     "hooks",
     "commands",
     "skills",
-    "plugins",
     "prompts",
     "schema",
     "docs/README.md",
+    "docs/index.html",
     "docs/INSTALL.md",
     "docs/ARCHITECTURE.md",
     "docs/RELEASE.md",
@@ -73,9 +77,19 @@
   },
   "license": "MIT",
   "devDependencies": {
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^12.0.6",
+    "@semantic-release/npm": "^13.1.5",
+    "@semantic-release/release-notes-generator": "^14.1.0",
     "@types/node": "^25.6.0",
+    "semantic-release": "^25.0.3",
     "typescript": "^6.0.3"
   },
+  "overrides": {
+    "npm": "^11.14.0"
+  },
   "engines": {
     "node": ">=18"
   }

package/skills/code-archaeology/SKILL.md

@@ -76,8 +76,8 @@ With `strict_mode: true`, restore also applies MEDIUM confidence findings.
 | `language` | `typescript` | Primary language |
 | `mode` | `survey` | `survey`, `excavate`, or `restore` |
 | `strict_mode` | `false` | Auto-restore medium-confidence findings |
-| `test_command` | `npm test` | Test runner command |
-| `typecheck_command` | `npx tsc --noEmit` | Type check command |
+| `test_command` | `npm test` | Recorded session default only; verification uses `CODE_ARCHAEOLOGY_TEST_COMMAND` for operator-approved overrides |
+| `typecheck_command` | `npx tsc --noEmit` | Recorded session default only; verification uses `CODE_ARCHAEOLOGY_TYPECHECK_COMMAND` for operator-approved overrides |
 | `branch_name` | `refactor/archaeology` | Git branch to create |
 
 ## Language-Specific Tooling

package/skills/hermes/INTEGRATION.md

@@ -0,0 +1,120 @@
+# Code Archaeology Hermes Integration
+
+## Overview
+
+Code Archaeology can run on Hermes Agent using cron-based phase execution. Each cron run executes exactly ONE expedition phase with test gates between phases.
+
+## Architecture
+
+```
+Hermes Cron (every 15m)
+  → Read .archaeology/session.json
+  → Detect current phase (1 of 10)
+  → Execute ONE phase:
+      survey → excavate → restore (per phase)
+  → Run test/typecheck verification
+  → Keep or revert changes
+  → Advance to next phase
+  → STOP (next cron continues)
+```
+
+## Key Differences from OpenCode
+
+| Feature | OpenCode | Hermes |
+|---------|----------|--------|
+| Entry | `/code-archaeology` slash command | `cronjob` |
+| Phases | All in one session | One per cron run |
+| Verification | Between expeditions | Between every phase |
+| Revert | Manual or automatic | Automatic on failure |
+| State | `.archaeology/session.json` | Same file |
+| Background | Plugin stays active | Cron resumes automatically |
+
+## Setup
+
+```bash
+# 1. Install Code Archaeology CLI
+npm install -g opencode-code-archaeology
+
+# 2. Setup Hermes runtime
+cd ~/projects/Code-Archaeology
+bash hooks/hermes/setup.sh
+
+# 3. Create Hermes cronjob
+hermes cronjob create \
+  --name "code-archaeology-expedition" \
+  --schedule "every 15m" \
+  --workdir ~/projects/Code-Archaeology \
+  --prompt "Run one Code Archaeology expedition phase. Read .archaeology/session.json, execute current phase with verification, advance to next phase."
+```
+
+## Hermes Prompt Template
+
+See `skills/hermes/code-archaeology-prompt.md` for the full cron prompt.
+
+## Commands Mapping
+
+| OpenCode | Hermes |
+|----------|--------|
+| `/code-archaeology` | `cronjob` runs expedition loop |
+| `/code-archaeology-survey` | `mode = "survey"` in session.json |
+| `/code-archaeology-excavate` | `mode = "excavate"` in session.json |
+| `/code-archaeology-restore` | `mode = "restore"` in session.json |
+
+## Session File Format
+
+Hermes uses the same `.archaeology/session.json` format as OpenCode:
+
+```json
+{
+  "runtime": "hermes",
+  "status": "running",
+  "current_phase": "dead-code",
+  "completed_phases": ["site-survey"],
+  "mode": "survey",
+  "repo_path": ".",
+  "language": "typescript",
+  "test_command": "npm test",
+  "typecheck_command": "npx tsc --noEmit",
+  "branch_name": "refactor/archaeology",
+  "strict_mode": false,
+  "started_at": "2026-05-03T14:00:00Z"
+}
+```
+
+## 10-Phase Expedition Order
+
+| # | Phase | Hermes Action |
+|---|-------|---------------|
+| 1 | Site Survey & Baseline | Generate inventory report |
+| 2 | Dead Code Excavation | Catalog unused code |
+| 3 | Legacy Stratum Removal | Identify deprecated shims |
+| 4 | Circular Dependency Cartography | Map dependency cycles |
+| 5 | Type Catalog Consolidation | Find duplicate types |
+| 6 | Type Restoration & Hardening | Flag weak types |
+| 7 | DRY Stratification | Find semantic duplication |
+| 8 | Error Handling Stratigraphy | Review error patterns |
+| 9 | Artifact Cleaning & Documentation | Clean stale artifacts |
+| 10 | Site Preservation & Final Catalog | Generate FINAL_CATALOG.md |
+
+## Safety Model
+
+Same as OpenCode:
+- `survey` is default — reports only, zero edits
+- `restore` modifies code only after review
+- Tests and type checks gate each phase
+- Failed restores are automatically reverted
+- Never remove try/catch from I/O boundaries
+
+## Limitations
+
+- One phase per cron run (10 phases = ~2.5 hours minimum)
+- No real-time slash command variants
+- Phase order is fixed; cannot skip ahead
+- Memory is session-based; use `memory` tool for persistence
+
+## Future Enhancements
+
+- [ ] Auto-detect optimal phase interval based on repo size
+- [ ] Parallel subagent analysis within a phase (Scout + Analyst)
+- [ ] Cross-session memory for language-specific patterns
+- [ ] Integration with Hermes checkpoint/rollback for safe resets

package/skills/hermes/README.md

@@ -0,0 +1,167 @@
+# Code Archaeology Hermes Skill
+
+## Installation
+
+```bash
+# Clone Code Archaeology
+git clone https://github.com/Maleick/Code-Archaeology.git
+cd Code-Archaeology
+
+# Install dependencies
+npm install
+
+# Verify
+npm run typecheck
+bash hooks/verify-package.sh
+```
+
+## Hermes Setup
+
+### 1. Setup Hermes Runtime
+
+```bash
+cd ~/projects/Code-Archaeology
+bash hooks/hermes/setup.sh
+```
+
+### 2. Create Session Config
+
+```bash
+# Create session config
+cat > .archaeology/session.json <<'EOF'
+{
+  "runtime": "hermes",
+  "status": "running",
+  "current_phase": "site-survey",
+  "completed_phases": [],
+  "mode": "survey",
+  "repo_path": ".",
+  "language": "typescript",
+  "test_command": "npm test",
+  "typecheck_command": "npx tsc --noEmit",
+  "branch_name": "refactor/archaeology",
+  "strict_mode": false,
+  "started_at": "2026-05-03T14:00:00Z"
+}
+EOF
+```
+
+### 3. Create Cronjob
+
+```bash
+hermes cronjob create \
+  --name "code-archaeology-expedition" \
+  --schedule "every 15m" \
+  --workdir ~/projects/Code-Archaeology \
+  --prompt "Run one Code Archaeology expedition phase. Read .archaeology/session.json, execute current phase with test/typecheck verification, advance to next phase. STOP after one phase."
+```
+
+## Usage
+
+### Start Expedition
+
+```bash
+# Resume cron (first run auto-initializes)
+hermes cronjob resume code-archaeology-expedition
+```
+
+### Check Status
+
+```bash
+cat .archaeology/session.json | jq .
+ls .archaeology/expedition*-report.md
+```
+
+### Change Mode
+
+```bash
+# Switch from survey to excavate
+jq '.mode = "excavate"' .archaeology/session.json > tmp.json && mv tmp.json .archaeology/session.json
+
+# Switch from excavate to restore
+jq '.mode = "restore"' .archaeology/session.json > tmp.json && mv tmp.json .archaeology/session.json
+```
+
+### Stop Expedition
+
+```bash
+# Set stop flag
+jq '.status = "stopped"' .archaeology/session.json > tmp.json && mv tmp.json .archaeology/session.json
+
+# Or pause cron
+hermes cronjob pause code-archaeology-expedition
+```
+
+## Phase Timeline
+
+With 15-minute intervals:
+- 10 phases × 15 min = **2.5 hours minimum**
+- Survey mode: ~2.5 hours (reports only)
+- Restore mode: ~2.5 hours + verification time
+
+## Reports Generated
+
+| File | Content |
+|------|---------|
+| `.archaeology/site_survey.md` | Baseline inventory |
+| `.archaeology/expedition1-report.md` | Site Survey |
+| `.archaeology/expedition2-report.md` | Dead Code |
+| `.archaeology/expedition3-report.md` | Legacy Removal |
+| `.archaeology/expedition4-report.md` | Dependency Mapping |
+| `.archaeology/expedition5-report.md` | Type Consolidation |
+| `.archaeology/expedition6-report.md` | Type Hardening |
+| `.archaeology/expedition7-report.md` | DRY Stratification |
+| `.archaeology/expedition8-report.md` | Error Handling |
+| `.archaeology/expedition9-report.md` | Artifact Cleaning |
+| `.archaeology/FINAL_CATALOG.md` | Complete summary |
+| `.archaeology/patches/*.patch` | Mock patches (excavate mode) |
+
+## Safety
+
+Same as OpenCode:
+- Survey mode: **zero file changes outside `.archaeology/`**
+- Restore mode: **test-gated, auto-revert on failure**
+- Never removes try/catch from I/O boundaries
+- Never guesses types; flags for human review
+
+## Troubleshooting
+
+### Cron not running
+
+```bash
+hermes cronjob list
+hermes cronjob log code-archaeology-expedition
+```
+
+### Phase blocked
+
+```bash
+# Check blocker
+cat .archaeology/session.json | jq '.flags.blocked_reason'
+
+# Reset and retry
+jq '.status = "running" | del(.flags.blocked_reason)' .archaeology/session.json > tmp.json && mv tmp.json .archaeology/session.json
+```
+
+### Reports empty
+
+- Ensure `mode` is set correctly in session.json
+- Check that language tools are installed (`knip`, `madge`, etc.)
+- Run `bash hooks/opencode/init.sh` to reinitialize
+
+## Comparison with OpenCode
+
+| Feature | OpenCode | Hermes |
+|---------|----------|--------|
+| Entry | `/code-archaeology` | Cronjob |
+| Phases | All in one session | One per 15-min cron |
+| Real-time | Yes | Delayed |
+| Slash variants | 3 commands | Mode flag in session |
+| Background | Plugin active | Native cron |
+| State | `.archaeology/session.json` | Same |
+
+## Links
+
+- Code Archaeology repo: https://github.com/Maleick/Code-Archaeology
+- Hermes docs: https://hermes-agent.nousresearch.com/docs
+- OpenCode plugin: `opencode-code-archaeology`