@pugi/cli 0.1.0-beta.2 → 0.1.0-beta.20

package/dist/tools/skill-tool.js

@@ -0,0 +1,96 @@
+import { listSkills } from '../core/skills/loader.js';
+import { hashSkillDir, verifyTrust } from '../core/skills/trust.js';
+export const SKILL_BODY_CAP_BYTES = 32 * 1024;
+export const SKILL_LIST_CAP = 100;
+export function skillList(ctx, input) {
+    const scope = input.scope ?? 'all';
+    const all = [];
+    if (scope === 'all' || scope === 'global') {
+        all.push(...listSkills('global', ctx.workspaceRoot));
+    }
+    if (scope === 'all' || scope === 'workspace') {
+        all.push(...listSkills('workspace', ctx.workspaceRoot));
+    }
+    // Dedup by name, prefer workspace scope when both exist (workspace
+    // overrides global per skills loader convention).
+    const byName = new Map();
+    for (const skill of all) {
+        const prev = byName.get(skill.name);
+        if (!prev || skill.scope === 'workspace') {
+            byName.set(skill.name, skill);
+        }
+    }
+    return Array.from(byName.values())
+        .slice(0, SKILL_LIST_CAP)
+        .map((skill) => ({
+        name: skill.name,
+        description: skill.frontmatter.description,
+        scope: skill.scope,
+    }));
+}
+export async function skillInvoke(ctx, input) {
+    if (!input.name || typeof input.name !== 'string') {
+        throw new Error('skill: name is required');
+    }
+    // Defense-in-depth: skill loader already validates slugs but the
+    // tool surface is operator-controlled.
+    if (!/^[a-zA-Z0-9_-]{1,128}$/.test(input.name)) {
+        throw new Error(`skill: invalid skill name shape: "${input.name}"`);
+    }
+    // Workspace scope wins over global (operator override). Mirrors
+    // SkillLoader convention.
+    const workspace = listSkills('workspace', ctx.workspaceRoot).find((s) => s.name === input.name);
+    const global = workspace
+        ? null
+        : listSkills('global', ctx.workspaceRoot).find((s) => s.name === input.name);
+    const skill = workspace ?? global;
+    if (!skill) {
+        throw new Error(`skill: not found: "${input.name}"`);
+    }
+    // β1a r1 (2026-05-26): re-verify the on-disk skill payload against
+    // the trust manifest sha256 on EVERY invoke, not just at install
+    // time. Before this fix a post-install swap (malicious npm dep that
+    // touches `~/.pugi/skills/<name>/SKILL.md` after the operator
+    // approved the install) would bypass the trust gate — `listSkills`
+    // reads the body fresh from disk and the loader does no integrity
+    // check. The skill body lands directly in the model's tool result,
+    // so a mutated body is a prompt-injection vector against the agent
+    // loop's tool surface.
+    //
+    // Posture:
+    //   - `trusted`   → proceed (body is hash-pinned).
+    //   - `unsigned`  → refuse: the operator never approved this skill.
+    //     This catches the case where a skill directory was dropped in
+    //     manually (no `pugi skills install`) and the loader picked it
+    //     up. Refusing is fail-closed.
+    //   - `mismatch`  → refuse + surface the recorded vs actual hashes
+    //     so the operator can decide between re-trust and revoke.
+    //
+    // Performance: `hashSkillDir` walks the skill directory on every
+    // invoke. Skills are small (median 4-8 files, <50KB total) so the
+    // cost is sub-millisecond on warm cache. The β1a r1 spec exercises
+    // a mutated-body case; the existing skill-tool.spec.ts cases for
+    // happy-path use the `recordTrust` helper to seed the registry.
+    const actualHash = hashSkillDir(skill.dir);
+    const verdict = await verifyTrust('skill', skill.scope, skill.name, actualHash);
+    if (verdict.status === 'unsigned') {
+        throw new Error(`skill: refused to invoke "${skill.name}" — no trust entry (run \`pugi skills trust ${skill.name}\` to approve)`);
+    }
+    if (verdict.status === 'mismatch') {
+        throw new Error(`skill: refused to invoke "${skill.name}" — sha256 mismatch (recorded ${verdict.recorded.slice(0, 12)}…, actual ${verdict.actual.slice(0, 12)}…). Re-trust via \`pugi skills trust ${skill.name}\`.`);
+    }
+    const body = skill.body;
+    const truncated = Buffer.byteLength(body, 'utf8') > SKILL_BODY_CAP_BYTES;
+    const cappedBody = truncated
+        ? body.slice(0, SKILL_BODY_CAP_BYTES) +
+            `\n\n(... truncated at ${SKILL_BODY_CAP_BYTES} bytes — see \`pugi skills info ${skill.name}\` for full text)`
+        : body;
+    return {
+        name: skill.name,
+        scope: skill.scope,
+        description: skill.frontmatter.description,
+        body: cappedBody,
+        truncated,
+    };
+}
+//# sourceMappingURL=skill-tool.js.map

package/dist/tools/tasks.js

@@ -0,0 +1,208 @@
+/**
+ * task_* tool family — β1 T1/T6 (TodoWrite + agent task ledger).
+ *
+ * Mirrors Claude Code's TodoWrite tool surface so a model trained on
+ * the upstream tool grammar speaks Pugi's variant verbatim. Four ops:
+ *
+ *   - `task_create` — append a new task to the session's todo ledger.
+ *     Returns the assigned id.
+ *   - `task_get`    — fetch a single task by id.
+ *   - `task_list`   — list every task in the current session, ordered
+ *                     by createdAt ascending.
+ *   - `task_update` — mutate status/title/notes of an existing task.
+ *                     Append-only journal — every mutation lands as a
+ *                     fresh JSONL line and the latest line per id wins
+ *                     on `task_list` / `task_get` reads.
+ *
+ * Persistence: append-only JSONL at
+ * `.pugi/sessions/<sessionId>/tasks.jsonl`. Append-only keeps crash
+ * recovery trivial — a partial write at the end of the file is the
+ * worst case and the parser drops the malformed tail line.
+ *
+ * Scope: this is the local-side ledger surface. Anvil-side mirror
+ * (cabinet `/projects/[id]/tasks` page) ships in β5 once the session-
+ * memory hook lands; until then the ledger is purely local.
+ */
+import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync, } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+function ledgerPath(ctx) {
+    // Defense-in-depth: the sessionId is supposed to be a UUID minted by
+    // openSession() but the tool surface is operator-facing. Validate the
+    // shape before composing a path — refuse anything that contains
+    // separators or shell wildcards.
+    if (!/^[a-zA-Z0-9_-]{1,128}$/.test(ctx.sessionId)) {
+        throw new Error(`task_*: invalid sessionId shape: "${ctx.sessionId}"`);
+    }
+    return join(ctx.workspaceRoot, '.pugi', 'sessions', ctx.sessionId, 'tasks.jsonl');
+}
+function nowIso(ctx) {
+    return (ctx.now ? ctx.now() : new Date()).toISOString();
+}
+function ensureDir(path) {
+    // β1a r1 (2026-05-26): switched from POSIX-only
+    // `path.slice(0, path.lastIndexOf('/'))` to `path.dirname()` so
+    // Windows path separators (`\`) work. Also chmod the per-session
+    // directory to 0o700 — the tasks ledger carries operator-confidential
+    // brief text, status notes, and timing metadata that should not be
+    // world-readable through an inherited umask.
+    const dir = dirname(path);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+        try {
+            chmodSync(dir, 0o700);
+        }
+        catch {
+            // Best-effort. POSIX permission setting is a no-op on Windows
+            // NTFS, and the dir-creation race with another concurrent task
+            // tool call is the only realistic failure case. The 0o600 mode
+            // on the JSONL file itself remains the primary guard; the dir
+            // chmod is defense in depth for tools that walk `.pugi/`.
+        }
+    }
+}
+function readJournal(ctx) {
+    const path = ledgerPath(ctx);
+    if (!existsSync(path))
+        return [];
+    const raw = readFileSync(path, 'utf8');
+    const out = [];
+    for (const line of raw.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if ((parsed.op === 'create' || parsed.op === 'update') &&
+                typeof parsed.id === 'string' &&
+                typeof parsed.at === 'string') {
+                out.push(parsed);
+            }
+        }
+        catch {
+            // Drop malformed line (partial-write tail or external corruption).
+            // The append-only design guarantees only the LAST line can be bad
+            // — everything before it is whole.
+        }
+    }
+    return out;
+}
+function fold(journal) {
+    const out = new Map();
+    for (const entry of journal) {
+        if (entry.op === 'create') {
+            if (!entry.title)
+                continue;
+            out.set(entry.id, {
+                id: entry.id,
+                title: entry.title,
+                status: entry.status ?? 'pending',
+                ...(entry.notes !== undefined ? { notes: entry.notes } : {}),
+                createdAt: entry.at,
+                updatedAt: entry.at,
+            });
+        }
+        else {
+            const prev = out.get(entry.id);
+            if (!prev)
+                continue; // update before create — drop silently
+            out.set(entry.id, {
+                ...prev,
+                ...(entry.title !== undefined ? { title: entry.title } : {}),
+                ...(entry.status !== undefined ? { status: entry.status } : {}),
+                ...(entry.notes !== undefined ? { notes: entry.notes } : {}),
+                updatedAt: entry.at,
+            });
+        }
+    }
+    return out;
+}
+function appendEntry(ctx, entry) {
+    const path = ledgerPath(ctx);
+    ensureDir(path);
+    appendFileSync(path, `${JSON.stringify(entry)}\n`, {
+        encoding: 'utf8',
+        mode: 0o600,
+    });
+}
+export function taskCreate(ctx, input) {
+    const title = input.title?.trim();
+    if (!title) {
+        throw new Error('task_create: title is required');
+    }
+    if (title.length > 2_000) {
+        throw new Error('task_create: title exceeds 2000 char cap');
+    }
+    const status = input.status ?? 'pending';
+    if (!isValidStatus(status)) {
+        throw new Error(`task_create: invalid status "${status}"`);
+    }
+    const id = `task-${randomUUID()}`;
+    const at = nowIso(ctx);
+    const entry = {
+        op: 'create',
+        id,
+        title,
+        status,
+        at,
+        ...(input.notes !== undefined ? { notes: input.notes } : {}),
+    };
+    appendEntry(ctx, entry);
+    return {
+        id,
+        title,
+        status,
+        ...(input.notes !== undefined ? { notes: input.notes } : {}),
+        createdAt: at,
+        updatedAt: at,
+    };
+}
+export function taskGet(ctx, id) {
+    if (typeof id !== 'string' || id.length === 0) {
+        throw new Error('task_get: id is required');
+    }
+    const folded = fold(readJournal(ctx));
+    return folded.get(id) ?? null;
+}
+export function taskList(ctx) {
+    const folded = fold(readJournal(ctx));
+    return Array.from(folded.values()).sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+}
+export function taskUpdate(ctx, input) {
+    if (!input.id)
+        throw new Error('task_update: id is required');
+    const folded = fold(readJournal(ctx));
+    const existing = folded.get(input.id);
+    if (!existing) {
+        throw new Error(`task_update: unknown id "${input.id}"`);
+    }
+    if (input.status !== undefined && !isValidStatus(input.status)) {
+        throw new Error(`task_update: invalid status "${input.status}"`);
+    }
+    if (input.title !== undefined && input.title.trim().length === 0) {
+        throw new Error('task_update: title cannot be empty');
+    }
+    const at = nowIso(ctx);
+    const entry = {
+        op: 'update',
+        id: input.id,
+        at,
+        ...(input.title !== undefined ? { title: input.title } : {}),
+        ...(input.status !== undefined ? { status: input.status } : {}),
+        ...(input.notes !== undefined ? { notes: input.notes } : {}),
+    };
+    appendEntry(ctx, entry);
+    return {
+        ...existing,
+        ...(input.title !== undefined ? { title: input.title } : {}),
+        ...(input.status !== undefined ? { status: input.status } : {}),
+        ...(input.notes !== undefined ? { notes: input.notes } : {}),
+        updatedAt: at,
+    };
+}
+function isValidStatus(status) {
+    return (status === 'pending' ||
+        status === 'in_progress' ||
+        status === 'completed' ||
+        status === 'cancelled');
+}
+//# sourceMappingURL=tasks.js.map

package/dist/tools/web-fetch.js

@@ -34,7 +34,7 @@
  * Brand voice: brief / dispatch / ship / sentinel only. The
  * brandbook §08 forbidden-word list applies — see CLAUDE.md.
  */
-import { request } from 'undici';
+import { request, Agent } from 'undici';
 import { Readability } from '@mozilla/readability';
 import { parseHTML } from 'linkedom';
 import TurndownService from 'turndown';
@@ -45,6 +45,72 @@ let activeLookup = async (hostname) => await dnsLookup(hostname, { all: true, ve
 export function _setLookupForTests(fn) {
     activeLookup = fn ?? (async (hostname) => await dnsLookup(hostname, { all: true, verbatim: true }));
 }
+/**
+ * β1b #62 — DNS rebinding guard via pinned-address Dispatcher.
+ *
+ * Without this, the SSRF guard's `dns.lookup` and undici's `request()`
+ * connect(2) each issue independent DNS queries. A hostile resolver
+ * can answer "8.8.8.8" the first time (passes the SSRF guard) and
+ * "127.0.0.1" the second time (kernel connects to local metadata).
+ *
+ * Fix: resolve once, validate, then pin the resolved address into a
+ * per-call `Agent` via `connect.lookup`. The connect() path no longer
+ * touches DNS — it uses the IP we already approved.
+ *
+ * Test seam: spec suite uses MockAgent as the global dispatcher; the
+ * MockAgent path does not exercise real connect(), so pinning is both
+ * pointless and would break the MockAgent stub. Specs flip
+ * `_disablePinnedDispatcherForTests(true)` in beforeEach to keep the
+ * MockAgent flow intact while production hits the pinned path.
+ */
+let pinnedDispatcherDisabled = false;
+export function _disablePinnedDispatcherForTests(disabled) {
+    pinnedDispatcherDisabled = disabled;
+}
+/**
+ * Build a per-call undici Agent that always returns the pre-resolved
+ * `address` from its connect.lookup hook. Returns `undefined` when the
+ * test flag disabled pinning — caller then falls back to the global
+ * dispatcher (MockAgent or production default).
+ */
+async function buildPinnedDispatcher(hostname) {
+    if (pinnedDispatcherDisabled)
+        return undefined;
+    // Skip pinning when hostname is already a literal IP — there is no
+    // DNS step to race in that case.
+    if (isIPv4(hostname) || isIPv6(hostname))
+        return undefined;
+    let answers;
+    try {
+        answers = await activeLookup(hostname);
+    }
+    catch {
+        // Best-effort — fall through without pinning; the SSRF guard will
+        // emit the canonical DNS-lookup-failed error on the caller's path.
+        return undefined;
+    }
+    const pinned = answers[0];
+    if (!pinned)
+        return undefined;
+    // β1b r1: close the DNS rebinding window the original guard could
+    // not see. `validateHostnameForFetch` already ran one lookup; the
+    // call above is a SECOND lookup whose answer feeds the pin. A
+    // hostile resolver can return a public address to the guard and a
+    // private address here — re-validate the pinned literal before we
+    // hand it to the Agent. Throws so the caller surfaces a security
+    // refusal rather than silently dispatching to the wrong host.
+    const ipCheck = validateIpLiteralForFetch(pinned.address, pinned.family);
+    if (ipCheck !== null) {
+        throw new Error(`ssrf_pinned_address_blocked: ${ipCheck}`);
+    }
+    return new Agent({
+        connect: {
+            lookup: (_h, _opts, cb) => {
+                cb(null, pinned.address, pinned.family);
+            },
+        },
+    });
+}
 const FETCH_TIMEOUT_MS = 10_000;
 const MAX_RESPONSE_BYTES = 5 * 1024 * 1024; // 5 MiB
 const MAX_REDIRECTS = 5;
@@ -231,6 +297,42 @@ function ipv4IsBlocked(ip) {
     }
     return false;
 }
+/**
+ * Validate a single IP literal (v4 or v6) against the SSRF blocklist.
+ * Pure synchronous check — no DNS. Returns `null` on success (safe to
+ * connect), an error string when the address is blocked or not a
+ * recognized IP literal.
+ *
+ * Used by the pinned-dispatcher path (web-fetch + web-search) to
+ * RE-VALIDATE the address actually pinned into `connect.lookup` AFTER
+ * the second DNS round-trip. Without this check the original SSRF
+ * guard's lookup answers can diverge from the lookup answers that
+ * feed the pin (hostile resolver flips public→private between calls);
+ * re-checking the pinned literal closes that window.
+ *
+ * Exported for spec coverage.
+ */
+export function validateIpLiteralForFetch(address, family) {
+    if (!address)
+        return 'empty address';
+    // Trust family hint when present (LookupAddress.family is 4 or 6),
+    // otherwise infer from the string shape.
+    const isV4 = family === 4 || (family === undefined && isIPv4(address));
+    const isV6 = family === 6 || (family === undefined && isIPv6(address));
+    if (isV4) {
+        if (ipv4IsBlocked(address)) {
+            return `IP ${address} is in a blocked range (SSRF guard)`;
+        }
+        return null;
+    }
+    if (isV6) {
+        if (ipv6IsBlocked(address)) {
+            return `IPv6 ${address} is in a blocked range (SSRF guard)`;
+        }
+        return null;
+    }
+    return `address ${address} is not a recognized IPv4/IPv6 literal`;
+}
 /**
  * Resolve `hostname` via dns.lookup and reject if any answer maps to
  * a private/loopback/link-local/CGNAT range. Returns `null` on success
@@ -395,10 +497,34 @@ export async function webFetchTool(input, ctx) {
     let currentUrl = parsedUrl;
     let hops = 0;
     const controller = new AbortController();
+    // β1b #62: per-hop pinned Agent so the post-lookup connect(2) cannot
+    // be redirected to a private IP by a hostile resolver. Built lazily
+    // per hop because each redirect target may resolve to a different
+    // host. `undefined` falls back to the global dispatcher (spec
+    // MockAgent or production default), preserving the existing test
+    // path. The current Agent is closed at end-of-call so we do not leak
+    // open connections.
+    let activeAgent;
+    const closeActiveAgent = async () => {
+        if (activeAgent) {
+            try {
+                await activeAgent.close();
+            }
+            catch {
+                /* ignore — agent already closed */
+            }
+            activeAgent = undefined;
+        }
+    };
     try {
         while (true) {
+            // β1b #62: refresh the pinned Agent for the current hop.
+            await closeActiveAgent();
+            const hopHost = currentUrl.hostname.replace(/^\[|\]$/g, '');
+            activeAgent = await buildPinnedDispatcher(hopHost);
             response = await request(currentUrl.toString(), {
                 method: 'GET',
+                ...(activeAgent ? { dispatcher: activeAgent } : {}),
                 headers: {
                     'user-agent': USER_AGENT,
                     accept: 'text/html,application/xhtml+xml',
@@ -436,6 +562,7 @@ export async function webFetchTool(input, ctx) {
                             /* socket already closed — nothing to do */
                         }
                     }
+                    await closeActiveAgent();
                     return { ok: false, error: `Exceeded ${MAX_REDIRECTS} redirect hops.` };
                 }
                 // Drain prior body so the socket can be reused.
@@ -445,9 +572,11 @@ export async function webFetchTool(input, ctx) {
                     nextUrl = new URL(locStr, currentUrl);
                 }
                 catch {
+                    await closeActiveAgent();
                     return { ok: false, error: `Invalid redirect target: ${locStr}` };
                 }
                 if (nextUrl.protocol !== 'http:' && nextUrl.protocol !== 'https:') {
+                    await closeActiveAgent();
                     return {
                         ok: false,
                         error: `Refusing redirect to unsupported scheme ${nextUrl.protocol}.`,
@@ -456,6 +585,7 @@ export async function webFetchTool(input, ctx) {
                 const nextHost = nextUrl.hostname.replace(/^\[|\]$/g, '');
                 const guard = await validateHostnameForFetch(nextHost);
                 if (guard) {
+                    await closeActiveAgent();
                     return { ok: false, error: `SSRF refused on redirect: ${guard}` };
                 }
                 currentUrl = nextUrl;
@@ -465,13 +595,23 @@ export async function webFetchTool(input, ctx) {
         }
     }
     catch (error) {
+        await closeActiveAgent();
         const message = error instanceof Error ? error.message : String(error);
+        // β1b r1: the pinned-dispatcher path throws `ssrf_pinned_address_blocked: …`
+        // when the second DNS lookup answered a private IP. Surface that as a
+        // first-class SSRF refusal so callers (and specs) can match on it
+        // without grovelling through `Fetch failed:` prefixes.
+        if (message.startsWith('ssrf_pinned_address_blocked')) {
+            return { ok: false, error: `SSRF refused: ${message}` };
+        }
         return { ok: false, error: `Fetch failed: ${message}` };
     }
     if (!response) {
+        await closeActiveAgent();
         return { ok: false, error: 'No response received.' };
     }
     if (response.statusCode < 200 || response.statusCode >= 300) {
+        await closeActiveAgent();
         return { ok: false, error: `HTTP ${response.statusCode} from ${currentUrl.toString()}` };
     }
     // content-length is advisory — never trust it for the size cap, but
@@ -489,6 +629,7 @@ export async function webFetchTool(input, ctx) {
             catch {
                 /* ignore */
             }
+            await closeActiveAgent();
             return {
                 ok: false,
                 error: `Declared content-length ${n} exceeds ${MAX_RESPONSE_BYTES} byte cap.`,
@@ -499,11 +640,14 @@ export async function webFetchTool(input, ctx) {
     const contentType = Array.isArray(contentTypeRaw) ? contentTypeRaw[0] : contentTypeRaw;
     const mime = typeof contentType === 'string' ? contentType.split(';')[0]?.trim().toLowerCase() ?? '' : '';
     if (!ALLOWED_CONTENT_TYPES.includes(mime)) {
+        await closeActiveAgent();
         return { ok: false, error: `Disallowed content-type ${mime || '(none)'}; only HTML/XHTML/text.` };
     }
     const bodyResult = await readBodyWithCap(response.body, controller);
-    if (!bodyResult.ok)
+    if (!bodyResult.ok) {
+        await closeActiveAgent();
         return bodyResult;
+    }
     const html = bodyResult.buffer.toString('utf8');
     // linkedom is the lightweight DOM Readability needs; jsdom would
     // add ~3 MB to the install footprint for the same surface.
@@ -524,6 +668,7 @@ export async function webFetchTool(input, ctx) {
         `Source: ${safeSource}\n\n` +
         `${scrubbedMarkdown}\n` +
         `</untrusted-content-${nonce}>`;
+    await closeActiveAgent();
     return {
         ok: true,
         url: currentUrl.toString(),