peaks-cli 1.0.0

package/dist/src/services/sc/sc-service.d.ts

@@ -0,0 +1,79 @@
+export type ChangeImpact = {
+    changeId: string;
+    sourceArtifacts: string[];
+    affectedModules: string[];
+    affectedFiles: string[];
+    qaImpact: {
+        coverageDelta: number | null;
+        testCount: number;
+        status: 'passed' | 'failed' | 'unknown';
+    };
+    riskImpact: {
+        level: 'low' | 'medium' | 'high';
+        factors: string[];
+    };
+    syncPointers: {
+        artifactRepo: string | null;
+        lastSync: string | null;
+        localPath: string;
+    };
+};
+export type ArtifactRetentionReport = {
+    sliceId: string;
+    prdArtifacts: string[];
+    rdArtifacts: string[];
+    qaArtifacts: string[];
+    coverageArtifacts: string[];
+    reviewArtifacts: string[];
+    codeChanges: string[];
+    commitStatus: 'committed' | 'pending' | 'rolled-back';
+    rollbackPoint: string | null;
+};
+export type ChangeTraceabilityStatus = {
+    changeId: string | null;
+    hasArtifactRepo: boolean;
+    artifactSyncStatus: 'synced' | 'pending' | 'out-of-sync' | 'unknown';
+    localArtifactPath: string;
+    requiredArtifacts: {
+        name: string;
+        path: string;
+        exists: boolean;
+    }[];
+    nextActions: string[];
+};
+export type CommitBoundary = {
+    sliceId: string;
+    commitHash: string | null;
+    timestamp: string;
+    artifacts: string[];
+    codeFiles: string[];
+    syncState: 'synced' | 'pending' | 'failed';
+    rollbackPoint: string | null;
+};
+export declare function getChangeTraceabilityStatus(): ChangeTraceabilityStatus;
+export declare function createChangeImpact(options: {
+    changeId: string;
+    sourceArtifacts?: string[];
+    affectedModules?: string[];
+    affectedFiles?: string[];
+}): ChangeImpact;
+export declare function createArtifactRetentionReport(options: {
+    sliceId: string;
+    prdArtifacts?: string[];
+    rdArtifacts?: string[];
+    qaArtifacts?: string[];
+    coverageArtifacts?: string[];
+    reviewArtifacts?: string[];
+    codeChanges?: string[];
+}): ArtifactRetentionReport;
+export declare function recordCommitBoundary(options: {
+    sliceId: string;
+    artifacts?: string[];
+    codeFiles?: string[];
+}): CommitBoundary;
+export declare function validateArtifactRetention(sliceId: string): {
+    valid: boolean;
+    missingArtifacts: string[];
+    warnings: string[];
+};
+export declare function getScHelpText(): string[];

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

@@ -0,0 +1,223 @@
+import { existsSync, lstatSync, readFileSync, realpathSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { basename, relative, resolve } from 'node:path';
+import { getCurrentWorkspaceConfig } from '../config/config-service.js';
+import { getArtifactWorkspaceStatus, getLocalArtifactPath } from '../artifacts/workspace-service.js';
+const REQUIRED_ARTIFACTS = [
+    { name: 'artifact-retention-report.md', path: ['qa', 'artifact-retention-report.md'] },
+    { name: 'change-impact.json', path: ['sc', 'change-impact.json'] },
+    { name: 'commit-boundary.md', path: ['checkpoints', 'commit-boundary.md'] },
+    { name: 'coverage-report.md', path: ['qa', 'coverage-report.md'] }
+];
+const RETENTION_REQUIREMENTS = [
+    ['product', 'prd.md'],
+    ['architecture', 'slice-spec.md'],
+    ['qa', 'validation-report.md'],
+    ['qa', 'coverage-report.md'],
+    ['review', 'code-review.md']
+];
+const SLICE_ID_PATTERN = /^(?!\.{1,2}$)[A-Za-z0-9._-]+$/;
+function getPeaksPath(workspaceRoot) {
+    return resolve(workspaceRoot, '.peaks');
+}
+function resolveCurrentChangeId(peaksPath) {
+    const currentChangePath = resolve(peaksPath, 'current-change');
+    if (!existsSync(currentChangePath))
+        return null;
+    try {
+        const stat = lstatSync(currentChangePath);
+        if (stat.isSymbolicLink()) {
+            return basename(realpathSync(currentChangePath));
+        }
+        const raw = readFileSync(currentChangePath, 'utf-8').trim();
+        if (!raw)
+            return null;
+        return basename(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function getArtifactRepoUrl(artifactRepo) {
+    if (!artifactRepo)
+        return null;
+    if (artifactRepo.provider === 'github') {
+        return `https://github.com/${artifactRepo.owner}/${artifactRepo.name}.git`;
+    }
+    return `https://gitlab.com/${artifactRepo.owner}/${artifactRepo.name}.git`;
+}
+function getCurrentCommitHash(workspaceRoot) {
+    if (!workspaceRoot)
+        return null;
+    try {
+        return execFileSync('git', ['rev-parse', 'HEAD'], { cwd: workspaceRoot, encoding: 'utf-8' }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+function mapSyncState(syncStatus) {
+    if (syncStatus === 'synced')
+        return 'synced';
+    if (syncStatus === 'pending')
+        return 'pending';
+    return 'failed';
+}
+function getCurrentArtifactDir(workspaceRoot) {
+    const peaksPath = getPeaksPath(workspaceRoot);
+    const changeId = resolveCurrentChangeId(peaksPath);
+    const effectiveChangeId = changeId ?? 'unknown-change';
+    return {
+        peaksPath,
+        changeId,
+        changeDir: resolve(peaksPath, 'changes', effectiveChangeId)
+    };
+}
+function getRetentionChangeDir(workspaceRoot, sliceId) {
+    const peaksPath = getPeaksPath(workspaceRoot);
+    return {
+        peaksPath,
+        changeId: sliceId,
+        changeDir: resolve(peaksPath, 'changes', sliceId)
+    };
+}
+export function getChangeTraceabilityStatus() {
+    const workspace = getCurrentWorkspaceConfig();
+    const artifactStatus = getArtifactWorkspaceStatus(workspace?.workspaceId);
+    if (!workspace) {
+        return {
+            changeId: null,
+            hasArtifactRepo: false,
+            artifactSyncStatus: 'unknown',
+            localArtifactPath: '.peaks-artifacts',
+            requiredArtifacts: REQUIRED_ARTIFACTS.map((artifact) => ({
+                name: artifact.name,
+                path: resolve('.peaks', 'changes', '<change-id>', ...artifact.path),
+                exists: false
+            })),
+            nextActions: ['Add a workspace: peaks config workspace add --id <id> --name <name> --path <path>']
+        };
+    }
+    const { peaksPath, changeId, changeDir } = getCurrentArtifactDir(workspace.rootPath);
+    const hasArtifactRepo = Boolean(workspace.artifactRepo);
+    const requiredArtifacts = REQUIRED_ARTIFACTS.map((artifact) => {
+        const artifactPath = resolve(changeDir, ...artifact.path);
+        return {
+            name: artifact.name,
+            path: resolve(peaksPath, 'changes', changeId ?? '<change-id>', ...artifact.path),
+            exists: existsSync(artifactPath)
+        };
+    });
+    const nextActions = [];
+    if (!changeId) {
+        nextActions.push('Set the current change in .peaks/current-change');
+    }
+    if (!hasArtifactRepo) {
+        nextActions.push('Configure artifact repo: peaks config workspace add --id <id> --provider github --repo-owner <owner> --repo-name <name>');
+        nextActions.push('Then run: peaks artifacts init --provider github --name <repo> --dry-run');
+    }
+    else if (artifactStatus.syncStatus === 'pending') {
+        nextActions.push(`Run peaks artifacts sync --workspace ${workspace.workspaceId} --dry-run`);
+    }
+    return {
+        changeId,
+        hasArtifactRepo,
+        artifactSyncStatus: artifactStatus.syncStatus,
+        localArtifactPath: getLocalArtifactPath(workspace),
+        requiredArtifacts,
+        nextActions
+    };
+}
+export function createChangeImpact(options) {
+    const workspace = getCurrentWorkspaceConfig();
+    const artifactRepo = workspace?.artifactRepo ?? null;
+    return {
+        changeId: options.changeId,
+        sourceArtifacts: options.sourceArtifacts ?? [],
+        affectedModules: options.affectedModules ?? [],
+        affectedFiles: options.affectedFiles ?? [],
+        qaImpact: {
+            coverageDelta: null,
+            testCount: 0,
+            status: 'unknown'
+        },
+        riskImpact: {
+            level: 'medium',
+            factors: ['Manual review required', 'No automated gates detected']
+        },
+        syncPointers: {
+            artifactRepo: getArtifactRepoUrl(artifactRepo ?? undefined),
+            lastSync: null,
+            localPath: workspace ? getLocalArtifactPath(workspace) : '.peaks-artifacts'
+        }
+    };
+}
+export function createArtifactRetentionReport(options) {
+    return {
+        sliceId: options.sliceId,
+        prdArtifacts: options.prdArtifacts ?? [],
+        rdArtifacts: options.rdArtifacts ?? [],
+        qaArtifacts: options.qaArtifacts ?? [],
+        coverageArtifacts: options.coverageArtifacts ?? [],
+        reviewArtifacts: options.reviewArtifacts ?? [],
+        codeChanges: options.codeChanges ?? [],
+        commitStatus: 'pending',
+        rollbackPoint: null
+    };
+}
+export function recordCommitBoundary(options) {
+    const workspace = getCurrentWorkspaceConfig();
+    const artifactStatus = getArtifactWorkspaceStatus(workspace?.workspaceId);
+    const commitHash = getCurrentCommitHash(workspace?.rootPath);
+    return {
+        sliceId: options.sliceId,
+        commitHash,
+        timestamp: new Date().toISOString(),
+        artifacts: options.artifacts ?? [],
+        codeFiles: options.codeFiles ?? [],
+        syncState: mapSyncState(artifactStatus.syncStatus),
+        rollbackPoint: commitHash
+    };
+}
+export function validateArtifactRetention(sliceId) {
+    const workspace = getCurrentWorkspaceConfig();
+    if (!workspace) {
+        return {
+            valid: false,
+            missingArtifacts: ['No workspace configured'],
+            warnings: ['Cannot validate without a configured workspace']
+        };
+    }
+    if (!SLICE_ID_PATTERN.test(sliceId)) {
+        return {
+            valid: false,
+            missingArtifacts: ['Invalid slice id'],
+            warnings: ['Slice id must stay inside .peaks/changes and only contain letters, numbers, dots, underscores, or hyphens']
+        };
+    }
+    const { changeDir } = getRetentionChangeDir(workspace.rootPath, sliceId);
+    const missingArtifacts = RETENTION_REQUIREMENTS
+        .map(([folder, file]) => resolve(changeDir, folder, file))
+        .filter((filePath) => !existsSync(filePath))
+        .map((filePath) => relative(changeDir, filePath).replace(/\\/g, '/'));
+    return {
+        valid: missingArtifacts.length === 0,
+        missingArtifacts,
+        warnings: missingArtifacts.length === 0 ? [] : ['Some required artifact files are missing']
+    };
+}
+export function getScHelpText() {
+    return [
+        'peaks sc status                          Show change traceability status',
+        'peaks sc impact --change-id <id>         Generate change impact artifact',
+        'peaks sc retention --slice-id <id>        Create artifact retention report',
+        'peaks sc validate --slice-id <id>         Validate artifact retention',
+        'peaks sc boundary --slice-id <id>         Record commit boundary for slice',
+        '',
+        'Change traceability workflow integration:',
+        '  1. Run peaks sc status to check current state',
+        '  2. After slice completion, run peaks sc retention --slice-id <id>',
+        '  3. Artifact sync is automatic when artifact repo is configured',
+        '  4. Commit boundary is recorded when code is committed'
+    ];
+}

package/dist/src/services/skills/skill-registry.d.ts

@@ -0,0 +1,17 @@
+export type SkillMetadata = {
+    name: string;
+    description: string;
+    directory: string;
+    skillPath: string;
+};
+export type SkillLoadFailure = {
+    directory: string;
+    skillPath: string;
+    message: string;
+};
+export type SkillRegistryResult = {
+    skills: SkillMetadata[];
+    failures: SkillLoadFailure[];
+};
+export declare function loadSkillRegistry(baseDir?: string): Promise<SkillRegistryResult>;
+export declare function listSkills(baseDir?: string): Promise<SkillMetadata[]>;

package/dist/src/services/skills/skill-registry.js

@@ -0,0 +1,40 @@
+import { join } from 'node:path';
+import { listDirectories, pathExists, readText } from '../../shared/fs.js';
+import { parseFrontmatter } from '../../shared/frontmatter.js';
+import { skillsDir } from '../../shared/paths.js';
+function getLoadFailureMessage(error) {
+    return error instanceof Error ? error.message : 'Unable to parse skill metadata';
+}
+export async function loadSkillRegistry(baseDir = skillsDir) {
+    if (!(await pathExists(baseDir))) {
+        return { skills: [], failures: [] };
+    }
+    const directories = await listDirectories(baseDir);
+    const skills = [];
+    const failures = [];
+    for (const directory of directories) {
+        const skillPath = join(baseDir, directory, 'SKILL.md');
+        if (!(await pathExists(skillPath))) {
+            continue;
+        }
+        try {
+            const frontmatter = parseFrontmatter(await readText(skillPath));
+            skills.push({
+                name: frontmatter.name,
+                description: frontmatter.description,
+                directory,
+                skillPath
+            });
+        }
+        catch (error) {
+            failures.push({ directory, skillPath, message: getLoadFailureMessage(error) });
+        }
+    }
+    return {
+        skills: skills.sort((left, right) => left.name.localeCompare(right.name)),
+        failures: failures.sort((left, right) => left.directory.localeCompare(right.directory))
+    };
+}
+export async function listSkills(baseDir = skillsDir) {
+    return (await loadSkillRegistry(baseDir)).skills;
+}

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

@@ -0,0 +1,82 @@
+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-solo'];
+    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[];
+    };
+};
+type ProjectStandardsInitOptions = {
+    readonly projectRoot: string;
+    readonly language?: string;
+    readonly apply?: boolean;
+};
+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;
+export {};