@planu/cli 4.12.3 → 4.14.1

package/dist/storage/migrations/cwd-to-absolute.js

@@ -1,281 +0,0 @@
-// cwd-to-absolute.ts — One-shot migration of legacy <cwd>/data/projects/{id}/
-// trees into the new absolute home (~/.planu/data/projects/{id}/) introduced
-// in v3.3.0 (SPEC-1007).
-//
-// Idempotent and safe to call before every read/write entry point. Uses three
-// short-circuits in order:
-//   1. In-memory Set<projectId> — same session, repeat calls return immediately.
-//   2. Sentinel file `<absolute>/.migrated-from-cwd` — across sessions.
-//   3. Walk-up of `cwd` ancestors (max 8) for `knowledge.json` anchor.
-//
-// On rename we attempt the atomic `fs.rename`. When the source and destination
-// live on different filesystems (`EXDEV`), we fall back to `fs.cp` + verify +
-// `rm -rf legacy`. Verify failures leave the legacy tree intact.
-//
-// Conflict semantics: if the absolute path already holds populated data and
-// the legacy tree also has populated data, we never auto-merge — the legacy
-// tree is renamed to `<legacy>.legacy-<ISO_TS>` and a warning is logged.
-import { stat, mkdir, rename, cp, rm, writeFile, open } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
-import { join, dirname, isAbsolute } from 'node:path';
-import { projectDataDir } from '../base-store.js';
-const SENTINEL_FILE = '.migrated-from-cwd';
-// LOCK_FILE is appended to absolute path as a sibling (e.g. `${absolute}.migration.lock`)
-// to avoid creating `absolute` itself before the rename can run.
-const LOCK_FILE = '.migration.lock';
-const MAX_WALK_DEPTH = 8;
-const ANCHOR_FILE = 'knowledge.json';
-const LEGACY_SUBPATH = 'data/projects';
-/**
- * Per-session set of projectIds already migrated. Cleared by tests via
- * `clearMigratedThisSession()` so each test gets a fresh slate.
- */
-const migratedThisSession = new Set();
-/** Test-only: reset the in-memory short-circuit set. */
-export function clearMigratedThisSession() {
-    migratedThisSession.clear();
-}
-async function pathExists(p) {
-    try {
-        await stat(p);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-async function fileExists(p) {
-    try {
-        const s = await stat(p);
-        return s.isFile();
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Walk upward from `startDir` looking for `<dir>/data/projects/<id>/knowledge.json`.
- * Returns the matched legacy data dir (`<dir>/data/projects/<id>`), or null.
- */
-async function walkUpForLegacy(startDir, projectId) {
-    if (!isAbsolute(startDir)) {
-        return null;
-    }
-    let current = startDir;
-    for (let i = 0; i < MAX_WALK_DEPTH; i++) {
-        const candidate = join(current, LEGACY_SUBPATH, projectId);
-        if (await fileExists(join(candidate, ANCHOR_FILE))) {
-            return candidate;
-        }
-        const parent = dirname(current);
-        if (parent === current) {
-            return null;
-        }
-        current = parent;
-    }
-    return null;
-}
-async function writeSentinel(absolute) {
-    await mkdir(absolute, { recursive: true });
-    await writeFile(join(absolute, SENTINEL_FILE), new Date().toISOString(), 'utf-8');
-}
-/**
- * Acquire an exclusive lock by opening LOCK_FILE with O_CREAT|O_EXCL. The lock
- * is a sibling file `<absolute>.migration.lock`, so we never create `<absolute>`
- * itself prematurely (rename(legacy, absolute) must operate on a non-existing
- * destination). Returns a release function. If the lock is already held, polls
- * every 100ms up to 5s.
- */
-async function acquireLock(absolute) {
-    const lockPath = `${absolute}${LOCK_FILE}`;
-    await mkdir(dirname(absolute), { recursive: true });
-    const deadline = Date.now() + 5000;
-    while (Date.now() < deadline) {
-        try {
-            const fh = await open(lockPath, 'wx');
-            await fh.close();
-            return async () => {
-                try {
-                    await rm(lockPath, { force: true });
-                }
-                catch {
-                    // Best-effort
-                }
-            };
-        }
-        catch (err) {
-            if (err instanceof Error &&
-                'code' in err &&
-                err.code === 'EEXIST') {
-                await new Promise((r) => setTimeout(r, 100));
-                continue;
-            }
-            throw err;
-        }
-    }
-    // Timed out — assume the other writer crashed; force-release and retry once.
-    try {
-        await rm(lockPath, { force: true });
-    }
-    catch {
-        // ignore
-    }
-    const fh = await open(lockPath, 'wx');
-    await fh.close();
-    return async () => {
-        try {
-            await rm(lockPath, { force: true });
-        }
-        catch {
-            // ignore
-        }
-    };
-}
-function isExdevError(err) {
-    return err instanceof Error && 'code' in err && err.code === 'EXDEV';
-}
-/**
- * Move a legacy `<cwd>/data/projects/<id>/` tree into the absolute home for
- * `projectId`. Idempotent across calls and processes.
- *
- * Test isolation: when PLANU_PROJECT_DATA_DIR is assigned to a fresh tmp dir
- * (as in `tests/setup.ts`), this migration walks `cwd` from the test's
- * directory and finds nothing — returns `noop` immediately.
- */
-export async function migrateLegacyDataDir(projectId, cwd = process.cwd()) {
-    // Reject obviously invalid input — projectDataDir already validates, but we
-    // want a typed result rather than a thrown error reaching callers.
-    if (!projectId || projectId.includes('..') || projectId.includes('/')) {
-        return {
-            status: 'error',
-            legacyPath: null,
-            absolutePath: '',
-            reason: `Invalid projectId: "${projectId}"`,
-        };
-    }
-    const absolute = projectDataDir(projectId);
-    // 1. In-memory short-circuit.
-    if (migratedThisSession.has(projectId)) {
-        return { status: 'noop', legacyPath: null, absolutePath: absolute };
-    }
-    // 2. Sentinel short-circuit (cross-session).
-    if (existsSync(join(absolute, SENTINEL_FILE))) {
-        migratedThisSession.add(projectId);
-        return { status: 'noop', legacyPath: null, absolutePath: absolute };
-    }
-    // 3. Walk up from cwd looking for legacy.
-    let legacyPath;
-    try {
-        legacyPath = await walkUpForLegacy(cwd, projectId);
-    }
-    catch (err) {
-        return {
-            status: 'error',
-            legacyPath: null,
-            absolutePath: absolute,
-            reason: `Walk-up failed: ${err instanceof Error ? err.message : String(err)}`,
-        };
-    }
-    // No legacy → first-time install. Mark with sentinel so we never re-walk.
-    if (legacyPath === null) {
-        try {
-            await writeSentinel(absolute);
-        }
-        catch {
-            // Best-effort: the absence of a sentinel just means we re-walk next call.
-        }
-        migratedThisSession.add(projectId);
-        return { status: 'noop', legacyPath: null, absolutePath: absolute };
-    }
-    // 4. Acquire lock and re-check sentinel inside the critical section.
-    let release;
-    try {
-        release = await acquireLock(absolute);
-    }
-    catch (err) {
-        return {
-            status: 'error',
-            legacyPath,
-            absolutePath: absolute,
-            reason: `Lock acquisition failed: ${err instanceof Error ? err.message : String(err)}`,
-        };
-    }
-    try {
-        if (existsSync(join(absolute, SENTINEL_FILE))) {
-            migratedThisSession.add(projectId);
-            return { status: 'noop', legacyPath, absolutePath: absolute };
-        }
-        const absoluteHasContent = await fileExists(join(absolute, ANCHOR_FILE));
-        if (absoluteHasContent) {
-            return await runConflictBranch(projectId, legacyPath, absolute);
-        }
-        return await runHappyPath(projectId, legacyPath, absolute);
-    }
-    finally {
-        await release();
-    }
-}
-async function runConflictBranch(projectId, legacyPath, absolute) {
-    const ts = new Date().toISOString().replace(/[:.]/g, '-');
-    const renamed = `${legacyPath}.legacy-${ts}`;
-    try {
-        await rename(legacyPath, renamed);
-    }
-    catch (err) {
-        return {
-            status: 'error',
-            legacyPath,
-            absolutePath: absolute,
-            reason: `Conflict rename failed: ${err instanceof Error ? err.message : String(err)}`,
-        };
-    }
-    console.warn(`[Planu] Migration conflict: legacy ${legacyPath} renamed to ${renamed}; absolute path retained as canonical.`);
-    await writeSentinel(absolute);
-    migratedThisSession.add(projectId);
-    return {
-        status: 'conflict',
-        legacyPath,
-        absolutePath: absolute,
-        reason: `Both legacy and absolute had populated content; legacy renamed to ${renamed}`,
-    };
-}
-async function runHappyPath(projectId, legacyPath, absolute) {
-    await mkdir(dirname(absolute), { recursive: true });
-    try {
-        await rename(legacyPath, absolute);
-    }
-    catch (err) {
-        if (!isExdevError(err)) {
-            return {
-                status: 'error',
-                legacyPath,
-                absolutePath: absolute,
-                reason: `Rename failed: ${err instanceof Error ? err.message : String(err)}`,
-            };
-        }
-        await cp(legacyPath, absolute, { recursive: true, errorOnExist: false });
-        if (!(await fileExists(join(absolute, ANCHOR_FILE)))) {
-            return {
-                status: 'error',
-                legacyPath,
-                absolutePath: absolute,
-                reason: 'Cross-filesystem copy verification failed; legacy tree preserved',
-            };
-        }
-        await rm(legacyPath, { recursive: true, force: true });
-    }
-    await writeSentinel(absolute);
-    migratedThisSession.add(projectId);
-    return { status: 'migrated', legacyPath, absolutePath: absolute };
-}
-// Re-export constants used by callers and tests.
-export const MIGRATION_INTERNALS = Object.freeze({
-    SENTINEL_FILE,
-    LOCK_FILE,
-    MAX_WALK_DEPTH,
-    ANCHOR_FILE,
-    LEGACY_SUBPATH,
-});
-// pathExists is an internal helper; export only when needed in tests.
-export const __test = { pathExists };
-//# sourceMappingURL=cwd-to-absolute.js.map

package/dist/tools/create-spec/adapters/prior-decisions-hint.d.ts

@@ -1,14 +0,0 @@
-import type { PriorDecisionLink } from '../../../types/prior-decisions.js';
-/**
- * Find prior decisions relevant to the new spec (AC1/AC2).
- *
- * Returns an empty array when:
- * - No decisions have been logged (AC4 — omit when empty)
- * - Any storage or search error occurs (best-effort, never blocks)
- *
- * @param projectId   - hashed project identifier
- * @param description - spec description + title (combined query text)
- * @param tags        - spec tags appended to the query for richer overlap
- */
-export declare function runPriorDecisionsHint(projectId: string, description: string, tags: string[]): Promise<PriorDecisionLink[]>;
-//# sourceMappingURL=prior-decisions-hint.d.ts.map

package/dist/tools/create-spec/adapters/prior-decisions-hint.js

@@ -1,30 +0,0 @@
-// tools/create-spec/adapters/prior-decisions-hint.ts — SPEC-615
-// Best-effort adapter: searches logged decisions for keyword overlap with the
-// new spec and returns formatted prior-decision links (AC1/AC2/AC4).
-import { getDecisions } from '../../../storage/decision-store.js';
-import { searchPriorDecisions } from '../../../engine/prior-decisions/index.js';
-/**
- * Find prior decisions relevant to the new spec (AC1/AC2).
- *
- * Returns an empty array when:
- * - No decisions have been logged (AC4 — omit when empty)
- * - Any storage or search error occurs (best-effort, never blocks)
- *
- * @param projectId   - hashed project identifier
- * @param description - spec description + title (combined query text)
- * @param tags        - spec tags appended to the query for richer overlap
- */
-export async function runPriorDecisionsHint(projectId, description, tags) {
-    try {
-        const decisions = await getDecisions(projectId);
-        if (decisions.length === 0) {
-            return [];
-        }
-        const query = tags.length > 0 ? `${description} ${tags.join(' ')}` : description;
-        return searchPriorDecisions(query, decisions);
-    }
-    catch {
-        return [];
-    }
-}
-//# sourceMappingURL=prior-decisions-hint.js.map

package/dist/tools/init-project/ancestor-data-detector.d.ts

@@ -1,22 +0,0 @@
-/**
- * Locations where an ancestor `data/projects/<projectId>/` directory was
- * found. Empty array means no ancestor data exists.
- */
-export interface AncestorDataReport {
-    /** Hits found by walking up from the projectPath itself. */
-    fromProjectPath: string[];
-    /** Hits found by walking up from process.cwd(). */
-    fromCwd: string[];
-}
-/**
- * Scan for ancestor `data/projects/<projectId>/` dirs above projectPath and cwd.
- * Returns deduplicated absolute paths (no double-counting when projectPath and
- * cwd share an ancestor).
- */
-export declare function detectAncestorDataDirs(projectPath: string, projectId: string, cwd?: string): Promise<AncestorDataReport>;
-/**
- * Build a single human-readable warning line summarizing every ancestor data
- * dir hit. Returns null when no warning is needed.
- */
-export declare function buildAncestorDataWarning(report: AncestorDataReport): string | null;
-//# sourceMappingURL=ancestor-data-detector.d.ts.map

package/dist/tools/init-project/ancestor-data-detector.js

@@ -1,81 +0,0 @@
-// tools/init-project/ancestor-data-detector.ts
-//
-// Detects existing `data/projects/<id>/` directories in ancestors of the
-// projectPath and in ancestors of the current cwd. When such a dir exists,
-// init_project would otherwise create a parallel, divergent data root in the
-// new cwd-relative location — splitting the project state across two
-// physical paths and confusing every downstream tool.
-//
-// This helper is read-only: it only reports findings. The handler decides
-// whether to surface them as warnings or block.
-import { stat } from 'node:fs/promises';
-import { dirname, isAbsolute, join } from 'node:path';
-const MAX_WALK_DEPTH = 8;
-async function isExistingDir(p) {
-    try {
-        const s = await stat(p);
-        return s.isDirectory();
-    }
-    catch {
-        return false;
-    }
-}
-async function walkUpForDir(startDir, relative) {
-    if (!isAbsolute(startDir)) {
-        return null;
-    }
-    let current = startDir;
-    for (let i = 0; i < MAX_WALK_DEPTH; i++) {
-        const candidate = join(current, relative);
-        if (await isExistingDir(candidate)) {
-            return candidate;
-        }
-        const parent = dirname(current);
-        if (parent === current) {
-            return null;
-        }
-        current = parent;
-    }
-    return null;
-}
-/**
- * Scan for ancestor `data/projects/<projectId>/` dirs above projectPath and cwd.
- * Returns deduplicated absolute paths (no double-counting when projectPath and
- * cwd share an ancestor).
- */
-export async function detectAncestorDataDirs(projectPath, projectId, cwd = process.cwd()) {
-    const subPath = join('data', 'projects', projectId);
-    const seen = new Set();
-    const fromProjectPath = [];
-    const cursor = isAbsolute(projectPath) ? dirname(projectPath) : null;
-    if (cursor !== null) {
-        const hit = await walkUpForDir(cursor, subPath);
-        if (hit !== null && !seen.has(hit)) {
-            seen.add(hit);
-            fromProjectPath.push(hit);
-        }
-    }
-    const fromCwd = [];
-    if (cwd !== projectPath) {
-        const hit = await walkUpForDir(cwd, subPath);
-        if (hit !== null && !seen.has(hit)) {
-            seen.add(hit);
-            fromCwd.push(hit);
-        }
-    }
-    return { fromProjectPath, fromCwd };
-}
-/**
- * Build a single human-readable warning line summarizing every ancestor data
- * dir hit. Returns null when no warning is needed.
- */
-export function buildAncestorDataWarning(report) {
-    const all = [...report.fromProjectPath, ...report.fromCwd];
-    if (all.length === 0) {
-        return null;
-    }
-    const list = all.map((p) => `  • ${p}`).join('\n');
-    return (`Existing Planu data found in ancestor directories — this project's state may be split across multiple locations:\n${list}\n` +
-        `If specs go missing, copy the contents into <projectPath>/data/projects/<id>/ and reopen Claude Code from the project root.`);
-}
-//# sourceMappingURL=ancestor-data-detector.js.map

package/dist/tools/update-status/force-done-audit.d.ts

@@ -1,2 +0,0 @@
-export declare function recordForceDoneBypass(specId: string, projectId: string, reason: string, failingItems: string[], warningItems: string[]): Promise<void>;
-//# sourceMappingURL=force-done-audit.d.ts.map

package/dist/tools/update-status/force-done-audit.js

@@ -1,23 +0,0 @@
-import { randomUUID } from 'node:crypto';
-import { projectDataDir, readJson, writeJson } from '../../storage/base-store.js';
-export async function recordForceDoneBypass(specId, projectId, reason, failingItems, warningItems) {
-    try {
-        const logPath = `${projectDataDir(projectId)}/force-bypass-log.json`;
-        const entries = await readJson(logPath, []);
-        entries.push({
-            id: randomUUID(),
-            timestamp: new Date().toISOString(),
-            action: 'force_done_bypass',
-            specId,
-            projectId,
-            reason,
-            failingItems,
-            warningItems,
-        });
-        await writeJson(logPath, entries);
-    }
-    catch {
-        // Best effort: audit storage failure must not hide the original gate result.
-    }
-}
-//# sourceMappingURL=force-done-audit.js.map

package/dist/types/migration/cwd-to-absolute.d.ts

@@ -1,8 +0,0 @@
-export type CwdMigrationStatus = 'noop' | 'migrated' | 'conflict' | 'error';
-export interface CwdMigrationResult {
-    status: CwdMigrationStatus;
-    legacyPath: string | null;
-    absolutePath: string;
-    reason?: string;
-}
-//# sourceMappingURL=cwd-to-absolute.d.ts.map

package/dist/types/migration/cwd-to-absolute.js

@@ -1,3 +0,0 @@
-// Planu — SPEC-1007 cwd→absolute migration types
-export {};
-//# sourceMappingURL=cwd-to-absolute.js.map