peaks-loop 3.1.2 → 4.0.0-beta.10

package/dist/services/workspace/workspace-claude-settings-materializer.js

@@ -0,0 +1,194 @@
+/**
+ * Workspace Service -- consumer `.claude/settings.local.json` materialization.
+ *
+ * v2.18.3 file-split: this module is the extracted sub-tree of the
+ * pre-split `workspace-service.ts`. It hosts the 3 helpers
+ * (`materializeClaudeSettingsLocal`, `writeOfflineTemplateCopy`,
+ * `upsertPeaksGitignoreSnippet`) plus the `PEAKS_GITIGNORE_*`
+ * constants. The high-level `initWorkspace` orchestrator lives in
+ * the parent module and calls into this sibling. Function signatures
+ * and behaviour are unchanged (verbatim move).
+ */
+import { existsSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { buildClaudeSettingsLocalJson, CLAUDE_SETTINGS_LOCAL_FILENAME, templateContentMatches } from './claude-settings-template.js';
+/**
+ * The peaks-managed snippet appended to the consumer project's
+ * `.peaks/.gitignore` so the local-only settings file never lands
+ * in a commit. Marked with a managed-by header so we can detect (and
+ * not double-append) on subsequent inits.
+ */
+const PEAKS_GITIGNORE_HEADER = '# >>> peaks-loop managed snippet (slice 2.0.1-bug3) — do not edit by hand';
+const PEAKS_GITIGNORE_FOOTER = '# <<< peaks-loop managed snippet';
+const PEAKS_GITIGNORE_SNIPPET = [
+    PEAKS_GITIGNORE_HEADER,
+    '# Consumer-project .claude/settings.local.json: written by `peaks workspace init`',
+    '# to bypass Claude Code [Fact-Forcing Gate] for .peaks/** writes. Local-only.',
+    '.claude/settings.local.json',
+    '# Offline template copy (.peaks/.claude-settings-template.json): written by',
+    '# `peaks workspace init` as a manual-recovery anchor. The source-of-truth is',
+    '# peaks-loop\'s own `buildClaudeSettingsLocalJson()` — NOT this committed copy.',
+    '# Gitignored so the init flow\'s drift-driven refresh does not show up as',
+    '# "modified" in `git status` on every release bump. Recovery path: re-run',
+    '# `peaks workspace init` to regenerate; or copy from peaks-loop source.',
+    '.peaks/.claude-settings-template.json',
+    PEAKS_GITIGNORE_FOOTER,
+    ''
+].join('\n');
+/**
+ * Materialize the consumer-project `.claude/settings.local.json` and
+ * ensure the consumer's `.peaks/.gitignore` covers it. Returns a
+ * `claudeSettings` descriptor that the caller surfaces in the JSON
+ * envelope.
+ *
+ * The function is idempotent: re-running on an already-materialized
+ * project is a no-op (the file is rewritten only when its content
+ * diverges from the current peaks-loop release's template, which
+ * keeps the consumer up to date as the template evolves).
+ *
+ * Even when the caller passes `noClaudeHooks: true`, the function
+ * still writes a copy of the template at
+ * `.peaks/.claude-settings-template.json` so the user has an offline
+ * recovery path: copy the file contents into
+ * `.claude/settings.local.json` manually. The recovery path is
+ * documented in
+ * `skills/peaks-code/references/anchoring-and-session-info.md`.
+ *
+ * Slice 2026-06-13-selfheal-claude-settings-template: the offline copy
+ * is now ALSO drift-checked (via `templateContentMatches`) so stale
+ * on-disk copies from earlier peaks-loop releases (which lacked the
+ * `node -e "..."` wrapper) get refreshed automatically on the next
+ * init. The action taken on the offline copy is surfaced in
+ * `claudeSettings.offlineTemplate.action`.
+ */
+export async function materializeClaudeSettingsLocal(projectRoot, noClaudeHooks) {
+    const settingsRel = CLAUDE_SETTINGS_LOCAL_FILENAME;
+    const settingsPath = join(projectRoot, settingsRel);
+    const template = buildClaudeSettingsLocalJson();
+    const serialized = JSON.stringify(template, null, 2) + '\n';
+    // Always drop (or self-heal) a copy of the template under .peaks/
+    // so the --no-claude-hooks recovery flow has a known source-of-truth
+    // on disk. The file is gitignored by the snippet below.
+    const offlineAction = await writeOfflineTemplateCopy(projectRoot, serialized);
+    const offlineTemplate = {
+        action: offlineAction,
+        path: '.peaks/.claude-settings-template.json'
+    };
+    if (noClaudeHooks) {
+        return { action: 'skipped', path: settingsRel, offlineTemplate };
+    }
+    // Best-effort: ensure .claude/ exists, then write the file. We do
+    // not assertSafeSettingsPath here (the .claude/ dir is local to
+    // the consumer and we trust it on first init; the existing
+    // hooks-settings-service applies the safety check for the Bash
+    // gate-enforce path).
+    await mkdir(join(projectRoot, '.claude'), { recursive: true });
+    let action = 'written';
+    if (existsSync(settingsPath)) {
+        try {
+            const { readFile } = await import('node:fs/promises');
+            const existing = await readFile(settingsPath, 'utf8');
+            if (existing === serialized) {
+                action = 'already-current';
+            }
+            else {
+                action = 'refreshed';
+            }
+        }
+        catch {
+            // Treat any read failure as "needs refresh" so the consumer
+            // always ends up with a valid template on disk.
+            action = 'refreshed';
+        }
+    }
+    if (action !== 'already-current') {
+        await writeFile(settingsPath, serialized, 'utf8');
+    }
+    // Ensure the consumer's .peaks/.gitignore covers the local-only
+    // settings file. The snippet is appended only when the header is
+    // missing, so subsequent inits do not double-append.
+    await upsertPeaksGitignoreSnippet(projectRoot);
+    return { action, path: settingsRel, offlineTemplate };
+}
+/**
+ * Always write (or refresh) a copy of the template at
+ * `.peaks/.claude-settings-template.json` so the user has a known
+ * source-of-truth on disk for the manual recovery flow. The file is
+ * GITIGNORED (added to `.peaks/.gitignore` by
+ * `upsertPeaksGitignoreSnippet`) — the source-of-truth lives in
+ * peaks-loop's own `buildClaudeSettingsLocalJson()`, NOT in any
+ * committed copy. Gitignoring it ensures the init flow's drift-driven
+ * refresh does not show up as "modified" in `git status` on every
+ * peaks-loop release bump.
+ *
+ * Recovery path for users who need to re-create their
+ * `.claude/settings.local.json`: re-run `peaks workspace init`
+ * (the file is regenerated); or copy the template straight from
+ * peaks-loop source (`src/services/workspace/claude-settings-template.ts`).
+ *
+ * Slice 2026-06-13-selfheal-claude-settings-template: drift-check via
+ * `templateContentMatches` BEFORE writing. If the on-disk copy's
+ * parsed hooks tree matches the current `buildClaudeSettingsLocalJson()`
+ * output, the write is skipped (`already-current`). If the file is
+ * missing, it is written (`written`). If it exists but has drifted
+ * (e.g. an earlier release's template without the `node -e "..."`
+ * wrapper, or a user-customised copy), it is rewritten (`refreshed`).
+ * The CLI caller surfaces a warning when `refreshed` because manual
+ * edits the user may have made would be overwritten.
+ *
+ * Returns the action taken so the caller can surface it in the
+ * envelope. Read failures are treated as drift so a malformed
+ * on-disk file always self-heals on the next init.
+ */
+async function writeOfflineTemplateCopy(projectRoot, serialized) {
+    const copyPath = join(projectRoot, '.peaks', '.claude-settings-template.json');
+    await mkdir(join(projectRoot, '.peaks'), { recursive: true });
+    let action = 'written';
+    if (existsSync(copyPath)) {
+        try {
+            const { readFile } = await import('node:fs/promises');
+            const existing = await readFile(copyPath, 'utf8');
+            if (templateContentMatches(serialized, existing)) {
+                action = 'already-current';
+            }
+            else {
+                action = 'refreshed';
+            }
+        }
+        catch {
+            // Treat any read failure as drift so the file self-heals.
+            action = 'refreshed';
+        }
+    }
+    if (action !== 'already-current') {
+        await writeFile(copyPath, serialized, 'utf8');
+    }
+    return action;
+}
+/**
+ * Append the peaks-managed `.claude/settings.local.json` snippet to
+ * the consumer project's `.peaks/.gitignore`. Preserves any user-
+ * managed entries above the snippet. Idempotent: re-running on a
+ * project that already has the snippet is a no-op.
+ */
+async function upsertPeaksGitignoreSnippet(projectRoot) {
+    const gitignorePath = join(projectRoot, '.peaks', '.gitignore');
+    await mkdir(join(projectRoot, '.peaks'), { recursive: true });
+    let existing = '';
+    if (existsSync(gitignorePath)) {
+        try {
+            const { readFile } = await import('node:fs/promises');
+            existing = await readFile(gitignorePath, 'utf8');
+        }
+        catch {
+            existing = '';
+        }
+    }
+    if (existing.includes(PEAKS_GITIGNORE_HEADER)) {
+        return;
+    }
+    const separator = existing.length > 0 && !existing.endsWith('\n') ? '\n' : '';
+    const next = existing + separator + (existing.length > 0 ? '\n' : '') + PEAKS_GITIGNORE_SNIPPET;
+    await writeFile(gitignorePath, next, 'utf8');
+}

package/dist/services/workspace/workspace-service.d.ts

@@ -0,0 +1,177 @@
+import { type MissingProjectStandardsDiagnostic } from '../standards/missing-standards-detector.js';
+import { type StandardsLanguage } from '../standards/project-standards-service.js';
+export type WorkspaceInitOptions = {
+    projectRoot: string;
+    sessionId: string;
+    /**
+     * When true, the conflict check is skipped and the new session id is
+     * written to .peaks/.session.json even if the project is already bound
+     * to a different (real) session. Use only with explicit user authorization
+     * — the CLI surfaces this as `--allow-session-rebind`.
+     */
+    allowSessionRebind?: boolean;
+    /**
+     * Slice 2.0.1-bug3-fact-forcing-bypass: opt out of writing the
+     * consumer-project `.claude/settings.local.json` file. Default
+     * (`false`) writes the file so the [Fact-Forcing Gate] is bypassed
+     * for tool calls inside `.peaks/**`. The CLI surfaces this as
+     * `--no-claude-hooks`.
+     */
+    noClaudeHooks?: boolean;
+    /**
+     * Slice 2026-06-16-peaks-code-auto-scaffold (RD#7): opt-in flag for
+     * auto-applying `peaks standards init` when the consumer project's
+     * `.claude/rules/` is missing or empty. Default (`false`) only emits
+     * the diagnostic; set to `true` to also scaffold the rules tree via
+     * `executeProjectStandardsInit({ projectRoot, apply: true })`. The
+     * CLI surfaces this as `--init-standards`.
+     */
+    initStandards?: boolean;
+    /**
+     * Optional language override for the standards scaffold. When unset,
+     * `detectLanguage(projectRoot)` is used (looks for tsconfig.json /
+     * package.json / pyproject.toml / go.mod / Cargo.toml). Pass this to
+     * force a specific language for the auto-apply path.
+     */
+    language?: StandardsLanguage;
+};
+export type WorkspaceInitReport = {
+    sessionId: string;
+    sessionRoot: string;
+    created: string[];
+    alreadyExisted: string[];
+    bound: boolean;
+    previousSessionId: string | null;
+    /**
+     * Slice 2.0.1-bug3-fact-forcing-bypass: what the consumer-project
+     * `.claude/settings.local.json` materialization did this call.
+     *   - written:        the file was freshly written
+     *   - refreshed:      the file already existed and was rewritten to
+     *                     match the current peaks-loop release's template
+     *   - already-current: the file already matched the template; no
+     *                     rewrite needed
+     *   - skipped:        the caller passed noClaudeHooks=true
+     * The LLM and the user both see this in the JSON envelope so they
+     * can decide whether the bypass is in effect.
+     *
+     * Slice 2026-06-13-selfheal-claude-settings-template: adds the
+     * `offlineTemplate` sub-field, which describes the self-heal action
+     * taken on the offline `.peaks/.claude-settings-template.json` copy.
+     * The offline copy is ALWAYS written/checked (regardless of
+     * noClaudeHooks) because it is the manual-recovery anchor — see
+     * `skills/peaks-code/references/anchoring-and-session-info.md`.
+     *   - written:        the file did not exist; it was created
+     *   - refreshed:      the file existed but its parsed hooks tree
+     *                     diverged from the current `buildClaudeSettingsLocalJson()`;
+     *                     it was rewritten
+     *   - already-current: the file already matched; no rewrite needed
+     */
+    claudeSettings: {
+        action: 'written' | 'refreshed' | 'already-current' | 'skipped';
+        path: string;
+        offlineTemplate: {
+            action: 'written' | 'refreshed' | 'already-current';
+            path: string;
+        };
+    };
+    /**
+     * Slice 2026-06-16-peaks-code-auto-scaffold (RD#7): structured
+     * diagnostic for missing or empty `.claude/rules/{common,<language>}/`.
+     * Always present (the detector runs on every init); `missing: false`
+     * means the project's rules tree is already populated and no action is
+     * required. The CLI copies this descriptor into the JSON envelope's
+     * `data.standardsMissing` so the LLM can read it programmatically.
+     */
+    standardsMissing: MissingProjectStandardsDiagnostic;
+    /**
+     * Slice 2026-06-16-peaks-code-auto-scaffold (RD#7): when the caller
+     * passed `initStandards: true` AND the detector reported `missing:
+     * true`, this field lists the files written by
+     * `executeProjectStandardsInit({ projectRoot, apply: true })`.
+     * Undefined when `initStandards` was not requested.
+     */
+    standardsApplied?: {
+        readonly language: StandardsLanguage;
+        readonly writtenFiles: string[];
+        readonly skippedFiles: string[];
+    };
+};
+/**
+ * Slice C10 (2026-06-24-legacy-change-id-sibling): the relative path
+ * patterns under `.peaks/_runtime/<sessionId>/` that the lazy WRITER (peaks-qa,
+ * peaks-rd, peaks-prd, peaks-txt, peaks-sc) creates via
+ * `mkdir(parent, { recursive: true })` immediately before a write. When
+ * a sibling `.peaks/_runtime/<sessionId>/` exists on disk AND every entry below
+ * it matches one of these patterns (AND no entry is a symlink), the
+ * dir is treated as legitimate writer output and `initWorkspace`
+ * re-init is tolerant — the binding is rewritten without throwing.
+ *
+ * Adding a new pattern here is a deliberate, reviewed change because
+ * it widens the heuristic. The list is intentionally narrow:
+ *   - `qa/screenshots/<file>.{png,jpg,jpeg,webp,gif}` — peaks-qa screenshots
+ *   - `<role>/requests/<file>.md`                     — RD/QA/PRD/TXT/SC artifacts
+ *   - `<role>/findings/<file>.md`                     — QA findings files
+ *
+ * Re-exported so unit tests can assert the pattern list directly.
+ */
+export declare const WRITER_ALLOWED_RELATIVE_PATTERNS: ReadonlyArray<RegExp>;
+export declare class InvalidSessionIdError extends Error {
+    readonly code = "INVALID_SESSION_ID";
+    constructor(message: string);
+}
+export declare class ConflictingSessionError extends Error {
+    readonly existingSessionId: string;
+    readonly requestedSessionId: string;
+    readonly code = "CONFLICTING_SESSION";
+    constructor(message: string, existingSessionId: string, requestedSessionId: string);
+}
+/**
+ * Thrown when `peaks workspace init --change-id <id>` is invoked but a
+ * 2.8.0-era legacy sibling directory `.peaks/_runtime/<sessionId>/` already exists
+ * at top level. Under the 2.8.0+ two-axis convention, change-id is a
+ * logical identifier in the SESSION axis — NOT a top-level sibling dir.
+ *
+ * The caller is expected to:
+ *   1. Inspect `.peaks/_runtime/<sessionId>/` to see if it contains user-authored
+ *      content worth preserving.
+ *   2. Migrate or delete the sibling dir.
+ *   3. Re-run `peaks workspace init --change-id <id>`.
+ */
+export declare class LegacyChangeIdSiblingError extends Error {
+    readonly sessionId: string;
+    readonly legacyPath: string;
+    readonly code = "LEGACY_CHANGE_ID_SIBLING";
+    constructor(sessionId: string, legacyPath: string);
+}
+export declare function validateSessionId(sessionId: string): void;
+export declare function initWorkspace(options: WorkspaceInitOptions): Promise<WorkspaceInitReport>;
+export { materializeClaudeSettingsLocal } from './workspace-claude-settings-materializer.js';
+/**
+ * Slice C10 (2026-06-24-legacy-change-id-sibling): whole-dir shape check
+ * for the legacy sibling `.peaks/_runtime/<sessionId>/`. Returns `true` ONLY when
+ * every leaf path under the sibling matches one of
+ * `WRITER_ALLOWED_RELATIVE_PATTERNS` AND no entry is a symlink (anywhere
+ * in the tree).
+ *
+ * Heuristic rationale (Karpathy #1 — name the tradeoff):
+ *   - False negative (reject writer-shaped content): we accept this
+ *     failure mode because it preserves the 2.8.3+ hard ban. The user
+ *     gets a clear migration message and can re-run after deleting the
+ *     sibling dir.
+ *   - False positive (accept legacy residue as writer output): we
+ *     REJECT this failure mode by requiring EVERY entry to match the
+ *     writer-allowed shape. One mismatched leaf ⇒ `false`. The whole-dir
+ *     check is conservative on purpose.
+ *
+ * Symlink rejection (Karpathy #3 — surgical): any symlinked entry — at
+ * the root or nested — returns `false` immediately. A symlinked
+ * `.peaks/_runtime/<sessionId>/qa/foo.png` could otherwise bypass the file-extension
+ * check by resolving to user content outside the project.
+ *
+ * Implementation note: the helper is synchronous and uses `lstatSync`
+ * recursively so the caller (the guard in `initWorkspace`) can decide
+ * inline without paying an async round-trip. Tree depth is bounded by
+ * the writer's mkdir pattern (≤3 levels: `<role>/<subdir>/<file>`).
+ * We cap the recursion at 8 levels as a defense-in-depth limit.
+ */
+export declare function isWriterCreatedSiblingShape(siblingDir: string): boolean;