@nerdvana/parism 0.3.0 → 0.5.0

package/README.en.md

@@ -34,6 +34,20 @@ This has a cost. Running `ls` once looks simple, but the agent may spend dozens
 
 ---
 
+## The Honest Truth — Tokens Cost More
+
+When building Parism, the expectation was token savings. Structured data should be more efficient than raw text.
+
+Benchmarks across 17 scenarios flatly contradicted that. JSON output averages 205% heavier than raw text. For `ls -la` with 200 files: raw 5,807 tokens, Parism 15,531 tokens. Nearly triple, because key names repeat with every entry. What a human eye resolves from a single header row, JSON spells out N times.
+
+But the same benchmarks revealed something else: the disappearance of "explanation tokens." With raw text, the agent needs context — "this format has permissions in the first column, owner in the third." That context prompt shrinks by an average of 61% with Parism. JSON describes its own structure. The agent just reads keys.
+
+And there is a crossover point. For one-shot queries — run `ls` once, done — Parism costs more tokens. But the moment that result feeds into a next step, the cost structure inverts. An agent that misreads raw text writes to a nonexistent path, debugs the failure by scanning history, retries, fails again. Tokens snowball. An agent that starts with structured data never enters that cycle.
+
+Parism's economics live not on the invoice, but in the space where mistakes and rework used to be. The cost of reading once more is nothing compared to the cost of reading once wrong.
+
+---
+
 ## What Parism Does
 
 A prism does not destroy light. It decomposes it.
@@ -62,12 +76,22 @@ The information does not change. The shape does. The agent no longer parses. It
 
 ### No More Parsing Errors
 
-Text parsing breaks easily. `ps aux` has different column ordering on Linux and macOS. The `1K-blocks` header in `df -h` varies by environment. Filenames with spaces almost always break `ls` parsing. Parism's parsers handle these cases directly. The agent receives structured data.
+Text parsing breaks easily. `ps aux` has different column ordering on Linux and macOS. The `1K-blocks` header in `df -h` varies by environment. Filenames with spaces almost always break `ls` parsing.
+
+In numbers: raw text parsing by agents has an average CFR (Critical Failure Rate) of 4.18%. With filenames containing spaces, it climbs to 28.6%. That means 286 out of 1,000 calls produce a wrong file listing that the agent then acts on — reading wrong files, writing to nonexistent paths, deleting the wrong thing.
+
+macOS `stat` is a starker example. Its output format is entirely different from Linux. Linux uses labeled lines like `Size: 4096`; macOS outputs a single unlabeled line. Apply a Linux parsing pattern and accuracy drops to 0%. Parism detects the OS and selects the correct parser. The agent never needs to know the difference.
+
+Parism's CFR is 0%. Parsers are deterministic code, not probabilistic inference. The agent receives structured data.
 
 ### Fewer Retries
 
 When an agent misinterprets output, it re-queries, runs a second command to verify, or proceeds with bad data. All three cost tokens. Structured output reduces room for misinterpretation. The file count is not something to infer — it is `entries.length`.
 
+### The Agent Gets Better at Everything Else
+
+Parsing text is inference. Inference consumes cognitive resources. When the agent spends capacity decoding output formats, less remains for the actual work — analyzing code, making design judgments, deciding the next step. Structured data eliminates parsing as a task entirely. The agent reads instead of reasons, and the freed capacity flows into the work that matters.
+
 ### `raw` Is Always Preserved
 
 Parsers can be wrong. Some commands have no parser. So Parism always keeps `raw`. `parsed` is a bonus. `raw` is the fallback. The agent can always return to the original output.
@@ -87,6 +111,10 @@ Whether success or failure, `ok` and `exitCode` are always in the same place. Th
 
 Every response includes `duration_ms`. The agent can judge whether a command is slow or fast. Useful for debugging too.
 
+### diff Is Optional
+
+`diff` (created/deleted/modified) is populated only when `includeDiff: true`. run/run_paged default to `includeDiff: false`, skipping snapshot cost to reduce MCP call latency.
+
 ---
 
 ## Guard — Why Not to Trust the Agent
@@ -99,7 +127,7 @@ There are four layers of defense.
 
 **Command Whitelist**: Commands not in `allowed_commands` are never executed. No process is created. Rejected silently.
 
-**Path Restriction**: When `allowed_paths` is set, Guard validates both `cwd` and path-like args (starting with `/`, `./`, `../`). Anything outside allowed paths is blocked.
+**Path Restriction**: When `allowed_paths` is set, Guard validates `cwd` and path args. Args starting with `/`, `./`, `../` and positional args of path-taking commands (`cat`, `find`, `ls`, `grep` — e.g. `cat subdir/file`, `find src`) are checked. References outside allowed paths are blocked. This is a guard, not a kernel-level sandbox.
 
 **Injection Pattern Blocking**: If `;`, `$(`, `` ` ``, `&&`, `||`, `|`, `>`, `>>`, or `<` appear in any argument, the command is not executed.
 
@@ -121,46 +149,60 @@ The agent receives the block reason in the same envelope structure as any other
 
 ---
 
-## Supported Commands — 34 Built-in Parsers
-
-| Category | Command | Parsed Output |
-|---|---|---|
-| Filesystem | `ls` | `entries[]` — name, type, permissions, size, modified time, owner |
-| Filesystem | `find` | `paths[]` — list of paths |
-| Filesystem | `stat` | `file`, `size_bytes`, `inode`, `permissions`, `uid`, `gid`, timestamps |
-| Filesystem | `du` | `entries[]` — size, path |
-| Filesystem | `df` | `filesystems[]` — partition, usage, mount point |
-| Filesystem | `tree` | `root`, `tree{}` — hierarchical node map, `total_files`, `total_dirs` |
-| Process | `ps` | `processes[]` — PID, CPU%, MEM%, command |
-| Process | `kill` | raw pass-through |
-| Network | `ping` | `target`, `packets_transmitted`, `packet_loss_percent`, `rtt_*_ms` |
-| Network | `curl -I` | `status_code`, `headers{}` |
-| Network | `netstat` | `connections[]` — proto, local/foreign address, state |
-| Network | `lsof -i` | `entries[]` — PID, process name, protocol, local/remote address, state |
-| Network | `ss` | `entries[]` — state, recv/send queue, local/peer address, process |
-| Network | `dig` | `query`, `answers[]` — type, value, TTL, `query_time_ms` |
-| Text | `grep` | `matches[]` — file, line number, text |
-| Text | `wc` | `entries[]` — count, filename |
-| Text | `head`, `tail`, `cat` | `lines[]` |
-| Git | `git status` | `branch`, `staged[]`, `modified[]`, `untracked[]` |
-| Git | `git log --oneline` | `commits[]` — hash, message |
-| Git | `git diff` | `files_changed[]` |
-| Git | `git branch -vv` | `branches[]` — name, current, upstream, ahead/behind |
-| DevOps | `kubectl get pods`, `kubectl get events` | `pods[]` / `events[]` — status, restarts, reasons, messages |
-| DevOps | `docker ps`, `docker stats --no-stream` | `containers[]` / `stats[]` — image, status, CPU/MEM/IO |
-| DevOps | `gh pr list` | `pull_requests[]` — number, title, state, author, labels |
-| Env | `env` | `vars{}` — key-value map (secrets filtered) |
-| Env | `pwd` | `path` |
-| Env | `which` | `paths[]` |
-| System | `free` | `mem`, `swap` — total, used, free, available in bytes |
-| System | `uname` | `kernel_name`, `hostname`, `kernel_release`, `machine`, `os` |
-| System | `id` | `uid`, `gid`, `user`, `group`, `groups[]` — id, name |
-| Windows | `dir` | `directory`, `entries[]` — name, type, size, modified time, `free_bytes` |
-| Windows | `tasklist` | `processes[]` — name, PID, session, memory. CSV format supported |
-| Windows | `ipconfig` | `hostname`, `adapters[]` — IPv4/6, subnet, gateway, DNS, MAC |
-| Windows | `systeminfo` | `hostname`, `os_name`, memory, `hotfixes[]`, `network_cards[]` |
-
-Commands without a parser return `parsed: null`. `raw` is always present.
+## Supported Commands — 44 Built-in Parsers
+
+| Category | Command | Parsed Output | Default |
+|---|---|---|---|
+| Filesystem | `ls` | `entries[]` — name, type, permissions, size, modified time, owner | O |
+| Filesystem | `find` | `paths[]` — list of paths | O |
+| Filesystem | `stat` | `file`, `size_bytes`, `inode`, `permissions`, `uid`, `gid`, timestamps | O |
+| Filesystem | `du` | `entries[]` — size, path | O |
+| Filesystem | `df` | `filesystems[]` — partition, usage, mount point | O |
+| Filesystem | `tree` | `root`, `tree{}` — hierarchical node map, `total_files`, `total_dirs` | O |
+| Process | `ps` | `processes[]` — PID, CPU%, MEM%, command | O |
+| Process | `kill` | raw pass-through (blocked by default, add to prism.config.json to allow) | X |
+| Network | `ping` | `target`, `packets_transmitted`, `packet_loss_percent`, `rtt_*_ms` | O |
+| Network | `curl -I` | `status_code`, `headers{}` | O |
+| Network | `netstat` | `connections[]` — proto, local/foreign address, state | O |
+| Network | `lsof -i` | `entries[]` — PID, process name, protocol, local/remote address, state | X |
+| Network | `ss` | `connections[]` — state, recv/send queue, local/peer address | X |
+| Network | `dig` | `query`, `answers[]` — type, value, TTL, `query_time_ms` | X |
+| Text | `grep -n` | `matches[]` — file, line number, text | O |
+| Text | `wc` | `entries[]` — count, filename | O |
+| Text | `head`, `tail`, `cat` | `lines[]` | O |
+| Git | `git status` | `branch`, `staged[]`, `modified[]`, `untracked[]` | O |
+| Git | `git log --oneline` | `commits[]` — hash, message | O |
+| Git | `git diff` | `files_changed[]` | O |
+| Git | `git branch -vv` | `branches[]` — name, current, upstream, ahead/behind | O |
+| DevOps | `kubectl get pods`, `kubectl get events` | `pods[]` / `events[]` — status, restarts, reasons, messages | O |
+| DevOps | `docker ps`, `docker stats --no-stream` | `containers[]` / `stats[]` — image, status, CPU/MEM/IO | O |
+| DevOps | `gh pr list` | `pull_requests[]` — number, title, state, author, labels | O |
+| DevOps | `helm list` | `releases[]` — name, namespace, status, chart, app_version | O |
+| DevOps | `terraform plan` | `summary` — to_add, to_change, to_destroy | O |
+| Env | `env` | `vars{}` — key-value map (secrets filtered) | O |
+| Env | `pwd` | `path` | O |
+| Env | `which` | `paths[]` | O |
+| System | `free` | `mem`, `swap` — total, used, free, available in bytes | X |
+| System | `uname` | `kernel_name`, `hostname`, `kernel_release`, `machine`, `os` | O |
+| System | `id` | `uid`, `gid`, `user`, `group`, `groups[]` — id, name | X |
+| System | `systemctl list-units` | `units[]` — name, load, active, sub, description (Linux) | O |
+| System | `journalctl -o short-iso` | `entries[]` — timestamp, hostname, unit, pid, message (Linux) | O |
+| System | `apt list --installed` | `packages[]` — name, version, arch, status | O |
+| System | `brew list --versions` | `packages[]` — name, version | O |
+| Package | `npm list`, `pnpm list`, `yarn list` | `dependencies[]` — name, version, depth | O |
+| Package | `cargo tree` | `crates[]` — name, version, path | O |
+| Windows | `dir` | `directory`, `entries[]` — name, type, size, modified time, `free_bytes` | X |
+| Windows | `tasklist` | `processes[]` — name, PID, session, memory. CSV format supported | X |
+| Windows | `ipconfig` | `hostname`, `adapters[]` — IPv4/6, subnet, gateway, DNS, MAC | X |
+| Windows | `systeminfo` | `hostname`, `os_name`, memory, `hotfixes[]`, `network_cards[]` | X |
+
+Default (O)=in DEFAULT_CONFIG. X=requires explicit allow in prism.config.json.
+
+Commands without a parser return `parsed: null`. `raw` is always present. When a parser throws, `stdout.parse_error` contains `{ reason: "parser_exception", message: string }` so you can distinguish "no parser" from "parser bug".
+
+### Native JSON Passthrough
+
+Commands without a dedicated parser still get JSON output passed through when the output is valid JSON (e.g. `kubectl get pods -o json`, `docker inspect`). Parism detects this and puts it in `parsed`. Guard checks and envelope wrapping apply the same. No extra configuration needed.
 
 ---
 
@@ -230,6 +272,8 @@ Parameters:
 - `cmd` — command name (e.g. `ls`, `git`)
 - `args` — argument array (default: `[]`)
 - `cwd` — working directory (default: current directory)
+- `format` — output format (`"json"` default, `"compact"`, `"json-no-raw"`)
+- `includeDiff` — include filesystem diff (default: `false`). `false` skips snapshot for lower latency. Recommended for MCP.
 
 ### run_paged
 
@@ -239,6 +283,7 @@ Parameters:
 - `cmd`, `args`, `cwd` — same as `run`
 - `page` — 0-indexed page number (default: `0`)
 - `page_size` — lines per page (default: `default_page_size`, 100 by default)
+- `includeDiff` — include filesystem diff (default: `false`)
 
 Extra fields:
 - `page_info.total_lines` — total line count
@@ -254,7 +299,7 @@ Place `prism.config.json` in the project root to control Guard behavior.
 ```json
 {
   "guard": {
-    "allowed_commands": ["ls", "git", "find", "grep", "env", "ps"],
+    "allowed_commands": ["ls", "git", "find", "grep", "env", "ps", "kubectl", "docker", "gh", "terraform", "helm", "cargo", "systemctl", "journalctl", "apt", "brew"],
     "allowed_paths": ["/home/user/projects"],
     "timeout_ms": 10000,
     "max_output_bytes": 102400,
@@ -278,6 +323,62 @@ Place `prism.config.json` in the project root to control Guard behavior.
 
 ---
 
+## Custom Parsers -- Build and Use Immediately
+
+When 44 built-in parsers are not enough, build your own. Parism v0.5.0 includes a CLI toolkit.
+
+### Create a Parser in 5 Minutes
+
+```bash
+# 1. Capture command output
+parism capture "htop -b -n 1"
+
+# 2. Scaffold a parser pack
+parism init-parser htop
+
+# 3. Edit parser.ts and test against fixtures
+parism test htop
+
+# 4. Register -- available immediately, no restart needed
+parism add ./htop
+
+# 5. Verify -- raw/parsed/compact comparison + token counts
+parism inspect "htop -b -n 1"
+```
+
+Registered parsers are stored in `~/.parism/parsers/` and automatically loaded when the MCP server starts.
+
+### CLI Commands
+
+| Command | Description |
+|---|---|
+| `parism capture "<command>"` | Execute command and save raw output as fixture |
+| `parism init-parser <name>` | Scaffold a TypeScript parser pack (parser.ts + schema.json + fixtures/) |
+| `parism test [parser]` | Run fixture replay tests |
+| `parism add <path>` | Register a local parser pack permanently to ~/.parism/parsers/ |
+| `parism inspect "<command>"` | Compare raw / parsed / compact output + token counts |
+
+### ParserPack Interface
+
+External parsers implement this interface:
+
+```typescript
+import type { ParserPack } from "@nerdvana/parism/types";
+
+const pack: ParserPack = {
+  name: "my-command",
+  parse(raw, args, ctx?) { /* return structured result */ },
+  schema: { /* JSON Schema */ },
+  fixtures: [{ input: "...", args: [], expected: { /* ... */ } }],
+};
+
+export default pack;
+```
+
+Running `parism` without arguments starts the MCP server as before.
+
+---
+
 ## What Parism Is Not
 
 Parism is not a new shell. It does not replace bash. It sits above bash, receives output, and structures it.

package/README.md

@@ -44,7 +44,11 @@ Parism을 만들 때 기대한 것은 토큰 절약이었다. 구조화된 데
 
 하지만 같은 벤치마크가 다른 사실 하나를 드러냈다. 에이전트가 raw 텍스트를 직접 파싱할 때 오독률이 평균 4.18%, 공백이 섞인 파일명에서는 28.6%에 달했다. 열 번 중 세 번은 틀린다. 틀린 결과로 에이전트가 다음 작업을 수행하고, 그 작업이 또 틀리고, 결국 사람이 개입해서 되돌린다. 재시도 토큰, 디버깅 시간, 롤백 비용. 보이지 않는 곳에서 비용이 불어난다.
 
-Parism의 경제성은 토큰 청구서 위에 있지 않다. 실수와 재작업이 사라지는 자리에 있다. 한 번 더 읽는 비용보다, 한 번 잘못 읽어서 치르는 비용이 더 크다.
+그러나 같은 벤치마크가 한 가지 더 보여준 것이 있다. "AI한테 설명하는 토큰"의 소멸이다. raw 텍스트를 주면 에이전트에게 "이 출력은 이런 형식이고, 첫 번째 열이 권한이고, 세 번째가 소유자야"라고 알려줘야 한다. 그 컨텍스트 프롬프트가 Parism을 쓰면 평균 61% 줄어든다. JSON이 스스로 자기 구조를 설명하기 때문이다. 에이전트는 키를 읽으면 된다.
+
+그리고 역전이 일어나는 지점이 있다. 단발성 조회 — `ls` 한 번 치고 끝나는 작업 — 에서는 Parism이 토큰을 더 먹는다. 그러나 그 결과를 에이전트가 다음 작업에 사용하는 순간, 비용 구조가 뒤집힌다. raw를 잘못 읽은 에이전트가 존재하지 않는 경로에 파일을 쓰고, 그 오류를 디버깅하느라 히스토리를 뒤지고, 재시도하고, 또 틀리는 순환이 시작되면 토큰은 눈덩이가 된다. 구조화된 데이터로 시작한 에이전트는 그 순환에 진입하지 않는다.
+
+Parism의 경제성은 청구서 위에 있지 않다. 한 번 더 읽는 비용보다, 한 번 잘못 읽어서 치르는 비용이 압도적으로 크다.
 
 ---
 
@@ -80,12 +84,18 @@ Parism의 경제성은 토큰 청구서 위에 있지 않다. 실수와 재작
 
 수치로 말하면: raw 텍스트를 에이전트가 직접 파싱할 때 평균 CFR(Critical Failure Rate)은 4.18%다. 공백이 포함된 파일명이 섞이면 28.6%까지 치솟는다. 1000회 호출 시 286회는 잘못된 파일 목록을 기반으로 에이전트가 다음 작업을 수행한다는 뜻이다. 잘못된 파일을 읽고, 존재하지 않는 경로에 쓰고, 엉뚱한 파일을 삭제한다.
 
+macOS의 `stat`은 더 극적이다. Linux와 출력 형식이 완전히 다르다. Linux는 `Size: 4096`처럼 레이블이 붙지만, macOS는 레이블 없는 단일 줄이다. Linux 파싱 패턴을 적용하면 정확도는 0%다. Parism은 OS를 감지하고 적합한 파서를 선택한다. 에이전트는 그 차이를 알 필요가 없다.
+
 Parism의 CFR은 0%다. 파서는 deterministic code이기 때문이다. 정규표현식 추론이 아니라 구조적 분해다. 에이전트는 구조화된 데이터만 받는다.
 
 ### 재시도가 줄어든다
 
 에이전트가 출력을 잘못 해석하면 재질문하거나, 다른 명령으로 다시 확인하거나, 잘못된 정보를 바탕으로 다음 단계를 진행한다. 세 가지 모두 토큰이 든다. 구조화된 출력은 오해의 여지를 줄인다. 파일이 몇 개인지 묻지 않아도 `entries.length`다.
 
+### 에이전트가 다른 일을 더 잘하게 된다
+
+텍스트를 파싱하는 것은 추론이다. 추론에는 인지 자원이 소모된다. 에이전트가 출력 형식을 해독하는 데 자원을 쓰면, 실제 작업 — 코드를 분석하고, 설계를 판단하고, 다음 단계를 결정하는 일 — 에 쓸 자원이 줄어든다. 구조화된 데이터를 받으면 파싱이라는 작업 자체가 사라진다. 에이전트는 읽기만 하면 되고, 남은 역량을 본래의 작업에 집중할 수 있다.
+
 ### raw가 항상 보존된다
 
 파서가 틀릴 수도 있다. 파서가 없는 명령어일 수도 있다. 그래서 Parism은 `raw`를 항상 유지한다. `parsed`는 보너스다. `raw`는 보험이다. 에이전트는 항상 원본으로 돌아갈 수 있다.
@@ -105,6 +115,10 @@ Parism의 CFR은 0%다. 파서는 deterministic code이기 때문이다. 정규
 
 모든 응답에 `duration_ms`가 포함된다. 명령이 느린지 빠른지를 에이전트가 판단하는 데 쓸 수 있다. 디버깅할 때도 유용하다.
 
+### diff는 선택적이다
+
+`includeDiff: true`일 때만 `diff`에 `created`, `deleted`, `modified`가 채워진다. run/run_paged 기본값은 `includeDiff: false`이므로 스냅샷 비용을 생략하여 MCP 호출 지연을 줄인다.
+
 ---
 
 ## 가드 — 에이전트를 신뢰하지 않는 이유
@@ -117,7 +131,7 @@ Parism의 CFR은 0%다. 파서는 deterministic code이기 때문이다. 정규
 
 **화이트리스트**: `allowed_commands`에 없는 명령어는 실행되지 않는다. 프로세스를 만들지도 않는다. 설명 없이 거절한다.
 
-**경로 제한**: `allowed_paths`를 설정하면 `cwd`뿐 아니라 경로형 인자(`/`, `./`, `../` 시작)도 검사한다. 허용 경로 밖을 참조하면 차단된다.
+**경로 제한**: `allowed_paths`를 설정하면 `cwd`와 경로 인자를 검사한다. `/`, `./`, `../`로 시작하는 인자와, `cat`, `find`, `ls`, `grep` 등 경로를 받는 명령의 positional 인자(`cat subdir/file`, `find src`)도 허용 경로 밖이면 차단된다. 커널 수준 샌드박스는 아니며, 가드 수준의 방어선이다.
 
 **인젝션 패턴 차단**: `;`, `$(`, `` ` ``, `&&`, `||`, `|`, `>`, `>>`, `<`가 인자에 포함되면 실행하지 않는다.
 
@@ -141,52 +155,54 @@ Parism의 CFR은 0%다. 파서는 deterministic code이기 때문이다. 정규
 
 ## 지원 명령어 — 44종 내장 파서
 
-| 카테고리 | 명령어 | 파싱 결과 |
-|---|---|---|
-| 파일시스템 | `ls` | `entries[]` — 이름, 타입, 권한, 크기, 수정 시각, 소유자 |
-| 파일시스템 | `find` | `paths[]` — 경로 목록 |
-| 파일시스템 | `stat` | `file`, `size_bytes`, `inode`, `permissions`, `uid`, `gid`, 타임스탬프 |
-| 파일시스템 | `du` | `entries[]` — 크기, 경로 |
-| 파일시스템 | `df` | `filesystems[]` — 파티션, 사용량, 마운트 위치 |
-| 파일시스템 | `tree` | `root`, `tree{}` — 계층 구조 노드, `total_files`, `total_dirs` |
-| 프로세스 | `ps` | `processes[]` — PID, CPU%, MEM%, 명령어 |
-| 프로세스 | `kill` | raw pass-through |
-| 네트워크 | `ping` | `target`, `packets_transmitted`, `packet_loss_percent`, `rtt_*_ms` |
-| 네트워크 | `curl -I` | `status_code`, `headers{}` |
-| 네트워크 | `netstat` | `connections[]` — proto, local/foreign address, state |
-| 네트워크 | `lsof -i` | `entries[]` — PID, 프로세스명, 프로토콜, 로컬/원격 주소, 상태 |
-| 네트워크 | `ss` | `entries[]` — 상태, 수신/발신 큐, 로컬/피어 주소, 프로세스 |
-| 네트워크 | `dig` | `query`, `answers[]` — 타입, 값, TTL, `query_time_ms` |
-| 텍스트 | `grep -n` | `matches[]` — 파일, 라인 번호, 텍스트 |
-| 텍스트 | `wc` | `entries[]` — count, 파일명 |
-| 텍스트 | `head`, `tail`, `cat` | `lines[]` |
-| Git | `git status` | `branch`, `staged[]`, `modified[]`, `untracked[]` |
-| Git | `git log --oneline` | `commits[]` — hash, message |
-| Git | `git diff` | `files_changed[]` |
-| Git | `git branch -vv` | `branches[]` — 이름, current, upstream, ahead/behind |
-| DevOps | `kubectl get pods`, `kubectl get events` | `pods[]`/`events[]` — 상태, 재시도, 이벤트 사유/메시지 |
-| DevOps | `docker ps`, `docker stats --no-stream` | `containers[]`/`stats[]` — 이미지, 상태, CPU/MEM/IO |
-| DevOps | `gh pr list` | `pull_requests[]` — 번호, 제목, 상태, 작성자, 라벨 |
-| DevOps | `helm list` | `releases[]` — name, namespace, status, chart, app_version |
-| DevOps | `terraform plan` | `summary` — to_add, to_change, to_destroy |
-| 환경 | `env` | `vars{}` — 키-값 맵 |
-| 환경 | `pwd` | `path` |
-| 환경 | `which` | `paths[]` |
-| 시스템 | `free` | `rows{}` — mem/swap별 total, used, free, available (bytes) |
-| 시스템 | `uname` | `kernel`, `hostname`, `release`, `version`, `arch`, `os` |
-| 시스템 | `id` | `uid`, `gid`, `username`, `groups[]` — id, name |
-| 시스템 | `systemctl list-units` | `units[]` — name, load, active, sub, description (Linux) |
-| 시스템 | `journalctl -o short-iso` | `entries[]` — timestamp, hostname, unit, pid, message (Linux) |
-| 시스템 | `apt list --installed` | `packages[]` — name, version, arch, status |
-| 시스템 | `brew list --versions` | `packages[]` — name, version |
-| 패키지 | `npm list`, `pnpm list`, `yarn list` | `dependencies[]` — name, version, depth |
-| 패키지 | `cargo tree` | `crates[]` — name, version, path |
-| Windows | `dir` | `directory`, `entries[]` — 이름, 타입, 크기, 수정 시각, `free_bytes` |
-| Windows | `tasklist` | `processes[]` — 이름, PID, 세션, 메모리. CSV 형식 지원 |
-| Windows | `ipconfig` | `hostname`, `adapters[]` — IPv4/6, 서브넷, 게이트웨이, DNS, MAC |
-| Windows | `systeminfo` | `hostname`, `os_name`, 메모리, `hotfixes[]`, `network_cards[]` |
-
-파서가 없는 명령어는 `parsed: null`로 반환된다. `raw`는 그대로 있다.
+| 카테고리 | 명령어 | 파싱 결과 | 기본 허용 |
+|---|---|---|---|
+| 파일시스템 | `ls` | `entries[]` — 이름, 타입, 권한, 크기, 수정 시각, 소유자 | O |
+| 파일시스템 | `find` | `paths[]` — 경로 목록 | O |
+| 파일시스템 | `stat` | `file`, `size_bytes`, `inode`, `permissions`, `uid`, `gid`, 타임스탬프 | O |
+| 파일시스템 | `du` | `entries[]` — 크기, 경로 | O |
+| 파일시스템 | `df` | `filesystems[]` — 파티션, 사용량, 마운트 위치 | O |
+| 파일시스템 | `tree` | `root`, `tree{}` — 계층 구조 노드, `total_files`, `total_dirs` | O |
+| 프로세스 | `ps` | `processes[]` — PID, CPU%, MEM%, 명령어 | O |
+| 프로세스 | `kill` | raw pass-through (기본 차단, prism.config.json에서 명시적 허용 시 사용) | X |
+| 네트워크 | `ping` | `target`, `packets_transmitted`, `packet_loss_percent`, `rtt_*_ms` | O |
+| 네트워크 | `curl -I` | `status_code`, `headers{}` | O |
+| 네트워크 | `netstat` | `connections[]` — proto, local/foreign address, state | O |
+| 네트워크 | `lsof -i` | `entries[]` — PID, 프로세스명, 프로토콜, 로컬/원격 주소, 상태 | X |
+| 네트워크 | `ss` | `entries[]` — 상태, 수신/발신 큐, 로컬/피어 주소, 프로세스 | X |
+| 네트워크 | `dig` | `query`, `answers[]` — 타입, 값, TTL, `query_time_ms` | X |
+| 텍스트 | `grep -n` | `matches[]` — 파일, 라인 번호, 텍스트 | O |
+| 텍스트 | `wc` | `entries[]` — count, 파일명 | O |
+| 텍스트 | `head`, `tail`, `cat` | `lines[]` | O |
+| Git | `git status` | `branch`, `staged[]`, `modified[]`, `untracked[]` | O |
+| Git | `git log --oneline` | `commits[]` — hash, message | O |
+| Git | `git diff` | `files_changed[]` | O |
+| Git | `git branch -vv` | `branches[]` — 이름, current, upstream, ahead/behind | O |
+| DevOps | `kubectl get pods`, `kubectl get events` | `pods[]`/`events[]` — 상태, 재시도, 이벤트 사유/메시지 | O |
+| DevOps | `docker ps`, `docker stats --no-stream` | `containers[]`/`stats[]` — 이미지, 상태, CPU/MEM/IO | O |
+| DevOps | `gh pr list` | `pull_requests[]` — 번호, 제목, 상태, 작성자, 라벨 | O |
+| DevOps | `helm list` | `releases[]` — name, namespace, status, chart, app_version | O |
+| DevOps | `terraform plan` | `summary` — to_add, to_change, to_destroy | O |
+| 환경 | `env` | `vars{}` — 키-값 맵 | O |
+| 환경 | `pwd` | `path` | O |
+| 환경 | `which` | `paths[]` | O |
+| 시스템 | `free` | `rows{}` — mem/swap별 total, used, free, available (bytes) | X |
+| 시스템 | `uname` | `kernel`, `hostname`, `release`, `version`, `arch`, `os` | O |
+| 시스템 | `id` | `uid`, `gid`, `username`, `groups[]` — id, name | X |
+| 시스템 | `systemctl list-units` | `units[]` — name, load, active, sub, description (Linux) | O |
+| 시스템 | `journalctl -o short-iso` | `entries[]` — timestamp, hostname, unit, pid, message (Linux) | O |
+| 시스템 | `apt list --installed` | `packages[]` — name, version, arch, status | O |
+| 시스템 | `brew list --versions` | `packages[]` — name, version | O |
+| 패키지 | `npm list`, `pnpm list`, `yarn list` | `dependencies[]` — name, version, depth | O |
+| 패키지 | `cargo tree` | `crates[]` — name, version, path | O |
+| Windows | `dir` | `directory`, `entries[]` — 이름, 타입, 크기, 수정 시각, `free_bytes` | X |
+| Windows | `tasklist` | `processes[]` — 이름, PID, 세션, 메모리. CSV 형식 지원 | X |
+| Windows | `ipconfig` | `hostname`, `adapters[]` — IPv4/6, 서브넷, 게이트웨이, DNS, MAC | X |
+| Windows | `systeminfo` | `hostname`, `os_name`, 메모리, `hotfixes[]`, `network_cards[]` | X |
+
+기본 허용(O)=DEFAULT_CONFIG에 포함. X=prism.config.json에서 명시적 허용 필요.
+
+파서가 없는 명령어는 `parsed: null`로 반환된다. `raw`는 그대로 있다. 파서가 예외를 던지면 `stdout.parse_error`에 `{ reason: "parser_exception", message: string }`가 포함되어 "파서 없음"과 "파서 버그"를 구분할 수 있다.
 
 ### 네이티브 JSON 패스스루
 
@@ -258,8 +274,8 @@ Claude Code (Linux):
   "mcpServers": {
     "parism": {
       "command": "node",
-      "args": ["/home/nirna/job/nerdvana-prism/dist/index.js"],
-      "cwd": "/home/nirna/job/nerdvana-prism"
+      "args": ["/path/to/parism/dist/index.js"],
+      "cwd": "/path/to/parism"
     }
   }
 }
@@ -279,7 +295,8 @@ Claude Code (Linux):
 - `cmd` — 명령어 이름 (예: `ls`, `git`)
 - `args` — 인자 배열 (기본값: `[]`)
 - `cwd` — 작업 디렉토리 (기본값: 현재 디렉토리)
-- `format` — 출력 형식 (`"json"` 기본값, `"compact"` 가능). compact는 리스트형 출력을 schema+rows 컬럼 기반으로 압축하여 토큰 비용을 절감한다.
+- `format` — 출력 형식 (`"json"` 기본값, `"compact"`, `"json-no-raw"`). compact는 리스트형 출력을 schema+rows 컬럼 기반으로 압축하여 토큰 비용을 절감한다.
+- `includeDiff` — 파일시스템 diff 포함 여부 (기본값: `false`). `false`면 스냅샷 생략으로 지연 감소. MCP 고빈도 호출 시 권장.
 
 compact 예시:
 
@@ -298,6 +315,7 @@ compact 예시:
 - `cmd`, `args`, `cwd` — `run`과 동일
 - `page` — 0-indexed 페이지 번호 (기본값: `0`)
 - `page_size` — 페이지당 줄 수 (기본값: `default_page_size` 설정값, 기본 100)
+- `includeDiff` — 파일시스템 diff 포함 여부 (기본값: `false`). `false`면 스냅샷 생략으로 지연 감소.
 
 응답 추가 필드:
 - `page_info.total_lines` — 전체 줄 수
@@ -346,6 +364,62 @@ compact 예시:
 
 ---
 
+## 커스텀 파서 -- 직접 만들고 바로 쓴다
+
+44개 내장 파서로 부족하면, 직접 만들면 된다. Parism v0.5.0부터 CLI 도구가 포함된다.
+
+### 5분 안에 파서 만들기
+
+```bash
+# 1. 명령어 출력을 캡처한다
+parism capture "htop -b -n 1"
+
+# 2. 파서 팩 스캐폴드를 생성한다
+parism init-parser htop
+
+# 3. parser.ts를 편집하고 fixture를 테스트한다
+parism test htop
+
+# 4. 등록한다 -- 재시작 없이 즉시 사용 가능
+parism add ./htop
+
+# 5. 결과를 확인한다 -- raw/parsed/compact 비교 + 토큰 수
+parism inspect "htop -b -n 1"
+```
+
+등록된 파서는 `~/.parism/parsers/`에 저장되고, MCP 서버 시작 시 자동으로 로드된다.
+
+### CLI 명령어
+
+| 명령어 | 설명 |
+|---|---|
+| `parism capture "<command>"` | 명령어를 실행하고 raw 출력을 fixture로 저장 |
+| `parism init-parser <name>` | TypeScript 파서 팩 스캐폴드 생성 (parser.ts + schema.json + fixtures/) |
+| `parism test [parser]` | fixture replay 테스트 실행 |
+| `parism add <path>` | 로컬 파서 팩을 ~/.parism/parsers/에 영구 등록 |
+| `parism inspect "<command>"` | raw / parsed / compact 출력 비교 + 토큰 수 |
+
+### ParserPack 인터페이스
+
+외부 파서는 이 인터페이스를 구현한다.
+
+```typescript
+import type { ParserPack } from "@nerdvana/parism/types";
+
+const pack: ParserPack = {
+  name: "my-command",
+  parse(raw, args, ctx?) { /* 구조화된 결과 반환 */ },
+  schema: { /* JSON Schema */ },
+  fixtures: [{ input: "...", args: [], expected: { /* ... */ } }],
+};
+
+export default pack;
+```
+
+인자 없이 `parism`을 실행하면 기존과 동일하게 MCP 서버로 동작한다.
+
+---
+
 ## Parism이 아닌 것
 
 Parism은 새로운 셸이 아니다. bash를 대체하지 않는다. bash 위에 앉아서 출력을 받아 구조화할 뿐이다.

package/dist/cli/add.d.ts

@@ -0,0 +1,9 @@
+export interface AddResult {
+    name: string;
+    installedTo: string;
+}
+/**
+ * 파서 팩을 ~/.parism/parsers/에 복사하고 registry.json에 등록한다.
+ */
+export declare function addParserPack(sourcePath: string, parismHome?: string): Promise<AddResult>;
+//# sourceMappingURL=add.d.ts.map

package/dist/cli/add.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"add.d.ts","sourceRoot":"","sources":["../../src/cli/add.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,SAAS;IACxB,IAAI,EAAS,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,wBAAsB,aAAa,CACjC,UAAU,EAAE,MAAM,EAClB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,SAAS,CAAC,CAsBpB"}

package/dist/cli/add.js

@@ -0,0 +1,25 @@
+import { cpSync, mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { loadParserPack } from "./loader.js";
+import { ensureParismDirs } from "./paths.js";
+/**
+ * 파서 팩을 ~/.parism/parsers/에 복사하고 registry.json에 등록한다.
+ */
+export async function addParserPack(sourcePath, parismHome) {
+    const pack = await loadParserPack(resolve(sourcePath));
+    const home = ensureParismDirs(parismHome);
+    const destDir = join(home, "parsers", pack.name);
+    mkdirSync(destDir, { recursive: true });
+    cpSync(resolve(sourcePath), destDir, { recursive: true });
+    const registryPath = join(home, "registry.json");
+    const registry = existsSync(registryPath)
+        ? JSON.parse(readFileSync(registryPath, "utf-8"))
+        : {};
+    registry[pack.name] = {
+        path: destDir,
+        addedAt: new Date().toISOString(),
+    };
+    writeFileSync(registryPath, JSON.stringify(registry, null, 2));
+    return { name: pack.name, installedTo: destDir };
+}
+//# sourceMappingURL=add.js.map

package/dist/cli/add.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"add.js","sourceRoot":"","sources":["../../src/cli/add.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrF,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAO9C;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,UAAkB,EAClB,UAAmB;IAEnB,MAAM,IAAI,GAAM,MAAM,cAAc,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC;IAC1D,MAAM,IAAI,GAAM,gBAAgB,CAAC,UAAU,CAAC,CAAC;IAC7C,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IAEjD,SAAS,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACxC,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAE1D,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC;IACjD,MAAM,QAAQ,GACZ,UAAU,CAAC,YAAY,CAAC;QACtB,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;QACjD,CAAC,CAAC,EAAE,CAAC;IAET,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;QACpB,IAAI,EAAK,OAAO;QAChB,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KAClC,CAAC;IAEF,aAAa,CAAC,YAAY,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAE/D,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC;AACnD,CAAC"}

package/dist/cli/auto-loader.d.ts

@@ -0,0 +1,7 @@
+import type { ParserRegistry } from "../parsers/registry.js";
+/**
+ * ~/.parism/registry.json을 읽고 등록된 외부 파서를 레지스트리에 로드한다.
+ * 로드 실패한 파서는 건너뛰고 경고 출력. 반환값: 성공 로드 수.
+ */
+export declare function loadExternalParsers(parismHome: string, registry: ParserRegistry): Promise<number>;
+//# sourceMappingURL=auto-loader.d.ts.map

package/dist/cli/auto-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-loader.d.ts","sourceRoot":"","sources":["../../src/cli/auto-loader.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAW,wBAAwB,CAAC;AAGlE;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAI,cAAc,GACzB,OAAO,CAAC,MAAM,CAAC,CAwBjB"}

package/dist/cli/auto-loader.js

@@ -0,0 +1,33 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { loadParserPack } from "./loader.js";
+/**
+ * ~/.parism/registry.json을 읽고 등록된 외부 파서를 레지스트리에 로드한다.
+ * 로드 실패한 파서는 건너뛰고 경고 출력. 반환값: 성공 로드 수.
+ */
+export async function loadExternalParsers(parismHome, registry) {
+    const registryPath = join(parismHome, "registry.json");
+    if (!existsSync(registryPath))
+        return 0;
+    let entries;
+    try {
+        entries = JSON.parse(readFileSync(registryPath, "utf-8"));
+    }
+    catch {
+        return 0;
+    }
+    let loaded = 0;
+    for (const [name, entry] of Object.entries(entries)) {
+        try {
+            const pack = await loadParserPack(entry.path);
+            registry.registerPack(pack);
+            loaded++;
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.warn(`[parism] Failed to load parser "${name}": ${msg}`);
+        }
+    }
+    return loaded;
+}
+//# sourceMappingURL=auto-loader.js.map

package/dist/cli/auto-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-loader.js","sourceRoot":"","sources":["../../src/cli/auto-loader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,MAA0B,WAAW,CAAC;AAErD,OAAO,EAAE,cAAc,EAAE,MAAgB,aAAa,CAAC;AAEvD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,UAAkB,EAClB,QAA0B;IAE1B,MAAM,YAAY,GAAG,IAAI,CAAC,UAAU,EAAE,eAAe,CAAC,CAAC;IACvD,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC;QAAE,OAAO,CAAC,CAAC;IAExC,IAAI,OAAyC,CAAC;IAC9C,IAAI,CAAC;QACH,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC,CAAC;IAC5D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,CAAC;IACX,CAAC;IAED,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACpD,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,cAAc,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAC9C,QAAQ,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;YAC5B,MAAM,EAAE,CAAC;QACX,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC7D,OAAO,CAAC,IAAI,CAAC,mCAAmC,IAAI,MAAM,GAAG,EAAE,CAAC,CAAC;QACnE,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/cli/capture.d.ts

@@ -0,0 +1,9 @@
+export interface CaptureResult {
+    exitCode: number;
+    fixturePath: string;
+}
+/**
+ * 명령어를 실행하고 stdout/stderr/exitCode를 fixture JSON으로 저장한다.
+ */
+export declare function captureCommand(cmd: string, args: string[], fixturesDir?: string): Promise<CaptureResult>;
+//# sourceMappingURL=capture.d.ts.map

package/dist/cli/capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture.d.ts","sourceRoot":"","sources":["../../src/cli/capture.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAK,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB;AASD;;GAEG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAG,MAAM,EACZ,IAAI,EAAE,MAAM,EAAE,EACd,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,aAAa,CAAC,CAqCxB"}