@planu/cli 0.63.7 → 0.64.1

package/dist/engine/spec-decomposer/ownership-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ownership-resolver.js","sourceRoot":"","sources":["../../../src/engine/spec-decomposer/ownership-resolver.ts"],"names":[],"mappings":"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"}

package/dist/engine/spec-observability/index.d.ts

@@ -0,0 +1,4 @@
+export { trackSpecAccess, trackFromArgs, extractSpecIds, extractAcRef } from './tracker.js';
+export { filterByPeriod, aggregateBySpec, buildObservabilityReport } from './metrics.js';
+export type { BuildReportOptions } from '../../types/spec-observability.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/engine/spec-observability/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/engine/spec-observability/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5F,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AACzF,YAAY,EAAE,kBAAkB,EAAE,MAAM,mCAAmC,CAAC"}

package/dist/engine/spec-observability/index.js

@@ -0,0 +1,4 @@
+// engine/spec-observability/index.ts — Barrel export (SPEC-158)
+export { trackSpecAccess, trackFromArgs, extractSpecIds, extractAcRef } from './tracker.js';
+export { filterByPeriod, aggregateBySpec, buildObservabilityReport } from './metrics.js';
+//# sourceMappingURL=index.js.map

package/dist/engine/spec-observability/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/engine/spec-observability/index.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5F,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC"}

package/dist/engine/spec-observability/metrics.d.ts

@@ -0,0 +1,8 @@
+import type { SpecUsageEvent, SpecUsageMetrics, SpecObservabilityReport, Period, BuildReportOptions } from '../../types/index.js';
+export declare function filterByPeriod(events: readonly SpecUsageEvent[], period: Period): SpecUsageEvent[];
+/**
+ * Aggregate a flat event list into per-spec metrics.
+ */
+export declare function aggregateBySpec(events: readonly SpecUsageEvent[]): SpecUsageMetrics[];
+export declare function buildObservabilityReport(opts: BuildReportOptions): SpecObservabilityReport;
+//# sourceMappingURL=metrics.d.ts.map

package/dist/engine/spec-observability/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../../src/engine/spec-observability/metrics.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,cAAc,EACd,gBAAgB,EAChB,uBAAuB,EACvB,MAAM,EACN,kBAAkB,EACnB,MAAM,sBAAsB,CAAC;AAgB9B,wBAAgB,cAAc,CAC5B,MAAM,EAAE,SAAS,cAAc,EAAE,EACjC,MAAM,EAAE,MAAM,GACb,cAAc,EAAE,CAGlB;AAMD;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,cAAc,EAAE,GAAG,gBAAgB,EAAE,CAmDrF;AAmCD,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,kBAAkB,GAAG,uBAAuB,CA0B1F"}

package/dist/engine/spec-observability/metrics.js

@@ -0,0 +1,116 @@
+// engine/spec-observability/metrics.ts — Aggregate usage data (SPEC-158)
+// Computes hot specs, cold specs, tool matrix, and hot ACs from raw events.
+function periodCutoff(period) {
+    const now = Date.now();
+    switch (period) {
+        case 'day':
+            return now - 24 * 60 * 60 * 1000;
+        case 'week':
+            return now - 7 * 24 * 60 * 60 * 1000;
+        case 'month':
+            return now - 30 * 24 * 60 * 60 * 1000;
+        case 'all':
+            return 0;
+    }
+}
+export function filterByPeriod(events, period) {
+    const cutoff = periodCutoff(period);
+    return events.filter((e) => new Date(e.timestamp).getTime() >= cutoff);
+}
+// ---------------------------------------------------------------------------
+// Per-spec aggregation
+// ---------------------------------------------------------------------------
+/**
+ * Aggregate a flat event list into per-spec metrics.
+ */
+export function aggregateBySpec(events) {
+    const bySpec = new Map();
+    for (const event of events) {
+        const existing = bySpec.get(event.specId) ?? [];
+        existing.push(event);
+        bySpec.set(event.specId, existing);
+    }
+    const results = [];
+    for (const [specId, specEvents] of bySpec.entries()) {
+        const toolMatrix = {};
+        const acCounts = {};
+        const toolsSet = new Set();
+        let firstAccess = specEvents[0]?.timestamp ?? '';
+        let lastAccess = specEvents[0]?.timestamp ?? '';
+        for (const e of specEvents) {
+            toolMatrix[e.toolName] = (toolMatrix[e.toolName] ?? 0) + 1;
+            toolsSet.add(e.toolName);
+            if (e.acRef) {
+                acCounts[e.acRef] = (acCounts[e.acRef] ?? 0) + 1;
+            }
+            if (e.timestamp < firstAccess) {
+                firstAccess = e.timestamp;
+            }
+            if (e.timestamp > lastAccess) {
+                lastAccess = e.timestamp;
+            }
+        }
+        const hotAcs = Object.entries(acCounts)
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, 5)
+            .map(([acRef, count]) => ({ acRef, count }));
+        results.push({
+            specId,
+            totalAccesses: specEvents.length,
+            toolsUsed: [...toolsSet],
+            toolMatrix,
+            hotAcs,
+            firstAccessAt: firstAccess,
+            lastAccessAt: lastAccess,
+        });
+    }
+    return results.sort((a, b) => b.totalAccesses - a.totalAccesses);
+}
+// ---------------------------------------------------------------------------
+// Top tools
+// ---------------------------------------------------------------------------
+function computeTopTools(events) {
+    const counts = {};
+    for (const e of events) {
+        counts[e.toolName] = (counts[e.toolName] ?? 0) + 1;
+    }
+    return Object.entries(counts)
+        .sort((a, b) => b[1] - a[1])
+        .map(([toolName, count]) => ({ toolName, count }));
+}
+// ---------------------------------------------------------------------------
+// Cold spec detection
+// ---------------------------------------------------------------------------
+/**
+ * Identify spec IDs that are known but had zero accesses in the period.
+ * `allKnownSpecIds` comes from the spec store (approved/implementing specs).
+ */
+function computeColdSpecs(accessedSpecIds, allKnownSpecIds) {
+    return allKnownSpecIds.filter((id) => !accessedSpecIds.has(id)).sort();
+}
+// ---------------------------------------------------------------------------
+// Full report builder
+// ---------------------------------------------------------------------------
+export function buildObservabilityReport(opts) {
+    const { projectId, period, events, allKnownSpecIds = [], filterSpecId } = opts;
+    const periodEvents = filterByPeriod(events, period);
+    const scopedEvents = filterSpecId !== undefined
+        ? periodEvents.filter((e) => e.specId === filterSpecId.toUpperCase())
+        : periodEvents;
+    const specMetrics = aggregateBySpec(scopedEvents);
+    const accessedIds = new Set(specMetrics.map((m) => m.specId));
+    const coldSpecs = filterSpecId !== undefined ? [] : computeColdSpecs(accessedIds, allKnownSpecIds);
+    const topTools = computeTopTools(scopedEvents);
+    const hotSpecs = specMetrics.slice(0, 10);
+    return {
+        projectId,
+        period,
+        generatedAt: new Date().toISOString(),
+        totalEvents: scopedEvents.length,
+        hotSpecs,
+        coldSpecs,
+        specMetrics,
+        topTools,
+    };
+}
+//# sourceMappingURL=metrics.js.map

package/dist/engine/spec-observability/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../../src/engine/spec-observability/metrics.ts"],"names":[],"mappings":"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"}

package/dist/engine/spec-observability/tracker.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Extract all SPEC-NNN identifiers mentioned in a string.
+ * Returns an empty array when none found.
+ */
+export declare function extractSpecIds(text: string): string[];
+/**
+ * Extract an AC reference like "AC-3" or "AC3" from a string.
+ * Returns the first match or undefined.
+ */
+export declare function extractAcRef(text: string): string | undefined;
+/**
+ * Record that `toolName` accessed `specId` (and optionally `acRef`).
+ * Fire-and-forget — errors are suppressed to avoid disrupting the caller.
+ */
+export declare function trackSpecAccess(projectId: string, toolName: string, specId: string, acRef?: string): void;
+/**
+ * Inspect a tool call's args object and record usage events for any SPEC-NNN
+ * identifiers found in string fields. Designed to be called from safe-handler
+ * or tool wrappers without any performance impact.
+ */
+export declare function trackFromArgs(projectId: string, toolName: string, args: unknown): void;
+//# sourceMappingURL=tracker.d.ts.map

package/dist/engine/spec-observability/tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracker.d.ts","sourceRoot":"","sources":["../../../src/engine/spec-observability/tracker.ts"],"names":[],"mappings":"AAYA;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAOrD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAG7D;AAMD;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,KAAK,CAAC,EAAE,MAAM,GACb,IAAI,CAWN;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CA4BtF"}

package/dist/engine/spec-observability/tracker.js

@@ -0,0 +1,77 @@
+// engine/spec-observability/tracker.ts — SpecUsageTracker (SPEC-158)
+// Records spec access events fire-and-forget — zero latency impact on callers.
+import { recordSpecAccess } from '../../storage/spec-observability-store.js';
+// ---------------------------------------------------------------------------
+// Spec ID extraction helpers
+// ---------------------------------------------------------------------------
+const SPEC_ID_PATTERN = /\bSPEC-\d+\b/gi;
+/**
+ * Extract all SPEC-NNN identifiers mentioned in a string.
+ * Returns an empty array when none found.
+ */
+export function extractSpecIds(text) {
+    const matches = text.match(SPEC_ID_PATTERN);
+    if (!matches) {
+        return [];
+    }
+    // Normalise to uppercase and deduplicate
+    return [...new Set(matches.map((m) => m.toUpperCase()))];
+}
+/**
+ * Extract an AC reference like "AC-3" or "AC3" from a string.
+ * Returns the first match or undefined.
+ */
+export function extractAcRef(text) {
+    const match = /\bAC[-\s]?(\d+)\b/i.exec(text);
+    return match ? `AC-${match[1]}` : undefined;
+}
+// ---------------------------------------------------------------------------
+// Public tracker API
+// ---------------------------------------------------------------------------
+/**
+ * Record that `toolName` accessed `specId` (and optionally `acRef`).
+ * Fire-and-forget — errors are suppressed to avoid disrupting the caller.
+ */
+export function trackSpecAccess(projectId, toolName, specId, acRef) {
+    const event = {
+        specId: specId.toUpperCase(),
+        toolName,
+        timestamp: new Date().toISOString(),
+        ...(acRef !== undefined ? { acRef } : {}),
+    };
+    recordSpecAccess(projectId, event).catch((err) => {
+        console.error('[Planu] spec-observability: failed to record event', err);
+    });
+}
+/**
+ * Inspect a tool call's args object and record usage events for any SPEC-NNN
+ * identifiers found in string fields. Designed to be called from safe-handler
+ * or tool wrappers without any performance impact.
+ */
+export function trackFromArgs(projectId, toolName, args) {
+    if (args === null || typeof args !== 'object') {
+        return;
+    }
+    const record = args;
+    // Fast-path: if specId is directly provided
+    if (typeof record.specId === 'string' && record.specId.length > 0) {
+        const specId = record.specId.toUpperCase();
+        const acRef = typeof record.acRef === 'string' ? record.acRef : undefined;
+        trackSpecAccess(projectId, toolName, specId, acRef);
+        return;
+    }
+    // Fallback: scan string values for SPEC-NNN patterns
+    for (const value of Object.values(record)) {
+        if (typeof value !== 'string') {
+            continue;
+        }
+        const ids = extractSpecIds(value);
+        for (const id of ids) {
+            trackSpecAccess(projectId, toolName, id);
+        }
+        if (ids.length > 0) {
+            return;
+        } // Only scan until we find at least one match
+    }
+}
+//# sourceMappingURL=tracker.js.map

package/dist/engine/spec-observability/tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracker.js","sourceRoot":"","sources":["../../../src/engine/spec-observability/tracker.ts"],"names":[],"mappings":"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"}

package/dist/engine/spec-reader.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Attempt to read the content of a spec file from disk.
+ * Returns null when specPath is undefined, the file does not exist, or a read
+ * error occurs. Callers should substitute a placeholder when null is returned.
+ */
+export declare function readSpecContent(specPath: string | undefined): Promise<string | null>;
+//# sourceMappingURL=spec-reader.d.ts.map

package/dist/engine/spec-reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-reader.d.ts","sourceRoot":"","sources":["../../src/engine/spec-reader.ts"],"names":[],"mappings":"AAKA;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAY1F"}

package/dist/engine/spec-reader.js

@@ -0,0 +1,23 @@
+// engine/spec-reader.ts — Shared helper for reading spec file content from disk
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+/**
+ * Attempt to read the content of a spec file from disk.
+ * Returns null when specPath is undefined, the file does not exist, or a read
+ * error occurs. Callers should substitute a placeholder when null is returned.
+ */
+export async function readSpecContent(specPath) {
+    if (specPath === undefined) {
+        return null;
+    }
+    try {
+        if (existsSync(specPath)) {
+            return await readFile(specPath, 'utf-8');
+        }
+    }
+    catch {
+        // ignore filesystem errors — callers handle null
+    }
+    return null;
+}
+//# sourceMappingURL=spec-reader.js.map

package/dist/engine/spec-reader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-reader.js","sourceRoot":"","sources":["../../src/engine/spec-reader.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAEhF,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,QAA4B;IAChE,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC;QACH,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YACzB,OAAO,MAAM,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC3C,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,iDAAiD;IACnD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/engine/spec-repair.d.ts

@@ -0,0 +1,10 @@
+import type { RepairResult } from '../types/index.js';
+/**
+ * Detect and optionally fix common spec problems.
+ *
+ * @param specContent - Raw markdown content of the spec.md file.
+ * @param dryRun - When true, detects issues but does not apply fixes.
+ * @returns RepairResult with all detected fixes and (if !dryRun) repaired content.
+ */
+export declare function repairSpec(specContent: string, dryRun?: boolean): RepairResult;
+//# sourceMappingURL=spec-repair.d.ts.map

package/dist/engine/spec-repair.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-repair.d.ts","sourceRoot":"","sources":["../../src/engine/spec-repair.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAa,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAiZjE;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,UAAQ,GAAG,YAAY,CA2C5E"}