Naru
pack 만들기
pack은 레거시 시스템을 다루는 도구(function) 묶음이에요. TypeScript로 쓰고, fixture로 시험하고, 나루가 직접 빌드해 배포해요.
pack의 모양
git 저장소 하나가 pack 하나예요.
naru.pack.json pack id, 이름, 버전, 쓰는 시스템 선언
functions/*.ts 도구(function). 파일 하나에 여러 개를 둬도 돼요
lib/*.ts function끼리 같이 쓰는 코드 (선택)
fixtures/*.json 시험용 기록: 시스템과 주고받은 요청·응답
naru.pack.json
{
"id": "groupware",
"name": "그룹웨어 결재",
"version": "0.1.0",
"description": "사내 그룹웨어의 결재함 조회와 결재",
"systems": {
"groupware": { "driver": "http", "description": "사내 그룹웨어 웹", "modes": ["personal"] }
}
}
도구 이름은 <pack id>_<function 이름>이에요(-는 _로). 예: groupware_approval_list. 새 pack은 naru init my-pack --id my-pack --name "내 pack"으로 시작하거나 templates/pack을 써요.
function
functions/approval.ts
import { defineFunction, fail, z } from '@naru/sdk';
export const approvalList = defineFunction({
name: 'approval_list',
title: '결재 대기 목록',
description: '내가 결재해야 할 문서 목록을 가져온다. 결재하려면 approve에 문서번호를 넘긴다.',
systems: ['groupware'],
identity: 'user', // 사람 이름으로만 호출
input: z.object({
box: z.enum(['todo', 'done']).default('todo').describe('todo: 결재할 문서, done: 결재한 문서'),
}),
output: z.object({ items: z.array(z.object({ docNo: z.string(), title: z.string() })) }),
async run({ input, systems }) {
const res = await systems.groupware.http.get('/approval/list.do', { query: { box: input.box }, as: 'html' });
return { items: res.$('tr.row').map((r) => ({ docNo: r.attr('data-no') ?? '', title: r.find('td.title').text() })) };
},
});
| 필드 | 뜻 |
|---|---|
description |
모델이 읽는 설명. 언제 쓰는지, 무엇을 돌려주는지, 한계를 적어요 |
effect |
read(기본) 또는 write |
risk |
low, medium, high. 되돌릴 수 없는 쓰기(결재, 송금, 삭제)는 high. toolset 설정에 따라 사람의 승인 뒤에 실행돼요 |
identity |
user면 사람 없는 서비스 토큰으로는 부를 수 없어요 |
input, output |
z.object(...). 결과는 마스킹 전에 이 스키마로 검사해요 |
audit |
감사 기록에 남길 입력: hash(기본), redact, full |
timeoutMs |
기본 NARU_FUNCTION_TIMEOUT_MS(60초), 그 5배까지 |
시스템 부르기
function은 비밀값을 받지 않고, 인터넷이나 파일에 직접 닿지 못해요. 로그인과 서명은 나루가 대신해요.
ts
// HTTP: path는 /로 시작하는 경로만. Authorization·Cookie는 인증 체인의 몫이에요
const res = await systems.erp.http.get('/api/v1/orders', { query: { status: 'OPEN' } });
res.json<T>(); res.text; res.$('table tr.row'); // JSON, 디코딩된 문자열, HTML(cheerio 방식)
// SOAP: WS-Security 헤더는 나루가 붙여요
const r = await systems['erp-soap'].soap.call({ path: '/soap/InventoryService', action: 'urn:erp:inventory/GetStock',
namespaces: { inv: 'urn:erp:inventory' }, body: `<inv:GetStock><inv:itemCode>${itemCode}</inv:itemCode></inv:GetStock>` });
// SQL: 자리표시자는 늘 ?. 읽기 전용 시스템에는 SELECT/WITH 한 문장만
const q = await systems.hr.sql.query('SELECT emp_no, name FROM emp WHERE dept = ?', [input.dept], { maxRows: 50 });
- 세션이 끊겨 로그인 페이지로 돌아가면 나루가 다시 로그인해 한 번 다시 해요.
- 모델이 읽고 다음 행동을 정할 실패는
fail('not_found', '그 사번의 직원이 없어요')로 내요. 다른 예외는function_failed가 되고, 운영에서는 메시지가 모델에게 가지 않아요. principal에 부른 사람의 사번, 이메일, 이름, 부서, 그룹이 있어요.
시험: fixture
갈피의 VM은 보통 레거시에 닿지 못해서, 시스템과 주고받은 기록을 fixtures/*.json에 두고 재생해요.
bash
naru list # 도구와 schema
naru test # fixture로 function을 돌려요
naru dev # 도구를 눌러 볼 수 있는 로컬 페이지
naru zip # 제출할 소스 ZIP
나루의 개발용 MCP(/dev/mcp)의 try_function은 실제 dev 레거시를 개발자 본인 자격으로 부르고, 비밀값과 주민번호를 지운 교환 기록을 그대로 fixture 모양으로 돌려줘요.
제출과 배포
- release: 나루가 제출된 소스 ZIP을 직접 빌드해요. import는
@naru/sdk와 pack 안 파일만 돼요. 결과는 sha256으로 고정한 불변 묶음이에요. - 배포: 환경마다 release를 골라요. 같은 약속(주 버전) 안에서 바뀌고, 다른 주 버전은 함께 돌 수 있어요.
- pack runner: release마다 따로 된 Node 프로세스예요. 자기 파일만 읽고, 자식 프로세스·worker·addon·문자열 코드 생성이 막히고,
fetch가 없고, 서버 환경 변수가 없어요. 시스템 호출은 IPC로 서버에 부탁해요.


bash
naru submit --url https://naru.corp.example --token <naru_dev_…> --deploy # 제출하고 dev에 배포
naru-admin packs releases <pack>
naru-admin packs deploy <pack> prod <releaseId> # 운영은 관리자
갈피에서 개발하는 흐름은 제품 잇기를 봐요.