@planu/cli 4.13.0 → 4.14.1

package/dist/engine/execution/native-relevance-scorer.js

@@ -0,0 +1,64 @@
+import { fastFindFilesByExt, fastReadFiles } from '../core-bridge.js';
+// Content scoring is advisory. Keep it bounded so a create_spec acknowledgement
+// never turns into an O(project-files) content read on large repositories.
+const MAX_CONTENT_CANDIDATES = 2_048;
+function normalizedRelativePath(rootPath, filePath) {
+    const normalizedRoot = rootPath.replaceAll('\\', '/').replace(/\/$/, '');
+    const normalizedFile = filePath.replaceAll('\\', '/');
+    return normalizedFile.startsWith(`${normalizedRoot}/`)
+        ? normalizedFile.slice(normalizedRoot.length + 1)
+        : normalizedFile;
+}
+function isRelevantSourcePath(rootPath, filePath) {
+    const relativePath = normalizedRelativePath(rootPath, filePath);
+    return ((relativePath.startsWith('src/') || relativePath.startsWith('tests/')) &&
+        !relativePath.includes('/node_modules/') &&
+        !relativePath.includes('/dist/'));
+}
+export function findRelevantFilesNative(input) {
+    const keywords = [...new Set(input.keywords.map((value) => value.trim()))].filter(Boolean);
+    if (keywords.length === 0 || !Number.isSafeInteger(input.limit) || input.limit < 1) {
+        return [];
+    }
+    const candidates = fastFindFilesByExt(input.rootPath, ['ts'])
+        .filter((filePath) => isRelevantSourcePath(input.rootPath, filePath))
+        .sort((left, right) => left.localeCompare(right));
+    const scores = new Map();
+    const pathMatched = new Set();
+    for (const filePath of candidates) {
+        const pathTokens = new Set(normalizedRelativePath(input.rootPath, filePath)
+            .toLowerCase()
+            .split(/[/\\.\-_]+/)
+            .filter((token) => token.length >= 3));
+        const pathScore = keywords.filter((keyword) => pathTokens.has(keyword)).length;
+        if (pathScore > 0) {
+            scores.set(filePath, pathScore * 2);
+            pathMatched.add(filePath);
+        }
+    }
+    // Prefer files already related by path, then inspect a deterministic bounded
+    // sample for content-only matches. The previous fastFindPatterns call walked
+    // and opened every source file a second time (10s+ at 100k files).
+    const contentCandidates = [
+        ...pathMatched,
+        ...candidates.filter((filePath) => !pathMatched.has(filePath)),
+    ].slice(0, MAX_CONTENT_CANDIDATES);
+    for (const file of fastReadFiles(contentCandidates)) {
+        const content = file.content.toLowerCase();
+        let contentScore = 0;
+        for (const keyword of keywords) {
+            if (content.includes(keyword.toLowerCase())) {
+                contentScore += 1;
+            }
+        }
+        if (contentScore > 0) {
+            scores.set(file.path, (scores.get(file.path) ?? 0) + contentScore);
+        }
+    }
+    return [...scores]
+        .filter(([, score]) => score > 0)
+        .sort(([leftPath, leftScore], [rightPath, rightScore]) => rightScore === leftScore ? leftPath.localeCompare(rightPath) : rightScore - leftScore)
+        .slice(0, input.limit)
+        .map(([filePath]) => filePath);
+}
+//# sourceMappingURL=native-relevance-scorer.js.map

package/dist/engine/execution/native-worker-dispatch.d.ts

@@ -0,0 +1,3 @@
+import type { NativeWorkerRequest } from './native-worker-protocol.js';
+export declare function dispatchNativeWorkerRequest(request: NativeWorkerRequest): unknown;
+//# sourceMappingURL=native-worker-dispatch.d.ts.map

package/dist/engine/execution/native-worker-dispatch.js

@@ -0,0 +1,46 @@
+import { fastDetectDriftParallel, fastScanAndHashFiles, fastScanProjectGraphSources, fastScanProjectMetadata, fastScanSpecAnnotations, fastScanSpecs, } from '../core-bridge.js';
+import { findRelevantFilesNative } from './native-relevance-scorer.js';
+function requiredString(payload, key) {
+    const value = payload[key];
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new Error(`[Planu] Native worker payload requires ${key}`);
+    }
+    return value;
+}
+function stringArray(payload, key) {
+    const value = payload[key];
+    if (!Array.isArray(value) || !value.every((item) => typeof item === 'string')) {
+        throw new Error(`[Planu] Native worker payload requires string[] ${key}`);
+    }
+    return value;
+}
+function positiveInteger(payload, key) {
+    const value = payload[key];
+    if (!Number.isSafeInteger(value) || value < 1) {
+        throw new Error(`[Planu] Native worker payload requires positive integer ${key}`);
+    }
+    return value;
+}
+export function dispatchNativeWorkerRequest(request) {
+    switch (request.operation) {
+        case 'scan-and-hash-files':
+            return fastScanAndHashFiles(requiredString(request.payload, 'rootPath'));
+        case 'scan-project-metadata':
+            return fastScanProjectMetadata(requiredString(request.payload, 'rootPath'));
+        case 'scan-spec-annotations':
+            return fastScanSpecAnnotations(requiredString(request.payload, 'rootPath'));
+        case 'detect-drift':
+            return fastDetectDriftParallel(requiredString(request.payload, 'rootPath'), stringArray(request.payload, 'keywords'));
+        case 'scan-specs':
+            return fastScanSpecs(requiredString(request.payload, 'rootPath'));
+        case 'find-relevant-files':
+            return findRelevantFilesNative({
+                rootPath: requiredString(request.payload, 'rootPath'),
+                keywords: stringArray(request.payload, 'keywords'),
+                limit: positiveInteger(request.payload, 'limit'),
+            });
+        case 'scan-project-graph-sources':
+            return fastScanProjectGraphSources(requiredString(request.payload, 'rootPath'), request.payload.policy, request.payload.overrides ?? {});
+    }
+}
+//# sourceMappingURL=native-worker-dispatch.js.map

package/dist/engine/execution/native-worker-protocol.d.ts

@@ -0,0 +1,6 @@
+import type { NativeWorkerOperation } from '../../types/native-worker.js';
+export type { NativeWorkerHandshake, NativeWorkerOperation, NativeWorkerRequest, NativeWorkerResponse, } from '../../types/native-worker.js';
+export declare const NATIVE_WORKER_OPERATIONS: readonly ["scan-and-hash-files", "scan-project-metadata", "scan-spec-annotations", "detect-drift", "scan-specs", "find-relevant-files", "scan-project-graph-sources"];
+export declare function nativeWorkerSchemaHash(): string;
+export declare function isNativeWorkerOperation(value: unknown): value is NativeWorkerOperation;
+//# sourceMappingURL=native-worker-protocol.d.ts.map

package/dist/engine/execution/native-worker-protocol.js

@@ -0,0 +1,33 @@
+import { createHash } from 'node:crypto';
+import { NATIVE_CAPABILITY_ABI, NATIVE_PROTOCOL_ABI, RUNTIME_STORAGE_SCHEMA, } from '../native-runtime-handshake.js';
+export const NATIVE_WORKER_OPERATIONS = [
+    'scan-and-hash-files',
+    'scan-project-metadata',
+    'scan-spec-annotations',
+    'detect-drift',
+    'scan-specs',
+    'find-relevant-files',
+    'scan-project-graph-sources',
+];
+export function nativeWorkerSchemaHash() {
+    return createHash('sha256')
+        .update(JSON.stringify({
+        protocolAbi: NATIVE_PROTOCOL_ABI,
+        capabilityAbi: NATIVE_CAPABILITY_ABI,
+        storageSchema: RUNTIME_STORAGE_SCHEMA,
+        capabilities: NATIVE_WORKER_OPERATIONS,
+        requestFields: [
+            'requestId',
+            'projectId',
+            'deadlineAt',
+            'cancellationId',
+            'operation',
+            'payload',
+        ],
+    }))
+        .digest('hex');
+}
+export function isNativeWorkerOperation(value) {
+    return (typeof value === 'string' && NATIVE_WORKER_OPERATIONS.includes(value));
+}
+//# sourceMappingURL=native-worker-protocol.js.map

package/dist/engine/execution/native-worker-runtime.d.ts

@@ -0,0 +1,4 @@
+import type { NativeWorkerCall, NativeWorkerFactory } from '../../types/native-worker.js';
+export type { NativeWorkerCall } from '../../types/native-worker.js';
+export declare function runNativeWorkerOperation(call: NativeWorkerCall, workerFactory?: NativeWorkerFactory): Promise<unknown>;
+//# sourceMappingURL=native-worker-runtime.d.ts.map

package/dist/engine/execution/native-worker-runtime.js

@@ -0,0 +1,177 @@
+import { randomBytes, randomUUID } from 'node:crypto';
+import { Worker } from 'node:worker_threads';
+import { nativeWorkerSchemaHash, NATIVE_WORKER_OPERATIONS, } from './native-worker-protocol.js';
+import { NATIVE_CAPABILITY_ABI, NATIVE_PROTOCOL_ABI, RUNTIME_STORAGE_SCHEMA, } from '../native-runtime-handshake.js';
+import { getExecutionContext } from './context.js';
+import { redactFailureMessage, reportClassifiedDegradation, } from '../../errors/classified-degradation.js';
+function validateCall(call) {
+    if (call.signal?.aborted) {
+        throw call.signal.reason instanceof Error
+            ? call.signal.reason
+            : new Error('[Planu] Native worker cancelled');
+    }
+    if (!call.projectId.trim() || !Number.isSafeInteger(call.deadlineAt)) {
+        throw new Error('[Planu] Native worker call requires projectId and an absolute deadline');
+    }
+    if (!NATIVE_WORKER_OPERATIONS.includes(call.operation)) {
+        throw new Error('[Planu] Native worker operation is not allowlisted');
+    }
+    if (Date.now() >= call.deadlineAt) {
+        throw new Error('[Planu] Native worker deadline already expired');
+    }
+}
+function validateHandshake(handshake, operation) {
+    const capabilities = new Set(handshake.capabilities);
+    if (handshake.protocolAbi !== NATIVE_PROTOCOL_ABI ||
+        handshake.capabilityAbi !== NATIVE_CAPABILITY_ABI ||
+        handshake.storageSchema !== RUNTIME_STORAGE_SCHEMA ||
+        handshake.schemaHash !== nativeWorkerSchemaHash() ||
+        capabilities.size !== NATIVE_WORKER_OPERATIONS.length ||
+        !NATIVE_WORKER_OPERATIONS.every((capability) => capabilities.has(capability)) ||
+        !capabilities.has(operation) ||
+        typeof handshake.engineVersion !== 'string' ||
+        handshake.engineVersion.trim() === '' ||
+        typeof handshake.target !== 'string' ||
+        handshake.target.trim() === '' ||
+        typeof handshake.artifactHash !== 'string' ||
+        !/^[a-f0-9]{64}$/.test(handshake.artifactHash) ||
+        !handshake.compatible) {
+        throw new Error('[Planu] Native worker handshake is incompatible');
+    }
+}
+// eslint-disable-next-line max-lines-per-function -- worker lifecycle keeps cancellation and identity fencing in one closure
+export async function runNativeWorkerOperation(call, workerFactory = (url, options) => new Worker(url, {
+    ...options,
+    execArgv: process.execArgv.filter((argument) => !argument.startsWith('--input-type')),
+})) {
+    const parent = getExecutionContext();
+    const deadlineAt = Math.min(call.deadlineAt, parent?.deadlineAt ?? Number.POSITIVE_INFINITY);
+    const cancellation = linkCancellation(call.signal, parent?.signal);
+    try {
+        validateCall({ ...call, deadlineAt, signal: cancellation.signal });
+    }
+    catch (error) {
+        cancellation.dispose();
+        throw error;
+    }
+    const secret = randomBytes(32).toString('hex');
+    const requestId = call.requestId ?? randomUUID();
+    const cancellationId = call.cancellationId ?? randomUUID();
+    const worker = workerFactory(new URL('./native-worker-thread.js', import.meta.url), {
+        workerData: { secret },
+    });
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let requestSent = false;
+        const timeoutMs = Math.max(1, deadlineAt - Date.now());
+        const finish = (error, value) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timer);
+            cancellation.signal.removeEventListener('abort', abort);
+            cancellation.dispose();
+            void worker.terminate();
+            if (error) {
+                reject(error);
+            }
+            else {
+                resolve(value);
+            }
+        };
+        const abort = () => {
+            const reason = cancellation.signal.reason;
+            finish(reason instanceof Error ? reason : new Error('[Planu] Native worker cancelled'));
+        };
+        const timer = setTimeout(() => {
+            finish(new Error('[Planu] Native worker deadline exceeded'));
+        }, timeoutMs);
+        cancellation.signal.addEventListener('abort', abort, { once: true });
+        if (cancellation.signal.aborted) {
+            abort();
+            return;
+        }
+        worker.once('error', (error) => {
+            finish(error instanceof Error ? error : new Error(String(error)));
+        });
+        worker.once('exit', (code) => {
+            if (!settled && code !== 0) {
+                finish(new Error(`[Planu] Native worker exited with code ${String(code)}`));
+            }
+        });
+        worker.on('message', (value) => {
+            if (!value || typeof value !== 'object' || !('kind' in value)) {
+                finish(new Error('[Planu] Native worker sent a malformed message'));
+                return;
+            }
+            const message = value;
+            if (message.kind === 'handshake') {
+                try {
+                    if (requestSent) {
+                        throw new Error('[Planu] Native worker sent a duplicate handshake');
+                    }
+                    validateHandshake(message, call.operation);
+                    const request = {
+                        kind: 'request',
+                        secret,
+                        requestId,
+                        projectId: call.projectId,
+                        deadlineAt,
+                        cancellationId,
+                        operation: call.operation,
+                        payload: call.payload,
+                    };
+                    requestSent = true;
+                    worker.postMessage(request);
+                }
+                catch (error) {
+                    /* reliability-optional: NATIVE_WORKER_MESSAGE_FAILURE — promise rejects through finish */
+                    reportClassifiedDegradation('NATIVE_WORKER_MESSAGE_FAILURE', error);
+                    finish(new Error(redactFailureMessage(error)));
+                }
+                return;
+            }
+            if (!requestSent || message.requestId !== requestId) {
+                finish(new Error('[Planu] Native worker response identity mismatch'));
+                return;
+            }
+            if (message.kind === 'error') {
+                finish(new Error(message.message));
+            }
+            else {
+                finish(undefined, message.value);
+            }
+        });
+    });
+}
+function linkCancellation(child, parent) {
+    const controller = new AbortController();
+    const signals = [child, parent].filter((signal) => signal !== undefined);
+    const abort = (signal) => {
+        if (!controller.signal.aborted) {
+            controller.abort(signal.reason);
+        }
+    };
+    const listeners = signals.map((signal) => {
+        const listener = () => {
+            abort(signal);
+        };
+        if (signal.aborted) {
+            abort(signal);
+        }
+        else {
+            signal.addEventListener('abort', listener, { once: true });
+        }
+        return { signal, listener };
+    });
+    return {
+        signal: controller.signal,
+        dispose: () => {
+            for (const listener of listeners) {
+                listener.signal.removeEventListener('abort', listener.listener);
+            }
+        },
+    };
+}
+//# sourceMappingURL=native-worker-runtime.js.map

package/dist/engine/execution/native-worker-thread.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=native-worker-thread.d.ts.map

package/dist/engine/execution/native-worker-thread.js

@@ -0,0 +1,66 @@
+import { parentPort, workerData } from 'node:worker_threads';
+import { isNativeActive, nativeLoadDiagnostic, NATIVE_CAPABILITY_ABI, NATIVE_PROTOCOL_ABI, RUNTIME_STORAGE_SCHEMA, } from '../core-bridge.js';
+import { PLANU_VERSION } from '../../config/version.js';
+import { redactFailureMessage, reportClassifiedDegradation, } from '../../errors/classified-degradation.js';
+import { isNativeWorkerOperation, nativeWorkerSchemaHash, NATIVE_WORKER_OPERATIONS, } from './native-worker-protocol.js';
+import { dispatchNativeWorkerRequest } from './native-worker-dispatch.js';
+const bootstrap = workerData;
+const bootstrapSecret = bootstrap && typeof bootstrap === 'object' && 'secret' in bootstrap
+    ? bootstrap.secret
+    : undefined;
+if (!parentPort || typeof bootstrapSecret !== 'string' || bootstrapSecret.length < 32) {
+    throw new Error('[Planu] Native worker bootstrap authentication failed');
+}
+const port = parentPort;
+isNativeActive();
+const diagnostic = nativeLoadDiagnostic();
+const nativeHandshake = diagnostic.compatibility?.handshake ?? null;
+port.postMessage({
+    kind: 'handshake',
+    protocolAbi: NATIVE_PROTOCOL_ABI,
+    capabilityAbi: NATIVE_CAPABILITY_ABI,
+    storageSchema: RUNTIME_STORAGE_SCHEMA,
+    schemaHash: nativeWorkerSchemaHash(),
+    capabilities: NATIVE_WORKER_OPERATIONS,
+    engineVersion: nativeHandshake?.engineVersion ?? PLANU_VERSION,
+    target: nativeHandshake?.target ?? null,
+    artifactHash: diagnostic.artifactSha256 ?? null,
+    compatible: diagnostic.compatibility?.compatible === true,
+});
+port.on('message', (value) => {
+    const request = value;
+    const requestId = typeof request.requestId === 'string' ? request.requestId : 'invalid';
+    const respond = (response) => {
+        port.postMessage(response);
+    };
+    try {
+        if (request.kind !== 'request' ||
+            request.secret !== bootstrapSecret ||
+            !isNativeWorkerOperation(request.operation) ||
+            typeof request.projectId !== 'string' ||
+            request.projectId.trim() === '' ||
+            typeof request.cancellationId !== 'string' ||
+            request.cancellationId.trim() === '' ||
+            typeof request.deadlineAt !== 'number' ||
+            Date.now() >= request.deadlineAt ||
+            !request.payload ||
+            typeof request.payload !== 'object') {
+            throw new Error('[Planu] Native worker rejected malformed or expired request');
+        }
+        respond({
+            kind: 'result',
+            requestId,
+            value: dispatchNativeWorkerRequest(request),
+        });
+    }
+    catch (error) {
+        /* reliability-optional: NATIVE_WORKER_OPERATION_FAILURE — typed error response is emitted */
+        reportClassifiedDegradation('NATIVE_WORKER_OPERATION_FAILURE', error);
+        respond({
+            kind: 'error',
+            requestId,
+            message: redactFailureMessage(error),
+        });
+    }
+});
+//# sourceMappingURL=native-worker-thread.js.map

package/dist/engine/execution/operation-journal.d.ts

@@ -0,0 +1,66 @@
+import type { RuntimeDatabase } from '../../storage/runtime-db.js';
+export type OperationState = 'intent' | 'prepared' | 'committed' | 'acknowledged' | 'rolled-back' | 'quarantined';
+export interface OperationJournalEntry<TResult = unknown, TPayload = unknown> {
+    readonly schemaVersion: 2;
+    readonly operation: string;
+    readonly idempotencyKey: string;
+    readonly requestDigest: string;
+    readonly state: OperationState;
+    readonly payloadVersion?: number;
+    readonly payload?: TPayload;
+    readonly result?: TResult;
+    readonly recoveryReason?: string;
+    readonly recoveryAttempts: number;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+}
+export type OperationRecoveryDecision<TResult> = {
+    readonly action: 'commit';
+    readonly result: TResult;
+    readonly outbox?: OutboxMessage;
+} | {
+    readonly action: 'rollback';
+    readonly reason: string;
+} | {
+    readonly action: 'quarantine';
+    readonly reason: string;
+};
+export interface OutboxMessage {
+    readonly topic: string;
+    readonly payload: unknown;
+}
+/** Durable, monotonic command journal backed by the canonical runtime database. */
+export declare class OperationJournal<TResult = unknown, TPayload = unknown> {
+    private readonly database;
+    private readonly projectId;
+    private readonly workspaceId;
+    constructor(database: RuntimeDatabase, projectId: string, workspaceId?: string);
+    get(operation: string, idempotencyKey: string): OperationJournalEntry<TResult, TPayload> | undefined;
+    list(operation?: string): readonly OperationJournalEntry<TResult, TPayload>[];
+    begin(operation: string, idempotencyKey: string, requestDigest: string, recovery?: {
+        readonly payloadVersion: number;
+        readonly payload: TPayload;
+    }): OperationJournalEntry<TResult, TPayload>;
+    setRecoveryPayload(operation: string, idempotencyKey: string, payloadVersion: number, payload: TPayload): OperationJournalEntry<TResult, TPayload>;
+    restartRolledBack(operation: string, idempotencyKey: string): OperationJournalEntry<TResult, TPayload>;
+    prepared(operation: string, idempotencyKey: string): OperationJournalEntry<TResult, TPayload>;
+    committed(operation: string, idempotencyKey: string, result: TResult): OperationJournalEntry<TResult, TPayload>;
+    commitWithOutbox(operation: string, idempotencyKey: string, result: TResult, outbox?: OutboxMessage): OperationJournalEntry<TResult, TPayload>;
+    acknowledged(operation: string, idempotencyKey: string): OperationJournalEntry<TResult, TPayload>;
+    resolveRecovery(operation: string, idempotencyKey: string, decision: OperationRecoveryDecision<TResult>): OperationJournalEntry<TResult, TPayload>;
+    resolveRecoveryIfCurrent(snapshot: OperationJournalEntry<TResult, TPayload>, decision: OperationRecoveryDecision<TResult>): OperationJournalEntry<TResult, TPayload>;
+    private applyRecovery;
+    private advance;
+    private next;
+    private require;
+    private put;
+    private recordKey;
+}
+/** Reconciles stale intents using one operation-specific, deterministic strategy. */
+export declare function recoverOperationJournal<TResult, TPayload>(input: {
+    readonly journal: OperationJournal<TResult, TPayload>;
+    readonly operation: string;
+    readonly staleBefore: string;
+    readonly decide: (entry: OperationJournalEntry<TResult, TPayload>) => Promise<OperationRecoveryDecision<TResult>>;
+}): Promise<readonly OperationJournalEntry<TResult, TPayload>[]>;
+//# sourceMappingURL=operation-journal.d.ts.map