@planu/cli 4.13.0 → 5.0.0

package/dist/storage/oauth-store.js

@@ -1,16 +1,29 @@
 // storage/oauth-store.ts — OAuth token persistence (SPEC-440)
 import { join } from 'node:path';
-import { hashProjectPath, readJson, writeJson } from './base-store.js';
+import { hashProjectPath, projectDataDir, readJson } from './base-store.js';
+import { deleteSecretField, resolveSecretField, storeSecretField, } from '../security/secret-field.js';
+import { writeSecureJson } from '../security/secure-json.js';
+function secretId(projectPath, integration, kind) {
+    return `${hashProjectPath(projectPath)}/oauth/${integration}/${kind}`;
+}
+async function resolveToken(token) {
+    return {
+        ...token,
+        accessToken: await resolveSecretField(token.accessToken),
+        ...(token.refreshToken ? { refreshToken: await resolveSecretField(token.refreshToken) } : {}),
+    };
+}
 function tokensPath(projectPath) {
     const id = hashProjectPath(projectPath);
-    return join('data', 'projects', id, 'oauth', 'tokens.json');
+    return join(projectDataDir(id), 'oauth', 'tokens.json');
 }
 /**
  * Retrieve the stored OAuth token for a specific integration, or null if not stored.
  */
 export async function getOAuthToken(projectPath, integration) {
     const tokens = await readJson(tokensPath(projectPath), []);
-    return tokens.find((t) => t.integration === integration) ?? null;
+    const token = tokens.find((t) => t.integration === integration);
+    return token ? resolveToken(token) : null;
 }
 /**
  * Persist an OAuth token for a project, replacing any existing token for the same integration.
@@ -18,14 +31,23 @@ export async function getOAuthToken(projectPath, integration) {
 export async function saveOAuthToken(projectPath, token) {
     const path = tokensPath(projectPath);
     const tokens = await readJson(path, []);
+    const stored = {
+        ...token,
+        accessToken: await storeSecretField(secretId(projectPath, token.integration, 'access'), 'oauth-access', token.accessToken),
+        ...(token.refreshToken
+            ? {
+                refreshToken: await storeSecretField(secretId(projectPath, token.integration, 'refresh'), 'oauth-refresh', token.refreshToken),
+            }
+            : {}),
+    };
     const index = tokens.findIndex((t) => t.integration === token.integration);
     if (index >= 0) {
-        tokens[index] = token;
+        tokens[index] = stored;
     }
     else {
-        tokens.push(token);
+        tokens.push(stored);
     }
-    await writeJson(path, tokens);
+    await writeSecureJson(path, tokens);
 }
 /**
  * Remove the stored OAuth token for a specific integration.
@@ -33,13 +55,19 @@ export async function saveOAuthToken(projectPath, token) {
 export async function removeOAuthToken(projectPath, integration) {
     const path = tokensPath(projectPath);
     const tokens = await readJson(path, []);
+    const removed = tokens.find((token) => token.integration === integration);
+    if (removed) {
+        await deleteSecretField(removed.accessToken);
+        await deleteSecretField(removed.refreshToken);
+    }
     const filtered = tokens.filter((t) => t.integration !== integration);
-    await writeJson(path, filtered);
+    await writeSecureJson(path, filtered);
 }
 /**
  * List all stored OAuth tokens for a project.
  */
 export async function listOAuthTokens(projectPath) {
-    return readJson(tokensPath(projectPath), []);
+    const tokens = await readJson(tokensPath(projectPath), []);
+    return Promise.all(tokens.map(resolveToken));
 }
 //# sourceMappingURL=oauth-store.js.map

package/dist/storage/path-resolver.js

@@ -6,6 +6,7 @@ import { stat, access } from 'node:fs/promises';
 import { join, dirname } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { constants } from 'node:fs';
+import { reportClassifiedDegradation } from '../errors/classified-degradation.js';
 // ---------------------------------------------------------------------------
 // Session-level cache
 // ---------------------------------------------------------------------------
@@ -22,7 +23,12 @@ async function hasPlanuDir(dir) {
         const s = await stat(join(dir, 'planu'));
         return s.isDirectory();
     }
-    catch {
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return false;
+        }
+        // reliability-optional: PLANU_DIRECTORY_PROBE — inaccessible candidates are skipped
+        reportClassifiedDegradation('PLANU_DIRECTORY_PROBE', error);
         return false;
     }
 }
@@ -32,7 +38,12 @@ export async function isAccessible(p) {
         await access(p, constants.F_OK);
         return true;
     }
-    catch {
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return false;
+        }
+        // reliability-optional: PATH_ACCESS_PROBE — callers consume a boolean probe
+        reportClassifiedDegradation('PATH_ACCESS_PROBE', error);
         return false;
     }
 }
@@ -48,7 +59,9 @@ function detectGitRootSync() {
         }
         return null;
     }
-    catch {
+    catch (error) {
+        // reliability-optional: GIT_ROOT_PROBE — upward directory discovery remains available
+        reportClassifiedDegradation('GIT_ROOT_PROBE', error);
         return null;
     }
 }

package/dist/storage/pr-store.js

@@ -1,8 +1,8 @@
-import { readJson, writeJson, hashProjectPath } from './base-store.js';
+import { readJson, writeJson, hashProjectPath, projectDataDir } from './base-store.js';
 import { withFileLock } from './file-mutex.js';
 function prLinksFile(projectPath) {
     const hash = hashProjectPath(projectPath);
-    return `data/projects/${hash}/pr-links.json`;
+    return `${projectDataDir(hash)}/pr-links.json`;
 }
 /**
  * Load all PR links for a project.

package/dist/storage/project-drift-store.js

@@ -2,9 +2,11 @@
 import { readFile, writeFile, unlink, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { analyzeCommitRecord } from '../engine/project-drift-detector.js';
+import { hashProjectPath, projectDataDir } from './base-store.js';
+import { reportClassifiedDegradation } from '../errors/classified-degradation.js';
 const DRIFT_FILE = 'drift-commits.ndjson';
 function driftFilePath(projectPath) {
-    return join(projectPath, '.planu', DRIFT_FILE);
+    return join(projectDataDir(hashProjectPath(projectPath)), DRIFT_FILE);
 }
 /**
  * Read all unprocessed DriftCommitRecords from .planu/drift-commits.ndjson.
@@ -25,14 +27,20 @@ export async function readDriftCommits(projectPath) {
                     records.push(parsed);
                 }
             }
-            catch {
-                /* skip malformed lines */
+            catch (error) {
+                /* reliability-compat: MALFORMED_DRIFT_LINE — skip malformed historical lines */
+                reportClassifiedDegradation('MALFORMED_DRIFT_LINE', error);
+                continue;
             }
         }
         return records;
     }
-    catch {
-        return [];
+    catch (error) {
+        if (error.code === 'ENOENT' ||
+            (error instanceof Error && error.message === 'ENOENT')) {
+            return [];
+        }
+        throw new Error('Project drift queue is unreadable.', { cause: error });
     }
 }
 /**
@@ -68,8 +76,12 @@ export async function clearDriftCommits(projectPath) {
     try {
         await unlink(driftFilePath(projectPath));
     }
-    catch {
-        /* file doesn't exist — that's fine */
+    catch (error) {
+        /* reliability-cleanup: ABSENT_DRIFT_FILE — idempotent removal */
+        if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT')) {
+            throw error;
+        }
+        reportClassifiedDegradation('ABSENT_DRIFT_FILE', error);
     }
 }
 /**
@@ -77,7 +89,7 @@ export async function clearDriftCommits(projectPath) {
  * Used by tests and the post-commit hook (via shell).
  */
 export async function appendDriftCommit(projectPath, record) {
-    const dir = join(projectPath, '.planu');
+    const dir = projectDataDir(hashProjectPath(projectPath));
     await mkdir(dir, { recursive: true });
     const line = JSON.stringify(record) + '\n';
     await writeFile(driftFilePath(projectPath), line, { flag: 'a', encoding: 'utf-8' });

package/dist/storage/project-identity.d.ts

@@ -0,0 +1,32 @@
+import { type StorageLayout } from './storage-layout.js';
+export interface ProjectIdentity {
+    readonly schemaVersion: 1;
+    readonly logicalProjectId: string;
+    readonly createdAt: string;
+    readonly forkedFrom?: string;
+}
+export interface WorkspaceIdentity {
+    readonly schemaVersion: 1;
+    readonly workspaceId: string;
+    readonly logicalProjectId: string;
+    readonly createdAt: string;
+}
+export interface ResolvedProjectIdentity {
+    readonly project: ProjectIdentity;
+    readonly workspace: WorkspaceIdentity;
+    readonly canonicalProjectPath: string;
+}
+export interface ProjectIdentityOptions {
+    readonly workspaceKey: string;
+    readonly layout?: StorageLayout;
+}
+/** Canonicalize a path without making it an identity source. */
+export declare function canonicalizeProjectPath(projectPath: string): Promise<string>;
+export declare function hashWorkspaceKey(workspaceKey: string): string;
+/** Derive a move-stable local checkout key from filesystem identity when available. */
+export declare function deriveWorkspaceKey(projectPath: string): Promise<string>;
+/** Resolve or create stable project and machine-workspace UUIDs. */
+export declare function ensureProjectIdentity(projectPath: string, options: ProjectIdentityOptions): Promise<ResolvedProjectIdentity>;
+/** Explicitly turn a copied project into an independent logical project. */
+export declare function forkProjectIdentity(projectPath: string, options: ProjectIdentityOptions): Promise<ResolvedProjectIdentity>;
+//# sourceMappingURL=project-identity.d.ts.map

package/dist/storage/project-identity.js

@@ -0,0 +1,194 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, open, readFile, realpath, rename, rm, stat } from 'node:fs/promises';
+import { basename, dirname, join, normalize, resolve, sep } from 'node:path';
+import { resolveStorageLayout } from './storage-layout.js';
+const IDENTITY_VERSION = 1;
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+function isProjectIdentity(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const candidate = value;
+    return (candidate.schemaVersion === IDENTITY_VERSION &&
+        typeof candidate.logicalProjectId === 'string' &&
+        UUID_PATTERN.test(candidate.logicalProjectId) &&
+        typeof candidate.createdAt === 'string' &&
+        (candidate.forkedFrom === undefined || UUID_PATTERN.test(candidate.forkedFrom)));
+}
+function isWorkspaceIdentity(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const candidate = value;
+    return (candidate.schemaVersion === IDENTITY_VERSION &&
+        typeof candidate.workspaceId === 'string' &&
+        UUID_PATTERN.test(candidate.workspaceId) &&
+        typeof candidate.logicalProjectId === 'string' &&
+        UUID_PATTERN.test(candidate.logicalProjectId) &&
+        typeof candidate.createdAt === 'string');
+}
+async function readValidated(filePath, validate) {
+    try {
+        const value = JSON.parse(await readFile(filePath, 'utf8'));
+        if (!validate(value)) {
+            throw new Error(`[Planu] Invalid identity document: ${filePath}`);
+        }
+        return value;
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            return undefined;
+        }
+        throw error;
+    }
+}
+async function createExclusiveJson(filePath, value) {
+    await mkdir(dirname(filePath), { recursive: true });
+    try {
+        const handle = await open(filePath, 'wx', 0o600);
+        try {
+            await handle.writeFile(`${JSON.stringify(value, null, 2)}\n`, 'utf8');
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        return value;
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'EEXIST') {
+            throw error;
+        }
+        throw error;
+    }
+}
+/** Canonicalize a path without making it an identity source. */
+export async function canonicalizeProjectPath(projectPath) {
+    if (!projectPath.trim()) {
+        throw new Error('[Planu] projectPath is required');
+    }
+    const absolute = resolve(projectPath);
+    const info = await stat(absolute);
+    if (!info.isDirectory()) {
+        throw new Error('[Planu] projectPath must be a directory');
+    }
+    const physical = normalize(await realpath(absolute));
+    const slashNormalized = sep === '\\' ? physical.replaceAll('\\', '/') : physical;
+    return process.platform === 'win32' ? slashNormalized.toLowerCase() : slashNormalized;
+}
+export function hashWorkspaceKey(workspaceKey) {
+    const normalizedKey = workspaceKey.trim();
+    if (!normalizedKey || normalizedKey.length > 1_024) {
+        throw new Error('[Planu] workspaceKey is required and must not exceed 1024 characters');
+    }
+    return createHash('sha256').update(normalizedKey).digest('hex');
+}
+/** Derive a move-stable local checkout key from filesystem identity when available. */
+export async function deriveWorkspaceKey(projectPath) {
+    const canonicalPath = await canonicalizeProjectPath(projectPath);
+    const info = await stat(canonicalPath);
+    if (info.dev !== 0 && info.ino !== 0) {
+        return `fs:${process.platform}:${info.dev.toString()}:${info.ino.toString()}`;
+    }
+    // Filesystems without stable inode identity still remain isolated by physical path.
+    return `path:${process.platform}:${canonicalPath}`;
+}
+function workspaceIdentityPath(layout, workspaceKey, logicalProjectId) {
+    const keyHash = hashWorkspaceKey(workspaceKey);
+    return join(layout.state, 'workspaces', 'identities', keyHash, `${logicalProjectId}.json`);
+}
+async function ensureProjectDocument(projectPath) {
+    const filePath = join(projectPath, 'planu', 'project.json');
+    const existing = await readValidated(filePath, isProjectIdentity);
+    if (existing) {
+        return existing;
+    }
+    const created = {
+        schemaVersion: IDENTITY_VERSION,
+        logicalProjectId: randomUUID(),
+        createdAt: new Date().toISOString(),
+    };
+    try {
+        return await createExclusiveJson(filePath, created);
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'EEXIST') {
+            const raced = await readValidated(filePath, isProjectIdentity);
+            if (raced) {
+                return raced;
+            }
+        }
+        throw error;
+    }
+}
+async function ensureWorkspaceDocument(layout, workspaceKey, logicalProjectId) {
+    const filePath = workspaceIdentityPath(layout, workspaceKey, logicalProjectId);
+    const existing = await readValidated(filePath, isWorkspaceIdentity);
+    if (existing) {
+        if (existing.logicalProjectId !== logicalProjectId) {
+            throw new Error('[Planu] Workspace identity belongs to a different logical project');
+        }
+        return existing;
+    }
+    const created = {
+        schemaVersion: IDENTITY_VERSION,
+        workspaceId: randomUUID(),
+        logicalProjectId,
+        createdAt: new Date().toISOString(),
+    };
+    try {
+        return await createExclusiveJson(filePath, created);
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'EEXIST') {
+            const raced = await readValidated(filePath, isWorkspaceIdentity);
+            if (raced) {
+                return raced;
+            }
+        }
+        throw error;
+    }
+}
+/** Resolve or create stable project and machine-workspace UUIDs. */
+export async function ensureProjectIdentity(projectPath, options) {
+    const canonicalProjectPath = await canonicalizeProjectPath(projectPath);
+    const project = await ensureProjectDocument(canonicalProjectPath);
+    const workspace = await ensureWorkspaceDocument(options.layout ?? resolveStorageLayout(), options.workspaceKey, project.logicalProjectId);
+    return { project, workspace, canonicalProjectPath };
+}
+/** Explicitly turn a copied project into an independent logical project. */
+export async function forkProjectIdentity(projectPath, options) {
+    const canonicalProjectPath = await canonicalizeProjectPath(projectPath);
+    const identityPath = join(canonicalProjectPath, 'planu', 'project.json');
+    const previous = await readValidated(identityPath, isProjectIdentity);
+    if (!previous) {
+        throw new Error('[Planu] Cannot fork a project without an existing identity');
+    }
+    const next = {
+        schemaVersion: IDENTITY_VERSION,
+        logicalProjectId: randomUUID(),
+        createdAt: new Date().toISOString(),
+        forkedFrom: previous.logicalProjectId,
+    };
+    // Prepare the new workspace document first. A crash before the identity rename
+    // leaves only an unreachable orphan; a crash after it leaves a complete pair.
+    const workspace = await ensureWorkspaceDocument(options.layout ?? resolveStorageLayout(), options.workspaceKey, next.logicalProjectId);
+    const temporary = join(dirname(identityPath), `.${basename(identityPath)}.${randomUUID()}.tmp`);
+    const handle = await open(temporary, 'wx', 0o600);
+    try {
+        await handle.writeFile(`${JSON.stringify(next, null, 2)}\n`, 'utf8');
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    try {
+        await rename(temporary, identityPath);
+    }
+    catch (error) {
+        await rm(temporary, { force: true });
+        throw error;
+    }
+    return { project: next, workspace, canonicalProjectPath };
+}
+//# sourceMappingURL=project-identity.js.map

package/dist/storage/project-resolver.js

@@ -6,6 +6,7 @@ import { access } from 'node:fs/promises';
 import { join } from 'node:path';
 import { getKnowledge, saveKnowledge } from './knowledge-store/knowledge.js';
 import { hashProjectPath, projectDataDir } from './base-store.js';
+import { reportClassifiedDegradation } from '../errors/classified-degradation.js';
 /**
  * Check whether a file/directory path exists on disk (no-throw helper).
  */
@@ -14,8 +15,12 @@ async function pathExists(p) {
         await access(p);
         return true;
     }
-    catch {
-        return false;
+    catch (error) {
+        if (error.code === 'ENOENT' ||
+            (error instanceof Error && error.message === 'ENOENT')) {
+            return false;
+        }
+        throw error;
     }
 }
 /**
@@ -51,7 +56,7 @@ export async function resolveProjectFromPath(projectPath) {
     ]);
     let matchedFingerprint = null;
     if (dataDirExists) {
-        matchedFingerprint = `data/projects/${projectId}/ exists`;
+        matchedFingerprint = 'canonical project data exists';
     }
     else if (planuDirExists && (statusJsonExists || specsDirExists)) {
         matchedFingerprint = statusJsonExists
@@ -66,8 +71,9 @@ export async function resolveProjectFromPath(projectPath) {
     try {
         await saveKnowledge(projectId, minimalKnowledge);
     }
-    catch {
-        // If save fails, still return the minimal knowledge so the caller can proceed this call
+    catch (error) {
+        // reliability-optional: MINIMAL_KNOWLEDGE_CACHE — caller can proceed with in-memory knowledge
+        reportClassifiedDegradation('MINIMAL_KNOWLEDGE_CACHE', error);
     }
     // Log the silent recovery for observability (best-effort, fire-and-forget)
     void logSilentRecovery(projectId, projectPath, matchedFingerprint);
@@ -87,8 +93,9 @@ async function logSilentRecovery(projectId, projectPath, reason) {
             ...{ event: 'silent_project_recovery', projectPath, reason },
         });
     }
-    catch {
-        // best-effort — log failure must never block project resolution
+    catch (error) {
+        // reliability-optional: RECOVERY_OBSERVABILITY_LOG — log failure must not block resolution
+        reportClassifiedDegradation('RECOVERY_OBSERVABILITY_LOG', error);
     }
 }
 /** Build a minimal but valid ProjectKnowledge entry for a recovered project. */

package/dist/storage/release-notes-store.js

@@ -1,14 +1,10 @@
 // storage/release-notes-store.ts — SPEC-438: Persistence for release notes config
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { join, dirname } from 'node:path';
-import { createHash } from 'node:crypto';
-import { safeJsonParse } from './base-store.js';
-function hashProjectPath(p) {
-    return createHash('sha256').update(p).digest('hex').slice(0, 16);
-}
+import { hashProjectPath, projectDataDir, safeJsonParse } from './base-store.js';
 function configFile(projectPath) {
     const hash = hashProjectPath(projectPath);
-    return join('data', 'projects', hash, 'release-notes-config.json');
+    return join(projectDataDir(hash), 'release-notes-config.json');
 }
 /**
  * Load the release notes config for a project.