# screenctx

`screenctx` collects the local files that explain **one Spring Boot + MyBatis screen** so you can hand a compact, structured context bundle to an AI tool (ChatGPT, Claude, Copilot, …) or read it yourself before making a change.

Given a single entry point — a route, a controller/Action class, a method, or a file — it walks the dependency graph (controller → business logic → DAO/Mapper → MyBatis XML, plus views, static assets, message properties, and config) and produces one Markdown file plus a copyable bundle.

It does **static analysis only**. No Maven/Gradle build, no Spring startup, no network. It favors recall over perfect precision, so related framework/base files may be included when they clarify the screen flow. References it cannot resolve statically (reflection, string-built bean names, runtime-only SQL ids) are reported under `unresolved`.

It collects, with reasons, things like:

- Spring Boot controllers or legacy-style `Action` classes
- JSP / Thymeleaf / template views and static assets
- `FormBean`, input/output beans, DTOs, constants, validators, helpers
- `BLogic` / `BaseLogic` / `Service` classes
- Mapper/DAO interfaces and MyBatis/iBATIS SQLMap XML
- message/error `.properties`
- `application.yml`, `application.properties`, `mybatis-config.xml`

---

## Requirements

- Python 3.10+
- No runtime dependencies for the CLI (the standard library only)
- Optional `mcp` package only if you use the MCP server

---

## Install

### macOS / Linux

```bash
git clone https://github.com/<your-account>/screenctx.git
cd screenctx
python3 -m venv .venv && source .venv/bin/activate
python3 -m pip install -e .
```

### Windows

PowerShell:

```powershell
git clone https://github.com/<your-account>/screenctx.git
cd screenctx
py -m venv .venv
.\.venv\Scripts\Activate.ps1
py -m pip install -e .
```

> If `Activate.ps1` is blocked, run once in the same PowerShell window:
> `Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass`

Command Prompt (cmd.exe):

```bat
git clone https://github.com/<your-account>/screenctx.git
cd screenctx
py -m venv .venv
.venv\Scripts\activate.bat
py -m pip install -e .
```

After installing, the `screenctx` command is on your PATH. You can always run it without installing too:

```bash
python3 -m screenctx.cli --help     # macOS/Linux
py -m screenctx.cli --help          # Windows
```

To also use the MCP server, install the extra:

```bash
python3 -m pip install -e ".[mcp]"   # macOS/Linux
py -m pip install -e ".[mcp]"        # Windows
```

---

## Collect one screen

```bash
screenctx collect \
  --root /path/to/spring-project \
  --entry /customer/detail \
  --out ./ctx \
  --force
```

Windows:

```powershell
screenctx collect --root C:\path\to\spring-project --entry /customer/detail --out .\ctx --force
```

### What `--entry` accepts

`--entry` is **repeatable** and is resolved in this order (the first form that matches wins):

| Form | Example | Notes |
|------|---------|-------|
| **File path** (absolute or relative to `--root`) | `src/main/webapp/WEB-INF/jsp/demo100/list.jsp` | Any file: `.jsp` / `.html` / `.java` / `.xml` / `.properties`. Use this to target a screen by its template file. |
| **Java class** (simple name or fully-qualified) | `CustomerAction`, `example.action.CustomerAction` | Any existing class — controller, `Action`, `BLogic`, `Service`, `Dao`/`Mapper`, … Use the name **without** a `.java` suffix. |
| **Class method** | `CustomerDao#selectByCustomerId`, `Demo100_02SearchAction#search` | Focuses on that method and its call chain. |
| **Route** | `/customer/detail`, `/Demo100_list` | Supports `{id}` path variables and `*` wildcards. |

Notes:

- **Traversal is downstream-only.** Starting from a **controller class or a route** gives the fullest screen context (it follows `return "view"` down to the JSP/Thymeleaf and the full BLogic → DAO → XML chain). Starting from a `BLogic`/`DAO` only collects what is downstream of it — it does **not** find its callers.
- There is no "bare view name" lookup: `--entry detail` will **not** resolve to a template. Use the screen's **route** (`/customer/detail`) or its **file path** instead.
- A simple class name matches **every** class with that name across the project; use the fully-qualified name to disambiguate.

### Useful options

```bash
screenctx collect --root /path/to/project --entry /Demo100_list --out ./ctx --depth 4
screenctx collect --root /path/to/project --entry Demo100_02SearchAction#search --out ./ctx --no-copy
screenctx collect --root /path/to/project --entry /Demo100_list --out ./ctx --dry-run
```

| Option | Default | Meaning |
|--------|---------|---------|
| `--depth N` | `3` | Dependency traversal depth. |
| `--max-files N` | `240` | Stop after collecting N files. |
| `--max-file-bytes N` | none | Cap bytes included **per file** in `context.md`. Off by default. |
| `--no-config` | off | Do not auto-include `application.*` / `mybatis-config.xml`. |
| `--no-follow-view-routes` | off | Do not follow form/action/fetch routes found in views/scripts. |
| `--no-copy` | off | Write reports only; do not copy files into `bundle/`. |
| `--force` | off | Overwrite the output directory (only if it is empty or screenctx-managed). |
| `--dry-run` | off | Analyze and print the file list without writing anything. |

`--force` will **refuse** to overwrite a directory that contains files screenctx did not write, and refuses to use the project root itself as `--out`.

---

## Output

```text
ctx/
  context.md          # one Markdown file ready to paste/upload to an AI tool
  tree.txt            # directory tree of collected files
  files.txt           # plain list of collected files
  manifest.json       # machine-readable reasons, routes, unresolved refs
  unresolved.jsonl    # only when unresolved refs exist
  bundle/             # copied original files, preserving relative paths
```

`context.md` includes the matched routes, the collected file tree, matched message lines, unresolved references, and each collected file with the reasons it was included and its content.

By default `context.md` does not truncate text files. For common utilities, DAO interfaces, Mapper/API-Mapper classes, and MyBatis/iBATIS SQLMap XML, it uses **focused snippets** when it can prove the called method or SQL statement; the full original file is still copied under `bundle/`.

`bundle/` is useful when the AI tool can accept a folder/zip; `context.md` is useful when it only accepts a single text file.

---

## Use from VS Code (MCP server)

screenctx ships an MCP server that exposes a `collect_screen_context` tool, so editors like VS Code (Copilot Chat / agent mode) can pull screen context on demand.

1. Install the MCP extra: `pip install -e ".[mcp]"`
2. The repo includes [`.vscode/mcp.json`](.vscode/mcp.json):

   ```json
   {
     "servers": {
       "screenctx": {
         "type": "stdio",
         "command": "python",
         "args": ["-m", "screenctx.mcp_server"]
       }
     }
   }
   ```

   On Windows, use `"command": "py"` if `python` is not on your PATH. If you installed into a virtual environment, point `command` at that interpreter (e.g. `.venv/bin/python` or `.venv\\Scripts\\python.exe`) so the `mcp` package is found.

3. Reload VS Code and start the `screenctx` server from the MCP view. The tool takes a `root` and a list of `entries` (same forms as `--entry` above) and returns the `context.md` content directly.

You can also run the server standalone over stdio:

```bash
python -m screenctx.mcp_server
# or, after install:
screenctx-mcp
```

---

## Development

```bash
python3 -m venv .venv && source .venv/bin/activate
python3 -m pip install -e ".[dev]"
pytest
```

Smoke checks against fixtures / a real project:

```bash
./scripts/smoke_sqlmap_fixture.sh
./scripts/smoke_work_test.sh /path/to/your-spring-project
```

---

## Current limits

- Conservative static collector, not a full Java compiler.
- Resolves common Spring annotations, Java type references, MyBatis XML namespaces, template includes, form actions, static assets, and message keys.
- Does not execute Maven/Gradle, start Spring, or require network access.
- Favors recall over perfect precision; some related base/framework files may be included.