peaks-cli 1.2.8 → 1.3.0

package/dist/src/services/sc/sc-service.js

@@ -1,6 +1,6 @@
-import { existsSync, lstatSync, readFileSync, realpathSync } from 'node:fs';
+import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
-import { basename, relative, resolve } from 'node:path';
+import { basename, join, resolve } from 'node:path';
 import { isInsidePath } from '../../shared/path-utils.js';
 import { getWorkspaceConfigForPath } from '../config/config-service.js';
 import { getArtifactRemoteRepo, getArtifactWorkspaceStatus, getLocalArtifactPath } from '../artifacts/workspace-service.js';
@@ -21,6 +21,27 @@ const RETENTION_REQUIREMENTS = [
     ['sc', 'retention-boundary.md'],
     ['txt', 'context-capsule.md']
 ];
+/**
+ * "Modern" retention requirements for the current peaks-cli artifact
+ * naming convention. The legacy `RETENTION_REQUIREMENTS` above assume
+ * older `refactor-goal.md` / `slice-spec.md` / `coverage-report.md` /
+ * `validation-report.md` / `change-impact.json` / `retention-boundary.md`
+ * / `context-capsule.md` filenames that predate the W4 session resolver.
+ *
+ * When the resolver finds a session that owns the slice, validate
+ * against the modern set: the actual files the current workflow emits
+ * (per-slice `prd/requests/<rid>.md`, per-slice `rd/requests/<rid>.md`,
+ * per-session `rd/tech-doc.md`, per-slice `qa/test-cases/<rid>.md`,
+ * per-slice `qa/test-reports/<rid>.md`, per-session `txt/handoff.md`).
+ * The legacy set is preserved for the workspace-artifact path so
+ * existing repos on the old convention keep working.
+ */
+const MODERN_RETENTION_REQUIREMENTS = [
+    'rd/tech-doc.md',
+    'qa/test-cases/{sliceId}.md',
+    'qa/test-reports/{sliceId}.md',
+    'txt/handoff.md'
+];
 const SLICE_ID_PATTERN = /^(?!\.{1,2}$)[A-Za-z0-9._-]+$/;
 function getPeaksPath(workspaceRoot) {
     return resolve(workspaceRoot, '.peaks');
@@ -108,6 +129,150 @@ function isRetainedArtifactFile(filePath, artifactWorkspacePath, changesRoot, ch
         return false;
     }
 }
+/**
+ * Read the orchestrator's active-skill marker and return its
+ * `sessionId`, or null when the file is missing / malformed.
+ *
+ * As of slice 2026-06-05-peaks-runtime-layer the canonical home is
+ * `<projectRoot>/.peaks/_runtime/active-skill.json`. The legacy
+ * `<projectRoot>/.peaks/.active-skill.json` is consulted as a
+ * one-minor-release back-compat fallback: if the new path is
+ * absent but the legacy path is present and valid, we use the
+ * legacy value. The new path always wins when both exist.
+ */
+function readActiveSkillSessionId(projectRoot) {
+    const newPath = join(projectRoot, '.peaks', '_runtime', 'active-skill.json');
+    const legacyPath = join(projectRoot, '.peaks', '.active-skill.json');
+    const pathToRead = existsSync(newPath) ? newPath : legacyPath;
+    if (!existsSync(pathToRead))
+        return null;
+    try {
+        const raw = readFileSync(pathToRead, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed?.sessionId === 'string' && parsed.sessionId.length > 0) {
+            return parsed.sessionId;
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+/**
+ * Read the workspace session binding and return its `sessionId`,
+ * or null when the file is missing / malformed.
+ *
+ * As of slice 2026-06-05-peaks-runtime-layer the canonical home is
+ * `<projectRoot>/.peaks/_runtime/session.json`. The legacy
+ * `<projectRoot>/.peaks/.session.json` is consulted as a
+ * one-minor-release back-compat fallback: if the new path is
+ * absent but the legacy path is present and valid, we use the
+ * legacy value. The new path always wins when both exist.
+ */
+function readSessionJsonBinding(projectRoot) {
+    const newPath = join(projectRoot, '.peaks', '_runtime', 'session.json');
+    const legacyPath = join(projectRoot, '.peaks', '.session.json');
+    const pathToRead = existsSync(newPath) ? newPath : legacyPath;
+    if (!existsSync(pathToRead))
+        return null;
+    try {
+        const raw = readFileSync(pathToRead, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed?.sessionId === 'string' && parsed.sessionId.length > 0) {
+            return parsed.sessionId;
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+/**
+ * The "marker" artifact whose existence under a session dir is the signal
+ * that the session owns the slice. We look for `qa/test-cases/<sliceId>.md`
+ * first (a present test plan is the most decisive signal of session
+ * ownership for a slice id). If the test plan is absent we also accept
+ * `qa/test-reports/<sliceId>.md` (a finished QA report is also a decisive
+ * ownership signal). When neither exists for a candidate session, that
+ * session does not own the slice.
+ */
+function sessionOwnsSlice(projectRoot, sessionId, sliceId) {
+    const sessionDir = join(projectRoot, '.peaks', sessionId);
+    if (!existsSync(sessionDir))
+        return false;
+    for (const marker of [`qa/test-cases/${sliceId}.md`, `qa/test-reports/${sliceId}.md`]) {
+        if (existsSync(join(sessionDir, marker)))
+            return true;
+    }
+    return false;
+}
+/**
+ * Find a session dir under `<projectRoot>/.peaks/` that owns the slice
+ * (see `sessionOwnsSlice`). Returns the first match in lexicographic
+ * order, or null when no session owns the slice.
+ */
+function findSessionOwningSlice(projectRoot, sliceId) {
+    const peaksRoot = join(projectRoot, '.peaks');
+    if (!existsSync(peaksRoot))
+        return null;
+    let names;
+    try {
+        names = readdirSync(peaksRoot);
+    }
+    catch {
+        return null;
+    }
+    names.sort();
+    for (const name of names) {
+        if (!/^\d{4}-\d{2}-\d{2}-session-[a-f0-9]+$/.test(name))
+            continue;
+        if (sessionOwnsSlice(projectRoot, name, sliceId)) {
+            return name;
+        }
+    }
+    return null;
+}
+/**
+ * Resolve the session id that owns the slice's artifacts using a 3-tier
+ * precedence:
+ *
+ *   1. `.peaks/_runtime/active-skill.json` `sessionId` (with back-compat
+ *      fallback to `.peaks/.active-skill.json`) if it points to a real
+ *      session that owns the slice.
+ *   2. `.peaks/_runtime/session.json` `sessionId` (with back-compat
+ *      fallback to `.peaks/.session.json`) if it points to a real
+ *      session that owns the slice.
+ *   3. `find .peaks/ -name '<marker>'` — the first session dir under
+ *      `.peaks/` that owns the slice.
+ *   4. else `{ resolvedSessionId: null, candidateSources: [] }`.
+ *
+ * The back-compat fallbacks are tolerated for one minor release so
+ * users with pre-migration trees (or running an older CLI version)
+ * still get a clean resolution. After the migration (or after v1.3.0
+ * is installed and `peaks workspace reconcile` has been run), only
+ * the new paths exist and the fallbacks never fire.
+ *
+ * `candidateSources` reports which sources were checked before the
+ * resolver found (or did not find) a winner; the list is in the order
+ * the resolver consulted them. This makes the precedence observable in
+ * the JSON envelope so a human reviewer can see "active-skill was empty
+ * AND session-json was empty, so find-fallback won".
+ */
+export function resolveArtifactSession(projectRoot, sliceId) {
+    const activeSkill = readActiveSkillSessionId(projectRoot);
+    if (activeSkill !== null && sessionOwnsSlice(projectRoot, activeSkill, sliceId)) {
+        return { resolvedSessionId: activeSkill, candidateSources: ['active-skill'] };
+    }
+    const sessionJson = readSessionJsonBinding(projectRoot);
+    if (sessionJson !== null && sessionOwnsSlice(projectRoot, sessionJson, sliceId)) {
+        return { resolvedSessionId: sessionJson, candidateSources: ['active-skill', 'session-json'] };
+    }
+    const findHit = findSessionOwningSlice(projectRoot, sliceId);
+    if (findHit !== null) {
+        return { resolvedSessionId: findHit, candidateSources: ['active-skill', 'session-json', 'find-fallback'] };
+    }
+    return { resolvedSessionId: null, candidateSources: [] };
+}
 export function getChangeTraceabilityStatus() {
     const workspace = getWorkspaceConfigForPath(process.cwd());
     const artifactStatus = getArtifactWorkspaceStatus(workspace?.workspaceId);
@@ -196,6 +361,8 @@ export function recordCommitBoundary(options) {
     const workspace = getWorkspaceConfigForPath(process.cwd());
     const artifactStatus = getArtifactWorkspaceStatus(workspace?.workspaceId);
     const commitHash = getCurrentCommitHash(workspace?.rootPath);
+    const projectRoot = workspace?.rootPath ?? process.cwd();
+    const resolution = resolveArtifactSession(projectRoot, options.sliceId);
     return {
         sliceId: options.sliceId,
         commitHash,
@@ -203,38 +370,120 @@ export function recordCommitBoundary(options) {
         artifacts: options.artifacts ?? [],
         codeFiles: options.codeFiles ?? [],
         syncState: mapSyncState(artifactStatus.syncStatus),
-        rollbackPoint: commitHash
+        rollbackPoint: commitHash,
+        resolvedSessionId: resolution.resolvedSessionId,
+        candidateSources: resolution.candidateSources
     };
 }
 export function validateArtifactRetention(sliceId) {
     const workspace = getWorkspaceConfigForPath(process.cwd());
-    if (!workspace) {
+    // Resolve from `process.cwd()` even when no workspace is configured, so
+    // the W4 session resolver can still find the slice's owning session.
+    // The legacy "no workspace" check still surfaces as a missing artifact,
+    // but the resolution happens first so the JSON envelope's additive
+    // `resolvedSessionId` is populated regardless of workspace state.
+    const projectRoot = workspace?.rootPath ?? process.cwd();
+    if (!SLICE_ID_PATTERN.test(sliceId)) {
         return {
             valid: false,
-            missingArtifacts: ['No workspace configured'],
-            warnings: ['Cannot validate without a configured workspace']
+            missingArtifacts: ['Invalid slice id'],
+            warnings: ['Slice id must stay inside .peaks/<session-id> and only contain letters, numbers, dots, underscores, or hyphens'],
+            resolvedSessionId: null,
+            candidateSources: []
         };
     }
-    if (!SLICE_ID_PATTERN.test(sliceId)) {
+    const resolution = resolveArtifactSession(projectRoot, sliceId);
+    const effectiveSliceId = resolution.resolvedSessionId ?? sliceId;
+    // W4: if the resolver found a session, ALSO accept artifacts under
+    // `<projectRoot>/.peaks/<resolvedSessionId>/` (the canonical per-slice
+    // dir). The project-root peaks is where the orchestrator's skills
+    // actually write (see `initWorkspace` in `workspace-service.ts`), so
+    // when the resolution chain lands on a real session the artifacts are
+    // usually there. We accept either location — workspace artifact path
+    // OR project-root peaks — so the additive behavior does not regress
+    // existing workspaces.
+    const resolvedPeaksSessionDir = resolution.resolvedSessionId !== null
+        ? join(projectRoot, '.peaks', resolution.resolvedSessionId)
+        : null;
+    // Collect present files: legacy workspace-artifact-path check, OR the
+    // resolved session's project-root peaks dir.
+    const legacyPresent = (folder, file) => {
+        if (!workspace)
+            return false;
+        const artifactWorkspacePath = getLocalArtifactPath(workspace);
+        const { peaksPath, changeDir } = getRetentionChangeDir(artifactWorkspacePath, effectiveSliceId);
+        const filePath = resolve(changeDir, folder, file);
+        return isRetainedArtifactFile(filePath, artifactWorkspacePath, peaksPath, changeDir);
+    };
+    const resolvedPresent = (folder, file) => {
+        if (resolvedPeaksSessionDir === null)
+            return false;
+        return existsSync(join(resolvedPeaksSessionDir, folder, file));
+    };
+    if (!workspace) {
+        // No workspace: validate against the resolved session dir directly
+        // (this is the common peaks-solo / peaks-rd invocation: the slice
+        // lives under the project-root `.peaks/<sessionId>/`, and the
+        // workspace artifact path is irrelevant). When the resolution also
+        // fails, fall back to the legacy "No workspace configured" failure
+        // mode so the existing CLI contract is preserved.
+        if (resolvedPeaksSessionDir === null) {
+            return {
+                valid: false,
+                missingArtifacts: ['No workspace configured'],
+                warnings: ['Cannot validate without a configured workspace'],
+                resolvedSessionId: resolution.resolvedSessionId,
+                candidateSources: resolution.candidateSources
+            };
+        }
+        const missingArtifacts = modernRequirementRelativePaths(sliceId).filter((rel) => !existsSync(join(resolvedPeaksSessionDir, rel)));
         return {
-            valid: false,
-            missingArtifacts: ['Invalid slice id'],
-            warnings: ['Slice id must stay inside .peaks/<session-id> and only contain letters, numbers, dots, underscores, or hyphens']
+            valid: missingArtifacts.length === 0,
+            missingArtifacts,
+            warnings: missingArtifacts.length === 0 ? [] : ['Some required artifact files are missing'],
+            resolvedSessionId: resolution.resolvedSessionId,
+            candidateSources: resolution.candidateSources
         };
     }
-    const artifactWorkspacePath = getLocalArtifactPath(workspace);
-    const { peaksPath, changeDir } = getRetentionChangeDir(artifactWorkspacePath, sliceId);
-    const changesRoot = peaksPath;
     const missingArtifacts = RETENTION_REQUIREMENTS
-        .map(([folder, file]) => resolve(changeDir, folder, file))
-        .filter((filePath) => !isRetainedArtifactFile(filePath, artifactWorkspacePath, changesRoot, changeDir))
-        .map((filePath) => relative(changeDir, filePath).replace(/\\/g, '/'));
+        .map(([folder, file]) => `${folder}/${file}`)
+        .filter((rel) => !legacyPresent(...rel.split('/')) && !resolvedPresent(...rel.split('/')));
+    // If the legacy check is short (i.e. we're missing a lot of legacy-named
+    // files) but the resolver landed on a real session, ALSO accept the
+    // modern set. The legacy set was designed for an older workflow naming
+    // and a freshly-minted session in the current peaks-cli flow will not
+    // have the legacy names. This keeps `peaks sc validate --slice-id <rid>`
+    // returning `valid: true` for slices that completed under the current
+    // peaks-cli convention.
+    if (missingArtifacts.length > 0 && resolvedPeaksSessionDir !== null) {
+        const modernMissing = modernRequirementRelativePaths(sliceId).filter((rel) => !resolvedPresent(...rel.split('/')));
+        if (modernMissing.length === 0) {
+            return {
+                valid: true,
+                missingArtifacts: [],
+                warnings: [],
+                resolvedSessionId: resolution.resolvedSessionId,
+                candidateSources: resolution.candidateSources
+            };
+        }
+    }
     return {
         valid: missingArtifacts.length === 0,
         missingArtifacts,
-        warnings: missingArtifacts.length === 0 ? [] : ['Some required artifact files are missing']
+        warnings: missingArtifacts.length === 0 ? [] : ['Some required artifact files are missing'],
+        resolvedSessionId: resolution.resolvedSessionId,
+        candidateSources: resolution.candidateSources
     };
 }
+/**
+ * Render the modern retention requirements as relative paths keyed
+ * against the slice id. The `{sliceId}` placeholder in the template
+ * is replaced with the actual slice id; per-session files (no
+ * placeholder) keep their literal name.
+ */
+function modernRequirementRelativePaths(sliceId) {
+    return MODERN_RETENTION_REQUIREMENTS.map((template) => template.replace('{sliceId}', sliceId));
+}
 export function getScHelpText() {
     return [
         'peaks sc status                          Show change traceability status',

package/dist/src/services/scan/libraries-service.d.ts

@@ -0,0 +1,24 @@
+import type { LibraryReport } from './libraries-types.js';
+export type ScanLibrariesOptions = {
+    projectRoot: string;
+};
+/**
+ * Parse the major version from a semver-ish spec.
+ *
+ * Handles the common shapes:
+ *   "^5.18.0"      → 5
+ *   "~1.2.3"       → 1
+ *   "1.2.3"        → 1
+ *   ">=1.0.0"      → 1
+ *   "5"            → 5
+ *   "5.x"          → 5
+ *
+ * Returns null for non-semver specs that the LLM should not assume a
+ * major for:
+ *   "workspace:*"  → null
+ *   "file:../..."   → null
+ *   "git+https..." → null
+ *   "npm:@scope/x@1" → 1 (alias spec, we extract what we can)
+ */
+export declare function parseMajorVersion(spec: string): number | null;
+export declare function scanLibraries(options: ScanLibrariesOptions): Promise<LibraryReport>;