@junwu168/openshell 0.1.0

package/dist/product/workspace-tracker.js

@@ -0,0 +1,48 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+const readEntries = async (trackerFile) => {
+    try {
+        const raw = await readFile(trackerFile, "utf8");
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed)) {
+            return [];
+        }
+        return parsed.filter((entry) => {
+            if (typeof entry !== "object" || entry === null) {
+                return false;
+            }
+            const candidate = entry;
+            return typeof candidate.workspaceRoot === "string" && typeof candidate.managedPath === "string";
+        });
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return [];
+        }
+        throw error;
+    }
+};
+const writeEntries = async (trackerFile, entries) => {
+    await mkdir(dirname(trackerFile), { recursive: true });
+    await writeFile(trackerFile, JSON.stringify(entries, null, 2) + "\n");
+};
+export const createWorkspaceTracker = (trackerFile) => ({
+    async list() {
+        return readEntries(trackerFile);
+    },
+    async record(entry) {
+        const entries = await readEntries(trackerFile);
+        const next = [
+            ...entries.filter((existing) => existing.workspaceRoot !== entry.workspaceRoot),
+            entry,
+        ];
+        await writeEntries(trackerFile, next);
+    },
+    async remove(workspaceRoot) {
+        const entries = await readEntries(trackerFile);
+        await writeEntries(trackerFile, entries.filter((entry) => entry.workspaceRoot !== workspaceRoot));
+    },
+    async clear() {
+        await writeEntries(trackerFile, []);
+    },
+});

package/docs/superpowers/notes/2026-03-25-opencode-remote-tools-handoff.md

@@ -0,0 +1,81 @@
+# OpenCode Remote Tools Handoff
+
+Date: 2026-03-25
+Execution mode: `subagent-driven-development`
+Worktree: `.worktrees/opencode-v1`
+Branch: `opencode-v1`
+
+## Source Docs
+
+- Spec: `docs/superpowers/specs/2026-03-25-opencode-remote-tools-design.md`
+- Plan: `docs/superpowers/plans/2026-03-25-opencode-remote-tools.md`
+
+## What Was Completed
+
+- Tasks 1 through 9 from the implementation plan are complete.
+- The OpenCode adapter now registers explicit remote tools:
+  - `list_servers`
+  - `remote_exec`
+  - `remote_read_file`
+  - `remote_write_file`
+  - `remote_patch_file`
+  - `remote_list_dir`
+  - `remote_stat`
+  - `remote_find`
+- The local smoke fixture exists under `examples/opencode-local/`.
+- Build output now aligns with package and smoke-fixture expectations by emitting `dist/index.js`.
+- The plugin test no longer relies on checkout-specific absolute paths or global module-mock leakage.
+
+## Final Verified State
+
+Verified on the latest branch head after the approval-gap fix:
+
+- `~/.bun/bin/bun test tests/unit/*.test.ts tests/integration/ssh-runtime.test.ts tests/integration/orchestrator.test.ts`
+  - Result: `56 pass`, `0 fail`
+- `~/.bun/bin/bun run typecheck`
+  - Result: pass
+- `~/.bun/bin/bun run build`
+  - Result: pass
+
+## Smoke-Test Evidence
+
+- `examples/opencode-local/.opencode/plugins/open-code.ts` resolves successfully against the built package.
+- `opencode run --print-logs "Call list_servers and print the raw tool result."` loaded the local plugin and executed `list_servers` successfully.
+- OpenCode logs showed the custom tools were registered, including `list_servers`, `remote_exec`, `remote_read_file`, `remote_write_file`, `remote_patch_file`, `remote_list_dir`, `remote_stat`, and `remote_find`.
+- Unit coverage now verifies the approval handoff path:
+  - safe `remote_exec` does not call `context.ask(...)`
+  - approval-required `remote_exec` calls `context.ask(...)` with built-in `bash` permission
+  - `remote_write_file` calls `context.ask(...)` with built-in `edit` permission
+  - the local example `opencode.json` is aligned to `bash` / `edit`, not custom tool ids
+
+## Approval Gap Root Cause And Fix
+
+- Root cause: OpenCode did not enforce `opencode.json` permission entries keyed by custom plugin tool names like `remote_write_file` or `remote_exec`.
+- Evidence: interactive OpenCode allowed `remote_write_file` to run without a prompt and returned our structured `SERVER_NOT_FOUND` result.
+- Fix: the adapter now explicitly requests approval through the plugin SDK `context.ask(...)` API before:
+  - approval-required `remote_exec`
+  - `remote_write_file`
+  - `remote_patch_file`
+- The adapter requests approval under OpenCode's built-in permission families:
+  - `bash` for approval-required remote shell execution
+  - `edit` for remote file mutations
+- The example config now uses `bash` and `edit` permission keys accordingly.
+
+## Residual Gap
+
+- A fresh interactive manual re-check is still required on the latest head to confirm host-side prompt UX:
+  - safe `remote_exec` must not prompt
+  - `remote_write_file` must prompt before the tool returns `SERVER_NOT_FOUND` for a missing server
+- The prior upstream OpenCode provider/certificate instability remains a possible source of noise for nontrivial end-to-end runs.
+
+## Recommended Starting Point For The Next Session
+
+- Start from the pushed `opencode-v1` branch.
+- If the next session is feature design, begin from the shipped v1 boundary in the spec and treat this branch as the implementation baseline.
+- If the next session is verification-focused, first re-run the manual OpenCode smoke flow on the latest head:
+  1. `bun run build`
+  2. `cd examples/opencode-local`
+  3. `opencode`
+  4. confirm `list_servers`
+  5. confirm safe `remote_exec`
+  6. confirm `remote_write_file` shows approval prompt

package/docs/superpowers/notes/2026-03-26-openshell-pre-release-review.md

@@ -0,0 +1,174 @@
+# OpenShell Pre-Release Review Note
+
+Date: 2026-03-26
+Branch: `main`
+Reviewer: Claude Code
+
+## Scope
+
+This document reviews the first pre-release candidate for:
+
+- npm package: `@junwu168/openshell`
+- CLI binary: `openshell`
+- supported host: `opencode`
+
+The package enables AI coding CLIs to safely operate on remote Linux servers over SSH with credential isolation, user approval enforcement, and local audit trails.
+
+## Automated Verification
+
+Verified on current HEAD:
+
+```bash
+bun test
+bun run typecheck
+bun run build
+```
+
+Observed result:
+
+- `bun test` -> `96 pass, 0 fail`
+- `typecheck` -> pass
+- `build` -> pass
+
+## Architecture Summary
+
+```
+src/
+├── index.ts                    # Package exports (OpenCodePlugin, contracts)
+├── core/                       # Host-agnostic runtime core
+│   ├── contracts.ts            # Shared types: ServerID, ToolPayload, ToolResult, PolicyDecision
+│   ├── result.ts               # okResult(), partialFailureResult(), errorResult()
+│   ├── paths.ts                # Runtime path resolution via env-paths
+│   ├── policy.ts               # Deterministic command classification
+│   ├── patch.ts                # Unified diff application
+│   ├── orchestrator.ts         # Central pipeline: validate -> classify -> approve -> execute -> audit
+│   ├── registry/               # Server registry (layered JSON, NOT encrypted)
+│   │   └── server-registry.ts  # Global + workspace scoped server records
+│   ├── ssh/                    # SSH/SFTP operations
+│   │   └── ssh-runtime.ts      # exec, readFile, writeFile, listDir, stat
+│   └── audit/                 # Audit logging and git-backed snapshots
+│       ├── log-store.ts        # JSONL append-only audit log
+│       ├── git-audit-repo.ts   # Git-backed file snapshots
+│       └── redact.ts           # Secret redaction before logging
+├── opencode/
+│   └── plugin.ts              # OpenCode adapter (tool definitions, approval prompts)
+├── cli/                       # CLI commands
+│   ├── openshell.ts           # Main CLI entry (install/uninstall/server-registry)
+│   └── server-registry.ts     # Interactive server registry CLI
+└── product/                   # Install/uninstall lifecycle
+    ├── install.ts             # openshell install
+    ├── uninstall.ts           # openshell uninstall
+    ├── opencode-config.ts     # OpenCode config merging
+    └── workspace-tracker.ts   # Track workspaces for cleanup
+```
+
+## Implemented Features
+
+### Remote Tools (8 tools)
+- `list_servers` - List registered servers
+- `remote_exec` - Execute shell commands on remote servers
+- `remote_read_file` - Read remote files
+- `remote_write_file` - Write remote files (approval-required)
+- `remote_patch_file` - Apply unified diffs (approval-required)
+- `remote_list_dir` - List remote directories
+- `remote_stat` - Stat remote paths
+- `remote_find` - Search remote files/content
+
+### Policy Engine
+- **Auto-allow:** Safe inspection commands (cat, grep, find, ls, pwd, uname, df, free, ps, systemctl status)
+- **Approval-required:** Middleware commands (psql, mysql, redis-cli, kubectl, docker, helm, aws, gcloud, az) and shell composition (pipes, redirects, chaining)
+- **Reject:** Empty commands
+
+### Server Registry
+- **Layered configuration:** Global (`~/.config/openshell/servers.json`) and workspace (`<workspace>/.open-code/servers.json`)
+- **File locking:** Prevents concurrent write corruption
+- **Workspace shadowing:** Workspace entries override global entries with the same ID
+- **Auth types:** Password, private key (with optional passphrase), certificate
+
+### Audit System
+- **JSONL action log:** All tool actions logged with timestamps, sanitized secrets
+- **Git-backed snapshots:** Before/after content for file writes stored in git commits
+- **Fail-closed:** If audit preflight fails, operations do not proceed
+
+### Install/Uninstall Lifecycle
+- `openshell install` - Creates dirs, merges OpenCode config with plugin + permissions
+- `openshell uninstall` - Aggressively removes all OpenShell state and tracked workspace `.open-code/` dirs
+
+## Security Considerations
+
+### Known Security Model (Documented)
+
+> "Password auth is stored in plain text. That is intentionally simple for this pre-release and not recommended for long-term production use."
+
+### Secret Handling
+- Passwords stored in plain text JSON files (keytar dependency was removed)
+- Private key paths and certificate paths are read from filesystem at runtime
+- Secret redaction in audit logs covers URLs with embedded credentials and `password=`, `secret=`, `token=` patterns
+- `list_servers` properly excludes auth data from returned server records
+
+### Credential Isolation
+- Server IDs used in tool calls, not raw credentials
+- Auth paths validated for workspace-scoped records only
+- Relative auth paths rejected for global scope
+
+## Pre-Release Concerns
+
+### 1. Plain-Text Password Storage
+The current implementation stores passwords in plain text JSON. For a production release, encryption at rest would be essential.
+
+### 2. `remote_find` Uses Shell Execution (Medium Risk)
+The `remote_find` implementation builds shell commands (`find ... | head -n ...` or `grep -R -n ... | head -n ...`) which bypasses the policy engine's shell composition detection. Commands with pipes or redirects could be constructed via the `pattern` or `glob` arguments.
+
+### 3. No Connection Pooling/Reuse (Performance)
+Each SSH operation creates a new connection. For high-frequency tool use, this could be inefficient.
+
+### 4. Uninstall Removes Workspace `.open-code/` Dirs
+The uninstall is "aggressive" and removes ALL tracked workspace `.open-code/` directories. If users have other plugins or data in those directories, it would be lost.
+
+### 5. Bun Runtime Dependency
+The project uses Bun as its runtime/package manager. Node.js compatibility would require additional work.
+
+### 6. No Connection Recovery (Reliability)
+The audit system is fail-closed, but there's no retry logic or recovery for transient SSH failures.
+
+## Review Path
+
+Reviewer flow:
+
+1. `npm install -g @junwu168/openshell`
+2. `openshell install`
+3. `openshell server-registry add`
+4. Launch `opencode`
+5. Exercise:
+   - `list_servers`
+   - safe `remote_exec`
+   - approval-gated `remote_write_file`
+6. `openshell uninstall`
+
+## Prior Fix (Verified in This Review)
+
+During prior verification, an uninstall bug was fixed:
+
+- if OpenCode config only contained `@junwu168/openshell`, uninstall preserved the plugin entry because the config writer spread `...current` back into the output when the filtered plugin list became empty
+
+This is covered by `tests/unit/opencode-config.test.ts` and fixed in `src/product/opencode-config.ts`.
+
+## Test Coverage
+
+| File | Approx Lines | Coverage Relevance |
+|------|-------------|-------------------|
+| `src/core/orchestrator.ts` | ~1080 | Central pipeline (critical) |
+| `src/core/registry/server-registry.ts` | ~505 | Server registry |
+| `src/cli/server-registry.ts` | ~470 | Interactive CLI |
+| `src/core/ssh/ssh-runtime.ts` | ~355 | SSH operations |
+| `src/opencode/plugin.ts` | ~243 | OpenCode adapter |
+| `src/product/opencode-config.ts` | ~118 | Config lifecycle |
+
+## Verdict
+
+**Ready for pre-release** with the documented concerns understood by users:
+
+- Plain-text password storage is acceptable for pre-release evaluation
+- `remote_find` shell composition bypass should be addressed before production
+- All automated tests pass (96 tests)
+