opencode-code-archaeology 2.0.0 → 2.0.2

package/docs/INSTALL.md

@@ -0,0 +1,117 @@
+# Install Code Archaeology
+
+This guide mirrors the root [`INSTALL.md`](../INSTALL.md) and covers the recommended OpenCode plugin configuration plus the npm CLI install path.
+
+## Prerequisites
+
+- OpenCode installed and available in your shell.
+- Node.js 18 or newer with npm.
+- Git installed and available in your shell.
+- A target repository with tests or type checks before running `restore` mode.
+
+## Recommended OpenCode Plugin Install
+
+Add Code Archaeology to the top-level `plugin` array in `opencode.json`:
+
+```json
+{
+  "plugin": [
+    "opencode-code-archaeology@git+https://github.com/Maleick/Code-Archaeology.git"
+  ]
+}
+```
+
+Restart OpenCode after editing the configuration. The command family should then be available inside a Git repository:
+
+```text
+/code-archaeology
+/code-archaeology-survey
+/code-archaeology-excavate
+/code-archaeology-restore
+```
+
+## npm Global Install
+
+Use the npm package when you want the CLI installer and diagnostics:
+
+```bash
+npm install -g opencode-code-archaeology
+opencode-code-archaeology install
+opencode-code-archaeology doctor
+opencode-code-archaeology version
+```
+
+Then restart OpenCode and run:
+
+```text
+/code-archaeology-survey
+```
+
+## Verification
+
+Confirm the published package and local CLI are visible:
+
+```bash
+npm view opencode-code-archaeology version
+npm view opencode-code-archaeology dist-tags
+opencode-code-archaeology doctor
+opencode-code-archaeology version
+```
+
+For a local clone, run focused package checks:
+
+```bash
+npm install
+npm run build
+npm run typecheck
+bash -n hooks/opencode/*.sh
+```
+
+To verify plugin behavior, restart OpenCode in a Git repository and run:
+
+```text
+/code-archaeology-survey
+```
+
+The survey should create `.archaeology/` reports without modifying source files.
+
+## Updating
+
+For plugin-array installs, update through your OpenCode package manager flow, then restart OpenCode. If your setup caches Git plugins, clear the cached `opencode-code-archaeology` package and let OpenCode reinstall it.
+
+For npm global installs:
+
+```bash
+npm install -g opencode-code-archaeology@latest
+npm list -g opencode-code-archaeology --depth=0
+opencode-code-archaeology doctor
+```
+
+## Troubleshooting
+
+### Plugin Not Loading
+
+- Confirm `opencode.json` is valid JSON.
+- Confirm the package entry is in the top-level `plugin` array, not `plugins`.
+- Restart OpenCode after changing configuration.
+- Confirm Git can reach `https://github.com/Maleick/Code-Archaeology.git`.
+
+### Commands Not Found
+
+- Restart OpenCode so it reloads plugin commands.
+- Confirm the npm package installed with `npm list -g opencode-code-archaeology --depth=0` if using the global path.
+- Run `/code-archaeology-survey` from inside a Git repository.
+
+### Stale Cache
+
+- Remove the cached OpenCode package for `opencode-code-archaeology` if your runtime keeps one.
+- Reinstall or rerun OpenCode plugin resolution.
+- Restart OpenCode before testing again.
+
+### Restore Safety
+
+- Start with `/code-archaeology-survey`; it writes reports only.
+- Review `.archaeology/site_survey.md` and expedition reports before restore.
+- Use `/code-archaeology-excavate` for mock patches if you want another review gate.
+- Run `/code-archaeology-restore` only when the target repository has tests or type checks available.
+- Do not commit `.archaeology/`; it is local runtime state.

package/docs/README.md

@@ -0,0 +1,44 @@
+# Code Archaeology Documentation
+
+Code Archaeology is an OpenCode plugin for systematic codebase excavation, cataloging, and restoration. It runs inside the target repository, writes local `.archaeology/` reports, and only modifies source files in `restore` mode after review and verification.
+
+These Markdown files are ready to serve from GitHub Pages, but this repository does not assume Pages is already enabled.
+
+## Quick Links
+
+- [Install Guide](INSTALL.md)
+- [Architecture](ARCHITECTURE.md)
+- [Release Process](RELEASE.md)
+- [Security Audit](SECURITY_AUDIT.md)
+- [Repository README](../README.md)
+- [Root Install Handoff](../INSTALL.md)
+
+## Quick Start
+
+Install the package globally, register the plugin, then verify the CLI:
+
+```bash
+npm install -g opencode-code-archaeology
+opencode-code-archaeology install
+opencode-code-archaeology doctor
+opencode-code-archaeology version
+```
+
+Restart OpenCode in the repository you want to inspect and start with the non-destructive survey command:
+
+```text
+/code-archaeology-survey
+```
+
+Review `.archaeology/site_survey.md` and expedition reports before using:
+
+```text
+/code-archaeology-excavate
+/code-archaeology-restore
+```
+
+## Safety Warning
+
+`survey` mode writes reports only. `excavate` mode writes reports and mock patches. `restore` mode can edit source files and should only run after report review, on an isolated branch, with tests or type checks available.
+
+Do not commit `.archaeology/`; it is local runtime state.

package/docs/RELEASE.md

@@ -0,0 +1,135 @@
+# Release Process
+
+This checklist is for future `opencode-code-archaeology` releases. `v2.0.2` is the current release example; replace it with the next version when preparing a new release.
+
+## 1. Preflight
+
+- Work from the release readiness branch or a dedicated release worktree.
+- Confirm the worktree has no unrelated changes you intend to publish accidentally.
+- Confirm no secrets or local runtime state are staged.
+- Review `README.md`, `INSTALL.md`, `docs/`, `wiki/`, `CHANGELOG.md`, and package metadata for version-specific claims.
+- Confirm `.archaeology/`, `.superpowers/`, `node_modules/`, and logs are ignored.
+
+## 2. Version Bump
+
+For a future release, replace `2.0.2` with the target version:
+
+```bash
+npm version 2.0.2 --no-git-tag-version
+```
+
+Update `VERSION` to the same value:
+
+```text
+2.0.2
+```
+
+Confirm `package.json`, `package-lock.json`, and `VERSION` agree.
+
+## 3. Changelog
+
+- Add a `v2.0.2` entry, or the future target version, to `CHANGELOG.md`.
+- Include user-visible changes, safety notes, and any migration instructions.
+- Keep the release notes factual and avoid claiming publication steps that have not happened yet.
+
+## 4. Verification
+
+Run focused release checks before committing:
+
+```bash
+npm install
+npm run build
+npm run typecheck
+npm audit --audit-level=moderate
+npm outdated --json
+bash -n hooks/opencode/*.sh
+npm pack --json --dry-run
+```
+
+Expected outcomes:
+
+- Build and typecheck pass.
+- npm audit reports no moderate-or-higher vulnerabilities.
+- npm outdated reports `{}` or no actionable outdated dependencies.
+- Shell hooks pass syntax checks.
+- The package dry run includes required files.
+
+## 5. npm Pack Required Files
+
+Inspect `npm pack --json --dry-run` output for the package contents. Required files should include:
+
+- `dist/`
+- `assets/`
+- `hooks/`
+- `commands/`
+- `skills/`
+- `plugins/`
+- `schema/`
+- `prompts/`
+- `docs/`
+- `wiki/`
+- `AGENTS.md`
+- `VERSION`
+- `INSTALL.md`
+- `README.md`
+- `CHANGELOG.md`
+- `CONTRIBUTING.md`
+- `SECURITY.md`
+- `LICENSE`
+
+If any required file is missing, update the `files` array in `package.json`, rerun `npm install` if the lockfile needs to change, and repeat the package dry run.
+
+## 6. Commit, Tag, And Push
+
+Only perform these steps after verification passes and after confirming the branch is safe to publish:
+
+```bash
+git status --short
+git add README.md INSTALL.md docs wiki assets .github SECURITY.md CONTRIBUTING.md CHANGELOG.md package.json package-lock.json VERSION .gitignore
+git commit -m "chore: prepare v2.0.2 release"
+git tag v2.0.2
+git push origin HEAD
+git push origin v2.0.2
+```
+
+For a future release, use the future version in the commit message and tag.
+
+## 7. GitHub Release
+
+Create the GitHub release from the matching tag:
+
+```bash
+gh release create v2.0.2 --title "v2.0.2" --notes-file CHANGELOG.md
+```
+
+Before publishing, trim the notes to the specific version section if `CHANGELOG.md` contains multiple releases.
+
+## 8. npm Publish
+
+Publish only after the GitHub tag and release are correct:
+
+```bash
+npm publish --access public
+```
+
+If publishing fails, do not create a replacement tag unless the failure requires a new package version. Fix the issue, rerun verification, and follow npm versioning rules.
+
+## 9. Final Checks
+
+Confirm the public release surfaces report the expected version:
+
+```bash
+npm view opencode-code-archaeology version
+npm view opencode-code-archaeology dist-tags
+gh release view v2.0.2
+```
+
+Optionally verify a fresh install path:
+
+```bash
+npm install -g opencode-code-archaeology@latest
+opencode-code-archaeology doctor
+opencode-code-archaeology version
+```
+
+Do not claim GitHub Pages is enabled unless repository settings confirm it.

package/docs/SECURITY_AUDIT.md

@@ -0,0 +1,38 @@
+# Security Audit Notes
+
+These notes capture the current release-readiness security posture for Code Archaeology. They are intended to accompany the release checklist and should be refreshed before each publication.
+
+## Current Findings
+
+- `npm audit --audit-level=moderate` is expected to be clean for the current dependency set.
+- `npm outdated --json` is expected to be clean for the current dependency set.
+- No hardcoded secrets are expected in source, docs, hooks, commands, prompts, schemas, or package metadata.
+- `.archaeology/` is local runtime state and is ignored by Git.
+- `.superpowers/` is local planning state and is ignored by Git.
+- Shell hooks in `hooks/opencode/` are syntax-checkable with `bash -n hooks/opencode/*.sh`.
+
+## Local State
+
+Code Archaeology writes operational state into `.archaeology/` in the target repository. This directory can contain project structure, findings, generated reports, mock patches, and restoration logs. It should stay local unless a maintainer intentionally extracts a report for review.
+
+## Restore-Mode Safety Caveat
+
+`restore` mode can modify source files. It should only run after `survey` reports are reviewed, preferably after `excavate` mock patches are reviewed, and only when the target repository has tests or type checks available. Failed restore phases should be reverted with the bundled revert hook before continuing.
+
+The tool must not remove try/catch blocks around I/O or external input boundaries automatically, and uncertain type replacements should be flagged for human review instead of guessed.
+
+## Release Checklist
+
+Before publishing a release:
+
+```bash
+npm install
+npm run build
+npm run typecheck
+npm audit --audit-level=moderate
+npm outdated --json
+bash -n hooks/opencode/*.sh
+npm pack --json --dry-run
+```
+
+Inspect the package dry run for required files and for accidental inclusion of local state. Do not publish if `.archaeology/`, `.superpowers/`, credentials, logs, or editor state appear in the package contents.

package/hooks/opencode/verify-package.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+pack_json=$(npm pack --json --dry-run)
+
+PACK_JSON="$pack_json" node <<'NODE'
+const pack = JSON.parse(process.env.PACK_JSON ?? '[]');
+const files = new Set((pack[0]?.files ?? []).map((file) => file.path));
+
+const requiredFiles = [
+  'dist/cli.js',
+  'dist/index.js',
+  'commands/code-archaeology.md',
+  'skills/code-archaeology/SKILL.md',
+  'hooks/opencode/init.sh',
+  'hooks/opencode/verify-phase.sh',
+  'hooks/opencode/revert-phase.sh',
+  'hooks/opencode/update-expedition.sh',
+  'hooks/opencode/verify-package.sh',
+  'prompts/discovery.md',
+  'schema/expedition-report.json',
+  'docs/README.md',
+  'wiki/Home.md',
+  'assets/code-archaeology-banner.svg',
+  'AGENTS.md',
+  'VERSION',
+  'README.md',
+  'INSTALL.md',
+  'SECURITY.md',
+  'CONTRIBUTING.md',
+  'CHANGELOG.md',
+  'LICENSE',
+];
+
+const missingFiles = requiredFiles.filter((file) => !files.has(file));
+
+if (missingFiles.length > 0) {
+  console.error('Package is missing required files:');
+  for (const file of missingFiles) {
+    console.error(`- ${file}`);
+  }
+  process.exit(1);
+}
+
+console.log(`Package dry-run includes ${files.size} files and all required release assets.`);
+NODE

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-code-archaeology",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "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",
@@ -12,6 +12,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "default": "./dist/plugin.js"
     }
   },
   "files": [
@@ -20,15 +24,28 @@
     "commands",
     "skills",
     "plugins",
-    "policies",
+    "prompts",
     "schema",
+    "docs/README.md",
+    "docs/INSTALL.md",
+    "docs/ARCHITECTURE.md",
+    "docs/RELEASE.md",
+    "docs/SECURITY_AUDIT.md",
+    "wiki",
+    "assets",
+    ".github",
     "AGENTS.md",
     "VERSION",
     "README.md",
+    "INSTALL.md",
+    "SECURITY.md",
+    "CONTRIBUTING.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "scripts": {
     "build": "tsc",
+    "test": "npm run build && node --test tests/*.test.mjs",
     "typecheck": "tsc --noEmit",
     "verify:pack": "bash hooks/opencode/verify-package.sh",
     "prepack": "tsc"
@@ -46,14 +63,18 @@
     "type": "git",
     "url": "git+https://github.com/Maleick/Code-Archaeology.git"
   },
-  "homepage": "https://github.com/Maleick/Code-Archaeology",
+  "author": {
+    "name": "Maleick",
+    "url": "https://github.com/Maleick"
+  },
+  "homepage": "https://github.com/Maleick/Code-Archaeology#readme",
   "bugs": {
     "url": "https://github.com/Maleick/Code-Archaeology/issues"
   },
   "license": "MIT",
   "devDependencies": {
-    "@types/node": "^20.0.0",
-    "typescript": "^5.0.0"
+    "@types/node": "^25.6.0",
+    "typescript": "^6.0.3"
   },
   "engines": {
     "node": ">=18"

package/prompts/dead_code.md

@@ -0,0 +1,45 @@
+# Expedition 1: Dead Code Excavation
+
+## Objective
+Identify and catalog all dead code—unused exports, unreachable functions, unreferenced variables, and orphaned files.
+
+## Instructions
+
+1. **Tool-Based Discovery**
+   - Run `knip` (TypeScript/JavaScript) or `vulture` (Python)
+   - Run `jscpd` to find duplicate code that may indicate dead copies
+   - If tools unavailable, perform AST-based manual analysis
+
+2. **Classification**
+   For each finding, classify confidence:
+   - **HIGH**: Tool-confirmed unused export with zero references
+   - **MEDIUM**: Likely unused but has dynamic access or test references
+   - **LOW**: Possibly used via reflection or build-time injection
+
+3. **Impact Assessment**
+   - Note if removal affects public API
+   - Check for test files that import but don't meaningfully test
+   - Verify no build scripts or CI depend on the code
+
+## Output
+
+Write to `.archaeology/expedition1-report.md`:
+- Table of all findings with file paths, line numbers, confidence levels
+- Categorized by type (unused export, unreachable code, orphaned file, duplicate)
+- Recommended action per finding (remove, flag for review, keep)
+- Estimated lines of code affected
+
+## Execution Rules
+- If `mode == survey`: catalog only, zero changes
+- If `mode == excavate`: generate mock patch files for review
+- If `mode == restore`:
+  - Remove HIGH confidence artifacts always
+  - Remove MEDIUM confidence artifacts only if `strict_mode == true`
+  - NEVER remove LOW confidence artifacts
+  - Run tests after each removal batch
+  - Revert immediately if tests fail
+
+## Constraints
+- NEVER remove code that is dynamically accessed (eval, require(variable), etc.)
+- NEVER remove exports that are part of a public API unless explicitly deprecated
+- ALWAYS verify with grep that no references exist before removing

package/prompts/dependencies.md

@@ -0,0 +1,49 @@
+# Expedition 3: Circular Dependency Cartography
+
+## Objective
+Map all circular dependencies in the module graph and provide remediation strategies.
+
+## Instructions
+
+1. **Tool-Based Analysis**
+   - Run `madge --circular` (TypeScript/JavaScript)
+   - Run `pydeps` (Python) or equivalent
+   - If tools unavailable, build import graph manually
+
+2. **Dependency Mapping**
+   For each cycle found:
+   - List all files in the cycle
+   - Identify the specific imports creating the cycle
+   - Determine if the cycle is direct (A→B→A) or indirect (A→B→C→A)
+   - Calculate cycle complexity (number of nodes, edges)
+
+3. **Remediation Strategy**
+   For each cycle, determine the best fix:
+   - Extract shared code to a new module (preferred)
+   - Use dependency inversion / interfaces
+   - Move code to break the cycle
+   - Convert to dynamic imports (if appropriate)
+   - Flag as architectural issue requiring human design review
+
+## Output
+
+Write to `.archaeology/expedition3-report.md`:
+- Complete cycle inventory with file paths and import chains
+- Visualization data (can be rendered with graphviz)
+- Remediation recommendation per cycle
+- Estimated effort to resolve each cycle
+
+## Execution Rules
+- If `mode == survey`: catalog only
+- If `mode == excavate`: generate detailed migration plans
+- If `mode == restore`:
+  - Fix simple cycles (2-node, clear extraction path) automatically
+  - Flag complex cycles for human review
+  - NEVER create new abstractions that obscure the cycle—break it properly
+  - Run tests after each fix
+
+## Constraints
+- NEVER introduce dynamic imports just to hide a cycle—fix the architecture
+- NEVER extract code into poorly-named "utils" files—use domain-appropriate names
+- ALWAYS ensure the fixed graph has no new cycles introduced
+- ALWAYS verify the cycle is real (not a type-only import that tree-shakes away)

package/prompts/discovery.md

@@ -0,0 +1,47 @@
+# Phase 0: Site Survey & Baseline
+
+## Objective
+Establish a complete inventory of the codebase before any modifications. Document the baseline state so all subsequent expeditions have a reference point.
+
+## Instructions
+
+1. **Verify Preconditions**
+   - Confirm working tree is clean
+   - Confirm tests pass at baseline
+   - Create branch `{{ branch_name }}`
+   - Create `.archaeology/` directory
+
+2. **File Inventory**
+   - Catalog all source files by directory
+   - Note file counts, line counts, and language distribution
+   - Identify configuration files (package.json, tsconfig, etc.)
+
+3. **Dependency Mapping**
+   - Document all external dependencies
+   - Note devDependencies vs production dependencies
+   - Flag any deprecated or outdated packages
+
+4. **Baseline Metrics**
+   - Record test count and coverage (if available)
+   - Record type error count
+   - Record lint error count
+   - Save current git HEAD to `.archaeology/baseline.txt`
+
+## Output
+
+Write to `.archaeology/site_survey.md`:
+- Executive summary of codebase size and structure
+- Dependency health assessment
+- Baseline metrics table
+- Risk factors identified
+
+Write to `.archaeology/artifact_inventory.json`:
+- Machine-readable file inventory
+
+Write to `.archaeology/stratum_graph.json`:
+- Dependency graph data for visualization
+
+## Constraints
+- ZERO file modifications in this phase
+- If tests fail at baseline, abort immediately
+- Do not proceed to Expedition 1 until this report is complete

package/prompts/dry.md

@@ -0,0 +1,49 @@
+# Expedition 6: DRY Stratification
+
+## Objective
+Identify semantic duplication across the codebase and extract shared abstractions. Only extract true semantic duplicates, not coincidental similarity.
+
+## Instructions
+
+1. **Duplicate Detection**
+   - Run `jscpd` with `min_duplicate_lines: 5`
+   - Search for repeated patterns manually (error messages, validation logic, API calls)
+   - Look for copy-pasted code blocks with minor variations
+
+2. **Semantic Analysis**
+   For each duplicate found:
+   - Determine if the duplication is coincidental (same structure, different semantics)
+   - Check if the duplicated code represents a real domain concept
+   - Assess if extraction would create a meaningful abstraction
+   - Verify the duplicated code isn't better left inline (trivial one-liners)
+
+3. **Extraction Planning**
+   - Identify the canonical location for the extracted code
+   - Determine the appropriate abstraction level (function, class, constant, etc.)
+   - Plan parameterization for minor variations
+   - Check for existing utility libraries that could host the code
+
+## Output
+
+Write to `.archaeology/expedition6-report.md`:
+- Catalog of all duplications with locations and similarity scores
+- Classification: semantic vs. coincidental
+- Extraction recommendation for each semantic duplicate
+- Proposed abstraction name and location
+- Files affected by extraction
+
+## Execution Rules
+- If `mode == survey`: catalog only
+- If `mode == excavate`: generate extraction plans with before/after code
+- If `mode == restore`:
+  - Extract HIGH confidence semantic duplications
+  - Extract MEDIUM confidence only if `strict_mode == true`
+  - NEVER extract coincidental similarities—leave them inline
+  - Run tests after each extraction
+
+## Constraints
+- NEVER extract code into a "utils" grab bag—use domain-appropriate names
+- NEVER create abstractions over cyclic dependencies (fix cycles in Expedition 3 first)
+- ALWAYS ensure the extracted code is actually used in 3+ places or is likely to be
+- NEVER change behavior during extraction—pure refactor only
+- ALWAYS prefer composition over premature abstraction