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

package/dist/core/agents/query-decomposer.js

@@ -1,297 +0,0 @@
-/**
- * Query decomposer — primitive #3 of the 9-layer RAG architecture gap
- * analysis (docs/research/2026-05-31-9-layer-rag-architecture-.md).
- *
- * Splits a user request into ordered atomic sub-queries the engine can
- * route, plan, and execute step-by-step. This file is pure logic — it
- * never opens a network connection itself. The caller injects a
- * `transport` callback that maps a prompt string to a model response
- * string, which keeps Anvil-engine wiring (Hiroshi persona, auth,
- * retry, telemetry) out of the primitive and makes tests deterministic.
- *
- * Failure model is fail-closed to a single-step pass-through. Every
- * malformed response, transport throw, schema violation, dependency
- * cycle, or oversized step list collapses to:
- *
- *  { steps: [{ id: 'step-1', query, dependsOn: [], intent: 'unknown' }],
- *    usedFallback: true, reason: '<why>' }
- *
- * The caller inspects `usedFallback` plus `reason` and decides whether
- * the degradation is acceptable for the active route. Decomposition is
- * never load-bearing for correctness — the engine can always treat the
- * pass-through as the original query.
- *
- * Out of scope (separate PRs):
- *  - Engine wire-up that binds Hiroshi persona to `transport`.
- *  - Adaptive router (primitive #4) that consumes the step list.
- *  - Cost telemetry for the decomposer call itself.
- */
-import { estimateTokens } from '../compact/token-counter.js';
-/** Whitelisted intent categories. Anything outside collapses to 'unknown'. */
-const INTENT_VALUES = ['read', 'write', 'verify', 'plan', 'explain', 'unknown'];
-const DEFAULT_MAX_STEPS = 8;
-const DEFAULT_MAX_INPUT_TOKENS = 4000;
-const STEP_ID_PATTERN = /^step-\d+$/;
-/**
- * Prompt template embedded as a constant so the primitive has zero
- * filesystem dependencies. The `{query}` marker is substituted at call
- * time. The instruction explicitly forbids markdown fences and prose
- * around the JSON, which trims the most common parse failures observed
- * with mid-tier models.
- */
-export const DECOMPOSER_PROMPT_TEMPLATE = [
-    'You are a query decomposer for a software-engineering AI assistant.',
-    "Split the user's request into atomic ordered steps.",
-    '',
-    'Return JSON only, matching this exact schema:',
-    '{ "steps": [{ "id": "step-N", "query": "...", "dependsOn": ["step-M", ...], "intent": "read|write|verify|plan|explain|unknown" }] }',
-    '',
-    'Rules:',
-    '- Max 8 steps.',
-    '- Single-step queries return one step.',
-    '- "dependsOn" lists earlier step IDs this step needs. Empty if independent.',
-    '- "intent" is the top action verb category.',
-    '- No prose around the JSON. No markdown fences.',
-    '',
-    'USER QUERY:',
-    '{query}',
-].join('\n');
-/**
- * Decompose a query into ordered atomic sub-queries.
- *
- * The function never throws. Every internal failure mode collapses to
- * a single-step fallback result. Caller inspects `usedFallback` and
- * `reason` to decide whether to surface a warning or treat the
- * decomposition as opaque.
- */
-export async function decomposeQuery(query, opts) {
-    const trimmed = query.trim();
-    if (trimmed.length === 0) {
-        return fallback(query, 'empty-query');
-    }
-    const maxSteps = clampMaxSteps(opts.maxSteps);
-    const maxInputTokens = clampMaxInputTokens(opts.maxInputTokens);
-    const safeQuery = truncateToTokenBudget(trimmed, maxInputTokens);
-    const prompt = DECOMPOSER_PROMPT_TEMPLATE.replace('{query}', safeQuery);
-    let raw;
-    try {
-        raw = await opts.transport(prompt);
-    }
-    catch {
-        return fallback(safeQuery, 'transport-error');
-    }
-    const parseResult = parseAndValidate(raw, maxSteps);
-    if (parseResult.ok) {
-        return { steps: parseResult.steps, usedFallback: false };
-    }
-    return fallback(safeQuery, parseResult.reason);
-}
-function parseAndValidate(raw, maxSteps) {
-    let parsed;
-    try {
-        parsed = JSON.parse(stripFences(raw));
-    }
-    catch {
-        return { ok: false, reason: 'parse-failed' };
-    }
-    if (!isRecord(parsed)) {
-        return { ok: false, reason: 'schema-violation' };
-    }
-    const stepsRaw = parsed.steps;
-    if (!Array.isArray(stepsRaw)) {
-        return { ok: false, reason: 'schema-violation' };
-    }
-    if (stepsRaw.length === 0) {
-        return { ok: false, reason: 'empty-step-list' };
-    }
-    if (stepsRaw.length > maxSteps) {
-        return { ok: false, reason: 'exceeds-max-steps' };
-    }
-    const steps = [];
-    const seenIds = new Set();
-    for (const candidate of stepsRaw) {
-        const built = buildStep(candidate);
-        if (!built.ok) {
-            return { ok: false, reason: built.reason };
-        }
-        if (seenIds.has(built.step.id)) {
-            return { ok: false, reason: 'duplicate-id' };
-        }
-        seenIds.add(built.step.id);
-        steps.push(built.step);
-    }
-    for (const step of steps) {
-        for (const dep of step.dependsOn) {
-            if (!seenIds.has(dep)) {
-                return { ok: false, reason: 'unknown-dependency' };
-            }
-        }
-    }
-    if (hasCycle(steps)) {
-        return { ok: false, reason: 'dependency-cycle' };
-    }
-    return { ok: true, steps };
-}
-function buildStep(candidate) {
-    if (!isRecord(candidate)) {
-        return { ok: false, reason: 'schema-violation' };
-    }
-    const id = candidate.id;
-    const query = candidate.query;
-    const dependsOn = candidate.dependsOn;
-    const intent = candidate.intent;
-    if (typeof id !== 'string' || !STEP_ID_PATTERN.test(id)) {
-        return { ok: false, reason: 'schema-violation' };
-    }
-    if (typeof query !== 'string' || query.trim().length === 0) {
-        return { ok: false, reason: 'schema-violation' };
-    }
-    const depsList = [];
-    if (dependsOn !== undefined) {
-        if (!Array.isArray(dependsOn)) {
-            return { ok: false, reason: 'schema-violation' };
-        }
-        for (const dep of dependsOn) {
-            if (typeof dep !== 'string' || !STEP_ID_PATTERN.test(dep)) {
-                return { ok: false, reason: 'schema-violation' };
-            }
-            if (dep === id) {
-                // self-dependency is a degenerate cycle, surface explicitly
-                return { ok: false, reason: 'dependency-cycle' };
-            }
-            depsList.push(dep);
-        }
-    }
-    let intentValue;
-    if (intent === undefined) {
-        intentValue = 'unknown';
-    }
-    else if (typeof intent === 'string' && isIntent(intent)) {
-        intentValue = intent;
-    }
-    else {
-        return { ok: false, reason: 'schema-violation' };
-    }
-    return {
-        ok: true,
-        step: {
-            id,
-            query: query.trim(),
-            dependsOn: depsList,
-            intent: intentValue,
-        },
-    };
-}
-/**
- * Cycle detection via iterative depth-first search with coloring.
- * `WHITE` = unvisited, `GRAY` = on current stack, `BLACK` = fully
- * explored. A back edge to a GRAY node is a cycle.
- */
-function hasCycle(steps) {
-    const WHITE = 0;
-    const GRAY = 1;
-    const BLACK = 2;
-    const colors = new Map();
-    for (const step of steps)
-        colors.set(step.id, WHITE);
-    const byId = new Map(steps.map((s) => [s.id, s]));
-    for (const root of steps) {
-        if (colors.get(root.id) !== WHITE)
-            continue;
-        const stack = [{ id: root.id, depIdx: 0 }];
-        colors.set(root.id, GRAY);
-        while (stack.length > 0) {
-            const frame = stack[stack.length - 1];
-            if (!frame)
-                break;
-            const node = byId.get(frame.id);
-            if (!node) {
-                stack.pop();
-                continue;
-            }
-            if (frame.depIdx >= node.dependsOn.length) {
-                colors.set(node.id, BLACK);
-                stack.pop();
-                continue;
-            }
-            const next = node.dependsOn[frame.depIdx];
-            frame.depIdx += 1;
-            if (next === undefined)
-                continue;
-            const c = colors.get(next);
-            if (c === GRAY)
-                return true;
-            if (c === WHITE) {
-                colors.set(next, GRAY);
-                stack.push({ id: next, depIdx: 0 });
-            }
-        }
-    }
-    return false;
-}
-function fallback(query, reason) {
-    return {
-        steps: [
-            {
-                id: 'step-1',
-                query: query.trim(),
-                dependsOn: [],
-                intent: 'unknown',
-            },
-        ],
-        usedFallback: true,
-        reason,
-    };
-}
-function clampMaxSteps(value) {
-    if (typeof value !== 'number' || !Number.isFinite(value) || value < 1) {
-        return DEFAULT_MAX_STEPS;
-    }
-    return Math.floor(value);
-}
-function clampMaxInputTokens(value) {
-    if (typeof value !== 'number' || !Number.isFinite(value) || value < 1) {
-        return DEFAULT_MAX_INPUT_TOKENS;
-    }
-    return Math.floor(value);
-}
-/**
- * Truncate input to the token budget using the existing chars/4
- * heuristic. We slice by characters proportional to the budget rather
- * than by binary-searching `estimateTokens`, because the heuristic is
- * monotonic in length and an over-shoot is acceptable — the prompt
- * also carries the static template overhead.
- */
-function truncateToTokenBudget(text, maxTokens) {
-    const current = estimateTokens(text);
-    if (current <= maxTokens)
-        return text;
-    const ratio = maxTokens / current;
-    const targetLength = Math.max(1, Math.floor(text.length * ratio));
-    return text.slice(0, targetLength);
-}
-/**
- * Tolerate the most common mid-tier-model deviation: wrapping JSON in
- * a fenced code block. We strip a single leading and trailing fence
- * marker when both are present; otherwise the raw text is returned
- * unchanged and `JSON.parse` will reject it through the normal path.
- */
-function stripFences(raw) {
-    const trimmed = raw.trim();
-    if (!trimmed.startsWith('```'))
-        return trimmed;
-    const firstNewline = trimmed.indexOf('\n');
-    if (firstNewline < 0)
-        return trimmed;
-    const closing = trimmed.lastIndexOf('```');
-    if (closing <= firstNewline)
-        return trimmed;
-    return trimmed.slice(firstNewline + 1, closing).trim();
-}
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-function isIntent(value) {
-    return INTENT_VALUES.includes(value);
-}
-//# sourceMappingURL=query-decomposer.js.map

package/dist/core/agents/registry.js

@@ -1,69 +0,0 @@
-/**
- * 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 : 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 ; 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  — the cabinet's review
- * pipeline already merges the two surfaces.
- */
-export const SUBAGENT_REGISTRY = [
-    { role: 'orchestrator', persona: requirePersona('main') }, // Pugi (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

package/dist/core/approvals/shortcut-resolver.js

@@ -1,98 +0,0 @@
-/**
- * Numbered-shortcut + reject-with-reason resolver for approval UX .
- *
- * pattern: when an approval modal lists options, the user can
- * press a digit (1-9) or single letter (y/n/a/d/q) to act without
- * arrow-key navigation. Reject-with-reason lets the user type
- * `n: didn't like the plan` so downstream callers know WHY и can
- * potentially auto-revise.
- *
- * This module is the pure parsing layer — no Ink, no TUI. The TUI
- * consumer wires `parseShortcut` to keyboard events и passes the
- * result back к the engine.
- */
-const ACCEPT_LETTERS = new Set(['y', 'a']);
-const REJECT_LETTERS = new Set(['n']);
-const ABORT_LETTERS = new Set(['q', 'x']);
-const DEFER_LETTERS = new Set(['d', 'l']);
-const MAX_DIGIT_SHORTCUT = 9;
-/**
- * Parse a single keystroke or short input string into a decision.
- *
- * Supported forms (case-insensitive on letters):
- *  "1" .. "9"              → accept option by 1-based index
- *  "y" / "a"               → accept first option
- *  "n"                     → reject (no reason)
- *  "n: didn't like the AST" → reject with reason
- *  "q" / "x"               → abort
- *  "d" / "l"               → defer (decide later)
- *  anything else           → unknown
- *
- * Whitespace around the input is trimmed. Reject-reason syntax accepts
- * both `n:` и `n -` separators, plus the longer `reject: <reason>`.
- */
-export function parseShortcut(input, options = []) {
-    const raw = input.trim();
-    if (raw.length === 0)
-        return { kind: 'unknown' };
-    // reject:<reason> или reject - <reason>
-    const rejectVerbose = /^reject\s*[:\-]\s*(.*)$/i.exec(raw);
-    if (rejectVerbose) {
-        const reason = (rejectVerbose[1] ?? '').trim();
-        return { kind: 'reject', reason: reason.length > 0 ? reason : null };
-    }
-    // n: <reason> / n - <reason>
-    const rejectShort = /^n\s*[:\-]\s*(.*)$/i.exec(raw);
-    if (rejectShort) {
-        const reason = (rejectShort[1] ?? '').trim();
-        return { kind: 'reject', reason: reason.length > 0 ? reason : null };
-    }
-    // Single digit 1..9 mapped to option index (1-based)
-    if (/^\d$/.test(raw)) {
-        const idx = Number.parseInt(raw, 10);
-        if (idx >= 1 && idx <= MAX_DIGIT_SHORTCUT) {
-            // If options provided, validate в range; else trust the index
-            if (options.length === 0 || idx <= options.length) {
-                return { kind: 'accept', index: idx };
-            }
-        }
-        return { kind: 'unknown' };
-    }
-    const lowered = raw.toLowerCase();
-    // Explicit per-option shortcut letter (e.g., "y" wired to option 1)
-    for (const opt of options) {
-        if (opt.shortcut && opt.shortcut.toLowerCase() === lowered) {
-            return { kind: 'accept', index: opt.index };
-        }
-    }
-    // Generic letters
-    if (ACCEPT_LETTERS.has(lowered))
-        return { kind: 'accept', index: 1 };
-    if (REJECT_LETTERS.has(lowered))
-        return { kind: 'reject', reason: null };
-    if (ABORT_LETTERS.has(lowered))
-        return { kind: 'abort' };
-    if (DEFER_LETTERS.has(lowered))
-        return { kind: 'defer' };
-    return { kind: 'unknown' };
-}
-/**
- * Pre-render a help line listing shortcuts. Used by the TUI footer.
- * Format: "[1-N] accept · [n] reject · [q] abort · [d] defer".
- */
-export function formatShortcutHelp(options) {
-    const parts = [];
-    if (options.length > 0) {
-        if (options.length === 1) {
-            parts.push('[1] accept');
-        }
-        else {
-            parts.push(`[1-${Math.min(options.length, MAX_DIGIT_SHORTCUT)}] accept`);
-        }
-    }
-    parts.push('[n] reject ([n: reason] для details)');
-    parts.push('[d] defer');
-    parts.push('[q] abort');
-    return parts.join(' · ');
-}
-//# sourceMappingURL=shortcut-resolver.js.map

package/dist/core/artifact-chain/dispatcher.js

@@ -1,148 +0,0 @@
-/**
- * Artifact chain dispatcher — Pugi  .
- *
- * Bridges the chain state machine (`state.ts`) to the existing
- * `pugi delegate` surface. Each step renders a brief from the
- * step's template + chain context, dispatches the brief to the
- * step's persona, and writes the persona's response verbatim to the
- * artifact file on disk.
- *
- * Mock-friendly by contract — the dispatcher accepts an injected
- * `dispatch` function so specs can drive every branch without
- * standing up a real runtime + Anvil round-trip. The real wire-up
- * binds `dispatch` to the existing `submitDelegate` SDK helper +
- * the SSE waiter; that wiring lives in `runtime/commands/chain.ts`
- * so this module stays pure with respect to the network.
- *
- * Module contract:
- *
- *  - `dispatchStep` is the ONLY entry point. It reads the chain,
- *    renders the brief, calls the injected dispatcher, persists the
- *    artifact, and flips the step state. Callers do not touch the
- *    state machine directly — that surface is intentionally narrow.
- *
- *  - The dispatcher never auto-advances. After a step lands the
- *    cursor stays on the same step until the operator runs
- *    `pugi chain next` again (or until `markComplete` is invoked
- *    by the CLI handler after operator approval).
- */
-import { mkdirSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { chainDir, markComplete, markDispatched, markError, readChain, } from './state.js';
-import { findStep, renderBrief, } from './steps.js';
-/**
- * Dispatch one step in the chain. The function is non-throwing — every
- * failure mode returns a structured result so the CLI handler can map
- * to an exit code without a try/catch wrapper.
- */
-export async function dispatchStep(options) {
-    const now = options.now ?? (() => new Date());
-    const state = readChain(options.workspaceCwd, options.chainId);
-    if (!state) {
-        // Gemini P1 fix (PR): the docblock above promises a non-
-        // throwing surface, but the historical implementation threw here.
-        // Return a structured result keyed on `reason: 'chain_not_found'`
-        // so callers can switch on the failure family deterministically.
-        return {
-            ok: false,
-            stepId: 'prd',
-            error: `chain ${options.chainId} not found`,
-            reason: 'chain_not_found',
-            state: null,
-        };
-    }
-    const targetStepId = options.stepId ?? state.nextStep;
-    if (!targetStepId) {
-        return {
-            ok: false,
-            stepId: 'code',
-            error: 'chain is finalised — every step is already complete',
-            state,
-        };
-    }
-    const step = findStep(targetStepId);
-    if (!step) {
-        return {
-            ok: false,
-            stepId: targetStepId,
-            error: `unknown step id '${targetStepId}'`,
-            state,
-        };
-    }
-    const stepRecord = state.steps.find((s) => s.id === targetStepId);
-    if (stepRecord?.status === 'complete') {
-        return {
-            ok: false,
-            stepId: targetStepId,
-            error: `step '${targetStepId}' is already complete`,
-            state,
-        };
-    }
-    const brief = renderBrief(step.briefTemplate, {
-        chainId: state.id,
-        intent: state.intent,
-    });
-    let outcome;
-    try {
-        outcome = await options.dispatch({ chainId: state.id, step, brief });
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        const errorState = markError(options.workspaceCwd, options.chainId, targetStepId, message, { now });
-        return {
-            ok: false,
-            stepId: targetStepId,
-            error: message,
-            state: errorState,
-        };
-    }
-    if (outcome.kind === 'failed') {
-        const errorState = markError(options.workspaceCwd, options.chainId, targetStepId, outcome.error, { now });
-        return {
-            ok: false,
-            stepId: targetStepId,
-            error: outcome.error,
-            state: errorState,
-        };
-    }
-    // Success path: persist the artifact, flip the step to dispatched
-    // (or complete when autoApprove is set).
-    const dir = chainDir(options.workspaceCwd, state.id);
-    mkdirSync(dir, { recursive: true });
-    const artifactPath = join(dir, step.artifactFilename);
-    writeFileSync(artifactPath, ensureTrailingNewline(outcome.artifact), 'utf8');
-    let finalState = markDispatched(options.workspaceCwd, options.chainId, targetStepId, outcome.dispatchId, { now });
-    if (options.autoApprove) {
-        finalState = markComplete(options.workspaceCwd, options.chainId, targetStepId, { now });
-    }
-    return {
-        ok: true,
-        stepId: targetStepId,
-        dispatchId: outcome.dispatchId,
-        artifactPath,
-        state: finalState,
-    };
-}
-/**
- * Synthesize a dispatcher that captures every call for inspection.
- * Test-only — the real wire-up never uses this.
- */
-export function createRecordingDispatcher(outcomes) {
-    const calls = [];
-    let index = 0;
-    const fn = async ({ chainId, step, brief }) => {
-        calls.push({ chainId, stepId: step.id, brief });
-        const outcome = outcomes[index];
-        index += 1;
-        if (!outcome) {
-            throw new Error(`recording dispatcher exhausted at call #${calls.length}`);
-        }
-        return outcome;
-    };
-    fn.calls = calls;
-    return fn;
-}
-function ensureTrailingNewline(text) {
-    return text.endsWith('\n') ? text : `${text}\n`;
-}
-//# sourceMappingURL=dispatcher.js.map