peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/context/collector.js

@@ -0,0 +1,133 @@
+/**
+ * Per spec §4.1 Step 1 — Collector.
+ *
+ * Hard constraints H1 (CLI enforces reads, not LLM), H2 (locked version).
+ * All inputs validated via Zod; all reads via Node fs (no shell-out).
+ */
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { z } from 'zod';
+const CollectInputSchema = z.object({
+    goal: z.string().min(1),
+    project: z.string().min(1),
+    depsMode: z.enum(['locked', 'latest']),
+    out: z.string().optional(),
+});
+function classifyKind(path) {
+    if (path.includes('/__tests__/') || path.endsWith('.test.ts') || path.endsWith('.test.tsx')) {
+        return 'test';
+    }
+    if (path.startsWith('config') || path.endsWith('.config.ts') || path.endsWith('.config.js')) {
+        return 'config';
+    }
+    if (path.endsWith('.md') || path.endsWith('.mdx')) {
+        return 'doc';
+    }
+    return 'source';
+}
+async function scanFiles(root, exclude) {
+    const out = [];
+    async function walk(dir) {
+        const entries = await readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.name === 'node_modules' || entry.name === '.git' || entry.name === 'dist') {
+                continue;
+            }
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                await walk(full);
+                continue;
+            }
+            const rel = relative(root, full).replaceAll('\\', '/');
+            if (exclude !== undefined && rel === exclude) {
+                continue;
+            }
+            const s = await stat(full);
+            out.push({
+                path: rel,
+                kind: classifyKind(relative(root, full)),
+                lines: 0, // computed lazily; full line count is expensive
+                hash: '', // computed lazily via content-hash-cache-pattern
+            });
+        }
+    }
+    await walk(root);
+    return out;
+}
+async function readGitStatus(project) {
+    // Minimal git info via Node — for now delegate to `git` CLI in a future slice.
+    // Returning a placeholder keeps the collector testable; full git integration
+    // arrives in Task 4 (RD integration) when git is actually needed downstream.
+    return {
+        branch: 'main',
+        lastCommit: 'unknown',
+        dirty: false,
+    };
+}
+async function readMemoryEntries(project) {
+    // Read .peaks/memory/*.md frontmatter; for v1 store only hash + path
+    // (per H8 — never leak full memory text into LLM context).
+    const memDir = join(project, '.peaks', 'memory');
+    try {
+        const entries = await readdir(memDir);
+        return entries
+            .filter((n) => n.endsWith('.md'))
+            .map((n) => ({
+            path: join('.peaks/memory', n),
+            title: n,
+            relevanceScore: 0,
+            excerptHash: '',
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+async function readDeps(project, depsMode) {
+    if (depsMode === 'latest') {
+        throw new Error('BLOCKED: --deps-mode latest is forbidden by spec §4.1 (H2: locked only). ' +
+            'Configure the project lockfile to enable locked mode.');
+    }
+    const pkgPath = join(project, 'package.json');
+    let raw;
+    try {
+        raw = await readFile(pkgPath, 'utf8');
+    }
+    catch {
+        throw new Error(`BLOCKED: no package.json at ${project}`);
+    }
+    const pkg = JSON.parse(raw);
+    const deps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
+    if (Object.keys(deps).length === 0) {
+        throw new Error(`BLOCKED: no locked version found in ${pkgPath}. ` +
+            'spec §4.1 forbids running with empty dependencies (H2).');
+    }
+    const result = {};
+    for (const [name, version] of Object.entries(deps)) {
+        if (typeof version !== 'string' || version === '') {
+            throw new Error(`BLOCKED: dep ${name} has no locked version`);
+        }
+        result[name] = {
+            version,
+            source: 'package.json',
+            resolved: '', // filled by lockfile parser in a later slice
+        };
+    }
+    return result;
+}
+export async function collectContext(rawInput) {
+    const input = CollectInputSchema.parse(rawInput);
+    const exclude = input.out !== undefined
+        ? relative(input.project, input.out).replaceAll('\\', '/')
+        : undefined;
+    const [files, gitStatus, memoryEntries, deps] = await Promise.all([
+        scanFiles(input.project, exclude),
+        readGitStatus(input.project),
+        readMemoryEntries(input.project),
+        readDeps(input.project, input.depsMode),
+    ]);
+    return {
+        goal: input.goal,
+        collector: { files, gitStatus, memoryEntries, deps },
+    };
+}

package/dist/services/context/context-builder.d.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+import type { ContextJson } from './types.js';
+declare const BuildInputSchema: z.ZodObject<{
+    goal: z.ZodString;
+    project: z.ZodString;
+    audience: z.ZodEnum<["peaks-rd", "peaks-qa", "peaks-mut", "all"]>;
+    depsMode: z.ZodEnum<["locked", "latest"]>;
+    docBudgetTokens: z.ZodDefault<z.ZodNumber>;
+    out: z.ZodString;
+    fetcher: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnknown>;
+}, "strip", z.ZodTypeAny, {
+    project: string;
+    goal: string;
+    audience: "all" | "peaks-rd" | "peaks-qa" | "peaks-mut";
+    depsMode: "latest" | "locked";
+    out: string;
+    docBudgetTokens: number;
+    fetcher: (...args: unknown[]) => unknown;
+}, {
+    project: string;
+    goal: string;
+    audience: "all" | "peaks-rd" | "peaks-qa" | "peaks-mut";
+    depsMode: "latest" | "locked";
+    out: string;
+    fetcher: (...args: unknown[]) => unknown;
+    docBudgetTokens?: number | undefined;
+}>;
+export type BuildInput = z.infer<typeof BuildInputSchema>;
+export declare function buildContext(rawInput: unknown): Promise<ContextJson>;
+export {};

package/dist/services/context/context-builder.js

@@ -0,0 +1,78 @@
+/**
+ * Per spec §4.1 — ContextBuilder.
+ *
+ * Orchestrates Collector → DocRetriever → Tokenizer → Renderer.
+ * Computes sha256 over the content (excluding the sha256 field itself —
+ * H8 audit-trail integrity). Atomic write: tmp file + rename, so a crash
+ * mid-write leaves no partial context.json on disk.
+ */
+import { createHash } from 'node:crypto';
+import { writeFile, rename, unlink } from 'node:fs/promises';
+import { z } from 'zod';
+import { collectContext } from './collector.js';
+import { retrieveDocs } from './doc-retriever.js';
+import { tokenize } from './tokenizer.js';
+import { render } from './renderer.js';
+import { ContextJsonSchema } from './context-schema.js';
+const BuildInputSchema = z.object({
+    goal: z.string().min(1),
+    project: z.string().min(1),
+    audience: z.enum(['peaks-rd', 'peaks-qa', 'peaks-mut', 'all']),
+    depsMode: z.enum(['locked', 'latest']),
+    docBudgetTokens: z.number().int().positive().default(8000),
+    out: z.string().min(1),
+    fetcher: z.function(),
+});
+function sha256OfContent(content) {
+    // Exclude `sha256` field from the hash (else chicken-and-egg).
+    const { sha256: _omit, ...rest } = content;
+    void _omit;
+    const canonical = JSON.stringify(rest, Object.keys(rest).sort());
+    return createHash('sha256').update(canonical).digest('hex');
+}
+export async function buildContext(rawInput) {
+    const input = BuildInputSchema.parse(rawInput);
+    const collected = await collectContext({
+        goal: input.goal,
+        project: input.project,
+        depsMode: input.depsMode,
+        out: input.out,
+    });
+    const docs = await retrieveDocs(collected.collector.deps, { fetcher: input.fetcher });
+    const tok = tokenize(collected.collector, docs);
+    const renderInput = {
+        goal: input.goal,
+        audience: input.audience,
+        docBudgetTokens: input.docBudgetTokens,
+        collector: collected.collector,
+        docRetriever: docs,
+        tokenizer: tok,
+    };
+    const renderer = render(renderInput);
+    // First pass: placeholder sha256 so we can hash the rest.
+    const partial = {
+        version: '1.0',
+        goal: input.goal,
+        generatedAt: new Date().toISOString(),
+        sha256: '',
+        collector: collected.collector,
+        docRetriever: docs,
+        tokenizer: tok,
+        renderer,
+    };
+    const sha256 = sha256OfContent(partial);
+    const finalCtx = { ...partial, sha256 };
+    // Validate before write (H8: garbage context.json must never land).
+    ContextJsonSchema.parse(finalCtx);
+    // Atomic write: tmp + rename.
+    const tmp = `${input.out}.tmp`;
+    try {
+        await writeFile(tmp, JSON.stringify(finalCtx, null, 2), 'utf8');
+        await rename(tmp, input.out);
+    }
+    catch (err) {
+        await unlink(tmp).catch(() => undefined);
+        throw err;
+    }
+    return finalCtx;
+}

package/dist/services/context/context-guard.d.ts

@@ -0,0 +1,49 @@
+/**
+ * G9 — forced compression gate (RL-27..RL-32).
+ *
+ * The CLI 兜底 layer. Validates prompt size against the threshold
+ * table in `threshold.ts` and returns a decision. The PreToolUse hook
+ * layer (`peaks sub-agent-dispatch-guard`) re-runs the same logic
+ * without `--force` (RL-30 strict).
+ *
+ * Decision codes:
+ *   - `OK`                          — under 50%
+ *   - `CONTEXT_SOFT_WARN`           — 50-75%, suggest --use-headroom
+ *   - `CONTEXT_NEAR_LIMIT`          — 75-80%, mandatory --use-headroom suggestion
+ *   - `PROMPT_TOO_LARGE`            — 80-90%, hard reject (allow = false)
+ *   - `PROMPT_EMERGENCY`            — ≥ 90%, hard reject + emergency
+ *   - `FORCED_OVER_THRESHOLD`       — user passed --force at CLI; allow = true
+ *
+ * See: `.peaks/memory/sub-agent-headroom-forced-compression-gate.md`.
+ */
+import { tierToCode, type ThresholdEvaluation } from './threshold.js';
+export type ContextGuardCode = 'OK' | 'CONTEXT_SOFT_WARN' | 'CONTEXT_NEAR_LIMIT' | 'PROMPT_TOO_LARGE' | 'PROMPT_EMERGENCY' | 'FORCED_OVER_THRESHOLD';
+export interface ContextGuardDecision {
+    readonly allow: boolean;
+    readonly code: ContextGuardCode;
+    readonly warnings: readonly string[];
+    readonly suggest: string | null;
+    readonly evaluation: ThresholdEvaluation;
+    /** ISO8601 timestamp when --force override was applied. null otherwise. */
+    readonly forcedAt: string | null;
+}
+export interface ContextGuardOptions {
+    /** Pass `true` to allow override at the ≥ 80% tier. CLI-only; hook layer MUST NOT set this. */
+    readonly force?: boolean;
+    /** Override the default 256K context capacity (e.g. for tests). */
+    readonly capacityBytes?: number;
+}
+/**
+ * Evaluate a prompt size against the G9.3 threshold table.
+ *
+ * The `force` option is the **only** path that lets a ≥ 80% prompt
+ * through. The hook layer (PreToolUse) MUST NOT accept this option;
+ * it is enforced by the `peaks sub-agent-dispatch-guard` atom's
+ * command-line parser, which does not declare a `--force` flag.
+ */
+export declare function evaluatePromptSize(promptSize: number, opts?: ContextGuardOptions): ContextGuardDecision;
+/**
+ * Re-export of `tierToCode` for callers that want a stable mapping
+ * without depending on the threshold module directly.
+ */
+export { tierToCode };

package/dist/services/context/context-guard.js

@@ -0,0 +1,91 @@
+/**
+ * G9 — forced compression gate (RL-27..RL-32).
+ *
+ * The CLI 兜底 layer. Validates prompt size against the threshold
+ * table in `threshold.ts` and returns a decision. The PreToolUse hook
+ * layer (`peaks sub-agent-dispatch-guard`) re-runs the same logic
+ * without `--force` (RL-30 strict).
+ *
+ * Decision codes:
+ *   - `OK`                          — under 50%
+ *   - `CONTEXT_SOFT_WARN`           — 50-75%, suggest --use-headroom
+ *   - `CONTEXT_NEAR_LIMIT`          — 75-80%, mandatory --use-headroom suggestion
+ *   - `PROMPT_TOO_LARGE`            — 80-90%, hard reject (allow = false)
+ *   - `PROMPT_EMERGENCY`            — ≥ 90%, hard reject + emergency
+ *   - `FORCED_OVER_THRESHOLD`       — user passed --force at CLI; allow = true
+ *
+ * See: `.peaks/memory/sub-agent-headroom-forced-compression-gate.md`.
+ */
+import { CONTEXT_CAPACITY_DEFAULT_BYTES, evaluateThresholdTier, tierToCode } from './threshold.js';
+const NEAR_LIMIT_SUGGEST = 'Consider --use-headroom to compress prompt.';
+const SOFT_WARN_SUGGEST = 'Use --use-headroom to compress prompt proactively.';
+const HARD_REJECT_SUGGEST = 'Trim prompt to < 80% of context capacity. Pass --force at CLI to override (NOT allowed at hook layer).';
+const EMERGENCY_SUGGEST = 'Prompt exceeds 90% of context. Trim aggressively or split into multiple dispatches.';
+/**
+ * Evaluate a prompt size against the G9.3 threshold table.
+ *
+ * The `force` option is the **only** path that lets a ≥ 80% prompt
+ * through. The hook layer (PreToolUse) MUST NOT accept this option;
+ * it is enforced by the `peaks sub-agent-dispatch-guard` atom's
+ * command-line parser, which does not declare a `--force` flag.
+ */
+export function evaluatePromptSize(promptSize, opts = {}) {
+    const capacity = opts.capacityBytes ?? CONTEXT_CAPACITY_DEFAULT_BYTES;
+    const evaluation = evaluateThresholdTier(promptSize, capacity);
+    const tier = evaluation.tier;
+    let allow;
+    let code;
+    let suggest;
+    let forcedAt = null;
+    switch (tier) {
+        case 'ok':
+            allow = true;
+            code = 'OK';
+            suggest = null;
+            break;
+        case 'soft-warn':
+            allow = true;
+            code = 'CONTEXT_SOFT_WARN';
+            suggest = SOFT_WARN_SUGGEST;
+            break;
+        case 'near-limit':
+            allow = true;
+            code = 'CONTEXT_NEAR_LIMIT';
+            suggest = NEAR_LIMIT_SUGGEST;
+            break;
+        case 'hard-reject':
+            allow = false;
+            code = 'PROMPT_TOO_LARGE';
+            suggest = HARD_REJECT_SUGGEST;
+            break;
+        case 'emergency':
+            allow = false;
+            code = 'PROMPT_EMERGENCY';
+            suggest = EMERGENCY_SUGGEST;
+            break;
+    }
+    // --force override (CLI only; hook layer never reaches this branch)
+    if (!allow && opts.force === true) {
+        allow = true;
+        code = 'FORCED_OVER_THRESHOLD';
+        suggest = 'Override applied at CLI. Hook layer will still reject.';
+        forcedAt = new Date().toISOString();
+    }
+    const warnings = [...evaluation.warnings];
+    if (forcedAt !== null && !warnings.includes('FORCED_OVER_THRESHOLD')) {
+        warnings.push('FORCED_OVER_THRESHOLD');
+    }
+    return {
+        allow,
+        code,
+        warnings,
+        suggest,
+        evaluation,
+        forcedAt
+    };
+}
+/**
+ * Re-export of `tierToCode` for callers that want a stable mapping
+ * without depending on the threshold module directly.
+ */
+export { tierToCode };