peaks-cli 1.4.1 → 2.0.0

package/dist/src/services/audit/enforcers/lint-audit-regression.js

@@ -0,0 +1,86 @@
+/**
+ * P2-b Theme L — Audit regression enforcers.
+ *
+ * Slice #7 L2.4. These four enforcers run during the audit
+ * and check the audit framework's own integrity. They are
+ * the "gating" layer that `peaks slice check`'s new
+ * audit-regression stage asserts.
+ *
+ * Four checks:
+ *   1. catalog-stability       — catalog size has not grown >20% in 90 days
+ *   2. no-orphan-enforcer      — every enforcerRef points to a real file
+ *   3. no-orphan-catalog       — every catalog entry has a non-null enforcerRef
+ *   4. runtime-budget          — audit completes in < 2s on a 100-reference project
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { RED_LINE_CATALOG } from '../red-line-catalog.js';
+export const CATALOG_STABILITY_GROWTH_CAP = 0.20;
+export const CATALOG_STABILITY_WINDOW_DAYS = 90;
+export const RUNTIME_BUDGET_MS = 2000;
+const fakeCatalogPath = 'src/services/audit/red-line-catalog.ts';
+function syntheticHit(catalogId, rule, detail) {
+    return {
+        catalogId,
+        rule,
+        file: fakeCatalogPath,
+        line: 1,
+        matchedText: detail,
+    };
+}
+export function lintCatalogStability(input) {
+    if (input.sizeNinetyDaysAgo === null || input.sizeNinetyDaysAgo === 0) {
+        // No historical data — can't check stability. Treat as a
+        // soft pass (the catalog-stability enforcer is
+        // non-blocking when the data is missing).
+        return [];
+    }
+    const growth = (input.currentSize - input.sizeNinetyDaysAgo) / input.sizeNinetyDaysAgo;
+    if (growth <= CATALOG_STABILITY_GROWTH_CAP)
+        return [];
+    return [syntheticHit('rl-audit-catalog-stability-001', 'catalog size has not grown > 20% in the last 90 days', `(growth ${(growth * 100).toFixed(1)}% over 90 days; currentSize=${input.currentSize}, priorSize=${input.sizeNinetyDaysAgo})`)];
+}
+export function lintNoOrphanEnforcer(projectRoot) {
+    const hits = [];
+    for (const entry of RED_LINE_CATALOG) {
+        if (!entry.enforcerRef)
+            continue;
+        const absPath = join(projectRoot, entry.enforcerRef);
+        if (!existsSync(absPath)) {
+            hits.push(syntheticHit('rl-audit-no-orphan-enforcer-001', 'every enforcerRef points to a real file', `(enforcerRef "${entry.enforcerRef}" for ${entry.id} does not exist on disk)`));
+        }
+    }
+    return hits;
+}
+export function lintNoOrphanCatalog() {
+    const hits = [];
+    for (const entry of RED_LINE_CATALOG) {
+        if (entry.enforcerRef === null) {
+            hits.push(syntheticHit('rl-audit-no-orphan-catalog-001', 'every catalog entry has a non-null enforcerRef (or a documented reason)', `(catalog entry ${entry.id} has enforcerRef: null)`));
+        }
+    }
+    return hits;
+}
+export function lintRuntimeBudget(projectRoot, observedMs) {
+    if (observedMs <= RUNTIME_BUDGET_MS)
+        return [];
+    return [syntheticHit('rl-audit-runtime-budget-001', `peaks audit red-lines completes in < ${RUNTIME_BUDGET_MS}ms on a 100-reference project`, `(observed ${observedMs}ms > budget ${RUNTIME_BUDGET_MS}ms)`)];
+}
+/**
+ * Read the catalog-stability history file (if it exists). The
+ * file is a small JSON document maintained by the release
+ * pipeline; absent → null. We do not invent the historical
+ * data; absent data means "soft pass".
+ */
+export function readCatalogHistory(projectRoot) {
+    const path = join(projectRoot, '.peaks', 'audit-catalog-history.json');
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = JSON.parse(readFileSync(path, 'utf8'));
+        return typeof raw.sizeNinetyDaysAgo === 'number' ? raw.sizeNinetyDaysAgo : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/src/services/audit/enforcers/lint-catalog-governance.d.ts

@@ -0,0 +1,27 @@
+/**
+ * P2-a Theme G — catalog governance.
+ *
+ * Two enforcers: catalog size must grow to ≥ 40 (the P2-a target),
+ * and the prose-only ratio must stay ≤ 5% (per spec §10.2 L2
+ * acceptance). Both fire on the catalog's static state — no file
+ * scan, just the catalog itself.
+ */
+import type { LintHit } from './lint-style.js';
+export declare const CATALOG_SIZE_TARGET = 40;
+export declare const PROSE_ONLY_RATIO_TARGET = 0.05;
+export interface CatalogSize {
+    readonly size: number;
+    readonly target: number;
+}
+export interface CatalogProseOnlyRatio {
+    readonly ratio: number;
+    readonly target: number;
+}
+export declare function lintCatalogSize(actualSize: number): readonly LintHit[];
+/**
+ * Prose-only ratio: count catalog entries whose `enforcerRef` is
+ * null (i.e. not backed by a CLI surface) divided by the total
+ * catalog size. Per spec §10.2, the L2 acceptance is ≤ 10% at
+ * P2-a; this slice tightens to ≤ 5%.
+ */
+export declare function lintCatalogProseOnlyRatio(catalogSize: number, proseOnlyCount: number): readonly LintHit[];

package/dist/src/services/audit/enforcers/lint-catalog-governance.js

@@ -0,0 +1,38 @@
+export const CATALOG_SIZE_TARGET = 40;
+export const PROSE_ONLY_RATIO_TARGET = 0.05;
+function syntheticHit(catalogId, rule, matched) {
+    // No specific file to point at — return a synthetic hit against
+    // the catalog source file so the audit report can render a row.
+    const fake = {
+        name: 'catalog',
+        path: 'src/services/audit/red-line-catalog.ts',
+        body: '',
+        lines: [],
+    };
+    return {
+        catalogId,
+        rule,
+        file: fake.path,
+        line: 1,
+        matchedText: matched,
+    };
+}
+export function lintCatalogSize(actualSize) {
+    if (actualSize >= CATALOG_SIZE_TARGET)
+        return [];
+    return [syntheticHit('rl-catalog-total-001', 'Catalog governance: catalog size must grow to ≥ 40 (L2.3 P2-a target)', `(catalog size ${actualSize} < target ${CATALOG_SIZE_TARGET})`)];
+}
+/**
+ * Prose-only ratio: count catalog entries whose `enforcerRef` is
+ * null (i.e. not backed by a CLI surface) divided by the total
+ * catalog size. Per spec §10.2, the L2 acceptance is ≤ 10% at
+ * P2-a; this slice tightens to ≤ 5%.
+ */
+export function lintCatalogProseOnlyRatio(catalogSize, proseOnlyCount) {
+    if (catalogSize === 0)
+        return [];
+    const ratio = proseOnlyCount / catalogSize;
+    if (ratio <= PROSE_ONLY_RATIO_TARGET)
+        return [];
+    return [syntheticHit('rl-catalog-prose-only-ratio-001', 'Catalog governance: prose-only ratio must stay ≤ 5% (per §10.2 L2 acceptance)', `(prose-only ratio ${(ratio * 100).toFixed(1)}% > target ${PROSE_ONLY_RATIO_TARGET * 100}%; ${proseOnlyCount}/${catalogSize})`)];
+}

package/dist/src/services/audit/enforcers/lint-cli-back.d.ts

@@ -0,0 +1,16 @@
+/**
+ * P2-a Theme D — CLI-back gaps enforcers.
+ *
+ * A red line that says "BLOCKING" / "MANDATORY" / "MUST NOT" / "MUST"
+ * / "REQUIRED" must point at a `peaks *` enforcer in the
+ * surrounding ±2 lines, or it stays as `prose-only` (per §5.2).
+ *
+ * The enforcer walks each skill body, locates every
+ * `MANDATORY` / `BLOCKING` / `MUST NOT` marker, and reports an
+ * orphan-hit when the surrounding text does NOT name a peaks CLI
+ * command.
+ */
+import type { LintHit, SkillFile } from './lint-style.js';
+export declare function lintCliBackMandatorText(skill: SkillFile): readonly LintHit[];
+export declare function lintCliBackNoOrphanBlocking(skill: SkillFile): readonly LintHit[];
+export declare function lintCliBackNoOrphanMustNot(skill: SkillFile): readonly LintHit[];

package/dist/src/services/audit/enforcers/lint-cli-back.js

@@ -0,0 +1,35 @@
+const MANDATORY_PATTERN = /\bMANDATORY\b/;
+const BLOCKING_PATTERN = /\bBLOCKING\b/;
+const MUST_NOT_PATTERN = /\bMUST NOT\b/;
+const PEAKS_CLI_PATTERN = /\bpeaks\s+[a-z][a-z0-9-]*/;
+function findOrphans(skill, pattern, catalogId, rule) {
+    const hits = [];
+    for (let i = 0; i < skill.lines.length; i += 1) {
+        const line = skill.lines[i] ?? '';
+        if (!pattern.test(line))
+            continue;
+        // Look at ±2 lines for a `peaks *` reference
+        const ctx = skill.lines
+            .slice(Math.max(0, i - 2), Math.min(skill.lines.length, i + 3))
+            .join('\n');
+        if (!PEAKS_CLI_PATTERN.test(ctx)) {
+            hits.push({
+                catalogId,
+                rule,
+                file: skill.path,
+                line: i + 1,
+                matchedText: line.trim()
+            });
+        }
+    }
+    return hits;
+}
+export function lintCliBackMandatorText(skill) {
+    return findOrphans(skill, MANDATORY_PATTERN, 'rl-cli-back-mandatory-text-001', 'MANDATORY text has peaks * enforcer in the surrounding ±2 lines');
+}
+export function lintCliBackNoOrphanBlocking(skill) {
+    return findOrphans(skill, BLOCKING_PATTERN, 'rl-cli-back-no-orphan-blocking-001', 'no orphan BLOCKING marker without a peaks * enforcer');
+}
+export function lintCliBackNoOrphanMustNot(skill) {
+    return findOrphans(skill, MUST_NOT_PATTERN, 'rl-cli-back-no-orphan-must-not-001', 'no orphan MUST NOT marker without a peaks * enforcer');
+}

package/dist/src/services/audit/enforcers/lint-output-style.d.ts

@@ -0,0 +1,11 @@
+import type { LintHit, SkillFile } from './lint-style.js';
+export declare function lintNoFluff(skill: SkillFile): readonly LintHit[];
+export declare function lintNoClosingPrompt(skill: SkillFile): readonly LintHit[];
+/**
+ * Status header detection: scan the most-recent session log for the
+ * canonical header line. The session log is read from the project's
+ * `.peaks/_runtime/<sid>/session.log` (or the audit's per-test
+ * fixture). For static analysis (no session), the lint returns an
+ * empty array (the runtime check is elsewhere).
+ */
+export declare function lintStatusHeader(projectRoot: string, sessionId: string): readonly LintHit[];

package/dist/src/services/audit/enforcers/lint-output-style.js

@@ -0,0 +1,94 @@
+/**
+ * P2-a Theme C — output style enforcers.
+ *
+ * The peaks-cli dogfood rule: every skill response carries a status
+ * header (`Peaks-Cli Skill: <name> | Peaks-Cli Gate: <gate> | Next:
+ * <action>`), the SKILL.md body has no greeting/closing-prompt
+ * flattery, and the status header is detectable in the recent
+ * session transcript (test-only fixture).
+ *
+ * The status-header detection is a real check on the fixture's
+ * most-recent session file; the no-fluff and no-closing-prompt
+ * checks are static pattern scans of the skill's SKILL.md.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+const FLUFF_GREETINGS = [
+    /\b你好[！!。，,.]?\s*$/m,
+    /^\s*你好[！!。，,.]?\s*$/m,
+    /\bHello[,，]?\s*I am\b/i,
+    /\bI am (an? )?(helpful )?assistant\b/i,
+    /\b作为一个 AI\b/,
+    /\b我是 (一个 )?AI\b/,
+    /\b作为一个\b/,
+    /\b我是(助手|模型|AI)/i
+];
+const CLOSING_PROMPTS = [
+    /\bLet me know if you need\b/i,
+    /\b如有(任何)?需要\b/,
+    /\b如有需要\b/,
+    /\bfeel free to ask\b/i,
+    /\bdo not hesitate to\b/i,
+    /\b随时(欢迎)?(联系|提问)/i,
+    /\b随时 (欢迎 )?(联系|提问)/i
+];
+const STATUS_HEADER_PATTERN = /Peaks-Cli Skill:\s*peaks-[a-z0-9-]+\s*\|\s*Peaks-Cli Gate:\s*[A-Za-z0-9_.-]+\s*\|\s*Next:\s*\S/;
+export function lintNoFluff(skill) {
+    const hits = [];
+    for (const pattern of FLUFF_GREETINGS) {
+        const lineIdx = skill.lines.findIndex((l) => pattern.test(l));
+        if (lineIdx !== -1) {
+            hits.push({
+                catalogId: 'rl-output-style-no-fluff-001',
+                rule: 'no greeting / persona fluff in SKILL.md',
+                file: skill.path,
+                line: lineIdx + 1,
+                matchedText: (skill.lines[lineIdx] ?? '').trim()
+            });
+        }
+    }
+    return hits;
+}
+export function lintNoClosingPrompt(skill) {
+    const hits = [];
+    for (const pattern of CLOSING_PROMPTS) {
+        const lineIdx = skill.lines.findIndex((l) => pattern.test(l));
+        if (lineIdx !== -1) {
+            hits.push({
+                catalogId: 'rl-output-style-no-closing-prompt-001',
+                rule: 'no closing-prompt flattery',
+                file: skill.path,
+                line: lineIdx + 1,
+                matchedText: (skill.lines[lineIdx] ?? '').trim()
+            });
+        }
+    }
+    return hits;
+}
+/**
+ * Status header detection: scan the most-recent session log for the
+ * canonical header line. The session log is read from the project's
+ * `.peaks/_runtime/<sid>/session.log` (or the audit's per-test
+ * fixture). For static analysis (no session), the lint returns an
+ * empty array (the runtime check is elsewhere).
+ */
+export function lintStatusHeader(projectRoot, sessionId) {
+    const logPath = join(projectRoot, '.peaks', '_runtime', sessionId, 'session.log');
+    let body;
+    try {
+        body = readFileSync(logPath, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    if (!STATUS_HEADER_PATTERN.test(body)) {
+        return [{
+                catalogId: 'rl-output-style-status-header-001',
+                rule: 'Peaks-Cli status header on every response',
+                file: logPath,
+                line: 1,
+                matchedText: '(no Peaks-Cli Skill / Gate / Next header found in session.log)'
+            }];
+    }
+    return [];
+}

package/dist/src/services/audit/enforcers/lint-reference-integrity.d.ts

@@ -0,0 +1,6 @@
+import type { LintHit, SkillFile } from './lint-style.js';
+/** Theme E — reference integrity. */
+export declare function lintRefPathResolves(skillsRoot: string, name: string, refs: readonly string[]): readonly LintHit[];
+export declare function lintNoBrokenMkdir(skill: SkillFile): readonly LintHit[];
+export declare function lintNoPwdSymlinkJumps(skill: SkillFile): readonly LintHit[];
+export declare function lintNoRelativeArchivePaths(skill: SkillFile): readonly LintHit[];

package/dist/src/services/audit/enforcers/lint-reference-integrity.js

@@ -0,0 +1,83 @@
+/**
+ * P2-a Theme E — reference integrity enforcers.
+ *
+ * Static pattern scans of skill bodies + references/ for inline
+ * shell snippets that violate the project's "no
+ * mkdir-outside-project" / "no /tmp cp" / "no cd .." rules.
+ *
+ * These are pattern-based: the audit framework invokes the helper
+ * with a skill's body and the helper returns lint hits.
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+const MKDIR_PATTERN = /\bmkdir\s+(?:-p\s+)?(\/[^\s'`"]+|[A-Z]:[^\s'`"]+)/g;
+const CD_OUT_PATTERN = /\bcd\s+(\.\.[\\/]|[A-Z]:[\\/])/g;
+const CP_MV_LN_TMP_PATTERN = /\b(cp|mv|ln)\b[^\n]*\/tmp\b/g;
+/** Theme E — reference integrity. */
+export function lintRefPathResolves(skillsRoot, name, refs) {
+    const hits = [];
+    for (const ref of refs) {
+        const path = join(skillsRoot, name, 'references', ref);
+        if (!existsSync(path)) {
+            hits.push({
+                catalogId: 'rl-ref-path-resolves-001',
+                rule: 'every references/<file>.md link resolves',
+                file: join(skillsRoot, name, 'SKILL.md'),
+                line: 1,
+                matchedText: ref
+            });
+        }
+    }
+    return hits;
+}
+export function lintNoBrokenMkdir(skill) {
+    const hits = [];
+    for (let i = 0; i < skill.lines.length; i += 1) {
+        const line = skill.lines[i] ?? '';
+        if (MKDIR_PATTERN.test(line)) {
+            hits.push({
+                catalogId: 'rl-ref-no-broken-mkdir-001',
+                rule: 'no `mkdir -p` outside the project root',
+                file: skill.path,
+                line: i + 1,
+                matchedText: line.trim()
+            });
+        }
+        MKDIR_PATTERN.lastIndex = 0;
+    }
+    return hits;
+}
+export function lintNoPwdSymlinkJumps(skill) {
+    const hits = [];
+    for (let i = 0; i < skill.lines.length; i += 1) {
+        const line = skill.lines[i] ?? '';
+        if (CD_OUT_PATTERN.test(line)) {
+            hits.push({
+                catalogId: 'rl-ref-no-pwd-symlink-jumps-001',
+                rule: 'no `cd ..` chain jumping outside the project',
+                file: skill.path,
+                line: i + 1,
+                matchedText: line.trim()
+            });
+        }
+        CD_OUT_PATTERN.lastIndex = 0;
+    }
+    return hits;
+}
+export function lintNoRelativeArchivePaths(skill) {
+    const hits = [];
+    for (let i = 0; i < skill.lines.length; i += 1) {
+        const line = skill.lines[i] ?? '';
+        if (CP_MV_LN_TMP_PATTERN.test(line)) {
+            hits.push({
+                catalogId: 'rl-ref-no-relative-archive-paths-001',
+                rule: 'no `cp`/`mv`/`ln` to absolute /tmp paths',
+                file: skill.path,
+                line: i + 1,
+                matchedText: line.trim()
+            });
+        }
+        CP_MV_LN_TMP_PATTERN.lastIndex = 0;
+    }
+    return hits;
+}

package/dist/src/services/audit/enforcers/lint-reference-shape.d.ts

@@ -0,0 +1,30 @@
+import type { LintHit, SkillFile } from './lint-style.js';
+export interface ReferenceFile {
+    readonly skill: string;
+    readonly name: string;
+    readonly path: string;
+    readonly body: string;
+    readonly lines: readonly string[];
+}
+export declare function lintH1TitleRequired(ref: ReferenceFile): readonly LintHit[];
+export declare function lintApplicableTaskLevels(ref: ReferenceFile): readonly LintHit[];
+export declare function lintSeeAlsoSection(ref: ReferenceFile): readonly LintHit[];
+export declare function lintCrossRefResolves(ref: ReferenceFile, refsDir: string, siblings: readonly string[]): readonly LintHit[];
+export declare function lintNoSelfReference(ref: ReferenceFile): readonly LintHit[];
+export declare function lintNoOrphanLink(ref: ReferenceFile): readonly LintHit[];
+export declare function lintLineCountLe800(ref: ReferenceFile): readonly LintHit[];
+export declare function lintH2CountLe12(ref: ReferenceFile): readonly LintHit[];
+export declare function lintOverviewNearTop(ref: ReferenceFile): readonly LintHit[];
+export declare function lintLoadStrategyOnDemandFallback(ref: ReferenceFile): readonly LintHit[];
+export declare function lintLoadStrategyAlwaysCacheable(ref: ReferenceFile): readonly LintHit[];
+export declare function lintNoBashHeredoc(ref: ReferenceFile): readonly LintHit[];
+export declare function lintNoSudo(ref: ReferenceFile): readonly LintHit[];
+export declare function lintNoCurlPipeBash(ref: ReferenceFile): readonly LintHit[];
+export declare function lintCodeBlockLanguage(ref: ReferenceFile): readonly LintHit[];
+export declare function lintNoFakePrompt(ref: ReferenceFile): readonly LintHit[];
+export declare function lintNoAbsolutePaths(ref: ReferenceFile): readonly LintHit[];
+export declare function lintNoChmod777(ref: ReferenceFile): readonly LintHit[];
+export declare function lintNoMagicNumbers(ref: ReferenceFile): readonly LintHit[];
+export declare function lintSkillCitesEveryReference(ref: ReferenceFile, skill: SkillFile): readonly LintHit[];
+export declare function lintLoadStrategyMatchesSize(ref: ReferenceFile): readonly LintHit[];
+export declare function readReferenceFiles(skillsRoot: string, skillName: string, refNames: readonly string[]): readonly ReferenceFile[];