@pugi/cli 0.1.0-beta.99 → 1.0.0-alpha.2

package/dist/tools/skill-tool.js

@@ -1,96 +0,0 @@
-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 : 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/sleep.js

@@ -1,99 +0,0 @@
-/**
- * sleep tool — wall-clock pause primitive (tool gap pack).
- *
- * Closes a parity gap with the upstream tool's tool surface. The model calls
- * this when it needs a fixed delay before its next action (waiting on
- * a process the operator owns, throttling a poll loop). The call
- * counts against `--max-turns` like every other tool dispatch, so the
- * budget gate naturally caps abuse.
- *
- * Operator guidance: prefer a real poll loop (read + grep + retry) over
- * blind sleep. The tool exists for the cases where polling is not an
- * option (a fixed cooldown between API calls, a deterministic settle
- * window for a build) — most agent flows do NOT want it.
- *
- * Wire shape:
- *  args:  { seconds: number }
- *          - integer in [1, 600]; non-integer / out-of-range rejects
- *            at parse time with a sentinel string.
- *  return: { ok: true, sleptMs: number } serialised JSON.
- *
- * No side effects beyond the wall-clock delay; nothing on disk, no
- * subprocesses, no environment mutation.
- *
- * Brand voice: English only, no emoji, no banned words.
- */
-/** Hard caps. The lower bound rejects zero / negative inputs at parse
- * time so the model can self-correct; the upper bound matches the
- * standard tool timeout budget used elsewhere in the CLI. */
-export const SLEEP_MIN_SECONDS = 1;
-export const SLEEP_MAX_SECONDS = 600;
-/** Sentinel prefix returned when input validation rejects the call. */
-export const SLEEP_INVALID_ARGS = 'SLEEP_INVALID_ARGS';
-/**
- * Validate the raw arguments. Returns the typed value on success or a
- * `SLEEP_INVALID_ARGS: ...` sentinel string. Non-integer values reject
- * because partial seconds invite drift across platforms; the model
- * should round explicitly at the call site.
- */
-export function parseSleepArgs(raw) {
-    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
-        return `${SLEEP_INVALID_ARGS}: arguments must be a JSON object`;
-    }
-    const obj = raw;
-    const seconds = obj['seconds'];
-    if (typeof seconds !== 'number' || !Number.isFinite(seconds)) {
-        return `${SLEEP_INVALID_ARGS}: seconds must be a finite number`;
-    }
-    if (!Number.isInteger(seconds)) {
-        return `${SLEEP_INVALID_ARGS}: seconds must be an integer`;
-    }
-    if (seconds < SLEEP_MIN_SECONDS) {
-        return `${SLEEP_INVALID_ARGS}: seconds must be >= ${SLEEP_MIN_SECONDS}`;
-    }
-    if (seconds > SLEEP_MAX_SECONDS) {
-        return `${SLEEP_INVALID_ARGS}: seconds must be <= ${SLEEP_MAX_SECONDS}`;
-    }
-    return { seconds };
-}
-/**
- * Dispatch entry point. Validates input, awaits the wall-clock delay,
- * and returns the structured result envelope as JSON.
- *
- * On validation failure returns the sentinel string directly (no throw)
- * so the engine adapter surfaces it as a recoverable tool result and
- * the model can self-correct the arguments.
- */
-export async function dispatchSleep(ctx, raw) {
-    const parsed = parseSleepArgs(raw);
-    if (typeof parsed === 'string') {
-        return parsed;
-    }
-    const ms = parsed.seconds * 1_000;
-    const timer = ctx.timer ?? ((cb, delay) => setTimeout(cb, delay));
-    await new Promise((resolveDelay) => {
-        timer(resolveDelay, ms);
-    });
-    const result = { ok: true, sleptMs: ms };
-    return JSON.stringify(result);
-}
-/**
- * JSON-Schema fragment the schema builder advertises to the model.
- * Hand-written for parity with the rest of the tool surface (see the
- * note on `briefJsonSchema` for why we do not pull in zod-to-json-schema).
- */
-export const sleepJsonSchema = {
-    type: 'object',
-    additionalProperties: false,
-    required: ['seconds'],
-    properties: {
-        seconds: {
-            type: 'integer',
-            minimum: SLEEP_MIN_SECONDS,
-            maximum: SLEEP_MAX_SECONDS,
-            description: `Wall-clock pause in seconds. Integer in [${SLEEP_MIN_SECONDS}, ${SLEEP_MAX_SECONDS}]. ` +
-                'Prefer a real poll loop over blind sleep; this tool counts against --max-turns.',
-        },
-    },
-};
-//# sourceMappingURL=sleep.js.map

package/dist/tools/synthetic-output.js

@@ -1,133 +0,0 @@
-/**
- * synthetic_output tool — operator-readable echo helper (tool gap
- * pack). EXPERIMENTAL / engine-only.
- *
- * Test fixture cousin of `brief`. Whereas `brief` persists a structured
- * record to `.pugi/briefs/<session>.jsonl`, `synthetic_output` writes
- * the supplied text VERBATIM к the requested stream (`stdout` or
- * `stderr`). The use case is the engine-side test harness: a spec wants
- * to assert that "the loop ran this tool with this payload" without
- * spinning up the entire dispatch pipeline, AND wants to observe the
- * write the same way an operator would. Production agent flows should
- * prefer `brief` because the structured record survives crashes — the
- * stream write does not.
- *
- * The tool is NOT exposed as a slash command. The schema is advertised
- * to the engine only when the executor is built with an
- * `allowSyntheticOutput: true` opt-in. Customer CLIs leave it off so
- * the model cannot use it as a side-channel to bypass the normal tool
- * result envelope (which is logged, classified, hooked, etc.).
- *
- * Wire shape:
- *  args:  { stream: 'stdout'|'stderr', text: string }
- *          - text is capped at 16 KiB UTF-8; over-cap rejects with
- *            the SYNTHETIC_OUTPUT_TOO_LARGE sentinel.
- *  side:  raw `process.stdout.write(text)` or `process.stderr.write(text)`.
- *  return: short JSON envelope { ok, stream, bytes } so the engine
- *          loop can audit the call without re-reading the streamed
- *          bytes (which it does not buffer).
- *
- * Atomicity: writes go to the live process stream; partial writes are
- * the stream's responsibility, not the tool's. The tool does NOT add a
- * trailing newline — the model controls the exact bytes. This is the
- * design point that makes it a useful test fixture (specs assert on
- * verbatim bytes).
- *
- * Brand voice: English only, no emoji, no banned words.
- */
-/** Per-call byte cap. Mirrors the bash tool's stdout/stderr cap so the
- * model cannot blow either pane with a single synthetic flush. */
-export const SYNTHETIC_OUTPUT_MAX_BYTES = 16 * 1_024;
-/** Canonical stream values. */
-export const SYNTHETIC_OUTPUT_STREAMS = ['stdout', 'stderr'];
-/** Sentinel returned when input validation rejects the call. */
-export const SYNTHETIC_OUTPUT_INVALID_ARGS = 'SYNTHETIC_OUTPUT_INVALID_ARGS';
-/** Sentinel returned when the encoded text exceeds the per-call cap.
- * Distinct from the args-schema failure so the model knows to shorten
- * the payload rather than change the shape. */
-export const SYNTHETIC_OUTPUT_TOO_LARGE = 'SYNTHETIC_OUTPUT_TOO_LARGE';
-/**
- * Validate the raw arguments. Returns the typed value on success or a
- * `SYNTHETIC_OUTPUT_INVALID_ARGS: ...` sentinel string.
- */
-export function parseSyntheticOutputArgs(raw) {
-    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
-        return `${SYNTHETIC_OUTPUT_INVALID_ARGS}: arguments must be a JSON object`;
-    }
-    const obj = raw;
-    const issues = [];
-    const stream = obj['stream'];
-    if (typeof stream !== 'string') {
-        issues.push('stream: must be a string');
-    }
-    else if (!SYNTHETIC_OUTPUT_STREAMS.includes(stream)) {
-        issues.push(`stream: must be one of ${SYNTHETIC_OUTPUT_STREAMS.join('|')}`);
-    }
-    const text = obj['text'];
-    if (typeof text !== 'string') {
-        issues.push('text: must be a string');
-    }
-    if (issues.length > 0) {
-        return `${SYNTHETIC_OUTPUT_INVALID_ARGS}: ${issues.join('; ')}`;
-    }
-    return {
-        stream: stream,
-        text: text,
-    };
-}
-/**
- * Dispatch entry point. Validates input, writes the text verbatim to
- * the requested stream, and returns the structured envelope as JSON.
- *
- * Returns sentinel strings (no throw) on recoverable failures so the
- * engine adapter surfaces them as tool results.
- */
-export function dispatchSyntheticOutput(ctx, raw) {
-    const parsed = parseSyntheticOutputArgs(raw);
-    if (typeof parsed === 'string') {
-        return parsed;
-    }
-    const bytes = Buffer.byteLength(parsed.text, 'utf8');
-    if (bytes > SYNTHETIC_OUTPUT_MAX_BYTES) {
-        return `${SYNTHETIC_OUTPUT_TOO_LARGE}: encoded text exceeds ${SYNTHETIC_OUTPUT_MAX_BYTES} bytes`;
-    }
-    // Resolve writers once per call so a spec can override stdout while
-    // letting stderr fall through to the real process stream.
-    const writer = parsed.stream === 'stdout'
-        ? (ctx.stdoutWrite ?? defaultStdoutWrite)
-        : (ctx.stderrWrite ?? defaultStderrWrite);
-    writer(parsed.text);
-    const result = {
-        ok: true,
-        stream: parsed.stream,
-        bytes,
-    };
-    return JSON.stringify(result);
-}
-function defaultStdoutWrite(chunk) {
-    process.stdout.write(chunk);
-}
-function defaultStderrWrite(chunk) {
-    process.stderr.write(chunk);
-}
-/**
- * JSON-Schema fragment the schema builder advertises to the model.
- * Hand-written for parity with the rest of the tool surface.
- */
-export const syntheticOutputJsonSchema = {
-    type: 'object',
-    additionalProperties: false,
-    required: ['stream', 'text'],
-    properties: {
-        stream: {
-            type: 'string',
-            enum: [...SYNTHETIC_OUTPUT_STREAMS],
-            description: 'Destination stream: stdout or stderr.',
-        },
-        text: {
-            type: 'string',
-            description: `Verbatim bytes to write. Capped at ${SYNTHETIC_OUTPUT_MAX_BYTES} bytes UTF-8.`,
-        },
-    },
-};
-//# sourceMappingURL=synthetic-output.js.map

package/dist/tools/tasks.js

@@ -1,208 +0,0 @@
-/**
- * task_* tool family — β1 T1/T6 (TodoWrite + agent task ledger).
- *
- * Mirrors the standard tool'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 : 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