@planu/cli 4.8.0 → 4.10.0

package/dist/tools/validate-minimality.js

@@ -0,0 +1,22 @@
+// tools/validate-minimality.ts — Minimal implementation report helper for validate.
+import { analyzeMinimalImplementation, loadMinimalImplementationPolicy, } from '../engine/minimality/index.js';
+export async function buildMinimalityReport(args) {
+    try {
+        const { policy, evidence } = await loadMinimalImplementationPolicy(args.projectPath);
+        return analyzeMinimalImplementation({
+            policy,
+            specId: args.specId,
+            specRisk: args.risk,
+            specText: [args.title ?? '', ...args.missing, ...args.extra].join('\n'),
+            files: args.qualityIssues.map((issue) => ({
+                path: issue.file,
+                content: [issue.rule, issue.message, issue.suggestion ?? ''].join('\n'),
+            })),
+            evidence,
+        });
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=validate-minimality.js.map

package/dist/tools/validate-runtime.d.ts

@@ -0,0 +1,14 @@
+export interface ProjectCommandPlan {
+    requestedCommand: string;
+    executedCommand: string;
+    executable: string;
+    args: string[];
+    projectPackageManager: string | null;
+    source: 'project-package-manager' | 'host-path';
+    runtimeNode: string;
+    hint?: string;
+}
+export declare function resolveProjectCommandPlan(projectPath: string, requestedCommand: string, corepackAvailable?: boolean): ProjectCommandPlan;
+export declare function formatLintFailureDiagnostics(plan: ProjectCommandPlan, output: string): string;
+export declare function runProjectCommandPlan(plan: ProjectCommandPlan, projectPath: string, timeoutMs: number): void;
+//# sourceMappingURL=validate-runtime.d.ts.map

package/dist/tools/validate-runtime.js

@@ -0,0 +1,85 @@
+// tools/validate-runtime.ts — Project-aware command execution helpers for validate.
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+function readProjectPackageManager(projectPath) {
+    try {
+        const raw = readFileSync(`${projectPath}/package.json`, 'utf-8');
+        const parsed = JSON.parse(raw);
+        return typeof parsed.packageManager === 'string' ? parsed.packageManager : null;
+    }
+    catch {
+        return null;
+    }
+}
+function shellTokens(command) {
+    return command.split(/\s+/).filter((token) => token.length > 0);
+}
+function canRunCorepack(projectPath) {
+    try {
+        execFileSync('corepack', ['--version'], {
+            cwd: projectPath,
+            stdio: ['ignore', 'ignore', 'ignore'],
+            timeout: 5_000,
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function resolveProjectCommandPlan(projectPath, requestedCommand, corepackAvailable = canRunCorepack(projectPath)) {
+    const projectPackageManager = readProjectPackageManager(projectPath);
+    const tokens = shellTokens(requestedCommand);
+    const usesPnpm = tokens[0] === 'pnpm';
+    const projectPinsPnpm = projectPackageManager?.startsWith('pnpm@') ?? false;
+    if (usesPnpm && projectPinsPnpm && corepackAvailable) {
+        const args = ['pnpm', ...tokens.slice(1)];
+        return {
+            requestedCommand,
+            executedCommand: ['corepack', ...args].join(' '),
+            executable: 'corepack',
+            args,
+            projectPackageManager,
+            source: 'project-package-manager',
+            runtimeNode: process.version,
+        };
+    }
+    return {
+        requestedCommand,
+        executedCommand: requestedCommand,
+        executable: tokens[0] ?? requestedCommand,
+        args: tokens.slice(1),
+        projectPackageManager,
+        source: 'host-path',
+        runtimeNode: process.version,
+        ...(usesPnpm && projectPinsPnpm
+            ? {
+                hint: 'Project pins pnpm via packageManager but Corepack was unavailable; falling back to host PATH. Enable Corepack or run `corepack pnpm ...` to match the project runtime.',
+            }
+            : {}),
+    };
+}
+export function formatLintFailureDiagnostics(plan, output) {
+    const lines = [
+        output.trim(),
+        '',
+        'Planu validate runtime diagnostics:',
+        `- requestedCommand: ${plan.requestedCommand}`,
+        `- executedCommand: ${plan.executedCommand}`,
+        `- projectPackageManager: ${plan.projectPackageManager ?? 'unknown'}`,
+        `- commandSource: ${plan.source}`,
+        `- runtimeNode: ${plan.runtimeNode}`,
+    ];
+    if (plan.hint !== undefined) {
+        lines.push(`- hint: ${plan.hint}`);
+    }
+    return lines.filter((line, index) => index !== 0 || line.length > 0).join('\n');
+}
+export function runProjectCommandPlan(plan, projectPath, timeoutMs) {
+    execFileSync(plan.executable, plan.args, {
+        cwd: projectPath,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        timeout: timeoutMs,
+    });
+}
+//# sourceMappingURL=validate-runtime.js.map

package/dist/tools/validate.js

@@ -1,7 +1,5 @@
 // tools/validate.ts — Compare spec vs implementation (SPEC-595: elicitation on failures)
 // Uses the validator engine to check coverage, missing items, quality issues.
-import { execSync, execFileSync } from 'node:child_process';
-import { readFileSync } from 'node:fs';
 import { elicitOrFallback, buildEnumSchema } from '../engine/elicitation/elicit-helper.js';
 import { compactObj } from '../engine/compact-obj.js';
 import { resolveProjectId, missingProjectIdError } from './resolve-project-id.js';
@@ -16,104 +14,13 @@ import { parseConventions, scanConventions } from '../engine/convention-scanner/
 import { validateScopeCompliance } from '../engine/scope-boundaries/index.js';
 import { compareWithBaseline } from '../storage/convention-baseline.js';
 import { writeImplementationReviewReport } from '../engine/validator/validation-report-writer.js';
-import { evaluateNewCodeGate } from '../engine/ai-assurance/index.js';
-import { queryProjectGraphSlice } from '../engine/project-graph/index.js';
-import { analyzeMinimalImplementation, loadMinimalImplementationPolicy, } from '../engine/minimality/index.js';
+import { buildGraphCoverageReport, formatGraphCoverageText } from './validate-graph-coverage.js';
+import { buildMinimalityReport } from './validate-minimality.js';
+import { buildValidateFailureFallback, validateStrictLayoutOrError } from './validate-helpers.js';
+import { runLintCheck } from './validate-lint.js';
+import { checkPlanuUncommittedChanges, runAssuranceGates } from './validate-assurance.js';
 // Re-export for external use (SPEC-018)
 export { validateContractCompliance };
-function graphCoverageGaps(slice) {
-    if (slice === null) {
-        return [];
-    }
-    const criteria = slice.nodes.filter((node) => node.type === 'criterion');
-    return criteria
-        .filter((criterion) => {
-        const outgoing = slice.edges.filter((edge) => edge.from === criterion.id);
-        return !outgoing.some((edge) => edge.type === 'implements' || edge.type === 'tests');
-    })
-        .map((criterion) => criterion.label)
-        .slice(0, 10);
-}
-async function buildGraphCoverageReport(args) {
-    const graphSlice = await queryProjectGraphSlice(args).catch(() => null);
-    return {
-        freshness: graphSlice?.freshness,
-        gaps: graphCoverageGaps(graphSlice),
-        compactNodes: graphSlice?.nodes.length ?? 0,
-        compactEdges: graphSlice?.edges.length ?? 0,
-    };
-}
-function formatGraphCoverageText(report) {
-    return report.gaps.length > 0
-        ? `\nGRAPH     ${String(report.gaps.length)} graph-backed coverage gap(s)`
-        : '';
-}
-async function buildMinimalityReport(args) {
-    try {
-        const { policy, evidence } = await loadMinimalImplementationPolicy(args.projectPath);
-        return analyzeMinimalImplementation({
-            policy,
-            specId: args.specId,
-            specRisk: args.risk,
-            specText: [args.title ?? '', ...args.missing, ...args.extra].join('\n'),
-            files: args.qualityIssues.map((issue) => ({
-                path: issue.file,
-                content: [issue.rule, issue.message, issue.suggestion ?? ''].join('\n'),
-            })),
-            evidence,
-        });
-    }
-    catch {
-        return null;
-    }
-}
-async function validateStrictLayoutOrError(args) {
-    try {
-        const { validateStrictPlanuLayout } = await import('../engine/spec-migrator/index.js');
-        const layout = await validateStrictPlanuLayout(args.projectPath, {
-            specPath: args.specPath,
-            includeRoot: false,
-        });
-        if (layout.ok) {
-            return null;
-        }
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Strict Planu layout validation failed for ${args.specId}.\n\n` +
-                        `Non-canonical paths:\n${layout.offenders.map((p) => `- ${p}`).join('\n')}\n\n` +
-                        `Canonical contract:\n${layout.contract}`,
-                },
-            ],
-            isError: true,
-            structuredContent: {
-                error: 'strict_planu_layout_violation',
-                offenders: layout.offenders,
-                contract: layout.contract,
-            },
-        };
-    }
-    catch {
-        return null;
-    }
-}
-/** Build the fallback interactiveQuestion for validation failures. */
-function buildValidateFailureFallback(failedCount) {
-    return {
-        header: 'Failures',
-        question: `${failedCount} criteria failed. How do you want to proceed?`,
-        multiSelect: false,
-        options: [
-            {
-                label: 're-implement',
-                description: 'Fix the failing criteria and run validate again (Recommended)',
-            },
-            { label: 'ignore', description: 'Ignore failures and proceed (not recommended)' },
-            { label: 'mark-manual', description: 'Mark as manually reviewed — will bypass auto-check' },
-        ],
-    };
-}
 // SPEC-595: server? param enables elicitation on failures
 export async function handleValidate(args, server) {
     const { specId } = args;
@@ -478,130 +385,6 @@ function buildCompactValidateText(args) {
     const summaryLine = `❌ Validate: ${String(score)}/100 — ${String(failedCount)} failing: [${failNames}${remainingCount + shownFailures.length > 3 ? '...' : ''}]`;
     return summaryLine + '\n' + failureList + moreLine + commitReminder + planuReminder;
 }
-/** Allowlist: alphanumerics, spaces, and safe shell chars. Rejects ; | $ ` & < > */
-const SAFE_COMMAND_RE = /^[\w\s./:@~=-]+$/;
-const LINT_CHECK_TIMEOUT_MS = 50_000;
-function isSafeCommand(cmd) {
-    return SAFE_COMMAND_RE.test(cmd);
-}
-function isCommandTimeout(err) {
-    if (!(err instanceof Error)) {
-        return false;
-    }
-    const errorWithProcessFields = err;
-    return (errorWithProcessFields.signal === 'SIGTERM' ||
-        errorWithProcessFields.killed === true ||
-        errorWithProcessFields.code === 'ETIMEDOUT' ||
-        /timed out|timeout/i.test(err.message));
-}
-function commandOutput(err) {
-    if (!(err instanceof Error)) {
-        return String(err);
-    }
-    const errorWithOutput = err;
-    return [errorWithOutput.stdout, errorWithOutput.stderr]
-        .filter((chunk) => chunk !== undefined)
-        .map((chunk) => String(chunk))
-        .join('\n')
-        .trim();
-}
-function runAssuranceGates(projectPath) {
-    return {
-        newCode: evaluateNewCodeGate(readChangedSpecLogicFiles(projectPath)),
-    };
-}
-function readChangedSpecLogicFiles(projectPath) {
-    let changedFiles;
-    try {
-        const output = execFileSync('git', [
-            '-C',
-            projectPath,
-            'diff',
-            '--name-only',
-            'HEAD',
-            '--',
-            'src/tools/create-spec',
-            'src/tools/validate.ts',
-            'src/engine',
-        ], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
-        changedFiles = output
-            .split('\n')
-            .map((line) => line.trim())
-            .filter((line) => line.endsWith('.ts'));
-    }
-    catch {
-        return [];
-    }
-    return changedFiles.flatMap((path) => {
-        try {
-            return [{ path, content: readFileSync(`${projectPath}/${path}`, 'utf-8') }];
-        }
-        catch {
-            return [];
-        }
-    });
-}
-function runLintCheck(projectPath, lintCommand) {
-    if (lintCommand !== null && !isSafeCommand(lintCommand)) {
-        console.warn(`[Planu] validate: lintCommand contains unsafe characters — skipping execution`);
-        return {
-            passed: true,
-            command: lintCommand,
-            issueCount: 0,
-            output: '(skipped — unsafe command)',
-        };
-    }
-    // SPEC-787: use pnpm lint (same as `pnpm lint` in package.json) to match what
-    // the developer runs manually. The old `npx eslint src ... || true` never raised
-    // an error (|| true suppressed exit code) and ran against a different scope.
-    const command = lintCommand ?? 'pnpm lint';
-    try {
-        execSync(command, {
-            cwd: projectPath,
-            stdio: ['pipe', 'pipe', 'pipe'],
-            timeout: LINT_CHECK_TIMEOUT_MS,
-        });
-        return { passed: true, command, issueCount: 0, output: '' };
-    }
-    catch (err) {
-        if (isCommandTimeout(err)) {
-            const seconds = Math.round(LINT_CHECK_TIMEOUT_MS / 1000);
-            const output = `Lint command timed out after ${String(seconds)}s and was skipped so validate can complete within MCP request limits. ` +
-                `Run \`${command}\` manually before marking the spec done.`;
-            console.warn(`[Planu] lintCheck timed out: command="${command}" cwd="${projectPath}" timeoutMs=${String(LINT_CHECK_TIMEOUT_MS)}`);
-            return { passed: true, command, issueCount: 0, output };
-        }
-        const raw = commandOutput(err);
-        // SPEC-787: never truncate — preserve full output so caller sees real issues
-        const output = raw.trim();
-        const issueCount = parseLintIssueCount(output);
-        // SPEC-787: log exact command + cwd for debuggability
-        console.warn(`[Planu] lintCheck failed: command="${command}" cwd="${projectPath}" issues=${String(issueCount)}`);
-        return { passed: false, command, issueCount, output };
-    }
-}
-function parseLintIssueCount(output) {
-    const m = /(\d+)\s+problem/i.exec(output);
-    if (m) {
-        return parseInt(m[1] ?? '0', 10);
-    }
-    return output.split('\n').filter((l) => l.trim().length > 0).length;
-}
-/** Check if planu/ directory has uncommitted changes via git status --porcelain */
-function checkPlanuUncommittedChanges(projectPath) {
-    try {
-        const output = execFileSync('git', ['status', '--porcelain', 'planu/'], {
-            cwd: projectPath,
-            encoding: 'utf-8',
-            timeout: 5_000,
-            stdio: ['pipe', 'pipe', 'pipe'],
-        });
-        return output.trim().length > 0;
-    }
-    catch {
-        return false;
-    }
-}
 function scoreToGrade(score) {
     if (score >= 90) {
         return 'A';

package/dist/types/evidence-index.d.ts

@@ -1,5 +1,6 @@
 export type EvidenceRecordKind = 'scenario' | 'test' | 'contract' | 'manual' | 'changed-file' | 'validation' | 'reviewer';
 export type EvidenceRecordStatus = 'valid' | 'stale' | 'invalid' | 'missing';
+export type EvidencePathField = 'testEvidence' | 'contractEvidence' | 'changedFiles' | 'contractValidation.reportPath';
 export interface EvidenceRecord {
     kind: EvidenceRecordKind;
     value: string;

package/dist/types/feedback.d.ts

@@ -1,5 +1,20 @@
 export type FeedbackType = 'bug' | 'feature' | 'suggestion' | 'dx';
 export type FeedbackStatus = 'pending' | 'triaged' | 'spec_created' | 'implementing' | 'resolved' | 'dismissed';
+export type FeedbackRemoteStatus = 'pending' | 'synced' | 'failed' | 'skipped';
+export interface FeedbackRemoteDelivery {
+    status: FeedbackRemoteStatus;
+    attemptCount: number;
+    lastAttemptAt?: string;
+    lastSyncedAt?: string;
+    lastError?: string;
+    endpoint?: string;
+}
+export interface FeedbackRemoteResult {
+    ok: boolean;
+    status: 'synced' | 'failed' | 'skipped';
+    endpoint?: string;
+    error?: string;
+}
 export interface FeedbackEntry {
     id: string;
     type: FeedbackType;
@@ -20,6 +35,7 @@ export interface FeedbackEntry {
     planuVersion: string;
     tags?: string[];
     votes?: number;
+    remoteDelivery?: FeedbackRemoteDelivery;
 }
 export interface FeedbackFilter {
     type?: FeedbackType;
@@ -39,6 +55,10 @@ export interface FeedbackSummary {
         id: string;
     }[];
 }
+export interface FeedbackRemoteHealth {
+    byRemoteStatus: Record<FeedbackRemoteStatus, number>;
+    retryable: number;
+}
 export interface TriageGroup {
     representative: FeedbackEntry;
     similar: FeedbackEntry[];
@@ -65,7 +85,24 @@ export interface ResolveFeedbackInput {
     prUrl?: string;
     notes?: string;
 }
+export interface SyncFeedbackInput {
+    projectPath?: string;
+    includeSynced?: boolean;
+    limit?: number;
+}
+export interface FeedbackStatusInput {
+    projectPath?: string;
+}
+export interface SyncFeedbackSummary {
+    total: number;
+    synced: number;
+    failed: number;
+    skipped: number;
+    alreadySynced: number;
+    processedIds: string[];
+}
 export interface RemoteFeedbackPayload {
+    id?: string;
     type: string;
     title: string;
     description: string;

package/dist/types/index.d.ts

@@ -5,6 +5,8 @@ export * from './common/index.js';
 export * from './estimation.js';
 export * from './spec/index.js';
 export * from './project.js';
+export * from './project-knowledge-graph.js';
+export * from './structural-memory.js';
 export * from './schema.js';
 export * from './ui.js';
 export * from './analysis.js';

package/dist/types/index.js

@@ -6,6 +6,8 @@ export * from './common/index.js';
 export * from './estimation.js';
 export * from './spec/index.js';
 export * from './project.js';
+export * from './project-knowledge-graph.js';
+export * from './structural-memory.js';
 export * from './schema.js';
 export * from './ui.js';
 export * from './analysis.js';

package/dist/types/project-knowledge-graph.d.ts

@@ -27,6 +27,16 @@ export interface ProjectGraphPolicy {
         maxSnippetChars: number;
         redactPatterns: string[];
     };
+    structuralMemory?: {
+        schemaVersion: string;
+        nodeTypes: string[];
+        edgeTypes: string[];
+        response: {
+            defaultLimit: number;
+            maxLimit: number;
+        };
+        propertySchemas: Record<string, string[]>;
+    };
     toolNamePatterns: string[];
 }
 export interface ProjectGraphEvidencePointer {

package/dist/types/structural-memory.d.ts

@@ -0,0 +1,138 @@
+import type { ProjectGraphEdge, ProjectGraphFreshness, ProjectGraphNode, ProjectKnowledgeGraph } from './project-knowledge-graph.js';
+export type StructuralMemoryStatus = 'fresh' | 'stale' | 'missing' | 'corrupt' | 'partial';
+export type StructuralMemoryNextActionType = 'none' | 'rebuild_graph' | 'broaden_filters' | 'inspect_evidence' | 'run_validate';
+export interface StructuralMemoryNextAction {
+    type: StructuralMemoryNextActionType;
+    message: string;
+}
+export interface StructuralMemoryPagination {
+    total: number;
+    limit: number;
+    offset: number;
+    hasMore: boolean;
+    has_more: boolean;
+    truncated: boolean;
+}
+export interface StructuralMemoryFreshness {
+    status: StructuralMemoryStatus;
+    graphPath: string;
+    generatedAt?: string;
+    changedSources: string[];
+    reason: ProjectGraphFreshness['reason'] | 'partial';
+}
+export interface StructuralMemoryEnvelope {
+    graphVersion?: string;
+    freshness: StructuralMemoryFreshness;
+    pagination: StructuralMemoryPagination;
+    total: number;
+    limit: number;
+    offset: number;
+    hasMore: boolean;
+    has_more: boolean;
+    truncated: boolean;
+    nextAction: StructuralMemoryNextAction;
+}
+export interface StructuralMemoryQueryInput {
+    projectId?: string;
+    projectPath: string;
+    specId?: string;
+    filePath?: string;
+    nodeId?: string;
+    nodeTypes?: string[];
+    limit?: number;
+    offset?: number;
+}
+export interface StructuralMemoryQueryResult extends StructuralMemoryEnvelope {
+    nodes: ProjectGraphNode[];
+    edges: ProjectGraphEdge[];
+    summary: Record<string, number>;
+    sourceHash?: string;
+    sourceHashes?: Record<string, string>;
+}
+export type ArchitectureAspect = 'packages' | 'hotspots' | 'boundaries' | 'releaseRisks' | 'tests' | 'decisions' | 'all';
+export interface ArchitectureSnapshotInput {
+    projectId?: string;
+    projectPath: string;
+    pathPrefix?: string;
+    aspects?: ArchitectureAspect[];
+    limit?: number;
+}
+export interface ArchitectureSnapshotResult extends StructuralMemoryEnvelope {
+    aspects: {
+        packages?: {
+            name: string;
+            fileCount: number;
+        }[];
+        hotspots?: {
+            id: string;
+            label: string;
+            type: string;
+            degree: number;
+        }[];
+        boundaries?: {
+            from: string;
+            to: string;
+            type: string;
+        }[];
+        releaseRisks?: {
+            id: string;
+            label: string;
+            type: string;
+        }[];
+        tests?: {
+            id: string;
+            label: string;
+        }[];
+        decisions?: {
+            id: string;
+            label: string;
+        }[];
+    };
+}
+export interface StructuralMemoryStatusInput {
+    projectId?: string;
+    projectPath: string;
+}
+export interface StructuralMemoryArtifactPolicy {
+    artifactRoot: string;
+    graphPath: string;
+    projectDataDirectory: string;
+    forbiddenPathFragment: 'planu/specs';
+    specDirectoryPolicy: 'spec.md-only';
+    evidenceAndGraphArtifactsRemainOutsideSpecs: true;
+}
+export interface StructuralMemoryStatusResult {
+    freshness: StructuralMemoryFreshness;
+    nextAction: StructuralMemoryNextAction;
+    artifactPolicy: StructuralMemoryArtifactPolicy;
+    graph?: Pick<ProjectKnowledgeGraph, 'graphVersion' | 'generatedAt' | 'sourceHash'> & {
+        counts: ProjectKnowledgeGraph['metadata'];
+        sourceHashCount: number;
+    };
+}
+export interface StructuralChangeImpactInput {
+    projectId?: string;
+    projectPath: string;
+    baseRef?: string;
+    changedFiles?: string[];
+    includeUntracked?: boolean;
+    limit?: number;
+}
+export interface StructuralChangedFile {
+    path: string;
+    status: 'added' | 'modified' | 'deleted' | 'renamed' | 'untracked' | 'unknown';
+}
+export interface StructuralChangeImpactResult extends StructuralMemoryEnvelope {
+    changedFiles: StructuralChangedFile[];
+    affected: {
+        specs: ProjectGraphNode[];
+        criteria: ProjectGraphNode[];
+        tests: ProjectGraphNode[];
+        decisions: ProjectGraphNode[];
+        evidence: ProjectGraphNode[];
+        risks: ProjectGraphNode[];
+        releaseRisk: ProjectGraphNode[];
+    };
+    affectedEdges: ProjectGraphEdge[];
+}
+//# sourceMappingURL=structural-memory.d.ts.map

package/dist/types/structural-memory.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=structural-memory.js.map