@junwu168/openshell 0.1.3 → 0.1.4

package/docs/superpowers/specs/2026-03-25-opencode-remote-tools-design.md

@@ -1,378 +0,0 @@
-# Open Code v1 Design: OpenCode Remote Tools
-
-## Overview
-
-Open Code is a terminal-only plugin for AI coding CLIs. In v1, the first host integration is `opencode`.
-
-The product goal is to let an AI model operate on one or more remote Linux servers over SSH while keeping credentials isolated from the model, enforcing strict user approvals for risky actions, and preserving an audit trail on the client machine.
-
-This document defines the design boundary for v1 so implementation planning can proceed without revisiting scope or architecture.
-
-## Problem Statement
-
-AI coding CLIs are useful for local development, but infrastructure and operations work often happens across multiple remote machines. Existing CLI tools do not provide a safe, structured way for a model to:
-
-- work against multiple remote servers in one session,
-- use isolated SSH credentials that the model cannot read,
-- require explicit approval before risky remote actions,
-- preserve a local audit trail of commands and file changes, and
-- evolve cleanly to support additional host CLIs later.
-
-## Goals
-
-- Integrate with `opencode` as the first supported host CLI.
-- Expose explicit remote tools rather than pretending the remote machine is the local filesystem.
-- Support multiple registered servers from the start.
-- Store server credentials in a local encrypted registry controlled by Open Code, not by model-visible config files.
-- Allow clearly safe Linux inspection commands to run without approval.
-- Require per-action approval for every write operation.
-- Require approval for middleware-oriented commands even when they appear read-only.
-- Keep a structured local audit log for every action.
-- Keep a local git-backed audit repository for file changes made through dedicated remote file write tools.
-- Preserve a host-agnostic core so future adapters for `codex`, `claude code`, or similar CLIs can reuse the same runtime and policy logic.
-
-## Non-Goals
-
-- Supporting GUI editors or IDE plugins in v1.
-- Hiding remote execution behind local-looking file or shell tools.
-- Auto-approving writes for a whole session or server.
-- Using git on the remote server for audit or rollback.
-- Guaranteeing full file-level reconstruction for arbitrary shell commands that mutate remote state indirectly.
-- Supporting every possible remote protocol beyond SSH in v1.
-
-## Scope Summary
-
-V1 is a terminal plugin for `opencode` backed by a host-agnostic local core library that runs in-process with the plugin. The plugin defines explicit remote tools. The core handles encrypted credentials, SSH execution, policy enforcement, audit logging, and local git snapshots for dedicated file-write operations.
-
-## Architecture
-
-### High-Level Shape
-
-The system is split into two layers:
-
-1. `opencode` host adapter
-2. host-agnostic local core
-
-In v1, the local core is an in-process library rather than a separate background daemon or long-lived local service. This keeps packaging, lifecycle, and approval flow simple for the first release while preserving clear boundaries that can later be extracted behind an IPC layer if needed.
-
-The `opencode` adapter is responsible for:
-
-- registering tool definitions with `opencode`,
-- receiving tool calls,
-- surfacing approval prompts to the user,
-- returning structured tool results in the shape expected by `opencode`.
-
-The local core is responsible for:
-
-- encrypted server registry,
-- SSH connection and session reuse,
-- command classification and policy enforcement,
-- remote file and command execution,
-- audit log persistence,
-- local git-backed file snapshotting.
-
-### Core Module Boundaries
-
-The local core should be split into the following modules:
-
-- `host-adapter/opencode`
-  - The `opencode`-specific plugin layer.
-- `tool-orchestrator`
-  - Entry point for all tool calls.
-  - Applies common sequencing: validate, resolve server, classify, request approval when needed, execute, audit, return result.
-- `server-registry`
-  - Stores encrypted server definitions and authentication material.
-- `ssh-runtime`
-  - Owns connection lifecycle, command execution, file transfer, and remote patch/write operations.
-- `policy-engine`
-  - Classifies tool actions into auto-allow, approval-required, or reject.
-- `audit-engine`
-  - Writes structured action logs and manages local git-backed snapshots for file changes.
-
-### Design Rule
-
-All host tools must call the `tool-orchestrator`. No tool may bypass policy or audit directly. This keeps behavior consistent across commands and file tools and prevents policy drift as more adapters are added later.
-
-## Tool Surface
-
-The v1 tool set is explicit and server-targeted:
-
-- `list_servers()`
-- `remote_exec(server, command, cwd?, timeout?)`
-- `remote_read_file(server, path, offset?, length?)`
-- `remote_write_file(server, path, content, mode?)`
-- `remote_patch_file(server, path, diff_or_patch)`
-- `remote_list_dir(server, path, recursive?, limit?)`
-- `remote_stat(server, path)`
-- `remote_find(server, path, pattern, glob?, limit?)`
-
-### Tool Surface Principles
-
-- Every operation names a `server` explicitly.
-- The default behavior must favor clarity over convenience.
-- Session-local implicit "current server" behavior is out of scope for v1.
-- Dedicated file tools are preferred for file inspection and file mutation.
-- `remote_exec` remains available for shell-oriented work that does not map cleanly to a dedicated file tool.
-
-## Data Flow
-
-For every tool invocation, the runtime sequence is:
-
-1. The `opencode` adapter receives the tool call.
-2. `tool-orchestrator` validates arguments and resolves the target server via `server-registry`.
-3. `policy-engine` classifies the action.
-4. If the action requires approval, the adapter presents the exact server, path, and command or write intent to the user.
-5. `ssh-runtime` executes the command or file action.
-6. `audit-engine` records the action and, when relevant, creates local snapshots.
-7. A structured result is returned to the adapter and then back to `opencode`.
-
-## Security And Permissions
-
-### Permission Classes
-
-V1 uses three policy outcomes:
-
-- `auto-allow`
-- `approval-required`
-- `reject`
-
-### Auto-Allow
-
-The following operations may run directly:
-
-- dedicated read-focused file tools such as `remote_read_file`, `remote_list_dir`, `remote_stat`, and `remote_find`,
-- clearly safe Linux inspection commands executed through `remote_exec`.
-
-Examples of Linux inspection commands include:
-
-- `cat`
-- `grep`
-- `find`
-- `ls`
-- `pwd`
-- `uname`
-- `df`
-- `free`
-- `ps`
-- `systemctl status`
-
-The exact allowlist belongs in implementation, but the design intent is a conservative rule-based allowlist.
-
-### Approval-Required
-
-The following actions must require explicit user approval for each execution:
-
-- every file mutation,
-- every shell command that may mutate remote state,
-- every middleware-oriented command family even when the specific invocation appears read-only.
-
-Examples of middleware-oriented command families include:
-
-- `psql`
-- `mysql`
-- `redis-cli`
-- `kubectl`
-- `docker`
-- `helm`
-- cloud provider CLIs
-
-Unknown commands must default to `approval-required`.
-
-### Reject
-
-The runtime may reject requests that are malformed or unsupported, such as:
-
-- unknown server ids,
-- invalid file paths or missing required arguments,
-- unsupported patch formats,
-- actions that violate hard safety rules defined by the implementation.
-
-### Classification Strategy
-
-Policy classification must be deterministic and rule-based. V1 must not rely on a model to decide whether a command is safe. The model may propose commands, but the core decides whether they run directly, require approval, or are rejected.
-
-For `remote_exec`, the auto-allow path is intentionally narrow. Only simple invocations of allowlisted Linux inspection commands may bypass approval. Commands that include shell composition or higher-risk syntax must default to `approval-required`, including:
-
-- pipes,
-- redirection,
-- command chaining,
-- subshells,
-- compound shell expressions,
-- other command forms that require shell parsing beyond a single straightforward invocation.
-
-## Credential Model
-
-### Storage
-
-Open Code manages its own encrypted local server registry.
-
-Each server record stores:
-
-- server id,
-- host,
-- port,
-- username,
-- labels or grouping metadata,
-- authentication method,
-- authentication material,
-- optional non-secret metadata.
-
-Supported v1 authentication methods:
-
-- username plus password,
-- imported private key or certificate material.
-
-The registry encryption key should be protected by a client-controlled unlock mechanism such as an OS keychain entry or an equivalent local secret source selected during implementation. The design requirement is that registry decryption stays on the client machine and is independent of the model runtime.
-
-### Isolation Requirements
-
-- Credentials must not be stored in model-visible prompt files.
-- Raw credentials must never be returned by tools.
-- Tool calls reference servers by logical id, not by raw secret material.
-- Decryption and secret handling stay inside the core.
-
-## Multi-Server Model
-
-Multi-server support is a first-class requirement.
-
-Design implications:
-
-- every tool call requires an explicit server target,
-- the registry supports many named servers,
-- the SSH runtime may reuse connections per server during a session,
-- audit artifacts must be partitioned by server so changes remain attributable.
-
-Grouping, tags, or labels may be stored in the registry for future filtering, but group-based orchestration is not required in v1.
-
-## Audit Model
-
-Audit artifacts are stored on the client machine where `opencode` runs, not on the remote server.
-
-### Structured Action Log
-
-Every tool action writes a structured local log entry that includes:
-
-- timestamp,
-- server id,
-- tool name,
-- sanitized arguments,
-- approval status,
-- execution result metadata,
-- changed path metadata when available.
-
-Sensitive values must be redacted before persistence.
-
-Action logging is a hard requirement, not a best-effort feature. Before any remote operation runs, the runtime must verify that the action log sink is writable. If structured logging cannot be persisted, the tool call must fail closed and the remote action must not execute.
-
-### Git-Backed File Snapshot Audit
-
-Dedicated file mutation tools participate in local git-backed snapshotting.
-
-For `remote_write_file` and `remote_patch_file`, the audit flow is:
-
-1. capture the pre-change remote file content if the file exists,
-2. perform the write or patch,
-3. capture the post-change remote file content,
-4. store snapshots locally under an audit directory organized by server and remote path,
-5. commit the snapshot change into a local git repository.
-
-This repository exists only on the client machine and is used for inspection, history, and rollback support.
-
-For dedicated file mutation tools, snapshotting is also a hard requirement. Before a mutating file action executes, the runtime must verify that the snapshot workspace and local git repository are writable. If pre-change snapshot preparation cannot succeed, the write must not run.
-
-If the remote write succeeds but post-change snapshot persistence or git commit creation fails, the tool result must be returned as a partial failure rather than a clean success. The result must make clear that the remote state changed but audit completion failed, so the user can treat the operation as security-relevant follow-up work.
-
-### Limit Of Audit Guarantees
-
-`remote_exec` always creates structured command audit logs, but v1 does not promise file-level snapshots for arbitrary shell side effects. If a user wants file-level diffs and recovery guarantees, they should prefer dedicated file mutation tools.
-
-## Error Handling
-
-The system must return structured failures rather than flattening all problems into a generic error string.
-
-Important error classes:
-
-- server resolution failure,
-- credential decrypt or load failure,
-- SSH connection failure,
-- authentication failure,
-- timeout,
-- policy rejection,
-- approval denial,
-- remote file-not-found,
-- remote permission denied,
-- non-zero command exit,
-- patch apply failure,
-- local audit persistence failure,
-- local git snapshot failure.
-
-Tool results should distinguish:
-
-- whether the action was attempted,
-- whether it completed,
-- command exit status when applicable,
-- stdout and stderr payloads or truncation metadata,
-- audit/logging status when relevant.
-
-## Testing Strategy
-
-### Unit Tests
-
-- `policy-engine` command classification
-- argument validation and path validation
-- secret redaction
-- snapshot path mapping
-- `tool-orchestrator` sequencing logic
-
-### Integration Tests
-
-- encrypted registry load and server resolution
-- SSH connection against disposable local test targets
-- read-only command execution
-- approval-required command flow
-- dedicated file read and write flows
-- multi-server session isolation
-
-### Audit Tests
-
-- structured log persistence
-- pre-change and post-change snapshot capture
-- git commit creation for dedicated file writes
-- server-specific audit partitioning
-
-### Adapter Contract Tests
-
-- tool registration shape for `opencode`
-- argument-to-core mapping
-- structured result mapping back to the host runtime
-
-## Out Of Scope For V1
-
-- session-wide approval grants
-- group fan-out execution across multiple servers in one tool call
-- background daemon deployment model
-- remote git integration
-- full TUI management experience for registry and audit browsing
-- automatic command correction or command suggestion
-- support for non-SSH transports
-
-## Implementation Constraints For Planning
-
-- The architecture must preserve a strict boundary between the `opencode` adapter and the host-agnostic core.
-- The initial implementation should optimize for clear module ownership and extension over completeness of the tool catalog.
-- Policy logic must be centralized and deterministic.
-- File-change audit guarantees should attach only to dedicated file mutation tools in v1.
-- The plan should assume future host adapters are likely, even though only `opencode` is in scope now.
-
-## Success Criteria
-
-The design is successful for v1 when all of the following are true:
-
-- A user can register multiple remote servers locally with encrypted credentials.
-- `opencode` can invoke explicit remote tools against any registered server.
-- Clearly safe Linux inspection commands can run without approval.
-- Every write requires explicit approval.
-- Middleware-oriented commands require explicit approval even when nominally read-only.
-- Dedicated remote file writes create local git-backed before/after audit history.
-- Every tool action creates a structured local audit log.
-- The implementation plan can be written without reopening architecture or scope decisions.

package/docs/superpowers/specs/2026-03-26-config-backed-credential-registry-design.md

@@ -1,272 +0,0 @@
-# Config-Backed Credential Registry Design
-
-Date: 2026-03-26
-Branch: `registry-cli`
-Status: Approved for planning
-
-## Summary
-
-Replace the current encrypted registry plus OS keychain dependency with a simpler layered config model:
-
-- Read server definitions from two config files: user-global first, then workspace override.
-- Let workspace entries override global entries with the same `id`.
-- Store password auth in plain text, documented as unsafe.
-- Store certificate and private-key auth as filesystem paths only.
-- Remove reliance on macOS Keychain, `keytar`, or any other OS credential store.
-
-This change optimizes for operational simplicity and predictable cross-platform behavior over secret-at-rest protection.
-
-## Goals
-
-- Eliminate the current OS keychain dependency.
-- Keep the credential model easy to inspect and edit manually.
-- Support repo-local and user-global server definitions.
-- Never store PEM or private-key contents in plugin-managed config.
-- Preserve the current explicit remote-tool model and SSH runtime shape.
-
-## Non-Goals
-
-- Secret management or secure password storage.
-- Automatic migration from the current encrypted registry.
-- Environment-variable interpolation in v1 of this config-backed model.
-- Support for more than two config scopes.
-
-## Current Problem
-
-The current branch stores the registry payload encrypted at rest and uses a `SecretProvider` backed by `keytar` to read or create a master key in the OS credential store. That behavior is acceptable on macOS but creates avoidable complexity, prompts, and portability concerns.
-
-The user preference is to simplify:
-
-- Plain-text passwords are acceptable if clearly documented as unsafe.
-- Key and certificate auth should reference files already managed by the user.
-- The plugin should not attempt to manage or protect key material itself.
-
-## Proposed Design
-
-### Config Scopes
-
-Two config scopes will be supported:
-
-1. Workspace config
-2. User-global config
-
-Read order:
-
-1. Read the user-global config if present.
-2. Read the workspace config if present.
-3. Merge entries by `id`.
-4. When both scopes define the same `id`, the workspace entry wins.
-
-When a workspace entry overrides a global entry, CLI output should make that explicit so users understand which effective server is active.
-
-### File Locations
-
-Global config should live under the existing user config directory resolved by `env-paths`, for example:
-
-- macOS: `~/Library/Preferences/open-code/servers.json`
-- Linux: `~/.config/open-code/servers.json`
-- Windows: `%AppData%/open-code/servers.json`
-
-Workspace config should live in the repo/workspace root:
-
-- `<workspace>/.open-code/servers.json`
-
-The runtime should treat the presence of a workspace file as opt-in local override behavior.
-
-### Data Model
-
-The config file should remain intentionally small and explicit. Each file is a top-level JSON array of server records:
-
-```json
-[
-  {
-    "id": "prod-a",
-    "host": "10.0.0.5",
-    "port": 22,
-    "username": "ubuntu",
-    "labels": ["prod"],
-    "groups": ["cluster-a"],
-    "auth": {
-      "kind": "privateKey",
-      "privateKeyPath": "./keys/prod-a.pem"
-    }
-  }
-]
-```
-
-Supported auth shapes:
-
-- `password`
-  - fields: `kind`, `secret`
-- `privateKey`
-  - fields: `kind`, `privateKeyPath`, optional `passphrase`
-- `certificate`
-  - fields: `kind`, `certificatePath`, `privateKeyPath`, optional `passphrase`
-
-Notes:
-
-- `password.secret` is stored in plain text.
-- `privateKey` and `certificate` entries store paths only.
-- No PEM, private key, or certificate contents are copied into config.
-
-### Path Rules
-
-Workspace config:
-
-- may use relative key/cert paths
-- relative paths resolve from workspace root
-
-Global config:
-
-- key/cert paths must be absolute
-- relative paths in global config should be rejected as invalid
-
-At runtime, the effective server record should be normalized before SSH use:
-
-1. determine effective scope for the selected record
-2. resolve relative workspace paths
-3. validate that referenced files exist and are readable
-4. pass normalized auth inputs to the SSH runtime
-
-### Registry Backend Changes
-
-The current encrypted registry backend should be replaced with a config-backed registry implementation.
-
-That means:
-
-- remove the `SecretProvider` dependency from the active registry path
-- stop encrypting the server registry payload
-- stop calling `keytar`
-
-The registry abstraction can remain, but it should now operate on layered config files rather than an encrypted blob.
-
-Recommended interfaces:
-
-- `list()`: return effective records with scope metadata
-- `resolve(id)`: return effective record with scope metadata
-- `upsert(scope, record)`: write to the chosen scope
-- `remove(scope, id)`: remove from the chosen scope
-- `listRaw(scope)`: read one scope without merge logic when the CLI needs direct scope inspection
-
-## CLI Design
-
-The existing CLI entrypoint should remain:
-
-- `bun run server-registry add`
-- `bun run server-registry list`
-- `bun run server-registry remove`
-
-### Add
-
-Prompt sequence:
-
-1. choose target scope
-2. enter server identity fields
-3. choose auth kind
-4. prompt for auth-specific fields
-5. warn if storing a plain-text password
-
-Default scope behavior:
-
-- if workspace config exists, default to workspace
-- otherwise default to global
-
-If adding a workspace entry whose `id` already exists in global config:
-
-- print that the workspace entry will override the global entry
-
-### List
-
-Listing should show effective records and source scope, for example:
-
-- `workspace`
-- `global`
-
-If an entry is overridden, the effective list should show the workspace record and should indicate that it shadows a global record when relevant.
-
-### Remove
-
-Removal must be scope-aware.
-
-If the same `id` exists in both scopes:
-
-- prompt which scope to remove from
-- never remove both implicitly
-
-This keeps layered config behavior explicit and avoids destructive surprises.
-
-## Runtime Flow
-
-For remote tool execution:
-
-1. resolve the requested server `id` from the layered config registry
-2. determine whether the effective record came from workspace or global scope
-3. normalize auth paths if needed
-4. validate file existence and readability for path-based auth
-5. construct SSH auth options
-6. continue through the existing orchestrator, policy, SSH, and audit flow
-
-This keeps policy, SSH execution, and auditing unchanged while simplifying only the credential-storage layer.
-
-## Errors And Diagnostics
-
-The new registry path should return structured errors for:
-
-- missing config file when a write target is expected
-- malformed JSON
-- invalid schema
-- duplicate or conflicting records within one file if validation disallows them
-- relative key/cert path in global config
-- missing key/cert file
-- unreadable key/cert file
-- missing required auth fields
-
-Helpful CLI messaging matters here because users are now directly editing config.
-
-## Migration
-
-No automatic migration in this pass.
-
-If the old encrypted registry exists, the new config-backed flow should ignore it. Documentation should state that the credential backend changed and that users need to define servers in config files going forward.
-
-This avoids partial migration logic and keeps the new behavior obvious.
-
-## Testing
-
-Required test coverage:
-
-- parse and load a global-only config
-- parse and load a workspace-only config
-- workspace overrides global by `id`
-- workspace relative path resolution works
-- global relative path rejection works
-- path validation failures are surfaced cleanly
-- password auth records round-trip correctly through the config registry
-- `add` chooses the expected default scope
-- `add` warns when workspace overrides global
-- `list` reports source scope
-- `remove` prompts for scope when both scopes contain the same `id`
-
-Integration smoke coverage should continue to validate:
-
-- `list_servers`
-- safe `remote_exec`
-- `remote_write_file` approval behavior
-
-with at least one real SSH target, including the disposable Docker SSH path already used for manual smoke testing.
-
-## Risks
-
-- Plain-text passwords are intentionally weaker than the current encrypted model.
-- Users may accidentally commit workspace config files if ignore rules are not clear.
-- File path auth depends on the target machine having stable path layout and permissions.
-
-These are acceptable tradeoffs for the requested simplicity, but they must be documented directly.
-
-## Implementation Note
-
-Task 4 removed `keytar` from package metadata and synchronized the README with the config-backed registry model. The runtime design above remains unchanged.
-
-## Recommendation
-
-Implement this as a clean replacement of the current encrypted/keychain-backed registry path. Do not keep both systems active in parallel. The simpler model is easier to understand, easier to operate, and more likely to behave consistently across macOS, Linux, and Windows.