npm - @work-bridge/work-bridge - Versions diffs - 0.1.3 → 0.1.5 - Mend

@work-bridge/work-bridge 0.1.3 → 0.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2) hide show

package/README.md +146 -256
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -1,9 +1,16 @@
 # work-bridge
-> **Switching between Claude Code, Gemini CLI, OpenCode, and Codex due to LLM cost?**
-> Bring your session context, MCP configs, and skills with you — instantly.
+> **Switching between Claude Code, Gemini CLI, OpenCode, and Codex on the same project because of model cost or context limits?**
+> Inspect the source session, then either apply a target-ready handoff directly into the project or export the same handoff into a separate output tree.
-`work-bridge` is a local-first portability layer for AI coding-agent workflows. It inspects your current sessions, skills, and MCP server configs across all major tools, then exports a portable bundle that any other tool can pick up from where you left off.
+`work-bridge` is a local-first handoff tool for AI coding-agent workflows. It reads a source session, normalizes the useful project context, and either:
+- applies a target-ready state into project-native files
+- exports the same target-ready state to a separate directory
+It does **not** write into another tool's home-level session database.
+> **Stability:** `work-bridge` is still early and not fully stable. Project-native apply and export paths are covered by tests, but some migration paths are still under active refinement. Use `--dry-run` first when trying a new source/target pair.
 [![Go Version](https://img.shields.io/badge/Go-1.21+-00ADD8?style=flat&logo=go)](https://golang.org)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -13,346 +20,229 @@
 ## Why work-bridge?
-Modern AI coding agents store their state in incompatible formats:
+Most coding-agent tools keep valuable context in incompatible formats. `work-bridge` keeps the useful project-facing parts portable:
+| Preserved across tools | Notes |
+|------------------------|-------|
+| Task title and current goal | Normalized from the source session |
+| Session summary and decisions | Added to the target-ready handoff |
+| Project instruction context | Applied into `CLAUDE.md`, `GEMINI.md`, or `AGENTS.md` |
+| Project-scoped skills | Materialized into `.work-bridge/<target>/skills/` |
+| Effective MCP config | Materialized into `.work-bridge/<target>/mcp.json` and patched into supported target project config files |
+| Portable settings context | Source secrets remain redacted |
-| What you lose when switching tools | What work-bridge preserves |
-|------------------------------------|---------------------------|
-| Current task title & goal          | ✅ Task title & current goal |
-| Session summary & decisions        | ✅ Summary, decisions, failures |
-| Project instruction files (AGENTS.md, CLAUDE.md, GEMINI.md…) | ✅ All instruction artifacts |
-| MCP server configurations          | ✅ Inspected & validated MCP configs |
-| Portable settings (non-sensitive)  | ✅ Settings snapshot (secrets stripped) |
-| Touched files & tool events        | ✅ File touch history & event log |
+The current design is intentionally simpler than the older import/export pipeline:
+- `inspect` shows what can be handed off
+- `switch` previews and applies directly into the project
+- `export` writes the same target-ready state into a separate directory
 ---
 ## Supported Tools
-| Tool | Import | Export | MCP | Skills |
-|------|:------:|:------:|:---:|:------:|
-| **Claude Code** | ✅ | ✅ | ✅ | ✅ |
-| **Gemini CLI** | ✅ | ✅ | ✅ | ✅ |
-| **OpenCode** | ✅ | ✅ | ✅ | ✅ |
-| **Codex CLI** | ✅ | ✅ | ✅ | ✅ |
+| Tool | Inspect source sessions | Apply to project files | Export target-ready tree |
+|------|:-----------------------:|:----------------------:|:------------------------:|
+| **Claude Code** | ✅ | ✅ | ✅ |
+| **Gemini CLI** | ✅ | ✅ | ✅ |
+| **OpenCode** | ✅ | ✅ | ✅ |
+| **Codex CLI** | ✅ | ✅ | ✅ |
+Project-native apply means files inside the project root only. `work-bridge` does **not** recreate native session state in `~/.codex`, `~/.gemini`, `~/.claude`, or `~/.config/opencode`.
 ---
-## Quick Start
+## Install
-### Install via npm (recommended)
+### npm
 ```bash
 npm install -g @work-bridge/work-bridge
-work-bridge
 ```
-### Install via Go
+### Go
 ```bash
 go install github.com/jaeyoung0509/work-bridge/cmd/work-bridge@latest
 ```
-### Download binary
+### Binary
-Grab the latest release binary from [GitHub Releases](https://github.com/jaeyoung0509/work-bridge/releases).
+Download the latest release from [GitHub Releases](https://github.com/jaeyoung0509/work-bridge/releases).
 ---
-## Usage
-### TUI (Interactive Mode)
+## Quick Start
-Just run `work-bridge` in your terminal for the full interactive experience:
+### 1. Inspect available source sessions
 ```bash
-work-bridge
+work-bridge inspect gemini --limit 5
 ```
-The TUI provides five panels:
-| Panel | What it does |
-|-------|-------------|
-| **Sessions** | Browse, inspect, import, doctor-check, and export sessions |
-| **Projects** | Index project roots from configured workspace roots |
-| **Skills** | Compare project/user/global skill coverage and sync across scopes |
-| **MCP** | Inspect config locations, merge effective scope, and run runtime validation |
-| **Logs** | View recent workspace actions and errors |
-**Mouse support:** pane focus · list selection · preview tab switching · scroll
-### Migration Workflow
-```
-You were using Claude Code → now switching to Gemini CLI
-```
+### 2. Preview a handoff into another tool
 ```bash
-# 1. Inspect what Claude Code has
-work-bridge inspect claude --limit 5
-# 2. Import the latest session into a portable bundle
-work-bridge import --from claude --session latest --out ./bundle.json
-# 3. Check compatibility with the target tool
-work-bridge doctor --from claude --session latest --target gemini
-# 4. Export target-native artifacts
-work-bridge export --bundle ./bundle.json --target gemini --out ./out/
-# 5. Start Gemini CLI — it'll pick up GEMINI.work-bridge.md automatically
-cd ./out && gemini
+work-bridge switch \
+  --from gemini \
+  --session latest \
+  --to claude \
+  --project /path/to/repo \
+  --dry-run
 ```
-The exported `./out/` directory contains:
-- `GEMINI.work-bridge.md` — context supplement injected into Gemini CLI
-- `SETTINGS_PATCH.json` — portable settings to apply
-- `STARTER_PROMPT.md` — copy-paste prompt to resume your task
-- `manifest.json` — export manifest with portability warnings
-### Pack / Unpack (Portable Archives)
-Share your session state across machines or teammates:
+### 3. Apply the handoff into the project
 ```bash
-# Pack a session into a portable .spkg archive
-work-bridge pack --from claude --session latest --out ./my-session.spkg
-# Unpack on another machine and target a different tool
-work-bridge unpack --file ./my-session.spkg --target codex --out ./out/
+work-bridge switch \
+  --from gemini \
+  --session latest \
+  --to claude \
+  --project /path/to/repo
 ```
-### Detect
+### 4. Or export the same target-ready tree without touching the project
 ```bash
-# Auto-detect all installed tools and project artifacts
-work-bridge detect
-```
-### CLI Reference
-```
-work-bridge [flags]
-work-bridge detect
-work-bridge inspect <tool> [--limit N]
-work-bridge import  --from <tool> [--session <id|latest>] [--out <path>]
-work-bridge doctor  --from <tool> [--session <id|latest>] --target <tool>
-work-bridge export  --bundle <path> --target <tool> [--out <dir>]
-work-bridge pack    --from <tool> [--session <id|latest>] --out <path>
-work-bridge unpack  --file <path> --target <tool> [--out <dir>]
-work-bridge version
+work-bridge export \
+  --from gemini \
+  --session latest \
+  --to claude \
+  --project /path/to/repo \
+  --out /tmp/claude-handoff
 ```
-**Supported tools:** `claude` · `gemini` · `codex` · `opencode`
 ---
-## How It Works
+## What `switch` Applies
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                         work-bridge                             │
-│                                                                 │
-│  detect/ ──► inspect/ ──► importer/ ──► domain.SessionBundle   │
-│                                              │                  │
-│                                         doctor/                 │
-│                                    (compatibility check)        │
-│                                              │                  │
-│                                         exporter/               │
-│                                    (target-native artifacts)    │
-└─────────────────────────────────────────────────────────────────┘
-SessionBundle fields:
-  source_tool        · source_session_id  · project_root
-  task_title         · current_goal       · summary
-  instruction_artifacts (AGENTS.md, CLAUDE.md, GEMINI.md …)
-  settings_snapshot  (sensitive keys redacted automatically)
-  tool_events        · touched_files
-  decisions          · failures           · resume_hints
-  token_stats        · provenance         · redactions
-```
+`switch` writes a managed target state into the project.
-### Security & Redaction
+Managed session output:
-`work-bridge` automatically strips sensitive values during import:
+- Claude: `CLAUDE.md` + `.work-bridge/claude/*`
+- Gemini: `GEMINI.md` + `.work-bridge/gemini/*`
+- Codex: `AGENTS.md` + `.work-bridge/codex/*`
+- OpenCode: `AGENTS.md` + `.work-bridge/opencode/*`
-- Key-based: `secret`, `token`, `password`, `auth`, `oauth`, `credential`, `api_key`, `apikey`
-- Value-based heuristics: `sk-*`, `ghp_*`, `github_pat_*`, `AIza*` prefixes, and long random-looking strings
-- Redacted fields are listed in `bundle.redactions` for transparency — nothing is silently dropped
+Managed skills output:
----
+- `.work-bridge/<target>/skills/*.md`
+- `.work-bridge/<target>/skills/index.json`
-## MCP Validation
+Managed MCP output:
-The **MCP** panel (and `inspect` output) runs a real runtime handshake for supported transports:
+- `.work-bridge/<target>/mcp.json`
+- plus target project config patch where supported:
+  - Claude: `.claude/settings.local.json`
+  - Gemini: `.gemini/settings.json`
+  - OpenCode: `.opencode/opencode.jsonc`
+  - Codex: no separate project config patch
-1. Spawns the server process (stdio) or connects (HTTP / SSE)
-2. Sends `initialize` → waits for capability response
-3. Sends `notifications/initialized`
-4. Counts advertised `resources`, `resourceTemplates`, `tools`, and `prompts`
+Instruction files are updated through a managed block:
-This catches config problems that a static lint pass would miss.
+```md
+<!-- work-bridge:start -->
+...
+<!-- work-bridge:end -->
+```
----
+Re-running `switch` replaces that block instead of appending duplicate content.
-## Configuration
+---
-Configuration is resolved in this priority order:
+## What `export` Writes
-1. CLI flags
-2. Environment variables (`WORK_BRIDGE_` prefix)
-3. `--config <file>`
-4. Auto-discovered config in CWD → then home directory
-5. Built-in defaults
+`export` writes the same target-ready structure into a separate output root instead of modifying the source project.
-### Supported Config Files
+Example output for `--to claude --out /tmp/claude-handoff`:
-- `.work-bridge.yaml` / `.work-bridge.yml`
-- `.work-bridge.toml`
-- `.work-bridge.json`
+- `/tmp/claude-handoff/CLAUDE.md`
+- `/tmp/claude-handoff/.claude/settings.local.json`
+- `/tmp/claude-handoff/.work-bridge/claude/manifest.json`
+- `/tmp/claude-handoff/.work-bridge/claude/mcp.json`
+- `/tmp/claude-handoff/.work-bridge/claude/skills/index.json`
-### Key Config Fields
+This is useful when you want a reviewable, portable handoff tree before applying anything to a live repo.
-```yaml
-# .work-bridge.yaml
-workspace_roots:
-  - ~/Projects
-  - ~/work
+---
-paths:
-  codex:     ~/.local/share/codex
-  gemini:    ~/.config/gemini
-  claude:    ~/.claude
-  opencode:  ~/.config/opencode
+## TUI
-output:
-  export_dir:   ./out/work-bridge
-  package_path: ./session.spkg
-  unpack_dir:   ./out/unpacked
+Run `work-bridge` without arguments to open the interactive migration console:
-redaction:
-  detect_sensitive_values: true
-  additional_sensitive_keys:
-    - my_internal_token
+```bash
+work-bridge
 ```
-### JSON Example
-```json
-{
-  "format": "json",
-  "workspace_roots": ["~/Projects", "~/work"],
-  "paths": {
-    "codex": "/Users/me/.local/share/codex"
-  },
-  "output": {
-    "export_dir": "./out/work-bridge"
-  }
-}
-```
+The TUI is now focused on one workflow:
-### Environment Variables
+- choose a source session from the current project
+- choose a target tool
+- preview the handoff
+- apply or export
-| Variable | Config Key |
-|----------|-----------|
-| `WORK_BRIDGE_FORMAT` | `format` |
-| `WORK_BRIDGE_WORKSPACE_ROOTS` | `workspace_roots` |
-| `WORK_BRIDGE_PATHS_CODEX` | `paths.codex` |
-| `WORK_BRIDGE_PATHS_GEMINI` | `paths.gemini` |
-| `WORK_BRIDGE_PATHS_CLAUDE` | `paths.claude` |
-| `WORK_BRIDGE_PATHS_OPENCODE` | `paths.opencode` |
-| `WORK_BRIDGE_OUTPUT_EXPORT_DIR` | `output.export_dir` |
+Key actions:
----
+- `Enter` preview
+- `a` apply into the project
+- `e` export into `.work-bridge/exports/<target>/`
+- `r` refresh
+- `?` help
+- `q` quit
-## Repository Layout
+User-facing statuses are simplified:
-```
-cmd/work-bridge/          CLI entrypoint (main.go)
-internal/
-  cli/                    Cobra/Viper root command, TUI backend wiring
-    app.go                App struct, Run(), Config
-    root_tui.go           TUI launch logic and Backend wiring
-    legacy_commands.go    detect/inspect/import/doctor/export commands
-    package_commands.go   pack/unpack commands
-    root_tui_backend.go   All TUI backend action implementations
-  tui/                    Bubble Tea v2 interactive workspace
-  domain/                 Portable bundle types (SessionBundle, Tool, …)
-  importer/               Tool-specific session importers
-    claude.go / codex.go / gemini.go / opencode.go
-    normalizer.go         Signal extraction & normalization
-    signals.go            Decision/failure/hint signal detection
-  exporter/               Target-native artifact generation
-  detect/                 Tool installation & project artifact detection
-  inspect/                Session listing for each tool
-  doctor/                 Cross-tool compatibility analysis
-  catalog/                Skills catalog (project/user/global scopes)
-  capability/             MCP capability registry
-  packagex/               .spkg pack/unpack (zip-based)
-  platform/               FS, clock, archive, env, redact utilities
-testdata/                 Fixtures and golden outputs
-scripts/
-  install.cjs             npm postinstall binary downloader
-```
+- `READY`
+- `APPLIED`
+- `PARTIAL`
+- `ERROR`
 ---
-## Building from Source
-```bash
-git clone https://github.com/jaeyoung0509/work-bridge.git
-cd work-bridge
-# Build
-make build
-./bin/work-bridge
+## CLI Reference
-# Test
-make test
-# Lint
-make lint
-# Format
-make fmt
+```text
+work-bridge [flags]
+work-bridge inspect <tool> [--limit N]
+work-bridge switch --from <tool> --session <id|latest> --to <tool> --project <path> [--dry-run] [--no-skills] [--no-mcp] [--session-only]
+work-bridge export --from <tool> --session <id|latest> --to <tool> --project <path> --out <dir> [--dry-run] [--no-skills] [--no-mcp] [--session-only]
+work-bridge version
 ```
-**Requirements:** Go 1.21+
+Supported tools:
+- `claude`
+- `gemini`
+- `codex`
+- `opencode`
 ---
-## Publishing a Release
+## Limits
-Releases use [GoReleaser](https://goreleaser.com/). A GitHub Actions workflow triggers on version tags:
+Current non-goals in this slice:
-```bash
-git tag v0.1.0
-git push origin v0.1.0
-```
+- no home-level session-store injection
+- no recreation of a target tool's private resume database
+- no promise that every source-specific tool event becomes meaningful in every target
-GoReleaser builds cross-platform binaries (`darwin/amd64`, `darwin/arm64`, `linux/amd64`, `linux/arm64`, `windows/amd64`, `windows/arm64`) and uploads them as `.tar.gz` / `.zip` archives to the GitHub Release.
+Current behavior to be aware of:
-The npm package wrapper then downloads the correct binary at install time via `scripts/install.cjs`.
+- `switch` is project-native apply, not native session resurrection
+- `export` is out-of-project handoff generation, not a bundle archive format
+- `--session-only` disables skills and MCP materialization
+- `--dry-run` is the safest first step for new tool pairs
 ---
-## Contributing
+## Security and Redaction
-See [CONTRIBUTING.md](./CONTRIBUTING.md).
+Sensitive values are stripped during source import before a handoff is built.
-**Good first areas:**
-- Add a new tool importer under `internal/importer/`
-- Extend `internal/exporter/` with a new target format
-- Improve MCP runtime validation for new transport types
-- Add fixture-backed tests for edge cases
-Principles:
-- Local-first, no network calls during normal operation
-- Deterministic output for fixture-backed tests
-- Sensitive data must never leave the machine unredacted
----
+Examples include:
-## License
+- keys containing `secret`, `token`, `password`, `auth`, `credential`, `api_key`
+- values matching common token-like patterns such as `sk-*`, `ghp_*`, `github_pat_*`, `AIza*`
-MIT © [jaeyoung0509](https://github.com/jaeyoung0509)
+Redactions stay visible as warnings in the normalized handoff so you can see what was intentionally omitted.

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@work-bridge/work-bridge",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Portable session migration CLI for Claude Code, Gemini CLI, OpenCode, and Codex CLI.",
   "homepage": "https://github.com/jaeyoung0509/work-bridge",
   "repository": {