Naru
Writing packs
A pack is a bundle of tools (functions) for legacy systems. Write them in TypeScript, test them with fixtures, and Naru builds and deploys them.
A pack's shape
One git repository is one pack.
naru.pack.json pack id, name, version, systems it uses
functions/*.ts tools (functions); several per file is fine
lib/*.ts code shared between functions (optional)
fixtures/*.json recorded exchanges with the systems, for tests
{
"id": "groupware",
"name": "Groupware approvals",
"version": "0.1.0",
"description": "Approval inbox lookups and approvals in the company groupware",
"systems": {
"groupware": { "driver": "http", "description": "Company groupware web", "modes": ["personal"] }
}
}
Tool names are <pack id>_<function name> (- becomes _), such as groupware_approval_list. Start a new pack with naru init my-pack --id my-pack --name "My pack" or from templates/pack.
A function
import { defineFunction, fail, z } from '@naru/sdk';
export const approvalList = defineFunction({
name: 'approval_list',
title: 'Approvals waiting',
description: 'Lists documents waiting for my approval. Pass a document number to approve to approve it.',
systems: ['groupware'],
identity: 'user', // only in a person's name
input: z.object({
box: z.enum(['todo', 'done']).default('todo').describe('todo: to approve, done: approved'),
}),
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() })) };
},
});
| Field | Meaning |
|---|---|
description |
What the model reads: when to use it, what it returns, its limits |
effect |
read (default) or write |
risk |
low, medium, high. Irreversible writes (approvals, payments, deletions) are high and run after a person approves, as the toolset says |
identity |
With user, service tokens without a person can't call it |
input, output |
z.object(...). Results are checked against the schema before masking |
audit |
How input is recorded in the audit log: hash (default), redact, full |
timeoutMs |
Default NARU_FUNCTION_TIMEOUT_MS (60 s), up to five times that |
Calling systems
Functions receive no secrets and can't reach the internet or files directly. Naru signs in and signs requests for them.
// HTTP: paths only, starting with /. Authorization and Cookie belong to the auth chain
const res = await systems.erp.http.get('/api/v1/orders', { query: { status: 'OPEN' } });
res.json<T>(); res.text; res.$('table tr.row'); // JSON, decoded text, HTML (cheerio-style)
// SOAP: Naru adds the WS-Security header
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: always ? placeholders. Read-only systems accept one SELECT/WITH statement
const q = await systems.hr.sql.query('SELECT emp_no, name FROM emp WHERE dept = ?', [input.dept], { maxRows: 50 });
- When a session drops back to the sign-in page, Naru signs in again and retries once.
- Failures the model should act on are
fail('not_found', 'No employee with that number'). Other exceptions becomefunction_failed, and in production their message never reaches the model. principalholds the caller's employee number, email, name, department and groups.
Testing with fixtures
Galpi VMs usually can't reach legacy systems, so recorded exchanges in fixtures/*.json are replayed instead.
naru list # tools and schemas
naru test # run the functions against fixtures
naru dev # a local page to try the tools
naru zip # the source ZIP to submit
try_function on Naru's development MCP (/dev/mcp) calls the real dev legacy system with the developer's own credentials and returns the exchange, secrets and resident numbers removed, already in fixture form.
Submitting and deploying
- Release: Naru builds the submitted source ZIP itself. Imports are limited to
@naru/sdkand files in the pack. The result is an immutable bundle pinned by its sha256. - Deployment: a release per environment. It changes within one contract (major version); other major versions can run alongside.
- Pack runner: a separate Node process per release. It reads only its own files; child processes, workers, addons and string code generation are blocked; there is no
fetchand no server environment. System calls are requests to the server over IPC.


naru submit --url https://naru.corp.example --token <naru_dev_…> --deploy # submit and deploy to dev
naru-admin packs releases <pack>
naru-admin packs deploy <pack> prod <releaseId> # production: administrators
For developing packs from Galpi, see Connecting the products.