@planu/cli 4.13.0 → 5.0.0

package/dist/security/secret-provider.js

@@ -0,0 +1,145 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+import { LinuxSecretServiceAdapter } from './adapters/linux-secret-service.js';
+import { MacOSKeychainAdapter } from './adapters/macos-keychain.js';
+import { WindowsCredentialManagerAdapter } from './adapters/windows-credential-manager.js';
+export { EnvironmentSecretAdapter } from './adapters/environment.js';
+const REFERENCE_PREFIX = 'planu-secret:v1:';
+const SECRET_ID = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$/u;
+const PROVIDERS = new Set([
+    'macos-keychain',
+    'linux-secret-service',
+    'windows-credential-manager',
+    'environment',
+]);
+const PURPOSES = new Set([
+    'license',
+    'oauth-access',
+    'oauth-refresh',
+    'registry-pat',
+    'figma-pat',
+    'supabase-service-role',
+    'supabase-anon',
+    'sentry-auth',
+    'slack-webhook',
+    'validation-signing',
+]);
+export class SecretProviderError extends Error {
+    code;
+    constructor(code) {
+        super(`[Planu] ${code}`);
+        this.code = code;
+        this.name = 'SecretProviderError';
+    }
+}
+export function formatSecretReference(reference) {
+    const id = Buffer.from(reference.id, 'utf8').toString('base64url');
+    return `${REFERENCE_PREFIX}${reference.provider}:${reference.purpose}:${id}`;
+}
+export function parseSecretReference(value) {
+    const parts = value.split(':');
+    if (parts.length !== 5 || `${parts[0]}:${parts[1]}:` !== REFERENCE_PREFIX) {
+        throw new SecretProviderError('SECRET_REFERENCE_INVALID');
+    }
+    const provider = parts[2];
+    const purpose = parts[3];
+    const encodedId = parts[4];
+    if (!provider || !purpose || !encodedId) {
+        throw new SecretProviderError('SECRET_REFERENCE_INVALID');
+    }
+    const id = Buffer.from(encodedId, 'base64url').toString('utf8');
+    if (!PROVIDERS.has(provider) ||
+        !PURPOSES.has(purpose)) {
+        throw new SecretProviderError('SECRET_REFERENCE_INVALID');
+    }
+    const reference = { schemaVersion: 1, provider, purpose, id };
+    if (formatSecretReference(reference) !== value || !SECRET_ID.test(id)) {
+        throw new SecretProviderError('SECRET_REFERENCE_INVALID');
+    }
+    return reference;
+}
+export function isSecretReference(value) {
+    if (typeof value !== 'string' || !value.startsWith(REFERENCE_PREFIX)) {
+        return false;
+    }
+    try {
+        parseSecretReference(value);
+        return true;
+    }
+    catch (error) {
+        if (error instanceof SecretProviderError && error.code === 'SECRET_REFERENCE_INVALID') {
+            return false;
+        }
+        throw error;
+    }
+}
+function sameSecret(left, right) {
+    const leftDigest = createHash('sha256').update(left).digest();
+    const rightDigest = createHash('sha256').update(right).digest();
+    return timingSafeEqual(leftDigest, rightDigest);
+}
+export class SecretProvider {
+    adapter;
+    constructor(adapter) {
+        this.adapter = adapter;
+    }
+    reference(id, purpose) {
+        if (!SECRET_ID.test(id)) {
+            throw new SecretProviderError('SECRET_REFERENCE_INVALID');
+        }
+        return { schemaVersion: 1, provider: this.adapter.kind, id, purpose };
+    }
+    async store(reference, value) {
+        this.assertOwned(reference);
+        if (!value.trim()) {
+            throw new SecretProviderError('SECRET_VERIFY_FAILED');
+        }
+        await this.adapter.set(reference.id, value);
+        const verified = await this.adapter.get(reference.id);
+        if (verified === null || !sameSecret(verified, value)) {
+            await this.adapter.delete(reference.id);
+            throw new SecretProviderError('SECRET_VERIFY_FAILED');
+        }
+    }
+    async resolve(reference) {
+        this.assertOwned(reference);
+        const value = await this.adapter.get(reference.id);
+        if (value === null) {
+            throw new SecretProviderError('SECRET_NOT_FOUND');
+        }
+        return value;
+    }
+    async delete(reference) {
+        this.assertOwned(reference);
+        await this.adapter.delete(reference.id);
+    }
+    assertOwned(reference) {
+        if (reference.provider !== this.adapter.kind || !SECRET_ID.test(reference.id)) {
+            throw new SecretProviderError('SECRET_REFERENCE_INVALID');
+        }
+    }
+}
+function platformAdapter() {
+    if (process.platform === 'darwin') {
+        return new MacOSKeychainAdapter();
+    }
+    if (process.platform === 'linux') {
+        return new LinuxSecretServiceAdapter();
+    }
+    if (process.platform === 'win32') {
+        return new WindowsCredentialManagerAdapter();
+    }
+    throw new Error(`[Planu] Unsupported secure secret store platform: ${process.platform}`);
+}
+let configuredProvider;
+export function getSecretProvider() {
+    configuredProvider ??= new SecretProvider(platformAdapter());
+    return configuredProvider;
+}
+/** Explicitly configure a provider (including the environment adapter) before secret access. */
+export function configureSecretProvider(provider) {
+    configuredProvider = provider;
+}
+export function resetSecretProviderForTests() {
+    configuredProvider = undefined;
+}
+//# sourceMappingURL=secret-provider.js.map

package/dist/security/secure-json.d.ts

@@ -0,0 +1,3 @@
+/** Atomically write a secret-reference projection without plaintext backup rotation. */
+export declare function writeSecureJson(path: string, value: unknown): Promise<void>;
+//# sourceMappingURL=secure-json.d.ts.map

package/dist/security/secure-json.js

@@ -0,0 +1,29 @@
+import { randomBytes } from 'node:crypto';
+import { chmod, mkdir, rename, unlink, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+/** Atomically write a secret-reference projection without plaintext backup rotation. */
+export async function writeSecureJson(path, value) {
+    const directory = dirname(path);
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    await chmod(directory, 0o700);
+    const temporary = `${path}.tmp.${process.pid.toString()}.${randomBytes(4).toString('hex')}`;
+    try {
+        await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600, flag: 'wx' });
+        await rename(temporary, path);
+        await chmod(path, 0o600);
+    }
+    catch (error) {
+        try {
+            await unlink(temporary);
+        }
+        catch (cleanupError) {
+            if (cleanupError.code !== 'ENOENT') {
+                throw new AggregateError([error, cleanupError], 'Secure JSON write and cleanup failed.', {
+                    cause: cleanupError,
+                });
+            }
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=secure-json.js.map

package/dist/server/routes/specs.js

@@ -25,6 +25,11 @@ const VALID_STATUSES = [
     'done',
     'discarded',
 ];
+function containsReconciliationAuthorityFields(body) {
+    return ('reconciliationRequestId' in body ||
+        'expectedImplementingTransitionId' in body ||
+        'implementationReviewDigest' in body);
+}
 /** Resolve projectPath from the request Host header or fallback to process.cwd(). */
 function getProjectPath(ctx) {
     // The server is started with a projectPath; it is injected via the request context
@@ -188,6 +193,11 @@ export async function handleUpdateSpecStatus(ctx) {
         return;
     }
     const { status } = body;
+    if (containsReconciliationAuthorityFields(body)) {
+        ctx.res.writeHead(403, { 'Content-Type': 'application/json' });
+        ctx.res.end(JSON.stringify({ error: 'Reconciliation is available only through local MCP.' }));
+        return;
+    }
     if (typeof status !== 'string' || !VALID_STATUSES.includes(status)) {
         sendBadRequest(ctx.res, `Field "status" is required. Valid values: ${VALID_STATUSES.join(', ')}`);
         return;

package/dist/storage/api-surfaces-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 surfacesFile(projectPath) {
     const hash = hashProjectPath(projectPath);
-    return `data/projects/${hash}/api-surfaces.json`;
+    return `${projectDataDir(hash)}/api-surfaces.json`;
 }
 /** Load all API surfaces for a project. */
 export async function loadApiSurfaces(projectPath) {

package/dist/storage/approval-operation-lock.d.ts

@@ -6,5 +6,5 @@ export declare class ApprovalOperationBusyError extends Error {
  * processes. Reentrancy lets request_changes invoke update_status while retaining
  * the same outer exclusion boundary.
  */
-export declare function withApprovalSpecLock<T>(projectPath: string, specId: string, fn: () => Promise<T>): Promise<T>;
+export declare function withApprovalSpecLock<T>(projectPathOrId: string, specId: string, fn: () => Promise<T>): Promise<T>;
 //# sourceMappingURL=approval-operation-lock.d.ts.map

package/dist/storage/approval-operation-lock.js

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto';
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { resolve } from 'node:path';
+import { isAbsolute, resolve } from 'node:path';
 import { withFileLock } from './file-mutex.js';
 import { LockBusyError, withSpecLock } from '../engine/safety/cross-process-lock.js';
 const heldApprovalLocks = new AsyncLocalStorage();
@@ -19,8 +19,10 @@ export class ApprovalOperationBusyError extends Error {
  * processes. Reentrancy lets request_changes invoke update_status while retaining
  * the same outer exclusion boundary.
  */
-export async function withApprovalSpecLock(projectPath, specId, fn) {
-    const normalizedProjectPath = resolve(projectPath);
+export async function withApprovalSpecLock(projectPathOrId, specId, fn) {
+    const normalizedProjectPath = isAbsolute(projectPathOrId)
+        ? resolve(projectPathOrId)
+        : projectPathOrId;
     const lockId = approvalLockId(specId);
     const localLockKey = `${normalizedProjectPath}\0${lockId}`;
     const heldLocks = heldApprovalLocks.getStore();

package/dist/storage/audit-trail-store.d.ts

@@ -2,7 +2,7 @@ import type { AuditTrailEntry, AuditReadFilters } from '../types/audit.js';
 /**
  * Append a single AuditTrailEntry to the JSONL file.
  * Synchronous to guarantee ordering relative to tool responses.
- * Never throws — errors are swallowed so audit failures never affect tool execution.
+ * Fails closed: callers must observe and handle an audit persistence failure.
  */
 export declare function appendEntry(entry: AuditTrailEntry): void;
 /**

package/dist/storage/audit-trail-store.js

@@ -1,29 +1,26 @@
 // storage/audit-trail-store.ts — Append-only JSONL store for SPEC-387 EU AI Act audit trail
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
 import { join, dirname } from 'node:path';
-import { safeJsonParse } from './base-store.js';
+import { globalDataDir } from './base-store.js';
 /** Path to the global audit trail JSONL file. */
-const AUDIT_FILE = join(process.cwd(), 'data', 'global', 'audit-trail.jsonl');
-/** Ensure the data/global directory exists (called at module load). */
+function auditFile() {
+    return join(globalDataDir(), 'audit-trail.jsonl');
+}
+/** Ensure the global data directory exists immediately before a write. */
 function ensureDataDir() {
-    const dir = dirname(AUDIT_FILE);
+    const dir = dirname(auditFile());
     if (!existsSync(dir)) {
         mkdirSync(dir, { recursive: true });
     }
 }
-ensureDataDir();
 /**
  * Append a single AuditTrailEntry to the JSONL file.
  * Synchronous to guarantee ordering relative to tool responses.
- * Never throws — errors are swallowed so audit failures never affect tool execution.
+ * Fails closed: callers must observe and handle an audit persistence failure.
  */
 export function appendEntry(entry) {
-    try {
-        writeFileSync(AUDIT_FILE, JSON.stringify(entry) + '\n', { flag: 'a', encoding: 'utf-8' });
-    }
-    catch {
-        // Silent — audit must never affect tool execution
-    }
+    ensureDataDir();
+    writeFileSync(auditFile(), JSON.stringify(entry) + '\n', { flag: 'a', encoding: 'utf-8' });
 }
 /**
  * Read the hash of the last stored entry.
@@ -31,67 +28,56 @@ export function appendEntry(entry) {
  * Used to build the prevHash for the next entry.
  */
 export function getLastHash() {
-    try {
-        if (!existsSync(AUDIT_FILE)) {
-            return '';
-        }
-        const content = readFileSync(AUDIT_FILE, 'utf-8');
-        const lines = content.split('\n').filter((l) => l.trim().length > 0);
-        if (lines.length === 0) {
-            return '';
-        }
-        const lastLine = lines[lines.length - 1] ?? '';
-        const parsed = safeJsonParse(lastLine, {});
-        return typeof parsed.hash === 'string' ? parsed.hash : '';
+    if (!existsSync(auditFile())) {
+        return '';
     }
-    catch {
+    const content = readFileSync(auditFile(), 'utf-8');
+    const lines = content.split('\n').filter((l) => l.trim().length > 0);
+    if (lines.length === 0) {
         return '';
     }
+    const parsed = JSON.parse(lines[lines.length - 1] ?? '');
+    if (typeof parsed.hash !== 'string') {
+        throw new Error('Audit trail tail is missing its hash.');
+    }
+    return parsed.hash;
 }
 /**
  * Read all entries from the JSONL file and apply optional filters.
  * Returns an empty array if the file does not exist or is unreadable.
  */
 export function readEntries(filters) {
-    try {
-        if (!existsSync(AUDIT_FILE)) {
-            return [];
-        }
-        const content = readFileSync(AUDIT_FILE, 'utf-8');
-        const lines = content.split('\n').filter((l) => l.trim().length > 0);
-        let entries = [];
-        for (const line of lines) {
-            const entry = safeJsonParse(line, null);
-            if (entry !== null) {
-                entries.push(entry);
-            }
-        }
-        if (filters === undefined) {
-            return entries;
-        }
-        if (filters.fromDate !== undefined) {
-            const from = filters.fromDate;
-            entries = entries.filter((e) => e.timestamp >= from);
-        }
-        if (filters.toDate !== undefined) {
-            const to = filters.toDate;
-            entries = entries.filter((e) => e.timestamp <= to);
-        }
-        if (filters.specId !== undefined) {
-            const sid = filters.specId;
-            entries = entries.filter((e) => e.specId === sid);
-        }
-        if (filters.projectPath !== undefined) {
-            const pp = filters.projectPath;
-            entries = entries.filter((e) => e.projectPath === pp);
-        }
-        if (filters.limit !== undefined && filters.limit > 0) {
-            entries = entries.slice(0, filters.limit);
-        }
+    if (!existsSync(auditFile())) {
+        return [];
+    }
+    const content = readFileSync(auditFile(), 'utf-8');
+    const lines = content.split('\n').filter((l) => l.trim().length > 0);
+    let entries = [];
+    for (const line of lines) {
+        entries.push(JSON.parse(line));
+    }
+    if (filters === undefined) {
         return entries;
     }
-    catch {
-        return [];
+    if (filters.fromDate !== undefined) {
+        const from = filters.fromDate;
+        entries = entries.filter((e) => e.timestamp >= from);
+    }
+    if (filters.toDate !== undefined) {
+        const to = filters.toDate;
+        entries = entries.filter((e) => e.timestamp <= to);
+    }
+    if (filters.specId !== undefined) {
+        const sid = filters.specId;
+        entries = entries.filter((e) => e.specId === sid);
+    }
+    if (filters.projectPath !== undefined) {
+        const pp = filters.projectPath;
+        entries = entries.filter((e) => e.projectPath === pp);
+    }
+    if (filters.limit !== undefined && filters.limit > 0) {
+        entries = entries.slice(0, filters.limit);
     }
+    return entries;
 }
 //# sourceMappingURL=audit-trail-store.js.map

package/dist/storage/autopilot-log-store.js

@@ -2,9 +2,11 @@
 import { readFile, mkdir } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { atomicWriteFile } from '../engine/safety/atomic-write-file.js';
+import { reportClassifiedDegradation } from '../errors/classified-degradation.js';
+import { projectDataDir } from './base-store.js';
 const MAX_ENTRIES = 500;
 function logPath(projectId) {
-    return join('data', 'projects', projectId, 'autopilot-log.jsonl');
+    return join(projectDataDir(projectId), 'autopilot-log.jsonl');
 }
 /** Read all entries from autopilot-log.jsonl. Returns empty array if file missing. */
 async function readEntries(path) {
@@ -15,8 +17,12 @@ async function readEntries(path) {
             .filter(Boolean)
             .map((line) => JSON.parse(line));
     }
-    catch {
-        return [];
+    catch (error) {
+        if (error.code === 'ENOENT' ||
+            (error instanceof Error && error.message === 'ENOENT')) {
+            return [];
+        }
+        throw error;
     }
 }
 /**
@@ -32,8 +38,9 @@ export async function appendAutopilotLogEntry(projectId, entry) {
         const updated = [...existing, entry].slice(-MAX_ENTRIES);
         await atomicWriteFile(path, updated.map((e) => JSON.stringify(e)).join('\n') + '\n');
     }
-    catch {
-        // best-effort — never block caller
+    catch (error) {
+        // reliability-optional: AUTOPILOT_LOG_APPEND — never block caller
+        reportClassifiedDegradation('AUTOPILOT_LOG_APPEND', error);
     }
 }
 /**

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

@@ -21,9 +21,7 @@ export declare class CriticalJsonReadError extends Error {
         cause?: unknown;
     });
 }
-/**
- * Hash a project path into a deterministic projectId using SHA-256.
- */
+/** Resolve the portable logical identity for an initialized project. */
 export declare function hashProjectPath(projectPath: string): string;
 /**
  * Read a JSON file from disk. Returns the parsed contents, or the provided
@@ -45,21 +43,23 @@ export declare function readCriticalJson<T>(filePath: string, defaultValue: T, o
 export declare function writeJson(filePath: string, data: unknown): Promise<void>;
 /**
  * Resolve the data directory for a given project.
- * Layout: ~/.planu/data/projects/{projectId}/ (absolute, independent of cwd)
+ * Layout: <platform-data-root>/planu/projects/{projectId}/ (absolute, independent of cwd)
  *
  * Symmetric with globalDataDir(). Override via PLANU_PROJECT_DATA_DIR
- * environment variable (useful in tests and CI).
+ * environment variable (useful in tests and CI). PLANU_HOME is the canonical
+ * product-wide override.
  *
- * Validates that projectId is a safe hex hash (no path traversal).
- * projectId is always produced by hashProjectPath(), which returns a 16-char hex string.
+ * Validates that projectId is a safe logical storage identifier (no path traversal).
+ * Canonical initialized projects use the 32-character UUID form returned by
+ * hashProjectPath(); explicit internal fixture IDs remain supported by this path port.
  */
 export declare function projectDataDir(projectId: string): string;
 /**
  * Resolve the global data directory.
- * Layout: ~/.planu/data/global/ (absolute, independent of cwd)
+ * Layout: <platform-data-root>/planu/global/ (absolute, independent of cwd)
  *
  * Using an absolute path anchored to the user's home directory ensures that
- * global state (license, usage, registered projects) persists across sessions
+ * global state (usage and registered projects) persists across sessions
  * regardless of which project directory the MCP server is started from.
  *
  * Override via PLANU_GLOBAL_DATA_DIR environment variable (useful in tests

package/dist/storage/base-store.js

@@ -1,10 +1,11 @@
 // @crash-shield-ignore-file — config/cache reader for Planu-controlled JSON; writer is this codebase, shape guaranteed by build/seed.
 // base-store.ts — Shared JSON read/write logic for all stores
 import { readFile, mkdir } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
-import { homedir } from 'node:os';
+import { readFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { writeJsonSafe } from '../engine/safety/atomic-writer.js';
-import { fastHashProjectPath } from '../engine/core-bridge.js';
+import { resolveStorageLayout } from './storage-layout.js';
+import { reportClassifiedDegradation } from '../errors/classified-degradation.js';
 /**
  * Runtime-safe JSON.parse with typed fallback.
  *
@@ -28,7 +29,9 @@ export function safeJsonParse(raw, fallback) {
         }
         return parsed;
     }
-    catch {
+    catch (error) {
+        // reliability-compat: SAFE_JSON_PARSE_FALLBACK — callers explicitly supply the fallback
+        reportClassifiedDegradation('SAFE_JSON_PARSE_FALLBACK', error);
         return fallback;
     }
 }
@@ -42,11 +45,35 @@ export class CriticalJsonReadError extends Error {
         this.name = 'CriticalJsonReadError';
     }
 }
-/**
- * Hash a project path into a deterministic projectId using SHA-256.
- */
+/** Resolve the portable logical identity for an initialized project. */
 export function hashProjectPath(projectPath) {
-    return fastHashProjectPath(projectPath).slice(0, 16);
+    if (!projectPath.trim()) {
+        throw new Error('[Planu] projectPath is required');
+    }
+    if (!isAbsolute(projectPath)) {
+        throw new Error('[Planu] projectPath must be absolute');
+    }
+    if (projectPath.includes('\0') || projectPath.length > 4_096) {
+        throw new Error('[Planu] projectPath is invalid');
+    }
+    const identityPath = join(projectPath, 'planu', 'project.json');
+    try {
+        const identity = JSON.parse(readFileSync(identityPath, 'utf8'));
+        if (identity && typeof identity === 'object' && 'logicalProjectId' in identity) {
+            const logicalId = identity.logicalProjectId;
+            if (typeof logicalId === 'string' &&
+                /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(logicalId)) {
+                return logicalId.replaceAll('-', '').toLowerCase();
+            }
+        }
+        throw new Error('[Planu] project identity document is invalid');
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.includes('identity document is invalid')) {
+            throw error;
+        }
+        throw new Error(`[Planu] Project identity is unavailable at ${identityPath}. Run planu init first.`, { cause: error });
+    }
 }
 /**
  * Ensure the parent directory for a file path exists.
@@ -118,40 +145,50 @@ export async function writeJson(filePath, data) {
 }
 /**
  * Resolve the data directory for a given project.
- * Layout: ~/.planu/data/projects/{projectId}/ (absolute, independent of cwd)
+ * Layout: <platform-data-root>/planu/projects/{projectId}/ (absolute, independent of cwd)
  *
  * Symmetric with globalDataDir(). Override via PLANU_PROJECT_DATA_DIR
- * environment variable (useful in tests and CI).
+ * environment variable (useful in tests and CI). PLANU_HOME is the canonical
+ * product-wide override.
  *
- * Validates that projectId is a safe hex hash (no path traversal).
- * projectId is always produced by hashProjectPath(), which returns a 16-char hex string.
+ * Validates that projectId is a safe logical storage identifier (no path traversal).
+ * Canonical initialized projects use the 32-character UUID form returned by
+ * hashProjectPath(); explicit internal fixture IDs remain supported by this path port.
  */
 export function projectDataDir(projectId) {
-    if (!projectId ||
-        projectId.includes('..') ||
-        projectId.includes('/') ||
-        projectId.includes('\\')) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(projectId)) {
         throw new Error(`[Planu] Invalid projectId: "${projectId}"`);
     }
-    const root = process.env.PLANU_PROJECT_DATA_DIR ?? join(homedir(), '.planu', 'data');
-    return `${root}/projects/${projectId}`;
+    const override = absoluteStorageOverride('PLANU_PROJECT_DATA_DIR');
+    const root = override ?? resolveStorageLayout().data;
+    return join(root, 'projects', projectId);
 }
 /**
  * Resolve the global data directory.
- * Layout: ~/.planu/data/global/ (absolute, independent of cwd)
+ * Layout: <platform-data-root>/planu/global/ (absolute, independent of cwd)
  *
  * Using an absolute path anchored to the user's home directory ensures that
- * global state (license, usage, registered projects) persists across sessions
+ * global state (usage and registered projects) persists across sessions
  * regardless of which project directory the MCP server is started from.
  *
  * Override via PLANU_GLOBAL_DATA_DIR environment variable (useful in tests
  * and CI environments where HOME is not writable).
  */
 export function globalDataDir() {
-    return process.env.PLANU_GLOBAL_DATA_DIR ?? join(homedir(), '.planu', 'data', 'global');
+    return (absoluteStorageOverride('PLANU_GLOBAL_DATA_DIR') ?? join(resolveStorageLayout().data, 'global'));
 }
 // --- internal helpers ---
 function isNodeError(err) {
     return err instanceof Error && 'code' in err;
 }
+function absoluteStorageOverride(name) {
+    const value = process.env[name]?.trim();
+    if (!value) {
+        return undefined;
+    }
+    if (!isAbsolute(value)) {
+        throw new Error(`[Planu] ${name} must be an absolute path`);
+    }
+    return resolve(value);
+}
 //# sourceMappingURL=base-store.js.map

package/dist/storage/checkpoint-store.js

@@ -94,8 +94,11 @@ async function listCheckpointFiles(dir) {
         const entries = await readdir(dir);
         return entries.filter((f) => f.endsWith('.json')).sort();
     }
-    catch {
-        return [];
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return [];
+        }
+        throw error;
     }
 }
 //# sourceMappingURL=checkpoint-store.js.map

package/dist/storage/comments-store.js

@@ -38,8 +38,8 @@ function readComments(filePath) {
         }
         return parsed;
     }
-    catch {
-        return [];
+    catch (error) {
+        throw new Error(`Comments store is corrupt: ${filePath}`, { cause: error });
     }
 }
 function writeComments(filePath, comments) {

package/dist/storage/compliance-audit-store.js

@@ -39,8 +39,11 @@ export async function countComplianceAuditEvents(projectId) {
         const content = await readFile(file, 'utf-8');
         return content.split('\n').filter(Boolean).length;
     }
-    catch {
-        return 0;
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return 0;
+        }
+        throw error;
     }
 }
 //# sourceMappingURL=compliance-audit-store.js.map