@planu/cli 4.8.0 → 4.10.0

package/dist/engine/structural-memory/change-impact.js

@@ -0,0 +1,159 @@
+import { execFile as execFileCb } from 'node:child_process';
+import { promisify } from 'node:util';
+import { clampLimit, loadFreshGraph, nextActionForFreshness, pagination, resolveProjectId, safeRelativeProjectPath, structuralPolicy, } from './helpers.js';
+const execFile = promisify(execFileCb);
+function safeGitRef(ref) {
+    return (/^[A-Za-z0-9][A-Za-z0-9._/@{}:+-]{0,200}$/.test(ref) &&
+        !ref.includes('..') &&
+        !ref.startsWith('-'));
+}
+function statusFromCode(code) {
+    if (code.includes('A')) {
+        return 'added';
+    }
+    if (code.includes('D')) {
+        return 'deleted';
+    }
+    if (code.includes('R')) {
+        return 'renamed';
+    }
+    if (code.includes('?')) {
+        return 'untracked';
+    }
+    if (code.trim().length > 0) {
+        return 'modified';
+    }
+    return 'unknown';
+}
+function parseNameStatus(stdout, projectPath) {
+    return stdout
+        .split('\n')
+        .map((line) => line.trimEnd())
+        .filter((line) => line.length > 0)
+        .flatMap((line) => {
+        const [status, ...paths] = line.split(/\s+/);
+        const path = paths.at(-1);
+        if (!status || !path) {
+            return [];
+        }
+        const safePath = safeRelativeProjectPath(projectPath, path);
+        return safePath === null ? [] : [{ path: safePath, status: statusFromCode(status) }];
+    });
+}
+function parsePorcelain(stdout, projectPath, includeUntracked) {
+    return stdout
+        .split('\n')
+        .map((line) => line.trimEnd())
+        .filter((line) => line.length > 0)
+        .flatMap((line) => {
+        const code = line.slice(0, 2);
+        if (!includeUntracked && code === '??') {
+            return [];
+        }
+        const rawPath = line.slice(3).split(' -> ').at(-1);
+        if (!rawPath) {
+            return [];
+        }
+        const safePath = safeRelativeProjectPath(projectPath, rawPath);
+        return safePath === null ? [] : [{ path: safePath, status: statusFromCode(code) }];
+    });
+}
+async function gitChangedFiles(input) {
+    if (input.changedFiles !== undefined) {
+        return input.changedFiles.flatMap((path) => {
+            const safePath = safeRelativeProjectPath(input.projectPath, path);
+            return safePath === null ? [] : [{ path: safePath, status: 'unknown' }];
+        });
+    }
+    if (input.baseRef !== undefined) {
+        if (!safeGitRef(input.baseRef)) {
+            throw new Error('Unsafe git baseRef for structural change impact.');
+        }
+        const { stdout } = await execFile('git', ['diff', '--name-status', input.baseRef, '--'], {
+            cwd: input.projectPath,
+            maxBuffer: 1024 * 1024,
+        });
+        return parseNameStatus(stdout, input.projectPath);
+    }
+    const { stdout } = await execFile('git', ['status', '--porcelain'], {
+        cwd: input.projectPath,
+        maxBuffer: 1024 * 1024,
+    });
+    return parsePorcelain(stdout, input.projectPath, input.includeUntracked ?? true);
+}
+function uniqueNodes(nodes) {
+    return [...new Map(nodes.map((node) => [node.id, node])).values()];
+}
+function collectAffected(graphNodes, graphEdges, changedFiles) {
+    const changed = new Set(changedFiles.map((file) => file.path));
+    const fileNodeIds = new Set(graphNodes
+        .filter((node) => node.type === 'file' && changed.has(node.label))
+        .map((node) => node.id));
+    const affectedIds = new Set(fileNodeIds);
+    for (let depth = 0; depth < 3; depth += 1) {
+        for (const edge of graphEdges) {
+            if (affectedIds.has(edge.from)) {
+                affectedIds.add(edge.to);
+            }
+            if (affectedIds.has(edge.to)) {
+                affectedIds.add(edge.from);
+            }
+        }
+    }
+    const nodes = graphNodes.filter((node) => affectedIds.has(node.id));
+    const ids = new Set(nodes.map((node) => node.id));
+    const edges = graphEdges.filter((edge) => ids.has(edge.from) && ids.has(edge.to));
+    return { nodes, edges };
+}
+export async function detectStructuralChangeImpact(input) {
+    const policy = await structuralPolicy();
+    const projectId = resolveProjectId(input);
+    const limit = clampLimit(input.limit, policy);
+    const changedFiles = await gitChangedFiles(input);
+    const { graph, freshness } = await loadFreshGraph({
+        projectId,
+        projectPath: input.projectPath,
+        policy,
+    });
+    const page = pagination(changedFiles.length, limit, 0);
+    if (graph === null) {
+        return {
+            freshness,
+            pagination: page,
+            ...page,
+            nextAction: nextActionForFreshness(freshness, true),
+            changedFiles: changedFiles.slice(0, limit),
+            affected: {
+                specs: [],
+                criteria: [],
+                tests: [],
+                decisions: [],
+                evidence: [],
+                risks: [],
+                releaseRisk: [],
+            },
+            affectedEdges: [],
+        };
+    }
+    const affected = collectAffected(graph.nodes, graph.edges, changedFiles);
+    const byType = (types) => uniqueNodes(affected.nodes.filter((node) => types.includes(node.type))).slice(0, limit);
+    return {
+        graphVersion: graph.graphVersion,
+        freshness,
+        pagination: page,
+        ...page,
+        nextAction: nextActionForFreshness(freshness, affected.nodes.length === 0),
+        changedFiles: changedFiles.slice(0, limit),
+        affected: {
+            specs: byType(['spec']),
+            criteria: byType(['criterion']),
+            tests: byType(['test']),
+            decisions: byType(['decision', 'adr']),
+            evidence: byType(['handoff', 'validation', 'validation_evidence', 'contract']),
+            risks: byType(['risk', 'architecture_risk', 'drift']),
+            releaseRisk: byType(['release', 'release_risk']),
+        },
+        affectedEdges: affected.edges.slice(0, policy.query.maxEdges),
+    };
+}
+//# sourceMappingURL=change-impact.js.map

package/dist/engine/structural-memory/contracts.d.ts

@@ -0,0 +1,2 @@
+export type * from '../../types/structural-memory.js';
+//# sourceMappingURL=contracts.d.ts.map

package/dist/engine/structural-memory/contracts.js

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

package/dist/engine/structural-memory/helpers.d.ts

@@ -0,0 +1,28 @@
+import type { ProjectGraphEdge, ProjectGraphFreshness, ProjectGraphNode, ProjectGraphPolicy } from '../../types/project-knowledge-graph.js';
+import { readProjectGraph } from '../project-graph/cache.js';
+import type { StructuralMemoryFreshness, StructuralMemoryNextAction, StructuralMemoryPagination } from './contracts.js';
+export declare function resolveProjectId(input: {
+    projectId?: string;
+    projectPath: string;
+}): string;
+export declare function freshnessStatus(freshness: ProjectGraphFreshness): StructuralMemoryFreshness;
+export declare function nextActionForFreshness(freshness: StructuralMemoryFreshness, empty?: boolean): StructuralMemoryNextAction;
+export declare function pagination(total: number, limit: number, offset: number): StructuralMemoryPagination;
+export declare function clampLimit(limit: number | undefined, policy: ProjectGraphPolicy): number;
+export declare function safeRelativeProjectPath(projectPath: string, candidate: string): string | null;
+export declare function loadFreshGraph(args: {
+    projectId: string;
+    projectPath: string;
+    policy: ProjectGraphPolicy;
+}): Promise<{
+    graph: Awaited<ReturnType<typeof readProjectGraph>>;
+    freshness: StructuralMemoryFreshness;
+}>;
+export declare function summarizeNodes(nodes: ProjectGraphNode[]): Record<string, number>;
+export declare function relatedNodeIds(nodes: ProjectGraphNode[], edges: ProjectGraphEdge[], input: {
+    specId?: string;
+    filePath?: string;
+    nodeId?: string;
+}): Set<string>;
+export declare function structuralPolicy(): Promise<ProjectGraphPolicy>;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/engine/structural-memory/helpers.js

@@ -0,0 +1,122 @@
+import { isAbsolute, normalize, relative, resolve } from 'node:path';
+import { hashProjectPath } from '../../storage/base-store.js';
+import { getProjectGraphFreshness, loadProjectGraphPolicy, readProjectGraph, } from '../project-graph/cache.js';
+export function resolveProjectId(input) {
+    return input.projectId ?? hashProjectPath(input.projectPath);
+}
+export function freshnessStatus(freshness) {
+    const status = freshness.reason === 'missing'
+        ? 'missing'
+        : freshness.reason === 'corrupt'
+            ? 'corrupt'
+            : freshness.stale
+                ? 'stale'
+                : 'fresh';
+    return {
+        status,
+        graphPath: freshness.graphPath,
+        generatedAt: freshness.generatedAt,
+        changedSources: freshness.changedSources,
+        reason: freshness.reason,
+    };
+}
+export function nextActionForFreshness(freshness, empty = false) {
+    if (freshness.status === 'missing' || freshness.status === 'corrupt') {
+        return {
+            type: 'rebuild_graph',
+            message: 'Rebuild the project graph before trusting structural memory results.',
+        };
+    }
+    if (freshness.status === 'stale' || freshness.status === 'partial') {
+        return {
+            type: 'run_validate',
+            message: 'Run validation or rebuild graph context before using this result as gate evidence.',
+        };
+    }
+    if (empty) {
+        return {
+            type: 'broaden_filters',
+            message: 'No structural memory nodes matched; broaden filters or inspect evidence coverage.',
+        };
+    }
+    return { type: 'none', message: 'Structural memory result is ready to use.' };
+}
+export function pagination(total, limit, offset) {
+    const hasMore = offset + limit < total;
+    return {
+        total,
+        limit,
+        offset,
+        hasMore,
+        has_more: hasMore,
+        truncated: hasMore,
+    };
+}
+export function clampLimit(limit, policy) {
+    const defaultLimit = policy.structuralMemory?.response.defaultLimit ?? policy.query.maxNodes;
+    const maxLimit = policy.structuralMemory?.response.maxLimit ?? policy.query.maxNodes;
+    return Math.max(1, Math.min(limit ?? defaultLimit, maxLimit));
+}
+export function safeRelativeProjectPath(projectPath, candidate) {
+    if (candidate.trim().length === 0 || isAbsolute(candidate) || candidate.includes('\0')) {
+        return null;
+    }
+    const normalized = normalize(candidate).replace(/\\/g, '/');
+    if (normalized === '..' || normalized.startsWith('../') || normalized.includes('/../')) {
+        return null;
+    }
+    const root = resolve(projectPath);
+    const absolute = resolve(root, normalized);
+    const rel = relative(root, absolute).replace(/\\/g, '/');
+    if (rel === '..' || rel.startsWith('../') || isAbsolute(rel)) {
+        return null;
+    }
+    return rel;
+}
+export async function loadFreshGraph(args) {
+    const rawFreshness = await getProjectGraphFreshness(args);
+    return {
+        graph: await readProjectGraph(args.projectId, args.policy),
+        freshness: freshnessStatus(rawFreshness),
+    };
+}
+export function summarizeNodes(nodes) {
+    return nodes.reduce((acc, node) => {
+        return { ...acc, [node.type]: (acc[node.type] ?? 0) + 1 };
+    }, {});
+}
+export function relatedNodeIds(nodes, edges, input) {
+    const seeds = new Set();
+    for (const node of nodes) {
+        const specMatch = input.specId !== undefined &&
+            (node.id === `spec:${input.specId}` || node.metadata?.specId === input.specId);
+        const fileMatch = input.filePath !== undefined &&
+            (node.id === `file:${input.filePath}` || node.label === input.filePath);
+        const nodeMatch = input.nodeId !== undefined && node.id === input.nodeId;
+        if (specMatch || fileMatch || nodeMatch) {
+            seeds.add(node.id);
+        }
+    }
+    if (seeds.size === 0 &&
+        input.specId === undefined &&
+        input.filePath === undefined &&
+        input.nodeId === undefined) {
+        for (const node of nodes) {
+            seeds.add(node.id);
+        }
+    }
+    const related = new Set(seeds);
+    for (const edge of edges) {
+        if (seeds.has(edge.from)) {
+            related.add(edge.to);
+        }
+        if (seeds.has(edge.to)) {
+            related.add(edge.from);
+        }
+    }
+    return related;
+}
+export async function structuralPolicy() {
+    return loadProjectGraphPolicy();
+}
+//# sourceMappingURL=helpers.js.map

package/dist/engine/structural-memory/index.d.ts

@@ -0,0 +1,7 @@
+export type * from './contracts.js';
+export { queryStructuralMemory } from './query.js';
+export { detectStructuralChangeImpact } from './change-impact.js';
+export { getArchitectureSnapshot } from './architecture-snapshot.js';
+export { getStructuralMemoryStatus } from './status.js';
+export { createStructuralMemoryArtifactPolicy, isStructuralMemoryArtifactPathAllowed, } from './artifact-policy.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/engine/structural-memory/index.js

@@ -0,0 +1,6 @@
+export { queryStructuralMemory } from './query.js';
+export { detectStructuralChangeImpact } from './change-impact.js';
+export { getArchitectureSnapshot } from './architecture-snapshot.js';
+export { getStructuralMemoryStatus } from './status.js';
+export { createStructuralMemoryArtifactPolicy, isStructuralMemoryArtifactPathAllowed, } from './artifact-policy.js';
+//# sourceMappingURL=index.js.map

package/dist/engine/structural-memory/query.d.ts

@@ -0,0 +1,3 @@
+import type { StructuralMemoryQueryInput, StructuralMemoryQueryResult } from './contracts.js';
+export declare function queryStructuralMemory(input: StructuralMemoryQueryInput): Promise<StructuralMemoryQueryResult>;
+//# sourceMappingURL=query.d.ts.map

package/dist/engine/structural-memory/query.js

@@ -0,0 +1,67 @@
+import { clampLimit, loadFreshGraph, nextActionForFreshness, pagination, relatedNodeIds, resolveProjectId, safeRelativeProjectPath, structuralPolicy, summarizeNodes, } from './helpers.js';
+export async function queryStructuralMemory(input) {
+    const policy = await structuralPolicy();
+    const projectId = resolveProjectId(input);
+    const filePath = input.filePath === undefined
+        ? undefined
+        : safeRelativeProjectPath(input.projectPath, input.filePath);
+    const freshnessGraph = await loadFreshGraph({
+        projectId,
+        projectPath: input.projectPath,
+        policy,
+    });
+    const limit = clampLimit(input.limit, policy);
+    const offset = Math.max(0, input.offset ?? 0);
+    if (input.filePath !== undefined && filePath === null) {
+        const page = pagination(0, limit, offset);
+        return {
+            freshness: freshnessGraph.freshness,
+            pagination: page,
+            ...page,
+            nextAction: {
+                type: 'inspect_evidence',
+                message: 'Rejecting unsafe filePath filter; pass a project-relative path inside the repo.',
+            },
+            nodes: [],
+            edges: [],
+            summary: {},
+        };
+    }
+    const graph = freshnessGraph.graph;
+    if (graph === null) {
+        const page = pagination(0, limit, offset);
+        return {
+            freshness: freshnessGraph.freshness,
+            pagination: page,
+            ...page,
+            nextAction: nextActionForFreshness(freshnessGraph.freshness, true),
+            nodes: [],
+            edges: [],
+            summary: {},
+        };
+    }
+    const ids = relatedNodeIds(graph.nodes, graph.edges, {
+        specId: input.specId,
+        nodeId: input.nodeId,
+        filePath: filePath ?? undefined,
+    });
+    const typeFilter = new Set(input.nodeTypes ?? []);
+    const filteredNodes = graph.nodes.filter((node) => ids.has(node.id) && (typeFilter.size === 0 || typeFilter.has(node.type)));
+    const nodePage = filteredNodes.slice(offset, offset + limit);
+    const nodeIds = new Set(nodePage.map((node) => node.id));
+    const edges = graph.edges.filter((edge) => nodeIds.has(edge.from) && nodeIds.has(edge.to));
+    const page = pagination(filteredNodes.length, limit, offset);
+    return {
+        graphVersion: graph.graphVersion,
+        freshness: freshnessGraph.freshness,
+        pagination: page,
+        ...page,
+        nextAction: nextActionForFreshness(freshnessGraph.freshness, filteredNodes.length === 0),
+        nodes: nodePage,
+        edges,
+        summary: summarizeNodes(nodePage),
+        sourceHash: graph.sourceHash,
+        sourceHashes: graph.sourceHashes,
+    };
+}
+//# sourceMappingURL=query.js.map

package/dist/engine/structural-memory/status.d.ts

@@ -0,0 +1,3 @@
+import type { StructuralMemoryStatusInput, StructuralMemoryStatusResult } from './contracts.js';
+export declare function getStructuralMemoryStatus(input: StructuralMemoryStatusInput): Promise<StructuralMemoryStatusResult>;
+//# sourceMappingURL=status.d.ts.map

package/dist/engine/structural-memory/status.js

@@ -0,0 +1,30 @@
+import { createStructuralMemoryArtifactPolicy, isStructuralMemoryArtifactPathAllowed, } from './artifact-policy.js';
+import { loadFreshGraph, nextActionForFreshness, resolveProjectId, structuralPolicy, } from './helpers.js';
+export async function getStructuralMemoryStatus(input) {
+    const policy = await structuralPolicy();
+    const projectId = resolveProjectId(input);
+    const { graph, freshness } = await loadFreshGraph({
+        projectId,
+        projectPath: input.projectPath,
+        policy,
+    });
+    const artifactPolicy = createStructuralMemoryArtifactPolicy(projectId, policy);
+    if (!isStructuralMemoryArtifactPathAllowed(artifactPolicy.graphPath)) {
+        throw new Error('Structural memory graph artifacts must remain outside planu/specs.');
+    }
+    return {
+        freshness,
+        nextAction: nextActionForFreshness(freshness, graph === null),
+        artifactPolicy,
+        graph: graph === null
+            ? undefined
+            : {
+                graphVersion: graph.graphVersion,
+                generatedAt: graph.generatedAt,
+                sourceHash: graph.sourceHash,
+                counts: graph.metadata,
+                sourceHashCount: Object.keys(graph.sourceHashes).length,
+            },
+    };
+}
+//# sourceMappingURL=status.js.map

package/dist/storage/feedback-remote.d.ts

@@ -1,5 +1,9 @@
-import type { RemoteFeedbackPayload } from '../types/feedback.js';
+import type { FeedbackRemoteResult, RemoteFeedbackPayload } from '../types/feedback.js';
+export declare const DEFAULT_FEEDBACK_API = "https://canusqigtzldstnjddio.supabase.co/functions/v1/license-api/feedback";
 export type { RemoteFeedbackPayload };
+export declare function resolveFeedbackEndpoint(endpoint?: string): string;
+export declare function sanitizeRemoteFeedbackPayload(payload: RemoteFeedbackPayload): RemoteFeedbackPayload;
+export declare function deliverFeedbackRemote(payload: RemoteFeedbackPayload, endpoint?: string): Promise<FeedbackRemoteResult>;
 /**
  * Send feedback to central Supabase store (fire-and-forget).
  * Never throws. Returns true if sent successfully, false otherwise.

package/dist/storage/feedback-remote.js

@@ -1,27 +1,86 @@
 // storage/feedback-remote.ts — Remote feedback relay to Supabase (fire-and-forget)
 // No PII is ever sent: no project paths, no user names, no emails.
-const FEEDBACK_API = 'https://canusqigtzldstnjddio.supabase.co/functions/v1/license-api/feedback';
-/**
- * Send feedback to central Supabase store (fire-and-forget).
- * Never throws. Returns true if sent successfully, false otherwise.
- */
-export async function sendFeedbackRemote(payload) {
+export const DEFAULT_FEEDBACK_API = 'https://canusqigtzldstnjddio.supabase.co/functions/v1/license-api/feedback';
+export function resolveFeedbackEndpoint(endpoint) {
+    return endpoint ?? process.env.PLANU_FEEDBACK_ENDPOINT ?? DEFAULT_FEEDBACK_API;
+}
+function redactSensitiveText(value) {
+    return value
+        .replace(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi, '[redacted-email]')
+        .replace(/(?:\/Users|\/home|\/var|\/tmp|[A-Za-z]:\\)[^\s)'"`]+/g, '[redacted-path]')
+        .replace(/```[\s\S]*?```/g, '[redacted-code-block]')
+        .replace(/\b(?:const|let|var|function|class|import|export)\s+[^\n]+/g, '[redacted-code]');
+}
+export function sanitizeRemoteFeedbackPayload(payload) {
+    return {
+        ...payload,
+        title: redactSensitiveText(payload.title),
+        description: redactSensitiveText(payload.description),
+        ...(payload.stack !== undefined ? { stack: redactSensitiveText(payload.stack) } : {}),
+    };
+}
+export async function deliverFeedbackRemote(payload, endpoint) {
+    const resolvedEndpoint = resolveFeedbackEndpoint(endpoint);
+    let url;
     try {
-        const controller = new AbortController();
-        const timeout = setTimeout(() => {
-            controller.abort();
-        }, 5000); // 5s timeout
-        const res = await fetch(FEEDBACK_API, {
+        url = new URL(resolvedEndpoint);
+    }
+    catch {
+        return {
+            ok: false,
+            status: 'skipped',
+            endpoint: resolvedEndpoint,
+            error: 'Invalid feedback endpoint URL.',
+        };
+    }
+    if (url.protocol !== 'https:' && url.hostname !== 'localhost' && url.hostname !== '127.0.0.1') {
+        return {
+            ok: false,
+            status: 'skipped',
+            endpoint: resolvedEndpoint,
+            error: 'Feedback endpoint must use HTTPS.',
+        };
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => {
+        controller.abort();
+    }, 5000);
+    try {
+        const res = await fetch(resolvedEndpoint, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify(payload),
+            body: JSON.stringify(sanitizeRemoteFeedbackPayload(payload)),
             signal: controller.signal,
         });
-        clearTimeout(timeout);
-        return res.ok;
+        if (res.ok) {
+            return { ok: true, status: 'synced', endpoint: resolvedEndpoint };
+        }
+        return {
+            ok: false,
+            status: 'failed',
+            endpoint: resolvedEndpoint,
+            error: `Remote feedback endpoint returned HTTP ${res.status}.`,
+        };
     }
-    catch {
-        return false; // Network error, timeout, etc. — silently fail
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            status: 'failed',
+            endpoint: resolvedEndpoint,
+            error: message || 'Remote feedback request failed.',
+        };
     }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+/**
+ * Send feedback to central Supabase store (fire-and-forget).
+ * Never throws. Returns true if sent successfully, false otherwise.
+ */
+export async function sendFeedbackRemote(payload) {
+    const result = await deliverFeedbackRemote(payload);
+    return result.ok;
 }
 //# sourceMappingURL=feedback-remote.js.map

package/dist/storage/feedback-store.d.ts

@@ -1,4 +1,4 @@
-import type { FeedbackEntry, FeedbackFilter, FeedbackSummary } from '../types/index.js';
+import type { FeedbackEntry, FeedbackFilter, FeedbackSummary, FeedbackRemoteHealth, SyncFeedbackInput, SyncFeedbackSummary } from '../types/index.js';
 /**
  * Submit a new feedback entry. Auto-generates ID, timestamp, and version.
  */
@@ -19,6 +19,8 @@ export declare function resolveFeedback(dataDir: string, id: string, specId?: st
  * Compute summary statistics across all feedback.
  */
 export declare function getSummary(dataDir: string): FeedbackSummary;
+export declare function getFeedbackRemoteHealth(dataDir: string): FeedbackRemoteHealth;
+export declare function syncFeedbackRemote(dataDir: string, input?: SyncFeedbackInput): Promise<SyncFeedbackSummary>;
 /**
  * Find feedback entries with title similar to the given string.
  * Uses Jaccard word overlap. Threshold defaults to 0.3.