Parism

Refract the Shell. Every command, structured.

문서:README·SPECIFICATION·SECURITY·CHANGELOG

설계 결정, 버전 이력, 모듈 구조의 단일 권위 문서:SPECIFICATION.md

"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" }

"stdout": { "raw": "drwxr-xr-x ...", "parsed": { "entries": [ ... ] } }

성공이든 실패든,ok와exitCode는 항상 같은 자리에 있다. 에이전트가 분기 처리를 작성하는 방식이 단순해진다. "stdout을 파싱해서 오류인지 확인"이 아니라if (!result.ok)다.

모든 응답에duration_ms가 포함된다. 명령이 느린지 빠른지를 에이전트가 판단하는 데 쓸 수 있다. 디버깅할 때도 유용하다.

includeDiff: true일 때만diff에created,deleted,modified가 채워진다. run/run_paged 기본값은includeDiff: false이므로 스냅샷 비용을 생략하여 MCP 호출 지연을 줄인다.

에이전트는 오류를 범한다. 문맥을 잃고, 경로를 착각하고, 의도하지 않은 명령을 생성한다. Guard는 에이전트를 불신하는 것이 아니다. 에이전트의 실수가 파국으로 이어지지 않도록 설계하는 것이다.

화이트리스트:allowed_commands에 없는 명령어는 실행되지 않는다. 프로세스를 만들지도 않는다. 설명 없이 거절한다.

경로 제한:allowed_paths를 설정하면cwd와 경로 인자를 검사한다./,./,../로 시작하는 인자와,cat,find,ls,grep,git,docker,kubectl,cargo등 경로를 받는 명령의 positional 인자(cat subdir/file,find src)도 허용 경로 밖이면 차단된다. 커널 수준 샌드박스는 아니며, 가드 수준의 방어선이다.

인젝션 패턴 차단: 각 인자를 개별적으로 순회하며;,$(,``,&&,||,|,>,>>,<가 포함되면 실행하지 않는다. 인자 단위 검사이므로 서로 다른 인자 경계를 넘어서는 오탐이 발생하지 않는다.

명령별 인자 제한: 명령마다 차단할 플래그를 지정할 수 있다.node -e,node --eval,node --input-type은 기본 차단된다.npx --yes도 기본 차단된다.

{ "ok": false, "guard_error": { "reason": "command_not_allowed", "message": "Command 'rm' is not in the allowed list" }, "failure": { "kind": "guard", "reason": "command_not_allowed", "message": "Command 'rm' is not in the allowed list" } }

v0.6 부터failure필드가 권위 필드다.guard_error는 하위 호환을 위해 유지된다. 에이전트는result.failure.kind로 분기하는 것을 권장한다.

git clone https://github.com/JinHo-von-Choi/parism cd parism npm install && npm run build node dist/index.js

import { createEngine } from "@nerdvana/parism/engine"; const engine = await createEngine(); const result = await engine.run("ls", { args: ["-la"] }); console.log(result.stdout.parsed);

createEngine()은prism.config.json을 로드하고 외부 파서를 등록한 뒤ParismEngine인스턴스를 반환한다. 커스텀 설정 경로가 필요하면createEngine({ configPath: "/path/to/prism.config.json" })을 사용한다.

import { createEngine } from "@nerdvana/parism/engine"; const engine = await createEngine({ configPath: "/path/to/custom/prism.config.json", }); const result = await engine.run("git", { args: ["status", "--porcelain"] }); if (!result.ok) { console.error([${result.failure?.kind}] ${result.failure?.reason}: ${result.failure?.message}); process.exit(1); } console.log(result.stdout.parsed);

RunOptions —args/cwd/format/includeDiff. RunPagedOptions — 위 옵션 전체 +page/page_size.

Parism 은 MCP stdio 프로토콜을 통해 주요 AI CLI/IDE 에 연결할 수 있다. 클라이언트별 상세 설정은docs/mcp-clients/디렉토리를 참조한다.

연결이 성공하면run,run_paged,describe,dry_run네 도구가 노출된다. 에이전트는 먼저describe로 허용 명령과 파서를 파악하고,dry_run으로 guard 통과 여부를 사전 확인한 뒤,run/run_paged로 명령을 실행하고 구조화된 JSON 응답을 받는다.

- cmd— 명령어 이름 (예:ls,git)
- args— 인자 배열 (기본값:[])
- cwd— 작업 디렉토리 (기본값: 현재 디렉토리)
- format— 출력 형식 ("json"기본값,"compact","json-no-raw"). compact는 리스트형 출력을 schema+rows 컬럼 기반으로 압축하여 토큰 비용을 절감한다.
- includeDiff— 파일시스템 diff 포함 여부 (기본값:false).false면 스냅샷 생략으로 지연 감소. MCP 고빈도 호출 시 권장.

{ "schema": ["name", "type", "size_bytes"], "rows": [["src", "directory", 4096], ["main.ts", "file", 1200]] }

대용량 출력을 페이지 단위로 읽는다.ps aux,find,grep -r등에 사용한다.

- cmd,args,cwd—run과 동일
- page— 0-indexed 페이지 번호 (기본값:0)
- page_size— 페이지당 줄 수 (기본값:default_page_size설정값, 기본 100)
- includeDiff— 파일시스템 diff 포함 여부 (기본값:false).false면 스냅샷 생략으로 지연 감소.

- 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) 추가 호출

- version— Parism 패키지 버전
- allowed_commands— guard에서 허용하는 명령 목록
- available_parsers— 등록된 파서 이름 목록
- guard_summary—timeout_ms,max_output_bytes,max_items,block_patterns(전체 배열),allowed_paths
- telemetry_enabled— 텔레메트리 활성화 여부

- cmd— 명령어 이름 (예:rm,git)
- args— 인자 배열 (기본값:[])
- cwd— 작업 디렉토리 (기본값: 현재 디렉토리)

- would_pass— guard 통과 여부
- reason— 차단 시 사유 (command_not_allowed,path_not_allowed,injection_pattern,arg_not_allowed)
- message— 차단 시 상세 메시지

예:dry_run("rm", ["-rf", "/"])→{ would_pass: false, reason: "command_not_allowed", message: "..." }

prism.config.json을 프로젝트 루트에 두면 Guard 동작을 제어할 수 있다.

{ "guard": { "allowed_commands": ["ls", "git", "find", "grep", "env", "ps"], "allowed_paths": ["/home/user/projects"], "timeout_ms": 10000, "max_output_bytes": 102400, "max_items": 500, "default_page_size": 100, "block_patterns": [";", "$(", "", "&&", "||", ">", ">>", "<", "|"], "command_arg_restrictions": { "node": { "blocked_flags": ["-e", "--eval", "-r", "--require", "-p", "--print", "--input-type"] }, "npx": { "blocked_flags": ["--yes", "-y"] } }, "secrets": { "env_patterns": ["TOKEN", "SECRET", "AUTHZ", "PASSWORD", "PASSWD", "CREDENTIAL"], "output_patterns": ["Bearer [A-Za-z0-9._\\-]+", "ghp_[A-Za-z0-9]+"], "output_redaction_enabled": false } }, "parsers": { "strict_schemas": false }, "telemetry": { "enabled": false } }

allowed_paths가 비어 있으면 경로 제한 없이 실행된다. 판단은 당신 몫이다.

guard.secrets.env_patterns에 일치하는 환경 변수는 실행 전 자식 프로세스에서 제거된다.env명령 실행 시 해당 변수가 노출되지 않는다.

guard.secrets.output_redaction_enabled는 기본false로 opt-in 방식이다.true로 설정하면output_patterns에 매칭되는 문자열을 명령 실행 후 raw 출력에서[REDACTED]로 대체한다. 파싱 전에 적용되므로stdout.parsed결과에는 영향을 주지 않는다.

command_arg_restrictions는 기본값과 병합된다. 일부 명령만 override해도 나머지 기본 제한은 유지된다.

parsers.strict_schemas를true로 설정하면 각 파서의 Zod 스키마로 파싱 결과를 검증한다. 스키마 위반 시failure.reason === "schema_violation"을 반환한다. 기본false이며 opt-in 방식이다.

telemetry.enabled를true로 설정하면 응답 봉투에telemetry필드가 추가된다. guard/exec/parse/redact 각 단계의 소요 시간(ms)과 raw 출력 바이트 수를 포함한다. 기본false이며 opt-in 방식이다.

legacyenv_secret_patterns는 v2.0.0 에서 제거된다. 사용 시 stderr 에 deprecation 경고가 출력된다.

설정은 세 레이어를 순서대로 병합한다. 뒤 레이어가 앞 레이어를 덮어쓴다.
- 전역:~/.parism/prism.config.json
- 프로젝트:<cwd>/prism.config.json
- 환경 변수:PARISM_접두 변수

MCP 서버와 라이브러리 모드(createEngine()) 모두 동일한 3레이어 병합을 사용한다.createEngine({ configPath })로 특정 파일을 직접 지정하면 그 파일만 로드한다.

44개 내장 파서로 부족하면, 직접 만들면 된다. Parism v0.5.0 부터 CLI 도구가 포함된다. v1.0.0 부터ParserPack.schema는 Zod 스키마를 단일 소스로 사용한다.

# 1. 명령어 출력을 캡처한다 parism capture "htop -b -n 1" # 2. 파서 팩 스캐폴드를 생성한다 parism init-parser htop # 3. parser.ts를 편집하고 fixture를 검증한다 (fixture replay 는 예정 기능, 현재는 parism inspect 로 수동 대조) # 4. 등록한다 -- 재시작 없이 즉시 사용 가능 parism add ./htop # 5. 결과를 확인한다 -- raw/parsed/compact 비교 + 토큰 수 parism inspect "htop -b -n 1"

등록된 파서는~/.parism/parsers/에 저장되고, MCP 서버 시작 시 자동으로 로드된다.