@planu/cli 4.9.0 → 4.10.0

package/dist/tools/tool-registry/core-tools.js

@@ -37,6 +37,7 @@ import { handleIdeConfig } from '../ide-config-handler.js';
 import { IdeTargetEnum, IdeConfigScopeEnum } from '../schemas/ide-config.js';
 import { handleReconcileSpecLiving } from '../reconcile-spec-living-handler.js';
 import { handleSecurityReport } from '../security-report-handler.js';
+import { handleFeedbackStatus, handleResolveFeedback, handleSubmitFeedback, handleSyncFeedback, handleTriageFeedback, } from '../feedback-handler.js';
 import { SecurityReportTimeRangeEnum, SecurityReportFormatEnum, } from '../schemas/runtime-security.js';
 import { RenderSpecForProviderInputSchema, handleRenderSpecForProvider, } from '../render-spec-for-provider.js';
 import { handleTriageRequest, TriageRequestInputSchema } from '../triage-request.js';
@@ -750,6 +751,102 @@ const coreToolsRegistry = [
         wrap: 'tracked',
         group: 'core',
     },
+    // ── feedback hub (SPEC-188, SPEC-1100) ───────────────────────────────────
+    {
+        name: 'submit_feedback',
+        description: 'Submit user feedback or a bug report to Planu Feedback Hub. Always persists locally first, then attempts privacy-bounded remote registration with the central feedback intake.',
+        schema: {
+            type: z
+                .enum(['bug', 'feature', 'suggestion', 'dx'])
+                .describe('Feedback type: bug | feature | suggestion | dx'),
+            title: z.string().min(1).max(200).describe('Short feedback title'),
+            description: z.string().min(1).max(5000).describe('Detailed feedback description'),
+            context: z
+                .object({
+                projectPath: z.string().max(4096).optional(),
+                currentFile: z.string().max(4096).optional(),
+                errorMessage: z.string().max(2000).optional(),
+                stack: z.string().max(8000).optional(),
+            })
+                .optional()
+                .describe('Optional local-only context; sensitive path fields are not sent remotely.'),
+        },
+        handler: async (args) => handleSubmitFeedback(args),
+        annotations: {
+            title: 'Submit Feedback',
+            readOnlyHint: false,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+        wrap: 'tracked',
+        group: 'feedback',
+    },
+    {
+        name: 'triage_feedback',
+        description: 'Group pending local feedback by similarity so maintainers can decide whether to create specs, merge duplicates, or dismiss items.',
+        schema: {
+            filter: z
+                .enum(['bug', 'feature', 'suggestion', 'dx'])
+                .optional()
+                .describe('Optional feedback type filter'),
+        },
+        handler: async (args) => Promise.resolve(handleTriageFeedback(args)),
+        annotations: { title: 'Triage Feedback', readOnlyHint: true },
+        wrap: 'tracked',
+        group: 'feedback',
+    },
+    {
+        name: 'resolve_feedback',
+        description: 'Mark a local feedback item as resolved and optionally link it to a Planu spec, PR URL, and resolution notes.',
+        schema: {
+            feedbackId: z.string().min(1).max(50).describe('Local feedback ID, e.g. FB-001'),
+            specId: z.string().max(50).optional().describe('Optional linked Planu spec ID'),
+            prUrl: z.url().optional().describe('Optional pull request URL'),
+            notes: z.string().max(2000).optional().describe('Optional resolution notes'),
+        },
+        handler: async (args) => handleResolveFeedback(args),
+        annotations: { title: 'Resolve Feedback', readOnlyHint: false, destructiveHint: false },
+        wrap: 'tracked',
+        group: 'feedback',
+    },
+    {
+        name: 'sync_feedback',
+        description: 'Retry remote Supabase registration for local feedback entries whose delivery is pending or failed. Does not accept remote row IDs or perform direct SQL/Data API writes.',
+        schema: {
+            projectPath: z.string().max(4096).optional().describe('Absolute path to project root'),
+            includeSynced: z
+                .boolean()
+                .optional()
+                .describe('When true, also reprocess entries already marked synced. Default false.'),
+            limit: z
+                .number()
+                .int()
+                .positive()
+                .max(500)
+                .optional()
+                .describe('Maximum number of local entries to process.'),
+        },
+        handler: async (args) => handleSyncFeedback(args),
+        annotations: {
+            title: 'Sync Feedback',
+            readOnlyHint: false,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+        wrap: 'tracked',
+        group: 'feedback',
+    },
+    {
+        name: 'feedback_status',
+        description: 'Show aggregate local feedback totals and remote delivery health without exposing descriptions, file paths, user identifiers, or secrets.',
+        schema: {
+            projectPath: z.string().max(4096).optional().describe('Absolute path to project root'),
+        },
+        handler: async (args) => Promise.resolve(handleFeedbackStatus(args)),
+        annotations: { title: 'Feedback Status', readOnlyHint: true },
+        wrap: 'tracked',
+        group: 'feedback',
+    },
 ];
 export default coreToolsRegistry;
 //# sourceMappingURL=core-tools.js.map

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

@@ -0,0 +1,6 @@
+import { type NewCodeGateResult } from '../engine/ai-assurance/index.js';
+export declare function runAssuranceGates(projectPath: string): {
+    newCode: NewCodeGateResult;
+};
+export declare function checkPlanuUncommittedChanges(projectPath: string): boolean;
+//# sourceMappingURL=validate-assurance.d.ts.map

package/dist/tools/validate-assurance.js

@@ -0,0 +1,55 @@
+// tools/validate-assurance.ts — Validate assurance and local git helpers.
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { evaluateNewCodeGate } from '../engine/ai-assurance/index.js';
+export 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 [];
+        }
+    });
+}
+export 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;
+    }
+}
+//# sourceMappingURL=validate-assurance.js.map

package/dist/tools/validate-graph-coverage.d.ts

@@ -0,0 +1,8 @@
+import type { GraphCoverageReport } from '../types/project-knowledge-graph.js';
+export declare function buildGraphCoverageReport(args: {
+    projectId: string;
+    projectPath: string;
+    specId: string;
+}): Promise<GraphCoverageReport>;
+export declare function formatGraphCoverageText(report: GraphCoverageReport): string;
+//# sourceMappingURL=validate-graph-coverage.d.ts.map

package/dist/tools/validate-graph-coverage.js

@@ -0,0 +1,30 @@
+// tools/validate-graph-coverage.ts — Graph coverage helpers for validate.
+import { queryProjectGraphSlice } from '../engine/project-graph/index.js';
+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);
+}
+export 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,
+    };
+}
+export function formatGraphCoverageText(report) {
+    return report.gaps.length > 0
+        ? `\nGRAPH     ${String(report.gaps.length)} graph-backed coverage gap(s)`
+        : '';
+}
+//# sourceMappingURL=validate-graph-coverage.js.map

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

@@ -0,0 +1,9 @@
+import type { InteractiveQuestion } from '../types/clarification.js';
+import type { ToolResult } from '../types/index.js';
+export declare function validateStrictLayoutOrError(args: {
+    projectPath: string;
+    specId: string;
+    specPath?: string;
+}): Promise<ToolResult | null>;
+export declare function buildValidateFailureFallback(failedCount: number): InteractiveQuestion;
+//# sourceMappingURL=validate-helpers.d.ts.map

package/dist/tools/validate-helpers.js

@@ -0,0 +1,47 @@
+export 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;
+    }
+}
+export 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' },
+        ],
+    };
+}
+//# sourceMappingURL=validate-helpers.js.map

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

@@ -0,0 +1,3 @@
+import type { LintCheckResult } from '../types/index.js';
+export declare function runLintCheck(projectPath: string, lintCommand: string | null): LintCheckResult;
+//# sourceMappingURL=validate-lint.d.ts.map

package/dist/tools/validate-lint.js

@@ -0,0 +1,67 @@
+import { formatLintFailureDiagnostics, resolveProjectCommandPlan, runProjectCommandPlan, } from './validate-runtime.js';
+/** 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 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;
+}
+export 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)',
+        };
+    }
+    const command = lintCommand ?? 'pnpm lint';
+    const plan = resolveProjectCommandPlan(projectPath, command);
+    try {
+        runProjectCommandPlan(plan, projectPath, 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 \`${plan.executedCommand}\` manually before marking the spec done.`;
+            console.warn(`[Planu] lintCheck timed out: command="${plan.executedCommand}" cwd="${projectPath}" timeoutMs=${String(LINT_CHECK_TIMEOUT_MS)}`);
+            return { passed: true, command, issueCount: 0, output };
+        }
+        const raw = commandOutput(err);
+        const output = formatLintFailureDiagnostics(plan, raw);
+        const issueCount = parseLintIssueCount(raw.trim());
+        console.warn(`[Planu] lintCheck failed: command="${plan.executedCommand}" cwd="${projectPath}" issues=${String(issueCount)}`);
+        return { passed: false, command, issueCount, output };
+    }
+}
+//# sourceMappingURL=validate-lint.js.map

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

@@ -0,0 +1,16 @@
+import type { MinimalImplementationReport } from '../types/minimal-implementation-gate.js';
+export declare function buildMinimalityReport(args: {
+    projectPath: string;
+    specId: string;
+    risk?: string;
+    title?: string;
+    missing: string[];
+    extra: string[];
+    qualityIssues: {
+        file: string;
+        rule: string;
+        message: string;
+        suggestion?: string;
+    }[];
+}): Promise<MinimalImplementationReport | null>;
+//# sourceMappingURL=validate-minimality.d.ts.map

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