@planu/cli 4.1.0 → 4.1.2

package/dist/tools/workspace-overview.d.ts

@@ -1,4 +0,0 @@
-import type { ToolResult } from '../types/index.js';
-import type { ProjectOverviewInput } from '../types/workspace-overview.js';
-export declare function handleProjectOverview(params: ProjectOverviewInput): Promise<ToolResult>;
-//# sourceMappingURL=workspace-overview.d.ts.map

package/dist/tools/workspace-overview.js

@@ -1,316 +0,0 @@
-// tools/workspace-overview.ts — SPEC-753: project_overview tool
-//
-// Single-call state query: counts, pending, drift, version, cleanup, stale-implementing.
-// Replaces the multi-tool dance (planu_status + list_specs + filesystem reads).
-import { join } from 'node:path';
-import { checkBundledVersionGap } from '../engine/version-detector/bundled-version-checker.js';
-import { checkAndFixBundledVersion } from '../engine/mcp-config/mcp-config-writer.js';
-import { readFile } from 'node:fs/promises';
-import { resolveProjectPath } from '../storage/path-resolver.js';
-import { hashProjectPath } from '../storage/base-store.js';
-import { validateStatusJson } from '../storage/status-store/self-healing.js';
-import { syncVersionField } from '../storage/status-store/version-sync.js';
-import { findStaleImplementing } from '../engine/staleness/stale-implementing.js';
-import { readForceAnalytics } from '../storage/force-analytics-store.js';
-import { PLANU_VERSION } from '../config/version.js';
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-async function getForceUsage(projectId, totalSpecs) {
-    try {
-        const analytics = await readForceAnalytics(projectId);
-        const ratio = totalSpecs > 0 ? analytics.stats.forcedSpecs / totalSpecs : 0;
-        // Simple trend heuristic: compare current ratio to historical ratio stored in stats
-        const historicalRatio = analytics.stats.ratio;
-        let trend = 'stable';
-        if (ratio < historicalRatio - 0.05) {
-            trend = 'improving';
-        }
-        else if (ratio > historicalRatio + 0.05) {
-            trend = 'worsening';
-        }
-        return {
-            forcedSpecs: analytics.stats.forcedSpecs,
-            totalSpecs,
-            ratio: Math.round(ratio * 100) / 100,
-            trend,
-        };
-    }
-    catch {
-        return {
-            forcedSpecs: 0,
-            totalSpecs,
-            ratio: 0,
-            trend: 'stable',
-        };
-    }
-}
-async function getSpecCountsByStatus(projectPath, projectId) {
-    const emptyStatus = {
-        draft: 0,
-        approved: 0,
-        implementing: 0,
-        review: 0,
-        validating: 0,
-        done: 0,
-        discarded: 0,
-    };
-    try {
-        const { specStore } = await import('../storage/index.js');
-        const specs = await specStore.listSpecs(projectId);
-        const byStatus = { ...emptyStatus };
-        for (const spec of specs) {
-            const s = spec.status;
-            if (s in byStatus) {
-                byStatus[s]++;
-            }
-        }
-        const total = specs.length;
-        const pendingTotal = total - byStatus.done - byStatus.discarded;
-        return { byStatus, total, pendingTotal };
-    }
-    catch {
-        // Fall back to reading status.json directly
-    }
-    // Fallback: read status.json
-    const statusPath = join(projectPath, 'planu', 'status.json');
-    try {
-        const raw = await readFile(statusPath, 'utf-8');
-        const parsed = JSON.parse(raw);
-        if (typeof parsed === 'object' && parsed !== null && 'byStatus' in parsed) {
-            const bs = parsed.byStatus;
-            if (typeof bs === 'object' && bs !== null) {
-                const bsRec = bs;
-                const byStatus = {
-                    draft: bsRec.draft ?? 0,
-                    approved: bsRec.approved ?? 0,
-                    implementing: bsRec.implementing ?? 0,
-                    review: bsRec.review ?? 0,
-                    validating: bsRec.validating ?? 0,
-                    done: bsRec.done ?? 0,
-                    discarded: bsRec.discarded ?? 0,
-                };
-                const total = Object.values(bsRec).reduce((sum, v) => sum + v, 0);
-                const pendingTotal = total - byStatus.done - byStatus.discarded;
-                return { byStatus, total, pendingTotal };
-            }
-        }
-    }
-    catch {
-        // ignore
-    }
-    return { byStatus: emptyStatus, total: 0, pendingTotal: 0 };
-}
-async function getTopPending(projectId, topN) {
-    try {
-        const { specStore } = await import('../storage/index.js');
-        const specs = await specStore.listSpecs(projectId);
-        const pending = specs.filter((s) => s.status !== 'done' && s.status !== 'discarded');
-        // Sort by status priority: implementing > review > validating > approved > draft
-        const statusOrder = {
-            implementing: 0,
-            review: 1,
-            validating: 2,
-            approved: 3,
-            draft: 4,
-        };
-        pending.sort((a, b) => {
-            const ao = statusOrder[a.status] ?? 99;
-            const bo = statusOrder[b.status] ?? 99;
-            return ao - bo;
-        });
-        return pending.slice(0, topN).map((s) => ({
-            specId: s.id,
-            status: s.status,
-            title: s.title,
-            daysInStatus: 0, // best-effort; transition-log not queried here for performance
-            hasProgress: false,
-        }));
-    }
-    catch {
-        return [];
-    }
-}
-async function getLastRelease(projectPath) {
-    // Try reading from CHANGELOG.md or session-context.md
-    try {
-        const changelogPath = join(projectPath, 'CHANGELOG.md');
-        const raw = await readFile(changelogPath, 'utf-8');
-        const versionMatch = /^## \[([^\]]+)\].*?(\d{4}-\d{2}-\d{2})?/m.exec(raw);
-        if (versionMatch?.[1]) {
-            return {
-                version: versionMatch[1],
-                publishedAt: versionMatch[2] ?? null,
-                tagSha: null,
-            };
-        }
-    }
-    catch {
-        // ignore
-    }
-    try {
-        const pkgPath = join(projectPath, 'package.json');
-        const raw = await readFile(pkgPath, 'utf-8');
-        const pkg = JSON.parse(raw);
-        if (typeof pkg === 'object' && pkg !== null && 'version' in pkg) {
-            const v = pkg.version;
-            if (typeof v === 'string') {
-                return { version: v, publishedAt: null, tagSha: null };
-            }
-        }
-    }
-    catch {
-        // ignore
-    }
-    return null;
-}
-async function checkStatusJsonHealth(projectPath) {
-    const statusPath = join(projectPath, 'planu', 'status.json');
-    const validation = await validateStatusJson(statusPath);
-    let versionInSync = true;
-    if (validation.ok) {
-        const syncResult = await syncVersionField(statusPath);
-        versionInSync = !syncResult.synced; // synced=true means it WAS out of sync
-    }
-    return { healthy: validation.ok, versionInSync };
-}
-// ---------------------------------------------------------------------------
-// Hint generation
-// ---------------------------------------------------------------------------
-function generateHints(result) {
-    const hints = [];
-    if (!result.drift.statusJsonHealthy) {
-        hints.push('status.json is corrupt — run `reconcile_status_json` to repair it from frontmatters');
-    }
-    if (!result.drift.versionInSync) {
-        hints.push(`status.json version is out of sync with runtime — it will be updated automatically`);
-    }
-    for (const spec of result.staleImplementing) {
-        const days = spec.daysInStatus >= 0 ? `${spec.daysInStatus} days` : 'an unknown number of days';
-        hints.push(`Consider transitioning ${spec.specId} to done — in implementing for ${days}${spec.hasProgress ? ' (has progress.md)' : ' with no progress.md'}`);
-    }
-    if (result.status.byStatus.draft > 10) {
-        hints.push(`${result.status.byStatus.draft} specs in draft — consider approving or discarding stale ones`);
-    }
-    return hints;
-}
-// ---------------------------------------------------------------------------
-// Main handler
-// ---------------------------------------------------------------------------
-export async function handleProjectOverview(params) {
-    const { includeStaleImplementing = true, staleDays = 7, topN = 10 } = params;
-    // Resolve projectPath
-    const { projectPath } = await resolveProjectPath(params.projectPath);
-    const projectId = hashProjectPath(projectPath);
-    // Gather all data in parallel
-    const [statusCounts, health, topPending, lastRelease, staleRaw] = await Promise.all([
-        getSpecCountsByStatus(projectPath, projectId),
-        checkStatusJsonHealth(projectPath),
-        getTopPending(projectId, topN),
-        getLastRelease(projectPath),
-        includeStaleImplementing
-            ? findStaleImplementing({ projectPath, daysThreshold: staleDays })
-            : Promise.resolve([]),
-    ]);
-    // Drift score (best-effort — don't fail the whole call)
-    let planuDriftScore = 0;
-    try {
-        const { computePlanuDriftScore } = await import('../engine/dashboard/drift-score.js');
-        const driftResult = await computePlanuDriftScore(projectPath);
-        planuDriftScore = driftResult.score;
-    }
-    catch {
-        // ignore
-    }
-    const drift = {
-        statusJsonHealthy: health.healthy,
-        versionInSync: health.versionInSync,
-        pendingDriftReviews: 0, // SPEC-748 integration — placeholder
-        planuDriftScore,
-    };
-    const forceUsage = await getForceUsage(projectId, statusCounts.total);
-    const partialResult = {
-        projectId,
-        projectPath,
-        runtime: {
-            planuVersion: PLANU_VERSION,
-            node: process.version,
-        },
-        status: statusCounts,
-        topPending,
-        lastRelease,
-        drift,
-        pendingCleanup: null, // SPEC-751 integration — placeholder
-        staleImplementing: staleRaw,
-        forceUsage,
-    };
-    const hints = generateHints(partialResult);
-    const result = { ...partialResult, hints };
-    // Format as structured text for the LLM
-    const lines = [
-        `# Workspace Overview — ${projectPath.split('/').pop() ?? projectPath}`,
-        ``,
-        `**Runtime:** Planu v${PLANU_VERSION} · Node ${process.version}`,
-        `**Project:** \`${projectId}\` at \`${projectPath}\``,
-        ``,
-        `## Spec Status`,
-        `| Status | Count |`,
-        `|--------|-------|`,
-        ...Object.entries(result.status.byStatus).map(([s, n]) => `| ${s} | ${String(n)} |`),
-        `| **Total** | **${String(result.status.total)}** |`,
-        `| **Pending** | **${String(result.status.pendingTotal)}** |`,
-        ``,
-    ];
-    if (result.topPending.length > 0) {
-        lines.push(`## Top ${String(topN)} Pending Specs`);
-        lines.push(`| Spec | Status | Title |`);
-        lines.push(`|------|--------|-------|`);
-        for (const s of result.topPending) {
-            lines.push(`| ${s.specId} | ${s.status} | ${s.title} |`);
-        }
-        lines.push('');
-    }
-    if (result.staleImplementing.length > 0) {
-        lines.push(`## Stale Implementing (>${String(staleDays)}d)`);
-        for (const s of result.staleImplementing) {
-            const days = s.daysInStatus >= 0 ? `${s.daysInStatus}d` : '?d';
-            lines.push(`- **${s.specId}** — ${days} · progress: ${s.hasProgress ? 'yes' : 'no'}`);
-        }
-        lines.push('');
-    }
-    lines.push(`## Drift & Health`);
-    lines.push(`- status.json: ${result.drift.statusJsonHealthy ? 'healthy' : '⚠️ CORRUPT'}`);
-    lines.push(`- version sync: ${result.drift.versionInSync ? 'in sync' : '⚠️ out of sync'}`);
-    lines.push(`- drift score: ${String(result.drift.planuDriftScore)}`);
-    lines.push('');
-    lines.push(`## Force Usage`);
-    lines.push(`- ${result.forceUsage.forcedSpecs}/${result.forceUsage.totalSpecs} specs bypassed gates (${Math.round(result.forceUsage.ratio * 100)}%) — trend: ${result.forceUsage.trend}`);
-    lines.push('');
-    if (result.lastRelease) {
-        lines.push(`## Last Release: v${result.lastRelease.version}${result.lastRelease.publishedAt ? ` (${result.lastRelease.publishedAt})` : ''}`);
-        lines.push('');
-    }
-    if (hints.length > 0) {
-        lines.push(`## Hints`);
-        for (const h of hints) {
-            lines.push(`- ${h}`);
-        }
-    }
-    // SPEC-756: lazy version check — fire-and-forget, non-blocking
-    checkBundledVersionGap(2000)
-        .then((gap) => {
-        if (gap.gap) {
-            checkAndFixBundledVersion(projectPath, gap.current, gap.latest).catch(() => {
-                /* best-effort — never block project_overview */
-            });
-        }
-    })
-        .catch(() => {
-        /* best-effort */
-    });
-    return {
-        content: [{ type: 'text', text: lines.join('\n') }],
-        structuredContent: result,
-    };
-}
-//# sourceMappingURL=workspace-overview.js.map

package/dist/transports/middleware/index.d.ts

@@ -1,9 +0,0 @@
-export { composeMiddleware } from './compose.js';
-export { withBudget, resetSessionCounters, getSessionCallCount } from './with-budget.js';
-export { withTelemetry, isTelemetryEnabled } from './with-telemetry.js';
-export { withSandbox, requireSandbox, isSandboxRequired, SANDBOX_REQUIRED, } from './with-sandbox.js';
-export { TOOL_OVERRIDES, shouldSkip } from './overrides.js';
-export type { ToolHandler, ToolContext, Middleware } from './types.js';
-export type { ToolOverride } from './overrides.js';
-export type { TelemetryEntry } from './with-telemetry.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/transports/middleware/index.js

@@ -1,7 +0,0 @@
-// transports/middleware/index.ts — Barrel export for middleware chain (SPEC-740)
-export { composeMiddleware } from './compose.js';
-export { withBudget, resetSessionCounters, getSessionCallCount } from './with-budget.js';
-export { withTelemetry, isTelemetryEnabled } from './with-telemetry.js';
-export { withSandbox, requireSandbox, isSandboxRequired, SANDBOX_REQUIRED, } from './with-sandbox.js';
-export { TOOL_OVERRIDES, shouldSkip } from './overrides.js';
-//# sourceMappingURL=index.js.map

package/dist/transports/middleware/with-sandbox.d.ts

@@ -1,21 +0,0 @@
-import type { Middleware } from './types.js';
-/**
- * Flag value indicating a tool requires sandbox isolation.
- */
-export declare const SANDBOX_REQUIRED: "required";
-/**
- * withSandbox middleware: delegates to SPEC-742 sandbox runner when tool requires it.
- * No-op pass-through for tools that don't require sandbox.
- * Logs a warning when sandbox is required but no runner is available (transition period).
- */
-export declare const withSandbox: Middleware;
-/**
- * Register a tool as requiring sandbox isolation.
- * Used by tool registration code (e.g. execute-sdd-flow).
- */
-export declare function requireSandbox(toolName: string): void;
-/**
- * Check if a tool requires sandbox (for testing).
- */
-export declare function isSandboxRequired(toolName: string): boolean;
-//# sourceMappingURL=with-sandbox.d.ts.map

package/dist/transports/middleware/with-sandbox.js

@@ -1,68 +0,0 @@
-// transports/middleware/with-sandbox.ts — Sandbox adapter (SPEC-740)
-// Acts as a thin wiring layer to SPEC-742 sandbox runner.
-// When SPEC-742 is not yet wired, falls back to no-op pass-through.
-/**
- * Flag value indicating a tool requires sandbox isolation.
- */
-export const SANDBOX_REQUIRED = 'required';
-/**
- * Registry of tools that require sandbox isolation.
- * Keyed by tool name. When SPEC-742 lands, this is checked by the middleware.
- */
-const SANDBOX_REQUIRED_TOOLS = new Set(['execute_sdd_flow']);
-/**
- * Tries to import the SPEC-742 sandbox runner.
- * Returns null if not yet implemented (graceful degradation).
- */
-async function tryGetSandboxRunner() {
-    try {
-        // Dynamic import to avoid hard dependency before SPEC-742 lands.
-        // The path is intentionally via variable so tsc does not resolve it statically.
-        const sandboxPath = '../../engine/sandbox/index.js';
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
-        const mod = await import(/* @vite-ignore */ sandboxPath);
-        const fn = mod.runInSandbox;
-        return typeof fn === 'function' ? fn : null;
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * withSandbox middleware: delegates to SPEC-742 sandbox runner when tool requires it.
- * No-op pass-through for tools that don't require sandbox.
- * Logs a warning when sandbox is required but no runner is available (transition period).
- */
-export const withSandbox = (handler) => {
-    return async (input, ctx) => {
-        if (!SANDBOX_REQUIRED_TOOLS.has(ctx.toolName)) {
-            // No sandbox required — pass through
-            return handler(input, ctx);
-        }
-        // Sandbox required — try to get runner from SPEC-742
-        const runner = await tryGetSandboxRunner();
-        if (runner === null) {
-            // SPEC-742 not yet wired — log warning and pass through (transition period)
-            console.warn(`[Planu] Sandbox runner not available for ${ctx.toolName}. ` +
-                'Running without sandbox isolation. Install SPEC-742 to enable.');
-            return handler(input, ctx);
-        }
-        // Delegate to SPEC-742 runner — the handler is still called but command
-        // execution inside it will go through the sandbox runner
-        return handler(input, ctx);
-    };
-};
-/**
- * Register a tool as requiring sandbox isolation.
- * Used by tool registration code (e.g. execute-sdd-flow).
- */
-export function requireSandbox(toolName) {
-    SANDBOX_REQUIRED_TOOLS.add(toolName);
-}
-/**
- * Check if a tool requires sandbox (for testing).
- */
-export function isSandboxRequired(toolName) {
-    return SANDBOX_REQUIRED_TOOLS.has(toolName);
-}
-//# sourceMappingURL=with-sandbox.js.map

package/dist/types/heal.d.ts

@@ -1,18 +0,0 @@
-export type HealTier = 1 | 2 | 3;
-export interface HealFileResult {
-    path: string;
-    tier: HealTier;
-    action: 'auto-fixed' | 'proposal-emitted' | 'skipped';
-    backup?: string;
-    proposalPath?: string;
-    reason?: string;
-}
-export interface HealRunResult {
-    scanned: number;
-    results: HealFileResult[];
-    skipped: {
-        path: string;
-        reason: string;
-    }[];
-}
-//# sourceMappingURL=heal.d.ts.map

package/dist/types/heal.js

@@ -1,3 +0,0 @@
-// types/heal.ts — SPEC-745: Heal policy types
-export {};
-//# sourceMappingURL=heal.js.map