@nerdvana/parism 0.1.2 → 0.1.4

package/README.en.md

@@ -0,0 +1,256 @@
+# Parism
+
+> Refract the Shell. Every command, structured.
+
+<p align="right"><a href="README.md">한국어</a> | <a href="README.en.md">English</a></p>
+
+---
+
+## The Shell Was Not Designed for You
+
+In 1969, when Ken Thompson built Unix, he assumed the output would be read by a human — specifically, a creature with eyes sitting in front of a terminal.
+
+Half a century later, that assumption no longer holds.
+
+An AI agent runs `ls -la` and receives its output. Then the real work begins: split on whitespace, figure out that the first column is permissions, the third is the owner, infer where the filename starts — burning tokens to reason through what a human eye processes in 0.1 seconds.
+
+This is not translation. It is decrypting a message that was never encrypted.
+
+---
+
+## Why This Is a Problem
+
+Three translations happen.
+
+First: the kernel manages filesystem metadata as `stat` structures — `inode`, `mode`, `uid`, `gid`, `size`, `mtime`. Already perfectly structured data.
+
+Second: `ls` flattens that structure into human-readable text. `drwxr-xr-x  2 user group 4096 Mar 06 09:23 src`. Structure collapses into string.
+
+Third: the agent tries to reconstruct that structure from the text. Rebuilding what was just torn down.
+
+Parism intervenes between the second and third step. It recovers what was discarded.
+
+This has a cost. Running `ls` once looks simple, but the agent may spend dozens of inference steps parsing the output — and often gets it wrong. Edge cases, unexpected whitespace, OS-specific formatting quirks. Wrong means retry. Retry means more tokens.
+
+---
+
+## What Parism Does
+
+A prism does not destroy light. It decomposes it.
+
+```
+"drwxr-xr-x  2 user group 4096 Mar 06 09:23 src"
+
+                    ↓  Parism
+
+{
+  "type": "directory",
+  "name": "src",
+  "permissions": { "owner": "rwx", "group": "r-x", "other": "r-x" },
+  "size_bytes": 4096,
+  "owner": "user",
+  "group": "group",
+  "modified_at": "2026-03-06T09:23:00"
+}
+```
+
+The information does not change. The shape does. The agent no longer parses. It reads.
+
+---
+
+## Why This Is Better
+
+### 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.
+
+### 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`.
+
+### `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.
+
+```json
+"stdout": {
+  "raw": "drwxr-xr-x ...",
+  "parsed": { "entries": [ ... ] }
+}
+```
+
+### Consistent Response Structure
+
+Whether success or failure, `ok` and `exitCode` are always in the same place. The agent's branching logic becomes simple. Not "parse stdout to check for errors" — just `if (!result.ok)`.
+
+### Execution Time Is Recorded
+
+Every response includes `duration_ms`. The agent can judge whether a command is slow or fast. Useful for debugging too.
+
+---
+
+## Guard — Why Not to Trust the Agent
+
+`rm -rf /` can be written in three characters.
+
+Agents make mistakes. They lose context, confuse paths, generate unintended commands. Guard is not about distrust — it is about designing so that agent mistakes do not become catastrophes.
+
+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, commands referencing paths outside it are blocked. The agent cannot touch `/etc`.
+
+**Injection Pattern Blocking**: If `;`, `$(`, `` ` ``, `&&`, `||`, or `|` appear in any argument, the command is not executed. Regardless of agent intent.
+
+**Per-Command Argument Restrictions** *(v0.1.2)*: Specific flags can be blocked per command. `node -e` and `node --eval` allow arbitrary code execution — they are blocked by default. `npx --yes` silently installs packages from the internet — also blocked.
+
+A blocked command returns this:
+
+```json
+{
+  "ok": false,
+  "guard_error": {
+    "reason": "command_not_allowed",
+    "message": "Command 'rm' is not in the allowed list"
+  }
+}
+```
+
+The agent receives the block reason in the same envelope structure as any other result. No exceptions thrown. No pipeline broken.
+
+---
+
+## Supported Commands — 31 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 |
+| 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.
+
+---
+
+## Installation
+
+### npx
+
+```bash
+npx @nerdvana/parism
+```
+
+### Local Build
+
+```bash
+git clone https://github.com/your-org/parism
+cd parism
+npm install && npm run build
+node dist/index.js
+```
+
+---
+
+## Claude Desktop Integration
+
+`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
+`%APPDATA%\Claude\claude_desktop_config.json` (Windows)
+
+```json
+{
+  "mcpServers": {
+    "parism": {
+      "command": "npx",
+      "args": ["-y", "@nerdvana/parism"]
+    }
+  }
+}
+```
+
+Claude Code (Linux):
+
+```json
+{
+  "mcpServers": {
+    "parism": {
+      "command": "node",
+      "args": ["/path/to/parism/dist/index.js"],
+      "cwd": "/path/to/parism"
+    }
+  }
+}
+```
+
+Once connected, a single `run` tool is exposed. The agent uses it to execute commands and receive JSON.
+
+---
+
+## Configuration
+
+Place `prism.config.json` in the project root to control Guard behavior.
+
+```json
+{
+  "guard": {
+    "allowed_commands": ["ls", "git", "find", "grep", "env", "ps"],
+    "allowed_paths": ["/home/user/projects"],
+    "timeout_ms": 10000,
+    "block_patterns": [";", "$(", "`", "&&", "||", "|"],
+    "command_arg_restrictions": {
+      "node": { "blocked_flags": ["-e", "--eval", "-r", "--require", "-p", "--print"] },
+      "npx":  { "blocked_flags": ["--yes", "-y"] }
+    },
+    "env_secret_patterns": ["TOKEN", "SECRET", "AUTHZ", "PASSWORD", "CREDENTIAL"]
+  }
+}
+```
+
+`allowed_paths` being empty means no path restriction. That decision is yours.
+
+`env_secret_patterns` strips matching environment variables from child processes before execution. The `env` command will not expose them.
+
+---
+
+## What Parism Is Not
+
+Parism is not a new shell. It does not replace bash. It sits above bash, receives output, and structures it.
+
+Parism is not an operating system for AI. Its concern is singular: when an agent issues a command, return the result in a form the agent can understand.
+
+The Unix philosophy was "do one thing well." Parism understands that.
+
+---
+
+<p align="center">
+  Made by <a href="mailto:jinho.von.choi@nerdvana.kr">Jinho Choi</a> &nbsp;|&nbsp;
+  <a href="https://buymeacoffee.com/jinho.von.choi">Buy me a coffee</a>
+</p>

package/README.md

@@ -2,6 +2,8 @@
 
 > Refract the Shell. Every command, structured.
 
+<p align="right"><a href="README.md">한국어</a> | <a href="README.en.md">English</a></p>
+
 ---
 
 ## 셸은 당신을 위해 설계되지 않았다
@@ -93,7 +95,7 @@ Parism이 개입하는 것은 두 번째와 세 번째 사이다. 한 번 버려
 
 에이전트는 오류를 범한다. 문맥을 잃고, 경로를 착각하고, 의도하지 않은 명령을 생성한다. Guard는 에이전트를 불신하는 것이 아니다. 에이전트의 실수가 파국으로 이어지지 않도록 설계하는 것이다.
 
-세 겹의 방어선이 있다.
+네 겹의 방어선이 있다.
 
 **화이트리스트**: `allowed_commands`에 없는 명령어는 실행되지 않는다. 프로세스를 만들지도 않는다. 설명 없이 거절한다.
 
@@ -101,6 +103,8 @@ Parism이 개입하는 것은 두 번째와 세 번째 사이다. 한 번 버려
 
 **인젝션 패턴 차단**: `;`, `$(`, `` ` ``, `&&`, `||`, `|`가 인자에 포함되면 실행하지 않는다. 에이전트가 의도했든 아니든.
 
+**명령별 인자 제한** *(v0.1.2)*: 명령마다 차단할 플래그를 지정할 수 있다. `node -e`와 `node --eval`은 임의 코드 실행 경로이므로 기본 차단된다. `npx --yes`는 인터넷에서 패키지를 설치하므로 마찬가지다.
+
 차단된 명령은 이런 응답을 반환한다.
 
 ```json
@@ -123,7 +127,7 @@ Parism이 개입하는 것은 두 번째와 세 번째 사이다. 한 번 버려
 |---|---|---|
 | 파일시스템 | `ls` | `entries[]` — 이름, 타입, 권한, 크기, 수정 시각, 소유자 |
 | 파일시스템 | `find` | `paths[]` — 경로 목록 |
-| 파일시스템 | `stat` | `lines[]` — 원본 라인 배열 |
+| 파일시스템 | `stat` | `file`, `size_bytes`, `inode`, `permissions`, `uid`, `gid`, 타임스탬프 |
 | 파일시스템 | `du` | `entries[]` — 크기, 경로 |
 | 파일시스템 | `df` | `filesystems[]` — 파티션, 사용량, 마운트 위치 |
 | 파일시스템 | `tree` | `root`, `tree{}` — 계층 구조 노드, `total_files`, `total_dirs` |
@@ -206,7 +210,43 @@ Claude Code (Linux):
 }
 ```
 
-연결이 되면 `run` 도구 하나가 노출된다. 에이전트는 이 도구로 명령을 실행하고 JSON을 받는다.
+연결이 되면 `run`과 `run_paged` 두 도구가 노출된다. 에이전트는 이 도구로 명령을 실행하고 JSON을 받는다.
+
+---
+
+## Tools
+
+### run
+
+모든 명령의 기본 도구. 출력이 작거나 구조화 파싱이 필요할 때 사용한다.
+
+파라미터:
+- `cmd` — 명령어 이름 (예: `ls`, `git`)
+- `args` — 인자 배열 (기본값: `[]`)
+- `cwd` — 작업 디렉토리 (기본값: 현재 디렉토리)
+
+### run_paged
+
+대용량 출력을 페이지 단위로 읽는다. `ps aux`, `find`, `grep -r` 등에 사용한다.
+
+파라미터:
+- `cmd`, `args`, `cwd` — `run`과 동일
+- `page` — 0-indexed 페이지 번호 (기본값: `0`)
+- `page_size` — 페이지당 줄 수 (기본값: `default_page_size` 설정값, 기본 100)
+
+응답 추가 필드:
+- `page_info.total_lines` — 전체 줄 수
+- `page_info.has_next` — 다음 페이지 존재 여부
+- `stdout.parsed` — 항상 `null` (부분 출력은 구조화 불가)
+
+에이전트 패턴:
+
+```
+1. run_paged(cmd, page=0) → page_info.total_lines 확인
+2. 범위가 작으면 그대로 사용
+3. 범위가 크면 grep으로 먼저 필터링 후 run 호출
+4. 필요한 페이지만 run_paged(page=N) 추가 호출
+```
 
 ---
 
@@ -220,13 +260,21 @@ Claude Code (Linux):
     "allowed_commands": ["ls", "git", "find", "grep", "env", "ps"],
     "allowed_paths": ["/home/user/projects"],
     "timeout_ms": 10000,
-    "block_patterns": [";", "$(", "`", "&&", "||", "|"]
+    "block_patterns": [";", "$(", "`", "&&", "||", "|"],
+    "command_arg_restrictions": {
+      "node": { "blocked_flags": ["-e", "--eval", "-r", "--require", "-p", "--print"] },
+      "npx":  { "blocked_flags": ["--yes", "-y"] }
+    },
+    "env_secret_patterns": ["TOKEN", "SECRET", "AUTHZ", "PASSWORD", "CREDENTIAL"],
+    "default_page_size": 100
   }
 }
 ```
 
 `allowed_paths`가 비어 있으면 경로 제한 없이 실행된다. 판단은 당신 몫이다.
 
+`env_secret_patterns`에 일치하는 환경 변수는 실행 전 자식 프로세스에서 제거된다. `env` 명령 실행 시 해당 변수가 노출되지 않는다.
+
 ---
 
 ## Parism이 아닌 것

package/dist/config/loader.d.ts

@@ -5,6 +5,9 @@ export interface PrismGuardConfig {
     allowed_commands: string[];
     allowed_paths: string[];
     timeout_ms: number;
+    max_output_bytes: number;
+    max_items: number;
+    default_page_size: number;
     block_patterns: string[];
     command_arg_restrictions: Record<string, CommandArgRestriction>;
     env_secret_patterns: string[];

package/dist/config/loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/config/loader.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,qBAAqB;IACpC,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC/B,gBAAgB,EAAU,MAAM,EAAE,CAAC;IACnC,aAAa,EAAa,MAAM,EAAE,CAAC;IACnC,UAAU,EAAgB,MAAM,CAAC;IACjC,cAAc,EAAY,MAAM,EAAE,CAAC;IACnC,wBAAwB,EAAE,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC;IAChE,mBAAmB,EAAO,MAAM,EAAE,CAAC;CACpC;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,gBAAgB,CAAC;CACzB;AAED,eAAO,MAAM,cAAc,EAAE,WAsB5B,CAAC;AAEF;;;GAGG;AACH,wBAAsB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAWzE"}
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/config/loader.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,qBAAqB;IACpC,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC/B,gBAAgB,EAAU,MAAM,EAAE,CAAC;IACnC,aAAa,EAAa,MAAM,EAAE,CAAC;IACnC,UAAU,EAAgB,MAAM,CAAC;IACjC,gBAAgB,EAAU,MAAM,CAAC;IACjC,SAAS,EAAiB,MAAM,CAAC;IACjC,iBAAiB,EAAS,MAAM,CAAC;IACjC,cAAc,EAAY,MAAM,EAAE,CAAC;IACnC,wBAAwB,EAAE,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC;IAChE,mBAAmB,EAAO,MAAM,EAAE,CAAC;CACpC;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,gBAAgB,CAAC;CACzB;AAED,eAAO,MAAM,cAAc,EAAE,WAyB5B,CAAC;AAEF;;;GAGG;AACH,wBAAsB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAWzE"}

package/dist/config/loader.js

@@ -2,7 +2,7 @@ import { readFile } from "node:fs/promises";
 export const DEFAULT_CONFIG = {
     guard: {
         allowed_commands: [
-            "ls", "find", "stat", "du", "df",
+            "ls", "find", "stat", "du", "df", "tree",
             "ps", "kill",
             "ping", "curl", "netstat",
             "grep", "wc", "head", "tail", "cat",
@@ -12,6 +12,9 @@ export const DEFAULT_CONFIG = {
         ],
         allowed_paths: [],
         timeout_ms: 10000,
+        max_output_bytes: 102400, // 100 KB
+        max_items: 500,
+        default_page_size: 100,
         block_patterns: [";", "$(", "`", "&&", "||", ">", ">>", "<", "|"],
         command_arg_restrictions: {
             node: { blocked_flags: ["-e", "--eval", "-r", "--require", "-p", "--print", "--input-type"] },

package/dist/config/loader.js.map

@@ -1 +1 @@
-{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../src/config/loader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAmB5C,MAAM,CAAC,MAAM,cAAc,GAAgB;IACzC,KAAK,EAAE;QACL,gBAAgB,EAAE;YAChB,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI;YAChC,IAAI,EAAE,MAAM;YACZ,MAAM,EAAE,MAAM,EAAE,SAAS;YACzB,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK;YACnC,KAAK;YACL,KAAK,EAAE,KAAK,EAAE,OAAO;YACrB,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU;SACpC;QACD,aAAa,EAAG,EAAE;QAClB,UAAU,EAAM,KAAK;QACrB,cAAc,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC;QACjE,wBAAwB,EAAE;YACxB,IAAI,EAAE,EAAE,aAAa,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,EAAE,cAAc,CAAC,EAAE;YAC7F,GAAG,EAAG,EAAE,aAAa,EAAE,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE;SACzC;QACD,mBAAmB,EAAE;YACnB,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,YAAY;SAC/D;KACF;CACF,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,UAAkB;IACjD,IAAI,CAAC;QACH,MAAM,GAAG,GAAI,MAAM,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QACjD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAyB,CAAC;QAErD,OAAO;YACL,KAAK,EAAE,EAAE,GAAG,cAAc,CAAC,KAAK,EAAE,GAAG,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,EAAE;SAC1D,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,cAAc,CAAC;IACxB,CAAC;AACH,CAAC"}
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../src/config/loader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAsB5C,MAAM,CAAC,MAAM,cAAc,GAAgB;IACzC,KAAK,EAAE;QACL,gBAAgB,EAAE;YAChB,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM;YACxC,IAAI,EAAE,MAAM;YACZ,MAAM,EAAE,MAAM,EAAE,SAAS;YACzB,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK;YACnC,KAAK;YACL,KAAK,EAAE,KAAK,EAAE,OAAO;YACrB,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU;SACpC;QACD,aAAa,EAAK,EAAE;QACpB,UAAU,EAAQ,KAAK;QACvB,gBAAgB,EAAG,MAAM,EAAI,SAAS;QACtC,SAAS,EAAU,GAAG;QACtB,iBAAiB,EAAE,GAAG;QACtB,cAAc,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC;QACjE,wBAAwB,EAAE;YACxB,IAAI,EAAE,EAAE,aAAa,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,EAAE,cAAc,CAAC,EAAE;YAC7F,GAAG,EAAG,EAAE,aAAa,EAAE,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE;SACzC;QACD,mBAAmB,EAAE;YACnB,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,YAAY;SAC/D;KACF;CACF,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,UAAkB;IACjD,IAAI,CAAC;QACH,MAAM,GAAG,GAAI,MAAM,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QACjD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAyB,CAAC;QAErD,OAAO;YACL,KAAK,EAAE,EAAE,GAAG,cAAc,CAAC,KAAK,EAAE,GAAG,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,EAAE;SAC1D,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,cAAc,CAAC;IACxB,CAAC;AACH,CAAC"}

package/dist/engine/executor.d.ts

@@ -5,5 +5,5 @@ import type { ResponseEnvelope } from "../types/envelope.js";
  * - secretPatterns에 해당하는 환경 변수는 자식 프로세스에 전달하지 않음
  * - 실행 실패(명령 없음 포함)는 예외 대신 ok=false 봉투로 반환
  */
-export declare function execute(cmd: string, args: string[], cwd: string, secretPatterns?: string[]): Promise<ResponseEnvelope>;
+export declare function execute(cmd: string, args: string[], cwd: string, secretPatterns?: string[], timeoutMs?: number, maxOutputBytes?: number): Promise<ResponseEnvelope>;
 //# sourceMappingURL=executor.d.ts.map

package/dist/engine/executor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../src/engine/executor.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAqB7D;;;;;GAKG;AACH,wBAAsB,OAAO,CAC3B,GAAG,EAAa,MAAM,EACtB,IAAI,EAAY,MAAM,EAAE,EACxB,GAAG,EAAa,MAAM,EACtB,cAAc,GAAE,MAAM,EAAO,GAC5B,OAAO,CAAC,gBAAgB,CAAC,CA0C3B"}
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../src/engine/executor.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAsB7D;;;;;GAKG;AACH,wBAAsB,OAAO,CAC3B,GAAG,EAAc,MAAM,EACvB,IAAI,EAAa,MAAM,EAAE,EACzB,GAAG,EAAc,MAAM,EACvB,cAAc,GAAG,MAAM,EAAO,EAC9B,SAAS,GAAQ,MAAgB,EACjC,cAAc,GAAG,MAAY,GAC5B,OAAO,CAAC,gBAAgB,CAAC,CA6D3B"}

package/dist/engine/executor.js

@@ -1,5 +1,6 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
+import { takeSnapshot, computeDiff } from "./state-tracker.js";
 const execFileAsync = promisify(execFile);
 /**
  * process.env에서 시크릿 패턴과 일치하는 변수를 제거한 환경 객체를 반환한다.
@@ -23,14 +24,28 @@ function buildSanitizedEnv(secretPatterns) {
  * - secretPatterns에 해당하는 환경 변수는 자식 프로세스에 전달하지 않음
  * - 실행 실패(명령 없음 포함)는 예외 대신 ok=false 봉투로 반환
  */
-export async function execute(cmd, args, cwd, secretPatterns = []) {
+export async function execute(cmd, args, cwd, secretPatterns = [], timeoutMs = 10000, maxOutputBytes = 0) {
     const start = Date.now();
+    const before = await takeSnapshot(cwd);
     try {
         const { stdout, stderr } = await execFileAsync(cmd, args, {
             cwd,
+            timeout: timeoutMs,
             maxBuffer: 10 * 1024 * 1024, // 10 MB
             env: { ...buildSanitizedEnv(secretPatterns), LC_ALL: "C", LANG: "C" },
         });
+        const after = await takeSnapshot(cwd);
+        // stdout 크기 제한: 초과 시 마지막 완전한 줄까지 잘라내고 truncated=true 표시
+        let outRaw = stdout;
+        let truncated;
+        if (maxOutputBytes > 0 && Buffer.byteLength(outRaw, "utf8") > maxOutputBytes) {
+            const buf = Buffer.from(outRaw, "utf8").subarray(0, maxOutputBytes);
+            const partial = buf.toString("utf8");
+            const lastNewline = partial.lastIndexOf("\n");
+            outRaw = lastNewline > 0 ? partial.slice(0, lastNewline + 1) : partial;
+            outRaw += `...[truncated: output exceeded ${maxOutputBytes} bytes]\n`;
+            truncated = true;
+        }
         return {
             ok: true,
             exitCode: 0,
@@ -38,14 +53,16 @@ export async function execute(cmd, args, cwd, secretPatterns = []) {
             args,
             cwd,
             duration_ms: Date.now() - start,
-            stdout: { raw: stdout, parsed: null },
+            stdout: { raw: outRaw, parsed: null },
             stderr: { raw: stderr, parsed: null },
-            diff: null,
+            diff: computeDiff(before, after),
+            truncated,
         };
     }
     catch (err) {
         const e = err;
         const exitCode = typeof e.code === "number" ? e.code : 1;
+        const after = await takeSnapshot(cwd);
         return {
             ok: false,
             exitCode,
@@ -55,7 +72,7 @@ export async function execute(cmd, args, cwd, secretPatterns = []) {
             duration_ms: Date.now() - start,
             stdout: { raw: e.stdout ?? "", parsed: null },
             stderr: { raw: e.stderr ?? e.message, parsed: null },
-            diff: null,
+            diff: computeDiff(before, after),
         };
     }
 }

package/dist/engine/executor.js.map

@@ -1 +1 @@
-{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../src/engine/executor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAGtC,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAE1C;;;GAGG;AACH,SAAS,iBAAiB,CAAC,cAAwB;IACjD,IAAI,cAAc,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,OAAO,CAAC,GAAG,CAAC;IAEpD,MAAM,SAAS,GAAsB,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACvD,MAAM,KAAK,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC;QAChC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,EAAE,CAAC;YAC/D,SAAS,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACzB,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,GAAsB,EACtB,IAAwB,EACxB,GAAsB,EACtB,iBAA2B,EAAE;IAE7B,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAEzB,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,aAAa,CAAC,GAAG,EAAE,IAAI,EAAE;YACxD,GAAG;YACH,SAAS,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI,EAAE,QAAQ;YACrC,GAAG,EAAE,EAAE,GAAG,iBAAiB,CAAC,cAAc,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE;SACtE,CAAC,CAAC;QAEH,OAAO;YACL,EAAE,EAAW,IAAI;YACjB,QAAQ,EAAK,CAAC;YACd,GAAG;YACH,IAAI;YACJ,GAAG;YACH,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK;YAC/B,MAAM,EAAO,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE;YAC1C,MAAM,EAAO,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE;YAC1C,IAAI,EAAS,IAAI;SAClB,CAAC;IACJ,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,MAAM,CAAC,GAAG,GAIT,CAAC;QAEF,MAAM,QAAQ,GAAG,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QAEzD,OAAO;YACL,EAAE,EAAW,KAAK;YAClB,QAAQ;YACR,GAAG;YACH,IAAI;YACJ,GAAG;YACH,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK;YAC/B,MAAM,EAAO,EAAE,GAAG,EAAE,CAAC,CAAC,MAAM,IAAI,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE;YAClD,MAAM,EAAO,EAAE,GAAG,EAAE,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE;YACzD,IAAI,EAAS,IAAI;SAClB,CAAC;IACJ,CAAC;AACH,CAAC"}
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../src/engine/executor.ts"],"names":[],"mappings":"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"}

package/dist/engine/paginator.d.ts

@@ -0,0 +1,11 @@
+import type { PageInfo } from "../types/envelope.js";
+export interface PaginateResult {
+    lines: string[];
+    page_info: PageInfo;
+}
+/**
+ * raw stdout을 줄 단위로 분할하고 지정 페이지를 반환한다.
+ * trailing 빈 줄(마지막 newline으로 인한 빈 문자열)은 제외한다.
+ */
+export declare function paginateLines(raw: string, page: number, pageSize: number): PaginateResult;
+//# sourceMappingURL=paginator.d.ts.map

package/dist/engine/paginator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paginator.d.ts","sourceRoot":"","sources":["../../src/engine/paginator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAErD,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAM,MAAM,EAAE,CAAC;IACpB,SAAS,EAAE,QAAQ,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,cAAc,CAqBzF"}

package/dist/engine/paginator.js

@@ -0,0 +1,25 @@
+/**
+ * raw stdout을 줄 단위로 분할하고 지정 페이지를 반환한다.
+ * trailing 빈 줄(마지막 newline으로 인한 빈 문자열)은 제외한다.
+ */
+export function paginateLines(raw, page, pageSize) {
+    const allLines = raw.split("\n");
+    // trailing empty string from final newline 제거
+    if (allLines.length > 0 && allLines[allLines.length - 1] === "") {
+        allLines.pop();
+    }
+    const totalLines = allLines.length;
+    const start = page * pageSize;
+    const end = start + pageSize;
+    const sliced = allLines.slice(start, end);
+    return {
+        lines: sliced,
+        page_info: {
+            page,
+            page_size: pageSize,
+            total_lines: totalLines,
+            has_next: end < totalLines,
+        },
+    };
+}
+//# sourceMappingURL=paginator.js.map

package/dist/engine/paginator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paginator.js","sourceRoot":"","sources":["../../src/engine/paginator.ts"],"names":[],"mappings":"AAOA;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,GAAW,EAAE,IAAY,EAAE,QAAgB;IACvE,MAAM,QAAQ,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACjC,8CAA8C;IAC9C,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC;QAChE,QAAQ,CAAC,GAAG,EAAE,CAAC;IACjB,CAAC;IAED,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC;IACnC,MAAM,KAAK,GAAQ,IAAI,GAAG,QAAQ,CAAC;IACnC,MAAM,GAAG,GAAU,KAAK,GAAG,QAAQ,CAAC;IACpC,MAAM,MAAM,GAAO,QAAQ,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAE9C,OAAO;QACL,KAAK,EAAM,MAAM;QACjB,SAAS,EAAE;YACT,IAAI;YACJ,SAAS,EAAI,QAAQ;YACrB,WAAW,EAAE,UAAU;YACvB,QAAQ,EAAK,GAAG,GAAG,UAAU;SAC9B;KACF,CAAC;AACJ,CAAC"}

package/dist/engine/state-tracker.d.ts

@@ -0,0 +1,14 @@
+import type { DiffField } from "../types/envelope.js";
+/**
+ * 디렉토리 내 파일 경로 → mtime(ms) 맵.
+ */
+export type FileSnapshot = Map<string, number>;
+/**
+ * cwd 기준 depth 단계까지 재귀 스캔하여 파일 스냅샷을 반환한다.
+ */
+export declare function takeSnapshot(cwd: string, depth?: number): Promise<FileSnapshot>;
+/**
+ * 두 스냅샷을 비교하여 생성/삭제/수정된 경로 목록을 반환한다.
+ */
+export declare function computeDiff(before: FileSnapshot, after: FileSnapshot): DiffField;
+//# sourceMappingURL=state-tracker.d.ts.map

package/dist/engine/state-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-tracker.d.ts","sourceRoot":"","sources":["../../src/engine/state-tracker.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtD;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAwB/C;;GAEG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,SAAI,GAAG,OAAO,CAAC,YAAY,CAAC,CAIhF;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,YAAY,GAAG,SAAS,CAgBhF"}

package/dist/engine/state-tracker.js

@@ -0,0 +1,53 @@
+import { readdir, stat } from "node:fs/promises";
+async function walk(dir, depth, out) {
+    if (depth < 0)
+        return;
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return; // 권한 없음 등
+    }
+    for (const entry of entries) {
+        const full = `${dir}/${entry.name}`;
+        try {
+            const s = await stat(full);
+            out.set(full, s.mtimeMs);
+            if (entry.isDirectory())
+                await walk(full, depth - 1, out);
+        }
+        catch {
+            // 개별 항목 오류 무시
+        }
+    }
+}
+/**
+ * cwd 기준 depth 단계까지 재귀 스캔하여 파일 스냅샷을 반환한다.
+ */
+export async function takeSnapshot(cwd, depth = 2) {
+    const snap = new Map();
+    await walk(cwd, depth, snap);
+    return snap;
+}
+/**
+ * 두 스냅샷을 비교하여 생성/삭제/수정된 경로 목록을 반환한다.
+ */
+export function computeDiff(before, after) {
+    const created = [];
+    const deleted = [];
+    const modified = [];
+    for (const [path, mtime] of after) {
+        const prev = before.get(path);
+        if (prev === undefined)
+            created.push(path);
+        else if (prev !== mtime)
+            modified.push(path);
+    }
+    for (const path of before.keys()) {
+        if (!after.has(path))
+            deleted.push(path);
+    }
+    return { created, deleted, modified };
+}
+//# sourceMappingURL=state-tracker.js.map

package/dist/engine/state-tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-tracker.js","sourceRoot":"","sources":["../../src/engine/state-tracker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAQjD,KAAK,UAAU,IAAI,CAAC,GAAW,EAAE,KAAa,EAAE,GAAiB;IAC/D,IAAI,KAAK,GAAG,CAAC;QAAE,OAAO;IAEtB,IAAI,OAAO,CAAC;IACZ,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IACxD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,UAAU;IACpB,CAAC;IAED,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,IAAI,GAAG,GAAG,GAAG,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;QACpC,IAAI,CAAC;YACH,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC;YAC3B,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;YACzB,IAAI,KAAK,CAAC,WAAW,EAAE;gBAAE,MAAM,IAAI,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC;QAC5D,CAAC;QAAC,MAAM,CAAC;YACP,cAAc;QAChB,CAAC;IACH,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,GAAW,EAAE,KAAK,GAAG,CAAC;IACvD,MAAM,IAAI,GAAiB,IAAI,GAAG,EAAE,CAAC;IACrC,MAAM,IAAI,CAAC,GAAG,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;IAC7B,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,MAAoB,EAAE,KAAmB;IACnE,MAAM,OAAO,GAAc,EAAE,CAAC;IAC9B,MAAM,OAAO,GAAc,EAAE,CAAC;IAC9B,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,KAAK,EAAE,CAAC;QAClC,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC9B,IAAI,IAAI,KAAK,SAAS;YAAG,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;aACvC,IAAI,IAAI,KAAK,KAAK;YAAE,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC/C,CAAC;IAED,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;QACjC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3C,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;AACxC,CAAC"}

package/dist/parsers/fs/find.d.ts

@@ -1,4 +1,11 @@
-export declare function parseFind(cmd: string, args: string[], raw: string): {
+import type { ParseContext } from "../registry.js";
+export interface FindSummary {
+    total: number;
+    shown: number;
+    truncated: boolean;
+}
+export declare function parseFind(cmd: string, args: string[], raw: string, ctx?: ParseContext): {
     paths: string[];
+    _summary?: FindSummary;
 };
 //# sourceMappingURL=find.d.ts.map

package/dist/parsers/fs/find.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"find.d.ts","sourceRoot":"","sources":["../../../src/parsers/fs/find.ts"],"names":[],"mappings":"AAAA,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAGvF"}
+{"version":3,"file":"find.d.ts","sourceRoot":"","sources":["../../../src/parsers/fs/find.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAM,MAAM,CAAC;IAClB,KAAK,EAAM,MAAM,CAAC;IAClB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,wBAAgB,SAAS,CACvB,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,YAAY,GAC3D;IAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,EAAE,WAAW,CAAA;CAAE,CAW7C"}

package/dist/parsers/fs/find.js

@@ -1,5 +1,12 @@
-export function parseFind(cmd, args, raw) {
+export function parseFind(cmd, args, raw, ctx) {
     const paths = raw.split("\n").map(l => l.trim()).filter(Boolean);
+    const maxItems = ctx?.maxItems ?? 0;
+    if (maxItems > 0 && paths.length > maxItems) {
+        return {
+            paths: paths.slice(0, maxItems),
+            _summary: { total: paths.length, shown: maxItems, truncated: true },
+        };
+    }
     return { paths };
 }
 //# sourceMappingURL=find.js.map

package/dist/parsers/fs/find.js.map

@@ -1 +1 @@
-{"version":3,"file":"find.js","sourceRoot":"","sources":["../../../src/parsers/fs/find.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,SAAS,CAAC,GAAW,EAAE,IAAc,EAAE,GAAW;IAChE,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACjE,OAAO,EAAE,KAAK,EAAE,CAAC;AACnB,CAAC"}
+{"version":3,"file":"find.js","sourceRoot":"","sources":["../../../src/parsers/fs/find.ts"],"names":[],"mappings":"AAQA,MAAM,UAAU,SAAS,CACvB,GAAW,EAAE,IAAc,EAAE,GAAW,EAAE,GAAkB;IAE5D,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAEjE,MAAM,QAAQ,GAAG,GAAG,EAAE,QAAQ,IAAI,CAAC,CAAC;IACpC,IAAI,QAAQ,GAAG,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,QAAQ,EAAE,CAAC;QAC5C,OAAO;YACL,KAAK,EAAK,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC;YAClC,QAAQ,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE;SACpE,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,CAAC;AACnB,CAAC"}

package/dist/parsers/fs/ls.d.ts

@@ -1,3 +1,4 @@
+import type { ParseContext } from "../registry.js";
 export interface LsEntry {
     permissions: string;
     links: number;
@@ -8,7 +9,13 @@ export interface LsEntry {
     name: string;
     type: "file" | "directory" | "symlink" | "other";
 }
-export declare function parseLs(cmd: string, args: string[], raw: string): {
+export interface LsSummary {
+    total: number;
+    shown: number;
+    truncated: boolean;
+}
+export declare function parseLs(cmd: string, args: string[], raw: string, ctx?: ParseContext): {
     entries: LsEntry[];
+    _summary?: LsSummary;
 };
 //# sourceMappingURL=ls.d.ts.map

package/dist/parsers/fs/ls.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ls.d.ts","sourceRoot":"","sources":["../../../src/parsers/fs/ls.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,OAAO;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAQ,MAAM,CAAC;IACpB,KAAK,EAAQ,MAAM,CAAC;IACpB,KAAK,EAAQ,MAAM,CAAC;IACpB,UAAU,EAAG,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAS,MAAM,CAAC;IACpB,IAAI,EAAS,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;CACzD;AAED,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,OAAO,EAAE,CAAA;CAAE,CA6BxF"}
+{"version":3,"file":"ls.d.ts","sourceRoot":"","sources":["../../../src/parsers/fs/ls.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,MAAM,WAAW,OAAO;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAQ,MAAM,CAAC;IACpB,KAAK,EAAQ,MAAM,CAAC;IACpB,KAAK,EAAQ,MAAM,CAAC;IACpB,UAAU,EAAG,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAS,MAAM,CAAC;IACpB,IAAI,EAAS,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;CACzD;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAM,MAAM,CAAC;IAClB,KAAK,EAAM,MAAM,CAAC;IAClB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,wBAAgB,OAAO,CACrB,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,YAAY,GAC3D;IAAE,OAAO,EAAE,OAAO,EAAE,CAAC;IAAC,QAAQ,CAAC,EAAE,SAAS,CAAA;CAAE,CAoC9C"}

package/dist/parsers/fs/ls.js

@@ -1,4 +1,4 @@
-export function parseLs(cmd, args, raw) {
+export function parseLs(cmd, args, raw, ctx) {
     const entries = [];
     for (const line of raw.split("\n")) {
         if (!line || line.startsWith("total "))
@@ -21,6 +21,13 @@ export function parseLs(cmd, args, raw) {
                         : "other",
         });
     }
+    const maxItems = ctx?.maxItems ?? 0;
+    if (maxItems > 0 && entries.length > maxItems) {
+        return {
+            entries: entries.slice(0, maxItems),
+            _summary: { total: entries.length, shown: maxItems, truncated: true },
+        };
+    }
     return { entries };
 }
 //# sourceMappingURL=ls.js.map

package/dist/parsers/fs/ls.js.map

@@ -1 +1 @@
-{"version":3,"file":"ls.js","sourceRoot":"","sources":["../../../src/parsers/fs/ls.ts"],"names":[],"mappings":"AAWA,MAAM,UAAU,OAAO,CAAC,GAAW,EAAE,IAAc,EAAE,GAAW;IAC9D,MAAM,OAAO,GAAc,EAAE,CAAC;IAE9B,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACnC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;YAAE,SAAS;QAEjD,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAClB,0FAA0F,CAC3F,CAAC;QACF,IAAI,CAAC,CAAC;YAAE,SAAS;QAEjB,MAAM,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;QAEtE,OAAO,CAAC,IAAI,CAAC;YACX,WAAW,EAAE,QAAQ,GAAG,KAAK;YAC7B,KAAK,EAAQ,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC;YAChC,KAAK;YACL,KAAK;YACL,UAAU,EAAG,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC;YAC/B,WAAW,EAAE,KAAK,CAAC,IAAI,EAAE;YACzB,IAAI,EAAS,IAAI,CAAC,IAAI,EAAE;YACxB,IAAI,EAAS,QAAQ,KAAK,GAAG,CAAC,CAAC,CAAC,WAAW;gBAChC,CAAC,CAAC,QAAQ,KAAK,GAAG,CAAC,CAAC,CAAC,SAAS;oBAC9B,CAAC,CAAC,QAAQ,KAAK,GAAG,CAAC,CAAC,CAAC,MAAM;wBAC3B,CAAC,CAAC,OAAO;SACrB,CAAC,CAAC;IACL,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,CAAC;AACrB,CAAC"}
+{"version":3,"file":"ls.js","sourceRoot":"","sources":["../../../src/parsers/fs/ls.ts"],"names":[],"mappings":"AAmBA,MAAM,UAAU,OAAO,CACrB,GAAW,EAAE,IAAc,EAAE,GAAW,EAAE,GAAkB;IAE5D,MAAM,OAAO,GAAc,EAAE,CAAC;IAE9B,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACnC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;YAAE,SAAS;QAEjD,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAClB,0FAA0F,CAC3F,CAAC;QACF,IAAI,CAAC,CAAC;YAAE,SAAS;QAEjB,MAAM,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;QAEtE,OAAO,CAAC,IAAI,CAAC;YACX,WAAW,EAAE,QAAQ,GAAG,KAAK;YAC7B,KAAK,EAAQ,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC;YAChC,KAAK;YACL,KAAK;YACL,UAAU,EAAG,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC;YAC/B,WAAW,EAAE,KAAK,CAAC,IAAI,EAAE;YACzB,IAAI,EAAS,IAAI,CAAC,IAAI,EAAE;YACxB,IAAI,EAAS,QAAQ,KAAK,GAAG,CAAC,CAAC,CAAC,WAAW;gBAChC,CAAC,CAAC,QAAQ,KAAK,GAAG,CAAC,CAAC,CAAC,SAAS;oBAC9B,CAAC,CAAC,QAAQ,KAAK,GAAG,CAAC,CAAC,CAAC,MAAM;wBAC3B,CAAC,CAAC,OAAO;SACrB,CAAC,CAAC;IACL,CAAC;IAED,MAAM,QAAQ,GAAG,GAAG,EAAE,QAAQ,IAAI,CAAC,CAAC;IACpC,IAAI,QAAQ,GAAG,CAAC,IAAI,OAAO,CAAC,MAAM,GAAG,QAAQ,EAAE,CAAC;QAC9C,OAAO;YACL,OAAO,EAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC;YACpC,QAAQ,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE;SACtE,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,CAAC;AACrB,CAAC"}

package/dist/parsers/process/ps.d.ts

@@ -1,3 +1,4 @@
+import type { ParseContext } from "../registry.js";
 export interface PsEntry {
     user: string;
     pid: number;
@@ -11,7 +12,13 @@ export interface PsEntry {
     time: string;
     command: string;
 }
-export declare function parsePs(cmd: string, args: string[], raw: string): {
+export interface PsSummary {
+    total: number;
+    shown: number;
+    truncated: boolean;
+}
+export declare function parsePs(cmd: string, args: string[], raw: string, ctx?: ParseContext): {
     processes: PsEntry[];
+    _summary?: PsSummary;
 };
 //# sourceMappingURL=ps.d.ts.map

package/dist/parsers/process/ps.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ps.d.ts","sourceRoot":"","sources":["../../../src/parsers/process/ps.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,OAAO;IACtB,IAAI,EAAK,MAAM,CAAC;IAChB,GAAG,EAAM,MAAM,CAAC;IAChB,GAAG,EAAM,MAAM,CAAC;IAChB,GAAG,EAAM,MAAM,CAAC;IAChB,GAAG,EAAM,MAAM,CAAC;IAChB,GAAG,EAAM,MAAM,CAAC;IAChB,GAAG,EAAM,MAAM,CAAC;IAChB,IAAI,EAAK,MAAM,CAAC;IAChB,KAAK,EAAI,MAAM,CAAC;IAChB,IAAI,EAAK,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG;IAAE,SAAS,EAAE,OAAO,EAAE,CAAA;CAAE,CAuB1F"}
+{"version":3,"file":"ps.d.ts","sourceRoot":"","sources":["../../../src/parsers/process/ps.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,MAAM,WAAW,OAAO;IACtB,IAAI,EAAK,MAAM,CAAC;IAChB,GAAG,EAAM,MAAM,CAAC;IAChB,GAAG,EAAM,MAAM,CAAC;IAChB,GAAG,EAAM,MAAM,CAAC;IAChB,GAAG,EAAM,MAAM,CAAC;IAChB,GAAG,EAAM,MAAM,CAAC;IAChB,GAAG,EAAM,MAAM,CAAC;IAChB,IAAI,EAAK,MAAM,CAAC;IAChB,KAAK,EAAI,MAAM,CAAC;IAChB,IAAI,EAAK,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAM,MAAM,CAAC;IAClB,KAAK,EAAM,MAAM,CAAC;IAClB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,wBAAgB,OAAO,CACrB,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,YAAY,GAC3D;IAAE,SAAS,EAAE,OAAO,EAAE,CAAC;IAAC,QAAQ,CAAC,EAAE,SAAS,CAAA;CAAE,CA8BhD"}

package/dist/parsers/process/ps.js

@@ -1,4 +1,4 @@
-export function parsePs(cmd, args, raw) {
+export function parsePs(cmd, args, raw, ctx) {
     const lines = raw.split("\n").filter(Boolean);
     const processes = [];
     for (const line of lines.slice(1)) {
@@ -19,6 +19,13 @@ export function parsePs(cmd, args, raw) {
             command: cols.slice(10).join(" "),
         });
     }
+    const maxItems = ctx?.maxItems ?? 0;
+    if (maxItems > 0 && processes.length > maxItems) {
+        return {
+            processes: processes.slice(0, maxItems),
+            _summary: { total: processes.length, shown: maxItems, truncated: true },
+        };
+    }
     return { processes };
 }
 //# sourceMappingURL=ps.js.map

package/dist/parsers/process/ps.js.map

@@ -1 +1 @@
-{"version":3,"file":"ps.js","sourceRoot":"","sources":["../../../src/parsers/process/ps.ts"],"names":[],"mappings":"AAcA,MAAM,UAAU,OAAO,CAAC,GAAW,EAAE,IAAc,EAAE,GAAW;IAC9D,MAAM,KAAK,GAAO,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAClD,MAAM,SAAS,GAAc,EAAE,CAAC;IAEhC,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACtC,IAAI,IAAI,CAAC,MAAM,GAAG,EAAE;YAAE,SAAS;QAC/B,SAAS,CAAC,IAAI,CAAC;YACb,IAAI,EAAK,IAAI,CAAC,CAAC,CAAC;YAChB,GAAG,EAAM,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;YAC9B,GAAG,EAAM,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAC5B,GAAG,EAAM,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAC5B,GAAG,EAAM,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;YAC9B,GAAG,EAAM,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;YAC9B,GAAG,EAAM,IAAI,CAAC,CAAC,CAAC;YAChB,IAAI,EAAK,IAAI,CAAC,CAAC,CAAC;YAChB,KAAK,EAAI,IAAI,CAAC,CAAC,CAAC;YAChB,IAAI,EAAK,IAAI,CAAC,CAAC,CAAC;YAChB,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC;SAClC,CAAC,CAAC;IACL,CAAC;IAED,OAAO,EAAE,SAAS,EAAE,CAAC;AACvB,CAAC"}
+{"version":3,"file":"ps.js","sourceRoot":"","sources":["../../../src/parsers/process/ps.ts"],"names":[],"mappings":"AAsBA,MAAM,UAAU,OAAO,CACrB,GAAW,EAAE,IAAc,EAAE,GAAW,EAAE,GAAkB;IAE5D,MAAM,KAAK,GAAO,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAClD,MAAM,SAAS,GAAc,EAAE,CAAC;IAEhC,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACtC,IAAI,IAAI,CAAC,MAAM,GAAG,EAAE;YAAE,SAAS;QAC/B,SAAS,CAAC,IAAI,CAAC;YACb,IAAI,EAAK,IAAI,CAAC,CAAC,CAAC;YAChB,GAAG,EAAM,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;YAC9B,GAAG,EAAM,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAC5B,GAAG,EAAM,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAC5B,GAAG,EAAM,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;YAC9B,GAAG,EAAM,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;YAC9B,GAAG,EAAM,IAAI,CAAC,CAAC,CAAC;YAChB,IAAI,EAAK,IAAI,CAAC,CAAC,CAAC;YAChB,KAAK,EAAI,IAAI,CAAC,CAAC,CAAC;YAChB,IAAI,EAAK,IAAI,CAAC,CAAC,CAAC;YAChB,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC;SAClC,CAAC,CAAC;IACL,CAAC;IAED,MAAM,QAAQ,GAAG,GAAG,EAAE,QAAQ,IAAI,CAAC,CAAC;IACpC,IAAI,QAAQ,GAAG,CAAC,IAAI,SAAS,CAAC,MAAM,GAAG,QAAQ,EAAE,CAAC;QAChD,OAAO;YACL,SAAS,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC;YACvC,QAAQ,EAAG,EAAE,KAAK,EAAE,SAAS,CAAC,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE;SACzE,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,CAAC;AACvB,CAAC"}

package/dist/parsers/registry.d.ts

@@ -1,7 +1,14 @@
+/**
+ * 파서가 항목 수를 제한할 때 사용하는 컨텍스트.
+ * maxItems=0 이면 무제한.
+ */
+export interface ParseContext {
+    maxItems: number;
+}
 /**
  * 파서 함수 시그니처.
  */
-export type ParserFn = (cmd: string, args: string[], raw: string) => unknown;
+export type ParserFn = (cmd: string, args: string[], raw: string, ctx?: ParseContext) => unknown;
 /**
  * 명령어 → 파서 함수의 매핑 테이블.
  * 파서가 없거나 실패하면 null을 반환한다 (graceful degradation).
@@ -13,6 +20,6 @@ export declare class ParserRegistry {
      * cmd에 등록된 파서를 찾아 실행한다.
      * 파서 없음 또는 예외 → null 반환.
      */
-    parse(cmd: string, args: string[], raw: string): unknown | null;
+    parse(cmd: string, args: string[], raw: string, ctx?: ParseContext): unknown | null;
 }
 //# sourceMappingURL=registry.d.ts.map

package/dist/parsers/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/parsers/registry.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;AAE7E;;;GAGG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA+B;IAEvD,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,GAAG,IAAI;IAIzC;;;OAGG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI;CAUhE"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/parsers/registry.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,YAAY,KAAK,OAAO,CAAC;AAEjG;;;GAGG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA+B;IAEvD,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,GAAG,IAAI;IAIzC;;;OAGG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,YAAY,GAAG,OAAO,GAAG,IAAI;CAUpF"}

package/dist/parsers/registry.js

@@ -11,12 +11,12 @@ export class ParserRegistry {
      * cmd에 등록된 파서를 찾아 실행한다.
      * 파서 없음 또는 예외 → null 반환.
      */
-    parse(cmd, args, raw) {
+    parse(cmd, args, raw, ctx) {
         const fn = this.parsers.get(cmd);
         if (!fn)
             return null;
         try {
-            return fn(cmd, args, raw);
+            return fn(cmd, args, raw, ctx);
         }
         catch {
             return null;

package/dist/parsers/registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/parsers/registry.ts"],"names":[],"mappings":"AAKA;;;GAGG;AACH,MAAM,OAAO,cAAc;IACR,OAAO,GAAG,IAAI,GAAG,EAAoB,CAAC;IAEvD,QAAQ,CAAC,GAAW,EAAE,EAAY;QAChC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IAC5B,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,GAAW,EAAE,IAAc,EAAE,GAAW;QAC5C,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,CAAC,EAAE;YAAE,OAAO,IAAI,CAAC;QAErB,IAAI,CAAC;YACH,OAAO,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;QAC5B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;CACF"}
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/parsers/registry.ts"],"names":[],"mappings":"AAaA;;;GAGG;AACH,MAAM,OAAO,cAAc;IACR,OAAO,GAAG,IAAI,GAAG,EAAoB,CAAC;IAEvD,QAAQ,CAAC,GAAW,EAAE,EAAY;QAChC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IAC5B,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,GAAW,EAAE,IAAc,EAAE,GAAW,EAAE,GAAkB;QAChE,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,CAAC,EAAE;YAAE,OAAO,IAAI,CAAC;QAErB,IAAI,CAAC;YACH,OAAO,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;QACjC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;CACF"}

package/dist/parsers/text/grep.d.ts

@@ -1,9 +1,16 @@
+import type { ParseContext } from "../registry.js";
 export interface GrepMatch {
     file: string;
     line: number;
     text: string;
 }
-export declare function parseGrep(cmd: string, args: string[], raw: string): {
+export interface GrepSummary {
+    total: number;
+    shown: number;
+    truncated: boolean;
+}
+export declare function parseGrep(cmd: string, args: string[], raw: string, ctx?: ParseContext): {
     matches: GrepMatch[];
+    _summary?: GrepSummary;
 };
 //# sourceMappingURL=grep.d.ts.map

package/dist/parsers/text/grep.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"grep.d.ts","sourceRoot":"","sources":["../../../src/parsers/text/grep.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,SAAS,EAAE,CAAA;CAAE,CA+B5F"}
+{"version":3,"file":"grep.d.ts","sourceRoot":"","sources":["../../../src/parsers/text/grep.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAM,MAAM,CAAC;IAClB,KAAK,EAAM,MAAM,CAAC;IAClB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,wBAAgB,SAAS,CACvB,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,YAAY,GAC3D;IAAE,OAAO,EAAE,SAAS,EAAE,CAAC;IAAC,QAAQ,CAAC,EAAE,WAAW,CAAA;CAAE,CA6ClD"}

package/dist/parsers/text/grep.js

@@ -1,9 +1,15 @@
-export function parseGrep(cmd, args, raw) {
+export function parseGrep(cmd, args, raw, ctx) {
     const matches = [];
     for (const line of raw.split("\n")) {
         if (!line.trim())
             continue;
-        // file:line:text 형태 (grep -rn 또는 grep -n)
+        // Case 1: 첫 세그먼트가 순수 숫자 → linenum:text (단일파일 grep -n)
+        const lineNumOnly = line.match(/^(\d+):(.*)$/);
+        if (lineNumOnly) {
+            matches.push({ file: "", line: parseInt(lineNumOnly[1], 10), text: lineNumOnly[2] });
+            continue;
+        }
+        // Case 2: file:linenum:text 형태 (grep -rn 또는 다중파일 -n)
         const withLineNum = line.match(/^([^:]+):(\d+):(.*)$/);
         if (withLineNum) {
             matches.push({
@@ -13,7 +19,7 @@ export function parseGrep(cmd, args, raw) {
             });
             continue;
         }
-        // file:text 형태 (grep -r without -n) — 콜론 앞이 파일 경로
+        // Case 3: file:text 형태 (grep -r without -n) — 콜론 앞이 파일 경로
         const colonIdx = line.indexOf(":");
         if (colonIdx > 0) {
             matches.push({
@@ -26,6 +32,13 @@ export function parseGrep(cmd, args, raw) {
             matches.push({ file: "", line: 0, text: line });
         }
     }
+    const maxItems = ctx?.maxItems ?? 0;
+    if (maxItems > 0 && matches.length > maxItems) {
+        return {
+            matches: matches.slice(0, maxItems),
+            _summary: { total: matches.length, shown: maxItems, truncated: true },
+        };
+    }
     return { matches };
 }
 //# sourceMappingURL=grep.js.map

package/dist/parsers/text/grep.js.map

@@ -1 +1 @@
-{"version":3,"file":"grep.js","sourceRoot":"","sources":["../../../src/parsers/text/grep.ts"],"names":[],"mappings":"AAMA,MAAM,UAAU,SAAS,CAAC,GAAW,EAAE,IAAc,EAAE,GAAW;IAChE,MAAM,OAAO,GAAgB,EAAE,CAAC;IAEhC,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACnC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE;YAAE,SAAS;QAE3B,0CAA0C;QAC1C,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAC;QACvD,IAAI,WAAW,EAAE,CAAC;YAChB,OAAO,CAAC,IAAI,CAAC;gBACX,IAAI,EAAE,WAAW,CAAC,CAAC,CAAE;gBACrB,IAAI,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAE,EAAE,EAAE,CAAC;gBACnC,IAAI,EAAE,WAAW,CAAC,CAAC,CAAE;aACtB,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,kDAAkD;QAClD,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;YACjB,OAAO,CAAC,IAAI,CAAC;gBACX,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC;gBAC7B,IAAI,EAAE,CAAC;gBACP,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAC;aAC/B,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAClD,CAAC;IACH,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,CAAC;AACrB,CAAC"}
+{"version":3,"file":"grep.js","sourceRoot":"","sources":["../../../src/parsers/text/grep.ts"],"names":[],"mappings":"AAcA,MAAM,UAAU,SAAS,CACvB,GAAW,EAAE,IAAc,EAAE,GAAW,EAAE,GAAkB;IAE5D,MAAM,OAAO,GAAgB,EAAE,CAAC;IAEhC,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACnC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE;YAAE,SAAS;QAE3B,sDAAsD;QACtD,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;QAC/C,IAAI,WAAW,EAAE,CAAC;YAChB,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAE,EAAE,EAAE,CAAC,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC,CAAE,EAAE,CAAC,CAAC;YACvF,SAAS;QACX,CAAC;QAED,qDAAqD;QACrD,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAC;QACvD,IAAI,WAAW,EAAE,CAAC;YAChB,OAAO,CAAC,IAAI,CAAC;gBACX,IAAI,EAAE,WAAW,CAAC,CAAC,CAAE;gBACrB,IAAI,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAE,EAAE,EAAE,CAAC;gBACnC,IAAI,EAAE,WAAW,CAAC,CAAC,CAAE;aACtB,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,0DAA0D;QAC1D,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;YACjB,OAAO,CAAC,IAAI,CAAC;gBACX,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC;gBAC7B,IAAI,EAAE,CAAC;gBACP,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAC;aAC/B,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAClD,CAAC;IACH,CAAC;IAED,MAAM,QAAQ,GAAG,GAAG,EAAE,QAAQ,IAAI,CAAC,CAAC;IACpC,IAAI,QAAQ,GAAG,CAAC,IAAI,OAAO,CAAC,MAAM,GAAG,QAAQ,EAAE,CAAC;QAC9C,OAAO;YACL,OAAO,EAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC;YACpC,QAAQ,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE;SACtE,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,CAAC;AACrB,CAAC"}

package/dist/server.d.ts

@@ -5,6 +5,11 @@ import type { PrismConfig } from "./config/loader.js";
  * MCP 서버와 테스트 코드가 공통으로 사용한다.
  */
 export declare function buildRunResult(cmd: string, args: string[], cwd: string, config: PrismConfig): Promise<string>;
+/**
+ * Guard 검사 → 실행 → 페이지 분할 → JSON 직렬화.
+ * parsed는 항상 null (부분 출력은 구조화 파싱 불가).
+ */
+export declare function buildPagedResult(cmd: string, args: string[], cwd: string, page: number, pageSize: number, config: PrismConfig): Promise<string>;
 /**
  * MCP 서버를 생성하고 `run` 도구를 등록한다.
  */

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAmB,yCAAyC,CAAC;AAMjF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAY,oBAAoB,CAAC;AAI5D;;;GAGG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAK,MAAM,EACd,IAAI,EAAI,MAAM,EAAE,EAChB,GAAG,EAAK,MAAM,EACd,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,MAAM,CAAC,CA0BjB;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,CAwB3D"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAmB,yCAAyC,CAAC;AAOjF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAY,oBAAoB,CAAC;AAI5D;;;GAGG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAK,MAAM,EACd,IAAI,EAAI,MAAM,EAAE,EAChB,GAAG,EAAK,MAAM,EACd,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,MAAM,CAAC,CA+BjB;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAO,MAAM,EAChB,IAAI,EAAM,MAAM,EAAE,EAClB,GAAG,EAAO,MAAM,EAChB,IAAI,EAAM,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAI,WAAW,GACpB,OAAO,CAAC,MAAM,CAAC,CAqCjB;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,CA2C3D"}

package/dist/server.js

@@ -3,7 +3,8 @@ import { z } from "zod";
 import { execute } from "./engine/executor.js";
 import { checkGuard, GuardError } from "./engine/guard.js";
 import { defaultRegistry } from "./parsers/index.js";
-const PACKAGE_VERSION = "0.1.2";
+import { paginateLines } from "./engine/paginator.js";
+const PACKAGE_VERSION = "0.1.4";
 /**
  * Guard 검사 → 실행 → JSON 직렬화까지의 파이프라인.
  * MCP 서버와 테스트 코드가 공통으로 사용한다.
@@ -30,11 +31,48 @@ export async function buildRunResult(cmd, args, cwd, config) {
         }
         throw err;
     }
-    const envelope = await execute(cmd, args, cwd, config.guard.env_secret_patterns);
-    const parsed = defaultRegistry.parse(cmd, args, envelope.stdout.raw);
+    const envelope = await execute(cmd, args, cwd, config.guard.env_secret_patterns, config.guard.timeout_ms, config.guard.max_output_bytes);
+    const parsed = defaultRegistry.parse(cmd, args, envelope.stdout.raw, { maxItems: config.guard.max_items });
     const enriched = { ...envelope, stdout: { ...envelope.stdout, parsed } };
     return JSON.stringify(enriched, null, 2);
 }
+/**
+ * Guard 검사 → 실행 → 페이지 분할 → JSON 직렬화.
+ * parsed는 항상 null (부분 출력은 구조화 파싱 불가).
+ */
+export async function buildPagedResult(cmd, args, cwd, page, pageSize, config) {
+    try {
+        checkGuard(cmd, args, cwd, config);
+    }
+    catch (err) {
+        if (err instanceof GuardError) {
+            const envelope = {
+                ok: false,
+                exitCode: -1,
+                cmd,
+                args,
+                cwd,
+                duration_ms: 0,
+                stdout: { raw: "", parsed: null },
+                stderr: { raw: err.message, parsed: null },
+                diff: null,
+                guard_error: { reason: err.reason, message: err.message },
+            };
+            return JSON.stringify(envelope, null, 2);
+        }
+        throw err;
+    }
+    // 전체 stdout이 필요하므로 max_output_bytes 비활성 (0)
+    const envelope = await execute(cmd, args, cwd, config.guard.env_secret_patterns, config.guard.timeout_ms, 0);
+    const { lines, page_info } = paginateLines(envelope.stdout.raw, page, pageSize);
+    const pagedRaw = lines.join("\n") + (lines.length > 0 ? "\n" : "");
+    const enriched = {
+        ...envelope,
+        stdout: { raw: pagedRaw, parsed: null },
+        page_info,
+    };
+    return JSON.stringify(enriched, null, 2);
+}
 /**
  * MCP 서버를 생성하고 `run` 도구를 등록한다.
  */
@@ -54,6 +92,19 @@ export function createServer(config) {
             content: [{ type: "text", text: result }],
         };
     });
+    server.tool("run_paged", "Execute a shell command and return paginated stdout. " +
+        "Use this for commands with large output (ps aux, find, grep -r). " +
+        "Returns page_info with total_lines and has_next for navigation.", {
+        cmd: z.string().describe("Command name"),
+        args: z.array(z.string()).default([]).describe("Command arguments"),
+        cwd: z.string().default(process.cwd()).describe("Working directory"),
+        page: z.number().int().min(0).default(0).describe("Page index (0-based)"),
+        page_size: z.number().int().min(1).default(config.guard.default_page_size)
+            .describe("Lines per page"),
+    }, async ({ cmd, args, cwd, page, page_size }) => {
+        const result = await buildPagedResult(cmd, args, cwd, page, page_size, config);
+        return { content: [{ type: "text", text: result }] };
+    });
     return server;
 }
 //# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/types/envelope.d.ts

@@ -14,6 +14,15 @@ export interface DiffField {
     deleted: string[];
     modified: string[];
 }
+/**
+ * run_paged 응답에 포함되는 페이지 메타데이터.
+ */
+export interface PageInfo {
+    page: number;
+    page_size: number;
+    total_lines: number;
+    has_next: boolean;
+}
 /**
  * Prism의 모든 명령 실행 결과가 따르는 응답 봉투.
  * - ok: 실행 성공 여부 (exitCode === 0)
@@ -29,5 +38,7 @@ export interface ResponseEnvelope {
     stdout: OutputField;
     stderr: OutputField;
     diff: DiffField | null;
+    truncated?: boolean;
+    page_info?: PageInfo;
 }
 //# sourceMappingURL=envelope.d.ts.map

package/dist/types/envelope.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../../src/types/envelope.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAK,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;CACxB;AAGD,MAAM,MAAM,WAAW,GAAG,WAAW,CAAC;AAEtC;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,OAAO,EAAG,MAAM,EAAE,CAAC;IACnB,OAAO,EAAG,MAAM,EAAE,CAAC;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAW,OAAO,CAAC;IACrB,QAAQ,EAAK,MAAM,CAAC;IACpB,GAAG,EAAU,MAAM,CAAC;IACpB,IAAI,EAAS,MAAM,EAAE,CAAC;IACtB,GAAG,EAAU,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAO,WAAW,CAAC;IACzB,MAAM,EAAO,WAAW,CAAC;IACzB,IAAI,EAAS,SAAS,GAAG,IAAI,CAAC;CAC/B"}
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../../src/types/envelope.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAK,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;CACxB;AAGD,MAAM,MAAM,WAAW,GAAG,WAAW,CAAC;AAEtC;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,OAAO,EAAG,MAAM,EAAE,CAAC;IACnB,OAAO,EAAG,MAAM,EAAE,CAAC;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAS,MAAM,CAAC;IACpB,SAAS,EAAI,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAK,OAAO,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAW,OAAO,CAAC;IACrB,QAAQ,EAAK,MAAM,CAAC;IACpB,GAAG,EAAU,MAAM,CAAC;IACpB,IAAI,EAAS,MAAM,EAAE,CAAC;IACtB,GAAG,EAAU,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAO,WAAW,CAAC;IACzB,MAAM,EAAO,WAAW,CAAC;IACzB,IAAI,EAAS,SAAS,GAAG,IAAI,CAAC;IAC9B,SAAS,CAAC,EAAG,OAAO,CAAC;IACrB,SAAS,CAAC,EAAG,QAAQ,CAAC;CACvB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nerdvana/parism",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Structured shell output wrapper for AI agents",
   "type": "module",
   "main": "dist/index.js",
@@ -23,6 +23,11 @@
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   },
-  "files": ["dist", "prism.config.json"],
-  "engines": { "node": ">=20" }
+  "files": [
+    "dist",
+    "prism.config.json"
+  ],
+  "engines": {
+    "node": ">=20"
+  }
 }