@planu/cli 4.13.0 → 5.0.0

package/dist/tools/create-spec/post-creation.js

@@ -1,19 +1,15 @@
-// SPEC-597-EXEMPT: canonical mapping (npm-package↔framework, keyword catalogue)
-// — must enumerate framework names by design; no detection logic to migrate.
-// tools/create-spec/post-creation.ts — Git setup + contradiction detection + post-creation suggestions.
-// Extracted from create-spec.ts to keep file sizes within limits.
+import { technologyValue } from '../../engine/technology-registry.js';
 import { specStore } from '../../storage/index.js';
 import { detectContradictions } from '../../engine/contradiction-detector.js';
 import { detectCiCd } from '../../engine/detectors/cicd-detector.js';
 import { tryAutoSetupGit } from '../create-spec-helpers.js';
 import { emitAutopilotEvent } from '../../engine/autopilot/event-bus.js';
 import { incrementSpecCount } from '../../engine/autopilot/state-updater.js';
-import { writeFile, mkdir } from 'node:fs/promises';
-import { join, dirname } from 'node:path';
+import { join } from 'node:path';
 import { hashProjectPath, projectDataDir } from '../../storage/base-store.js';
 import { appendAutopilotLogEntry } from '../../storage/autopilot-log-store.js';
 import { analyzeContextPreflight, buildTokenWasteReport, loadTokenWastePolicy, recommendRelevantTools, toolsFromPolicyGroups, } from '../../engine/token-optimizer/index.js';
-import { queryProjectGraphSlice } from '../../engine/project-graph/index.js';
+import { atomicWriteFile } from '../../engine/safety/atomic-write-file.js';
 const ASYNC_ANALYSIS_HOOK = 'create-spec-async-analysis';
 export function getAsyncAnalysisPath(projectPath, specId) {
     const projectId = hashProjectPath(projectPath);
@@ -25,21 +21,15 @@ export async function buildInitialTokenWasteMetadata(specId, projectPath, descri
         if (!policy.enabled) {
             return null;
         }
-        const graphSlice = await queryProjectGraphSlice({ projectPath, specId }).catch(() => null);
-        const graphCandidates = graphSlice?.nodes
-            .filter((node) => node.type === 'file' || node.type === 'test')
-            .slice(0, 12)
-            .map((node) => ({
-            path: node.label,
-            reason: 'Related by Project Knowledge Graph compact slice.',
-        })) ?? [];
         const context = analyzeContextPreflight({
             action: 'create_spec',
             policy,
-            candidates: [
-                ...graphCandidates,
-                { path: 'planu/specs', reason: 'New spec workspace metadata.' },
-            ],
+            // A just-created spec cannot exist in the previous graph snapshot. Asking
+            // for a slice by its new ID therefore produced no candidates while forcing
+            // a full graph freshness scan/rebuild after every mutation. Graph refresh
+            // belongs to the durable post-commit worker; the acknowledgement metadata
+            // starts with the canonical spec workspace only.
+            candidates: [{ path: 'planu/specs', reason: 'New spec workspace metadata.' }],
             spec: { id: specId },
         });
         const tools = recommendRelevantTools({
@@ -156,7 +146,13 @@ function hasAffirmedPattern(description, pattern) {
     });
 }
 // === Serverless platform detection ===
-const SERVERLESS_PLATFORMS = ['vercel', 'netlify', 'lambda', 'cloudflare-workers', 'deno-deploy'];
+const SERVERLESS_PLATFORMS = [
+    technologyValue('technology-vercel-9d3508'),
+    technologyValue('technology-netlify-58465a'),
+    'lambda',
+    'cloudflare-workers',
+    'deno-deploy',
+];
 function isServerlessKnowledge(knowledge) {
     if (!knowledge) {
         return false;
@@ -235,41 +231,47 @@ export function formatPostCreationSuggestion(suggestion) {
  * Writes results to Planu's external project data dir and appends an
  * autopilot-log entry on completion. Never throws — fully best-effort.
  */
-export function runAutopilotAsync(specId, projectPath, _description) {
+export async function runAutopilotAnalysis(specId, projectPath, description) {
     const projectId = hashProjectPath(projectPath);
     const start = Date.now();
-    void (async () => {
-        try {
-            const analysisResult = {
-                specId,
-                completedAt: new Date().toISOString(),
-                pendingAnalysis: false,
-                tokenWasteAutopilot: await buildInitialTokenWasteMetadata(specId, projectPath, _description),
-            };
-            const analysisPath = getAsyncAnalysisPath(projectPath, specId);
-            await mkdir(dirname(analysisPath), { recursive: true });
-            await writeFile(analysisPath, JSON.stringify(analysisResult, null, 2), 'utf-8');
-            await appendAutopilotLogEntry(projectId, {
-                specId,
-                hookName: ASYNC_ANALYSIS_HOOK,
-                result: 'pass',
-                timestamp: new Date().toISOString(),
-                durationMs: Date.now() - start,
-            });
-        }
-        catch (err) {
-            const error = err instanceof Error ? err.message : String(err);
-            await appendAutopilotLogEntry(projectId, {
-                specId,
-                hookName: ASYNC_ANALYSIS_HOOK,
-                result: 'fail',
-                error,
-                timestamp: new Date().toISOString(),
-                durationMs: Date.now() - start,
-            }).catch(() => {
-                /* double best-effort */
-            });
-        }
-    })();
+    try {
+        const analysisResult = {
+            specId,
+            completedAt: new Date().toISOString(),
+            pendingAnalysis: false,
+            tokenWasteAutopilot: await buildInitialTokenWasteMetadata(specId, projectPath, description),
+        };
+        const analysisPath = getAsyncAnalysisPath(projectPath, specId);
+        await atomicWriteFile(analysisPath, JSON.stringify(analysisResult, null, 2), {
+            encoding: 'utf-8',
+        });
+        await appendAutopilotLogEntry(projectId, {
+            specId,
+            hookName: ASYNC_ANALYSIS_HOOK,
+            result: 'pass',
+            timestamp: new Date().toISOString(),
+            durationMs: Date.now() - start,
+        });
+    }
+    catch (err) {
+        const error = err instanceof Error ? err.message : String(err);
+        await appendAutopilotLogEntry(projectId, {
+            specId,
+            hookName: ASYNC_ANALYSIS_HOOK,
+            result: 'fail',
+            error,
+            timestamp: new Date().toISOString(),
+            durationMs: Date.now() - start,
+        }).catch(() => {
+            /* double best-effort */
+        });
+        throw err;
+    }
+}
+export function runAutopilotAsync(specId, projectPath, description) {
+    void runAutopilotAnalysis(specId, projectPath, description).catch(() => {
+        // The durable outbox consumer uses the awaited entry point above. This wrapper
+        // remains for callers that have not yet migrated and always observes rejection.
+    });
 }
 //# sourceMappingURL=post-creation.js.map

package/dist/tools/create-spec/relevance-scorer.d.ts

@@ -14,5 +14,5 @@ export declare function scoreFile(filePath: string, keywords: Set<string>): Prom
  * Scans `src/**\/\*.ts` and `tests/**\/\*.ts` under projectPath,
  * scores each, drops score=0 entries, returns top-`limit` by descending score.
  */
-export declare function findRelevantFiles(projectPath: string, keywords: Set<string>, limit?: number): Promise<string[]>;
+export declare function findRelevantFiles(projectPath: string, keywords: Set<string>, limit?: number, signal?: AbortSignal): Promise<string[]>;
 //# sourceMappingURL=relevance-scorer.d.ts.map

package/dist/tools/create-spec/relevance-scorer.js

@@ -4,6 +4,9 @@
 import { readFile } from 'node:fs/promises';
 import { glob } from 'glob';
 import { join } from 'node:path';
+import { isNativeActive } from '../../engine/core-bridge.js';
+import { runNativeWorkerOperation } from '../../engine/execution/native-worker-runtime.js';
+import { hashProjectPath } from '../../storage/base-store.js';
 /** Stop words to exclude from keyword extraction. */
 const STOP_WORDS = new Set([
     // English stop words
@@ -133,10 +136,23 @@ export async function scoreFile(filePath, keywords) {
  * Scans `src/**\/\*.ts` and `tests/**\/\*.ts` under projectPath,
  * scores each, drops score=0 entries, returns top-`limit` by descending score.
  */
-export async function findRelevantFiles(projectPath, keywords, limit = 10) {
+export async function findRelevantFiles(projectPath, keywords, limit = 10, signal) {
     if (keywords.size === 0) {
         return [];
     }
+    if (isNativeActive()) {
+        const result = await runNativeWorkerOperation({
+            projectId: hashProjectPath(projectPath),
+            operation: 'find-relevant-files',
+            payload: { rootPath: projectPath, keywords: [...keywords], limit },
+            deadlineAt: Date.now() + 5_000,
+            signal,
+        });
+        if (!Array.isArray(result) || !result.every((filePath) => typeof filePath === 'string')) {
+            throw new Error('[Planu] Native relevance worker returned an invalid payload');
+        }
+        return result;
+    }
     const patterns = [join(projectPath, 'src/**/*.ts'), join(projectPath, 'tests/**/*.ts')];
     const candidates = [];
     for (const pattern of patterns) {

package/dist/tools/create-spec/spec-builder.js

@@ -2,8 +2,6 @@
 // tools/create-spec/spec-builder.ts — Builds the Spec object and estimation (SPEC-461: lean format).
 // Extracted from create-spec.ts to keep file sizes within limits.
 import { hashProjectPath, knowledgeStore, specStore, globalStore } from '../../storage/index.js';
-import { getCurrentTier } from '../license-gate.js';
-import { checkLimits } from '../../engine/license-validator.js';
 import { inferDifficulty, calculateEstimation } from '../../engine/estimator.js';
 import { analyzeSplit, formatSplitSuggestion } from '../../engine/spec-splitter.js';
 import { isLegacyLocation, getSpecFileNames } from '../../engine/planu-config-writer.js';
@@ -25,15 +23,6 @@ export async function buildSpecContext(params) {
     const projectId = hashProjectPath(projectPath);
     const knowledge = await knowledgeStore.getKnowledge(projectId);
     const existingSpecs = await specStore.listSpecs(projectId);
-    // License: check active spec limit (exclude completed specs)
-    const activeSpecs = existingSpecs.filter((s) => s.status !== 'done' && s.status !== 'discarded');
-    const tier = await getCurrentTier();
-    const specLimit = checkLimits(tier, activeSpecs.length, 'maxActiveSpecs');
-    /* v8 ignore start -- license limit requires paid tier test env */
-    if (!specLimit.allowed) {
-        return { ok: false, errorMessage: specLimit.message };
-    }
-    /* v8 ignore stop */
     // Generate spec ID: combine store IDs + filesystem IDs for global max
     const fsSpecIds = await scanFilesystemSpecIds(projectPath);
     const allSpecs = [...existingSpecs, ...fsSpecIds.map((id) => ({ id }))];
@@ -51,17 +40,6 @@ export async function buildSpecContext(params) {
         : difficulty >= 3 || scope === 'cross-module'
             ? 'medium'
             : 'low';
-    // SPEC-697: Build agent team plan from spec tags (best-effort, fire-and-forget data)
-    const agentTeamPlanResult = await import('../../engine/agent-team-planner/index.js')
-        .then(({ buildAgentTeamPlan }) => buildAgentTeamPlan({
-        specId,
-        specTitle: title,
-        specDescription: description,
-        projectPath,
-        stackSignals: tags,
-        specScope: scope,
-    }))
-        .catch(() => null);
     // Build spec location with naming convention detection
     const specLocation = knowledge?.specLocation ?? 'planu/specs';
     const naming = isLegacyLocation(specLocation) ? 'legacy' : 'modern';
@@ -143,7 +121,8 @@ export async function buildSpecContext(params) {
             legalCriteria: [],
             mcpLayerSection: null,
             docCriteria: [],
-            agentTeamPlan: agentTeamPlanResult,
+            // Team planning is optional post-commit work and must never delay spec persistence.
+            agentTeamPlan: null,
         },
     };
 }

package/dist/tools/create-spec/spec-created-outbox-consumer.d.ts

@@ -0,0 +1,14 @@
+import { RuntimeDatabase } from '../../storage/runtime-db.js';
+import { type OutboxDeliveryContext, type SpecCreatedTaskHandlers } from '../../types/outbox-worker.js';
+export { SPEC_CREATED_POST_COMMIT_TASKS } from '../../types/outbox-worker.js';
+export type { SpecCreatedTaskHandlers } from '../../types/outbox-worker.js';
+export declare const DEFAULT_SPEC_CREATED_TASK_HANDLERS: SpecCreatedTaskHandlers;
+export declare class SpecCreatedOutboxConsumer {
+    private readonly database;
+    private readonly handlers;
+    constructor(database: RuntimeDatabase, handlers?: SpecCreatedTaskHandlers);
+    deliver(context: OutboxDeliveryContext): Promise<void>;
+}
+export declare function drainSpecCreatedOutbox(databasePath?: string): Promise<void>;
+export declare function startSpecCreatedOutboxConsumer(): Promise<void>;
+//# sourceMappingURL=spec-created-outbox-consumer.d.ts.map

package/dist/tools/create-spec/spec-created-outbox-consumer.js

@@ -0,0 +1,176 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { RuntimeDatabase } from '../../storage/runtime-db.js';
+import { resolveStorageLayout } from '../../storage/storage-layout.js';
+import { specStore } from '../../storage/index.js';
+import { runAutopilotAnalysis, setupGitBranch } from './post-creation.js';
+import { SPEC_CREATED_POST_COMMIT_TASKS, } from '../../types/outbox-worker.js';
+import { TransactionalOutboxWorker } from '../../engine/execution/outbox-worker.js';
+export { SPEC_CREATED_POST_COMMIT_TASKS } from '../../types/outbox-worker.js';
+const RESPONSE_ONLY_REASON = 'Advisory task is intentionally terminal because it has no durable post-commit side effect.';
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function parsePayload(context) {
+    if (context.topic !== 'spec.created' || !isObject(context.payload)) {
+        throw new Error(`[Planu] Unsupported outbox topic: ${context.topic}`);
+    }
+    const envelope = context.payload;
+    if (envelope.schemaVersion !== 1 ||
+        envelope.operation !== 'create_spec' ||
+        typeof envelope.idempotencyKey !== 'string' ||
+        !isObject(envelope.body)) {
+        throw new Error('[Planu] Invalid spec.created outbox envelope');
+    }
+    const payload = envelope.body;
+    const tasks = payload.postCommitTasks;
+    if (payload.schemaVersion !== 1 ||
+        typeof payload.specId !== 'string' ||
+        typeof payload.projectId !== 'string' ||
+        typeof payload.projectPath !== 'string' ||
+        !Array.isArray(tasks) ||
+        tasks.some((task) => typeof task !== 'string' ||
+            !SPEC_CREATED_POST_COMMIT_TASKS.includes(task))) {
+        throw new Error('[Planu] Invalid spec.created outbox payload');
+    }
+    return payload;
+}
+function parseReceipt(value) {
+    if (!isObject(value)) {
+        return undefined;
+    }
+    if (value.schemaVersion !== 1 ||
+        (value.status !== 'completed' && value.status !== 'skipped') ||
+        value.attempts !== 1 ||
+        typeof value.completedAt !== 'string') {
+        throw new Error('[Planu] Invalid spec.created task receipt');
+    }
+    return value;
+}
+function receiptKey(deliveryKey, task) {
+    const deliveryDigest = createHash('sha256').update(deliveryKey).digest('hex').slice(0, 24);
+    return `spec-created-task:${deliveryDigest}:${task}`;
+}
+function responseOnlyHandler() {
+    return () => Promise.resolve({ status: 'skipped', reason: RESPONSE_ONLY_REASON });
+}
+export const DEFAULT_SPEC_CREATED_TASK_HANDLERS = {
+    'git-setup': async ({ payload }) => {
+        const result = await setupGitBranch(payload.projectId, payload.specId);
+        return result
+            ? { status: 'completed' }
+            : { status: 'skipped', reason: 'Git auto-setup is not applicable to this repository.' };
+    },
+    analysis: async ({ payload }) => {
+        const spec = await specStore.getSpec(payload.projectId, payload.specId);
+        if (!spec) {
+            throw new Error(`[Planu] Spec ${payload.specId} was not found`);
+        }
+        const description = await readFile(spec.specPath, 'utf8').catch(() => spec.title);
+        await runAutopilotAnalysis(payload.specId, payload.projectPath, description);
+    },
+    'quality-score': responseOnlyHandler(),
+    'duplicate-detection': responseOnlyHandler(),
+    'complexity-advice': responseOnlyHandler(),
+    'prior-decisions': responseOnlyHandler(),
+    suggestions: responseOnlyHandler(),
+    'challenge-readiness': responseOnlyHandler(),
+};
+export class SpecCreatedOutboxConsumer {
+    database;
+    handlers;
+    constructor(database, handlers = DEFAULT_SPEC_CREATED_TASK_HANDLERS) {
+        this.database = database;
+        this.handlers = handlers;
+    }
+    async deliver(context) {
+        const payload = parsePayload(context);
+        const uniqueTasks = [...new Set(payload.postCommitTasks)];
+        for (const task of uniqueTasks) {
+            const key = receiptKey(context.deliveryKey, task);
+            const existing = parseReceipt(this.database.getRecord(payload.projectId, 'default', 'mutation', key)?.value);
+            if (existing) {
+                continue;
+            }
+            try {
+                const outcome = await this.handlers[task]({ deliveryKey: context.deliveryKey, payload });
+                const now = new Date().toISOString();
+                const receipt = {
+                    schemaVersion: 1,
+                    status: outcome?.status ?? 'completed',
+                    attempts: 1,
+                    ...(outcome?.reason ? { reason: outcome.reason } : {}),
+                    completedAt: now,
+                };
+                this.database.transaction(() => {
+                    if (parseReceipt(this.database.getRecord(payload.projectId, 'default', 'mutation', key)?.value)) {
+                        return;
+                    }
+                    this.database.putRecord({
+                        projectId: payload.projectId,
+                        workspaceId: 'default',
+                        kind: 'mutation',
+                        key,
+                        value: receipt,
+                        updatedAt: now,
+                    });
+                    this.database.appendAudit({
+                        projectId: payload.projectId,
+                        workspaceId: 'default',
+                        eventType: 'outbox.task.settled',
+                        payload: { deliveryKey: context.deliveryKey, task, ...receipt },
+                    });
+                });
+            }
+            catch (error) {
+                this.database.appendAudit({
+                    projectId: payload.projectId,
+                    workspaceId: 'default',
+                    eventType: 'outbox.task.failed',
+                    payload: {
+                        deliveryKey: context.deliveryKey,
+                        task,
+                        error: error instanceof Error ? error.message : String(error),
+                    },
+                });
+                throw error;
+            }
+        }
+    }
+}
+let interval;
+let activeDrain;
+export function drainSpecCreatedOutbox(databasePath = resolveStorageLayout().runtimeDatabase) {
+    if (activeDrain) {
+        return activeDrain;
+    }
+    activeDrain = (async () => {
+        const database = new RuntimeDatabase({ path: databasePath });
+        try {
+            const consumer = new SpecCreatedOutboxConsumer(database);
+            for (const scope of database.listPendingOutboxScopes()) {
+                const worker = new TransactionalOutboxWorker(database, scope.projectId, scope.workspaceId, `spec-created-${process.pid}-${randomUUID()}`);
+                await worker.drain((context) => consumer.deliver(context), { topics: ['spec.created'] });
+            }
+        }
+        finally {
+            database.close();
+        }
+    })().finally(() => {
+        activeDrain = undefined;
+    });
+    return activeDrain;
+}
+export async function startSpecCreatedOutboxConsumer() {
+    await drainSpecCreatedOutbox();
+    if (interval) {
+        return;
+    }
+    interval = setInterval(() => {
+        void drainSpecCreatedOutbox().catch((error) => {
+            console.error('[Planu] spec.created outbox drain failed:', error);
+        });
+    }, 30_000);
+    interval.unref();
+}
+//# sourceMappingURL=spec-created-outbox-consumer.js.map

package/dist/tools/create-spec.d.ts

@@ -1,4 +1,5 @@
 import type { CreateSpecInput, ToolResult } from '../types/index.js';
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function resolveGroundedVerificationCommands(projectPath: string, testPaths: string[]): Promise<string[]>;
 export declare function handleCreateSpec(inputParams: CreateSpecInput, server?: McpServer): Promise<ToolResult>;
 //# sourceMappingURL=create-spec.d.ts.map