peaks-loop 3.1.2 → 4.0.0-beta.10

package/dist/services/standards/missing-standards-detector.js

@@ -0,0 +1,139 @@
+/**
+ * Slice 2026-06-16-peaks-code-auto-scaffold (RD#7) — missing-standards-detector.
+ *
+ * Read-side companion to the `peaks standards init` / `peaks standards update`
+ * writers in `./project-standards-service.ts`. The writer KNOWS how to scaffold
+ * `.peaks/standards/{common,<language>}/` (2.0 canonical) from the curated
+ * baseline; this module detects when the consumer project's rules tree is
+ * missing or empty and emits a copy-pasteable diagnostic for the operator.
+ *
+ * Why a separate read module: the writer is `apply`-gated and write-bounded
+ * (it touches the filesystem via `prevalidateWrites`/`assertNotHomedirBaseline`).
+ * The detector is read-only and platform-aware (win32 path separators for
+ * Windows consumers) — coupling the two would force the writer to grow a
+ * read-only flag and a platform-switching argument.
+ *
+ * Cross-platform path rendering (AC6): the detector switches on
+ * `process.platform` and renders the project path with `path.sep` so Windows
+ * consumers see `C:\Users\<u>\project\.claude\rules\` verbatim rather than the
+ * POSIX form. The detection logic itself (readdirSync on `node:fs`) is
+ * platform-neutral.
+ *
+ * Once-per-session dedup (AC7): `peaks workspace init` writes a marker at
+ * `.peaks/_runtime/<sessionId>/.standards-checked` after the first detection
+ * pass. `detectMissingProjectStandards` does NOT consult the marker — that's
+ * the caller's responsibility (the CLI command decides whether to skip per
+ * AC7's "once per session" contract).
+ */
+import { existsSync, mkdirSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { isAbsolute, join, sep as pathSep } from 'node:path';
+const SUPPORTED_LANGUAGES = new Set([
+    'generic',
+    'typescript',
+    'javascript',
+    'python',
+    'go',
+    'rust'
+]);
+function normalizeProjectRoot(projectRoot) {
+    return isAbsolute(projectRoot) ? projectRoot : join(process.cwd(), projectRoot);
+}
+function renderForPlatform(projectRoot) {
+    // AC6: render with the platform-native separator. On win32 we replace '/'
+    // with '\\' in the project path; the rest of the path is constructed with
+    // the same separator via the literal '\\' join below.
+    //
+    // 2.0 canonical location: `<projectRoot>/.peaks/standards/`
+    // (slice 2026-07-15-missing-standards-on-fresh-project — the 2.0
+    // writer scaffolds the rules tree under `.peaks/standards/`, not
+    // the legacy `.claude/rules/`).
+    if (process.platform === 'win32') {
+        const nativeRoot = projectRoot.replace(/\//g, '\\');
+        return `${nativeRoot}\\.peaks\\standards`;
+    }
+    return `${projectRoot}/.peaks/standards`;
+}
+function hasPopulatedMarkdown(dir) {
+    if (!existsSync(dir))
+        return false;
+    const stat = statSync(dir);
+    if (!stat.isDirectory())
+        return false;
+    const entries = readdirSync(dir);
+    return entries.some((entry) => entry.toLowerCase().endsWith('.md'));
+}
+/**
+ * Detect whether a consumer project's `.peaks/standards/` tree (2.0
+ * canonical) is missing or empty.
+ *
+ * Rules (per PRD R2, slice 2026-07-15):
+ *   - `.peaks/standards/common/` MUST exist AND contain at least one
+ *     `.md` file.
+ *   - `.peaks/standards/<language>/` MUST exist AND contain at least one
+ *     `.md` file — except for `generic`, where the language dir is
+ *     OPTIONAL.
+ *
+ * Returns `{ missing: true, ... }` when either required dir is absent or
+ * empty. The diagnostic is always populated so the caller can surface the
+ * remediation hint unconditionally (the CLI uses the same string for both
+ * the stderr banner and the JSON envelope warning).
+ */
+export function detectMissingProjectStandards(projectRoot, language) {
+    if (!SUPPORTED_LANGUAGES.has(language)) {
+        throw new Error(`Unsupported standards language: ${String(language)}`);
+    }
+    const normalizedRoot = normalizeProjectRoot(projectRoot);
+    const renderedPath = renderForPlatform(normalizedRoot);
+    const commonDir = join(normalizedRoot, '.peaks', 'standards', 'common');
+    const languageDir = language === 'generic'
+        ? null
+        : join(normalizedRoot, '.peaks', 'standards', language);
+    const commonOk = hasPopulatedMarkdown(commonDir);
+    const languageOk = languageDir === null ? true : hasPopulatedMarkdown(languageDir);
+    const missing = !(commonOk && languageOk);
+    // Remediation message: copy-pasteable, mentions language, references the
+    // resolved project path, and hints at the `--init-standards` opt-in flag.
+    const remediation = missing
+        ? `⚠ no project-local standards found at ${renderedPath} — run \`peaks standards init --project ${normalizedRoot} --apply\` to scaffold, or pass --init-standards to peaks workspace init for one-shot auto-apply (language: ${language}).`
+        : `Project-local standards already present at ${renderedPath}. Re-run \`peaks standards init --project ${normalizedRoot} --apply\` to refresh from the curated baseline.`;
+    return {
+        missing,
+        path: renderedPath,
+        remediation,
+        language
+    };
+}
+/**
+ * Once-per-session marker file path. The CLI writes this file under
+ * `.peaks/_runtime/<sessionId>/` after the first diagnostic pass so that
+ * subsequent `peaks workspace init` invocations within the same session
+ * skip the stderr banner (the diagnostic is still computable for
+ * programmatic consumers via `detectMissingProjectStandards`).
+ */
+export function getStandardsCheckedMarkerPath(projectRoot, sessionId) {
+    const normalizedRoot = normalizeProjectRoot(projectRoot);
+    // Canonical session runtime dir — see `.peaks/memory/session-dir-canonical-resolver-must-route-all-writes.md`.
+    return join(normalizedRoot, '.peaks', '_runtime', sessionId, '.standards-checked');
+}
+/**
+ * Mark this session as "standards checked" so subsequent invocations can
+ * skip the stderr diagnostic. Idempotent: existing marker is left as-is.
+ * Returns true if the marker was newly created, false if it already existed.
+ */
+export function markStandardsChecked(projectRoot, sessionId) {
+    const markerPath = getStandardsCheckedMarkerPath(projectRoot, sessionId);
+    if (existsSync(markerPath))
+        return false;
+    mkdirSync(join(markerPath, '..'), { recursive: true });
+    writeFileSync(markerPath, 'standards-checked\n', 'utf8');
+    return true;
+}
+/**
+ * Test seam: check whether the once-per-session marker exists. Caller is
+ * responsible for routing the result into the AC7 dedup logic.
+ */
+export function hasStandardsCheckedMarker(projectRoot, sessionId) {
+    return existsSync(getStandardsCheckedMarkerPath(projectRoot, sessionId));
+}
+// Re-export path.sep for tests that want to assert the platform invariant.
+export const platformPathSeparator = pathSep;

package/dist/services/standards/project-standards-service.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Typed error raised when a planned `peaks standards` write target would
+ * land outside `projectRoot` (or collide with the user-level baseline
+ * under `<homedir>/.claude/**`). Surfaced as a stable error code so CLI
+ * callers can map it to a recoverable hint.
+ */
+export type ProjectStandardsWriteTargetReason = 'outside-project-root' | 'resolves-to-homedir-claude';
+export declare class ProjectStandardsWriteTargetError extends Error {
+    readonly code: "PROJECT_STANDARDS_WRITE_TARGET_OUTSIDE_ROOT";
+    readonly filePath: string;
+    readonly projectRoot: string;
+    readonly reason: ProjectStandardsWriteTargetReason;
+    constructor(input: {
+        readonly filePath: string;
+        readonly projectRoot: string;
+        readonly reason: ProjectStandardsWriteTargetReason;
+    });
+}
+export type StandardsLanguage = 'generic' | 'typescript' | 'javascript' | 'python' | 'go' | 'rust';
+export type StandardsWriteStatus = 'planned' | 'existing' | 'written' | 'appended' | 'review';
+export type StandardsWrite = {
+    readonly relativePath: string;
+    readonly filePath: string;
+    readonly content: string;
+    readonly status: StandardsWriteStatus;
+};
+export type ProjectStandardsSource = {
+    readonly sourceId: 'everything-claude-code';
+    readonly url: 'https://github.com/affaan-m/everything-claude-code';
+    readonly usage: 'curated-baseline-reference';
+};
+export type StandardsSkillPreflight = {
+    readonly appliesTo: readonly ['peaks-rd', 'peaks-qa', 'peaks-code'];
+    readonly summary: string;
+};
+export type ProjectStandardsInitPlan = {
+    readonly apply: boolean;
+    readonly projectRoot: string;
+    readonly language: StandardsLanguage;
+    readonly source: ProjectStandardsSource;
+    readonly skillPreflight: StandardsSkillPreflight;
+    readonly plannedWrites: StandardsWrite[];
+};
+export type ProjectStandardsInitResult = ProjectStandardsInitPlan & {
+    readonly writtenFiles: string[];
+};
+export type ProjectStandardsInitSummary = {
+    readonly apply: boolean;
+    readonly projectRoot: string;
+    readonly language: StandardsLanguage;
+    readonly source: ProjectStandardsSource;
+    readonly skillPreflight: StandardsSkillPreflight;
+    readonly plannedWrites: Array<Pick<StandardsWrite, 'relativePath' | 'status'>>;
+    readonly writtenFiles: string[];
+    readonly skippedFiles: string[];
+};
+export type ProjectStandardsUpdatePlan = ProjectStandardsInitPlan & {
+    readonly claudeMd: {
+        readonly relativePath: 'CLAUDE.md';
+        readonly filePath: string;
+        readonly status: StandardsWriteStatus;
+        readonly content: string;
+        readonly appendBlock: string;
+        readonly reviewSuggestions: string[];
+    };
+};
+export type ProjectStandardsUpdateResult = ProjectStandardsUpdatePlan & {
+    readonly writtenFiles: string[];
+    readonly appendedFiles: string[];
+    readonly reviewSuggestions: string[];
+};
+export type ProjectStandardsUpdateSummary = {
+    readonly apply: boolean;
+    readonly projectRoot: string;
+    readonly language: StandardsLanguage;
+    readonly source: ProjectStandardsSource;
+    readonly skillPreflight: StandardsSkillPreflight;
+    readonly plannedWrites: Array<Pick<StandardsWrite, 'relativePath' | 'status'>>;
+    readonly writtenFiles: string[];
+    readonly appendedFiles: string[];
+    readonly skippedFiles: string[];
+    readonly reviewSuggestions: string[];
+    readonly claudeMd: {
+        readonly relativePath: 'CLAUDE.md';
+        readonly status: StandardsWriteStatus;
+        readonly reviewSuggestions: string[];
+    };
+};
+export type ProjectStandardsInitOptions = {
+    readonly projectRoot: string;
+    readonly language?: string;
+    readonly apply?: boolean;
+    /**
+     * Test seam: override the homedir resolver used by the
+     * write-target containment guard. Defaults to `os.homedir()`.
+     * Production callers should NOT pass this — it exists so unit
+     * tests can simulate the "projectRoot === homedir" trap without
+     * mutating global Node state (which is read-only).
+     */
+    readonly resolveHomedir?: () => string;
+};
+/**
+ * Public alias for `detectLanguageInternal` so callers outside this
+ * module (e.g. `workspace-service.ts` for the slice 2026-06-16 RD#7
+ * auto-detect path) can ask the same heuristic without re-implementing
+ * the file-probe logic.
+ */
+export declare function detectLanguage(projectRoot: string): StandardsLanguage;
+export declare function createProjectStandardsInitPlan(options: ProjectStandardsInitOptions): ProjectStandardsInitPlan;
+export declare function createProjectStandardsUpdatePlan(options: ProjectStandardsInitOptions): ProjectStandardsUpdatePlan;
+export declare function executeProjectStandardsInit(options: ProjectStandardsInitOptions): ProjectStandardsInitResult;
+export declare function executeProjectStandardsUpdate(options: ProjectStandardsInitOptions): ProjectStandardsUpdateResult;
+export declare function summarizeProjectStandardsInitResult(result: ProjectStandardsInitResult): ProjectStandardsInitSummary;
+export declare function summarizeProjectStandardsUpdateResult(result: ProjectStandardsUpdateResult): ProjectStandardsUpdateSummary;