@pugi/cli 0.1.0-alpha.3 → 0.1.0-alpha.6

package/README.md

@@ -127,6 +127,26 @@ The CLI never installs anything outside the Node global prefix and the
 Homebrew cellar. `.pugi/` directories in your repos are left untouched on
 uninstall; remove them manually if you want a clean slate.
 
+## Hooks
+
+Pugi runs user-defined shell commands at lifecycle events (`SessionStart`,
+`PreToolUse`, `PermissionRequest`, `PostToolUse`, `PostToolUseFailure`,
+`Stop`, `SessionEnd`, `UserPromptSubmit`). Drop a `hooks.json` at one of:
+
+- `~/.pugi/hooks.json` — user hooks, always loaded.
+- `<workspace>/.pugi/hooks.json` — project hooks, loaded only when the
+  workspace is trusted (see Sprint α5.6 for the `pugi config trust .` UX).
+
+See [`docs/hooks-example.json`](./docs/hooks-example.json) for a working
+config. Example: log every bash invocation through `logger`:
+
+```json
+{ "event": "PreToolUse", "match": { "tool": "bash" }, "run": "logger -t pugi \"$PUGI_HOOK_PAYLOAD\"" }
+```
+
+Hooks cannot bypass permissions — a hook that re-invokes `pugi` re-enters
+the permission engine in its own process.
+
 ## Distribution
 
 The three install paths are documented in detail at

package/dist/commands/jobs.js

@@ -0,0 +1,245 @@
+/**
+ * `pugi jobs` command surface — Sprint α5.9 (ADR-0056 PR-PUGI-CLI-M1-GAP-J).
+ *
+ * Subcommands:
+ *   pugi jobs list                 — table of all tracked jobs (or JSON envelope)
+ *   pugi jobs status <id>          — full record + tail of overflow artifact
+ *   pugi jobs tail <id>            — stream the overflow artifact
+ *   pugi jobs kill <id>            — SIGTERM then SIGKILL after a grace
+ *   pugi jobs kill --all           — kill every running job in this session
+ *
+ * Power-word voice rules (per Pugi brand guide):
+ *   - status names render as "on watch" (running), "shipped" (finished),
+ *     "stood down" (killed), "blocked" (failed), "lost" (abandoned).
+ *   - JSON envelopes keep the machine-friendly enum so consumers do
+ *     not have to map back.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { formatDuration, getJobRegistry, relativeAge, } from '../core/jobs/registry.js';
+const HUMAN_STATUS = {
+    running: 'on watch',
+    finished: 'shipped',
+    killed: 'stood down',
+    failed: 'blocked',
+    abandoned: 'lost',
+};
+export async function runJobsCommand(args, flags, io, sessionId) {
+    const sub = args[0] ?? 'list';
+    switch (sub) {
+        case 'list':
+            return runList(flags, io);
+        case 'status':
+            return runStatus(args[1], flags, io);
+        case 'tail':
+            return runTail(args[1], flags, io);
+        case 'kill':
+            return runKill(args.slice(1), flags, io, sessionId);
+        default:
+            io.writeError(`Unknown subcommand: ${sub}`);
+            io.writeError(usage());
+            return 2;
+    }
+}
+function usage() {
+    return [
+        'Usage:',
+        '  pugi jobs list [--json]                  Table of background jobs.',
+        '  pugi jobs status <id> [--json]           Full record + tail of artifact.',
+        '  pugi jobs tail <id>                      Stream the captured artifact.',
+        '  pugi jobs kill <id> [--json]             SIGTERM, escalate to SIGKILL.',
+        '  pugi jobs kill --all [--json]            Stand down every running job.',
+    ].join('\n');
+}
+async function runList(flags, io) {
+    const registry = getJobRegistry();
+    const entries = await registry.list();
+    if (flags.json) {
+        io.write(`${JSON.stringify({
+            command: 'jobs.list',
+            count: entries.length,
+            jobs: entries.map(serializeForJson),
+        }, null, 2)}\n`);
+        return 0;
+    }
+    io.write(`${renderTable(entries)}\n`);
+    return 0;
+}
+async function runStatus(id, flags, io) {
+    if (!id) {
+        io.writeError('pugi jobs status requires a job id');
+        return 2;
+    }
+    const registry = getJobRegistry();
+    const entry = await registry.get(id);
+    if (!entry) {
+        if (flags.json) {
+            io.write(`${JSON.stringify({ command: 'jobs.status', error: 'not_found', id }, null, 2)}\n`);
+        }
+        else {
+            io.writeError(`Job not found: ${id}`);
+        }
+        return 1;
+    }
+    const tail = entry.outputArtifactRef ? readArtifactTail(entry.outputArtifactRef, 4_096) : '';
+    if (flags.json) {
+        io.write(`${JSON.stringify({
+            command: 'jobs.status',
+            job: serializeForJson(entry),
+            tail,
+        }, null, 2)}\n`);
+        return 0;
+    }
+    const lines = [
+        `Job ${entry.id}`,
+        `  PID:        ${entry.pid}`,
+        `  Command:    ${entry.command}`,
+        `  Class:      ${entry.bashClass}`,
+        `  Status:     ${HUMAN_STATUS[entry.status]} (${entry.status})`,
+        `  CWD:        ${entry.cwd}`,
+        `  Started:    ${entry.startedAt} (${relativeAge(entry.startedAt)} ago)`,
+        `  Duration:   ${formatDuration(entry.startedAt, entry.finishedAt)}`,
+    ];
+    if (entry.finishedAt)
+        lines.push(`  Finished:   ${entry.finishedAt}`);
+    if (entry.exitCode !== undefined)
+        lines.push(`  Exit code:  ${entry.exitCode}`);
+    if (entry.outputArtifactRef)
+        lines.push(`  Artifact:   ${entry.outputArtifactRef}`);
+    if (tail) {
+        lines.push('', '--- output tail ---', tail);
+    }
+    io.write(`${lines.join('\n')}\n`);
+    return 0;
+}
+async function runTail(id, _flags, io) {
+    if (!id) {
+        io.writeError('pugi jobs tail requires a job id');
+        return 2;
+    }
+    const registry = getJobRegistry();
+    const entry = await registry.get(id);
+    if (!entry) {
+        io.writeError(`Job not found: ${id}`);
+        return 1;
+    }
+    if (!entry.outputArtifactRef) {
+        io.writeError(`Job ${id} has no captured output artifact yet (background jobs spawn with stdio=ignore by default).`);
+        return 1;
+    }
+    if (!existsSync(entry.outputArtifactRef)) {
+        io.writeError(`Artifact missing on disk: ${entry.outputArtifactRef}`);
+        return 1;
+    }
+    const body = readFileSync(entry.outputArtifactRef, 'utf8');
+    io.write(body.endsWith('\n') ? body : `${body}\n`);
+    return 0;
+}
+async function runKill(args, flags, io, sessionId) {
+    const registry = getJobRegistry();
+    const killAll = flags.all || args.includes('--all');
+    if (killAll) {
+        const entries = await registry.list();
+        const targets = entries.filter((entry) => {
+            if (entry.status !== 'running')
+                return false;
+            if (sessionId && entry.sessionId !== sessionId)
+                return false;
+            return true;
+        });
+        const results = [];
+        for (const target of targets) {
+            const result = await registry.kill(target.id);
+            results.push({ id: target.id, ...result });
+        }
+        if (flags.json) {
+            io.write(`${JSON.stringify({ command: 'jobs.kill', scope: 'all', results }, null, 2)}\n`);
+        }
+        else if (results.length === 0) {
+            io.write('No running jobs to stand down.\n');
+        }
+        else {
+            for (const result of results) {
+                io.write(`  ${result.id}  ${result.killed ? 'stood down' : 'noop'} (${result.method})\n`);
+            }
+        }
+        return 0;
+    }
+    const id = args[0];
+    if (!id) {
+        io.writeError('pugi jobs kill requires a job id (or --all)');
+        return 2;
+    }
+    const result = await registry.kill(id);
+    if (flags.json) {
+        io.write(`${JSON.stringify({ command: 'jobs.kill', id, ...result }, null, 2)}\n`);
+        return result.killed || result.method === 'noop' ? 0 : 1;
+    }
+    if (result.killed) {
+        io.write(`Job ${id} stood down (${result.method}).\n`);
+        return 0;
+    }
+    io.writeError(`Job ${id} was not running or could not be signalled.`);
+    return 1;
+}
+function serializeForJson(entry) {
+    const ageSeconds = Math.max(0, Math.floor((Date.now() - Date.parse(entry.startedAt)) / 1000));
+    let durationSeconds;
+    if (entry.finishedAt) {
+        const start = Date.parse(entry.startedAt);
+        const end = Date.parse(entry.finishedAt);
+        if (!Number.isNaN(start) && !Number.isNaN(end) && end >= start) {
+            durationSeconds = Math.floor((end - start) / 1000);
+        }
+    }
+    return {
+        ...entry,
+        humanStatus: HUMAN_STATUS[entry.status],
+        ageSeconds,
+        durationSeconds,
+    };
+}
+function readArtifactTail(path, byteBudget) {
+    if (!existsSync(path))
+        return '';
+    try {
+        const body = readFileSync(path, 'utf8');
+        if (body.length <= byteBudget)
+            return body;
+        return `(...truncated; tail ${byteBudget} bytes of ${body.length})\n${body.slice(-byteBudget)}`;
+    }
+    catch {
+        return '';
+    }
+}
+function renderTable(entries) {
+    if (entries.length === 0) {
+        return 'No background jobs tracked. Spawn one via the bash tool (background: true) and it lands here.';
+    }
+    const header = ['ID', 'COMMAND', 'CLASS', 'STATUS', 'STARTED', 'DURATION'];
+    const rows = [header];
+    for (const entry of entries) {
+        rows.push([
+            entry.id.replace(/^pj-/, '').slice(0, 8),
+            truncate(entry.command, 24),
+            entry.bashClass,
+            HUMAN_STATUS[entry.status],
+            `${relativeAge(entry.startedAt)} ago`,
+            formatDuration(entry.startedAt, entry.finishedAt),
+        ]);
+    }
+    const widths = header.map((_, i) => Math.max(...rows.map((row) => (row[i] ?? '').length)));
+    // Reserve a little headroom so the right-hand columns do not bleed
+    // past 80 chars when the command column hits its 24-char ceiling.
+    return rows
+        .map((row) => row
+        .map((cell, i) => cell.padEnd(widths[i] ?? cell.length))
+        .join('  ')
+        .trimEnd())
+        .join('\n');
+}
+function truncate(value, max) {
+    if (value.length <= max)
+        return value;
+    return `${value.slice(0, max - 1)}…`;
+}
+//# sourceMappingURL=jobs.js.map

package/dist/core/agents/registry.js

@@ -0,0 +1,69 @@
+/**
+ * Subagent role → Cyber-Zoo persona mapping for the Pugi CLI.
+ *
+ * The CLI dispatcher resolves a role string ('coder', 'reviewer',
+ * 'orchestrator', ...) to a brand persona that owns the work and is
+ * stamped on the audit-trace event. This file is the single place where
+ * that mapping lives — keep it tight and explicit so persona drift never
+ * leaks back into the dispatch surface.
+ *
+ * M1 closed set (ADR-0056 Sprint α5.1): 9 roles, all mapped to Tier 1
+ * Engineering Core or Tier 2 Specialist personas from THE_TEN. Tier 1
+ * Missing Functions (Growth/Legal/Security/Sales/Support) are deferred
+ * to α7.5; Sigma is intentionally absent because it is an OES Enterprise
+ * persona via Anvil triple-review proxy, not a Cyber-Zoo brand persona.
+ */
+import { THE_TEN, getPersona } from '@pugi/personas';
+/**
+ * Resolve a slug from THE_TEN or throw with a build-time
+ * diagnostic. Used during registry construction so a typo in the mapping
+ * surfaces at module-load instead of at dispatch time.
+ */
+function requirePersona(slug) {
+    const persona = getPersona(slug);
+    if (!persona) {
+        const available = THE_TEN.map((p) => p.slug).join(', ');
+        throw new Error(`SUBAGENT_REGISTRY: slug '${slug}' is not in THE_TEN (have: ${available})`);
+    }
+    return persona;
+}
+/**
+ * CLI-only role-to-persona mapping. Roles are dispatcher-facing strings;
+ * personas come from the brand-canonical THE_TEN. Vera (qa) intentionally
+ * dual-roles as verifier + reviewer per ADR-0056 — the cabinet's review
+ * pipeline already merges the two surfaces.
+ */
+export const SUBAGENT_REGISTRY = [
+    { role: 'orchestrator', persona: requirePersona('main') }, // Mira (Pug)
+    { role: 'architect', persona: requirePersona('architect') }, // Marcus (Owl)
+    { role: 'coder', persona: requirePersona('dev') }, // Hiroshi (Wolf)
+    { role: 'verifier', persona: requirePersona('qa') }, // Vera (Fox)
+    { role: 'reviewer', persona: requirePersona('qa') }, // Vera dual-role
+    { role: 'researcher', persona: requirePersona('researcher') }, // Anika (Raven)
+    { role: 'release', persona: requirePersona('pm') }, // Olivia (Honeybee)
+    { role: 'devops', persona: requirePersona('devops') }, // Diego (Octopus)
+    { role: 'design_qa', persona: requirePersona('designer') }, // Sofia (Stag)
+];
+const REGISTRY_BY_ROLE = new Map(SUBAGENT_REGISTRY.map((d) => [d.role, d]));
+/**
+ * Resolve a role to its full subagent definition. Throws when the role
+ * is not registered; the closed SubagentRole union prevents that at
+ * compile time for typed callers, but the runtime guard catches dynamic
+ * dispatch paths (config files, plugin manifests, ...).
+ */
+export function getSubagent(role) {
+    const def = REGISTRY_BY_ROLE.get(role);
+    if (!def) {
+        throw new Error(`getSubagent: unknown role '${role}'`);
+    }
+    return def;
+}
+/** Convenience: resolve a role straight to its persona. */
+export function getPersonaForRole(role) {
+    return getSubagent(role).persona;
+}
+/** Stable enumeration of registered roles in registry order. */
+export function listRoles() {
+    return SUBAGENT_REGISTRY.map((d) => d.role);
+}
+//# sourceMappingURL=registry.js.map