@planu/cli 4.12.3 → 4.14.1

package/dist/storage/schema-registry.d.ts

@@ -0,0 +1,5 @@
+import type { CriticalSchema, VersionedDocument } from '../types/schema-registry.js';
+export declare function registerCriticalSchema<T>(schema: CriticalSchema<T>): void;
+export declare function readCriticalSchema<T>(filePath: string, schemaName: string): Promise<VersionedDocument<T>>;
+export declare function decodeCriticalSchema<T>(parsed: unknown, schemaName: string): VersionedDocument<T>;
+//# sourceMappingURL=schema-registry.d.ts.map

package/dist/storage/schema-registry.js

@@ -0,0 +1,74 @@
+import { readFile } from 'node:fs/promises';
+import { BoundaryFailure, classifyBoundaryFailure } from '../errors/error-taxonomy.js';
+const schemas = new Map();
+export function registerCriticalSchema(schema) {
+    if (!schema.name.trim() ||
+        !Number.isSafeInteger(schema.currentVersion) ||
+        schema.currentVersion < 1) {
+        throw new BoundaryFailure('IncompatibleVersion', 'schema registration', 'Register a named schema with a positive integer version.');
+    }
+    if (schemas.has(schema.name)) {
+        const existing = schemas.get(schema.name);
+        if (existing === schema) {
+            return;
+        }
+        throw new BoundaryFailure('Conflict', 'schema registration', `Schema ${schema.name} is already registered and cannot be replaced.`);
+    }
+    schemas.set(schema.name, schema);
+}
+export async function readCriticalSchema(filePath, schemaName) {
+    const schema = schemas.get(schemaName);
+    if (!schema) {
+        throw new BoundaryFailure('IncompatibleVersion', 'critical schema read', `Register schema ${schemaName} before reading persistent state.`);
+    }
+    let raw;
+    try {
+        raw = await readFile(filePath, 'utf8');
+    }
+    catch (error) {
+        const failure = classifyBoundaryFailure(error, `read ${schema.name}`, 'Restore access to the state file or initialize it if it does not exist.');
+        if (failure.kind === 'NotFound') {
+            return { schemaVersion: schema.currentVersion, data: schema.createDefault() };
+        }
+        throw failure;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new BoundaryFailure('Corrupt', `read ${schema.name}`, 'Recover the original file; Planu will not replace corrupt state with defaults.');
+    }
+    return decodeCriticalSchema(parsed, schemaName);
+}
+export function decodeCriticalSchema(parsed, schemaName) {
+    const schema = schemas.get(schemaName);
+    if (!schema) {
+        throw new BoundaryFailure('IncompatibleVersion', 'critical schema decode', `Register schema ${schemaName} before decoding persistent state.`);
+    }
+    const isEnvelope = parsed !== null && typeof parsed === 'object' && 'schemaVersion' in parsed && 'data' in parsed;
+    const document = isEnvelope
+        ? parsed
+        : { schemaVersion: 0, data: parsed };
+    if (typeof document.schemaVersion !== 'number' || !Number.isSafeInteger(document.schemaVersion)) {
+        throw new BoundaryFailure('Corrupt', `read ${schema.name}`, 'Recover a versioned document.');
+    }
+    if (document.schemaVersion > schema.currentVersion || document.schemaVersion < 0) {
+        throw new BoundaryFailure('IncompatibleVersion', `read ${schema.name}`, `Use a Planu runtime compatible with schema version ${String(document.schemaVersion)}.`);
+    }
+    let data;
+    try {
+        data =
+            document.schemaVersion === schema.currentVersion
+                ? document.data
+                : schema.migrate?.(document.data, document.schemaVersion);
+    }
+    catch {
+        throw new BoundaryFailure('IncompatibleVersion', `migrate ${schema.name}`, `Use a supported migration path to schema version ${String(schema.currentVersion)}.`);
+    }
+    if (data === undefined || !schema.validate(data)) {
+        throw new BoundaryFailure('Corrupt', `read ${schema.name}`, 'Recover state that satisfies the registered schema; no overwrite was performed.');
+    }
+    return { schemaVersion: schema.currentVersion, data };
+}
+//# sourceMappingURL=schema-registry.js.map

package/dist/storage/sentry-store.js

@@ -1,22 +1,33 @@
+import { technologyValue } from '../engine/technology-registry.js';
 // storage/sentry-store.ts — Sentry integration persistence (SPEC-435)
-import { readFile, writeFile, mkdir } from 'node:fs/promises';
-import { join, dirname } from 'node:path';
-import { safeJsonParse } from './base-store.js';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { hashProjectPath, projectDataDir, safeJsonParse } from './base-store.js';
+import { resolveSecretField, storeSecretField } from '../security/secret-field.js';
 function sentryConfigPath(projectPath) {
-    return join(projectPath, 'data', 'sentry', 'config.json');
+    return join(projectDataDir(hashProjectPath(projectPath)), technologyValue('technology-sentry-0cf685'), 'config.json');
 }
 export async function getSentryConfig(projectPath) {
     try {
         const raw = await readFile(sentryConfigPath(projectPath), 'utf-8');
-        return safeJsonParse(raw, null);
+        const config = safeJsonParse(raw, null);
+        return config ? { ...config, authToken: await resolveSecretField(config.authToken) } : null;
     }
-    catch {
-        return null;
+    catch (error) {
+        if (error.code === 'ENOENT' ||
+            (error instanceof Error && error.message === 'ENOENT')) {
+            return null;
+        }
+        throw error;
     }
 }
 export async function saveSentryConfig(projectPath, config) {
     const filePath = sentryConfigPath(projectPath);
-    await mkdir(dirname(filePath), { recursive: true });
-    await writeFile(filePath, JSON.stringify(config, null, 2), 'utf-8');
+    const authToken = await storeSecretField(`${hashProjectPath(projectPath)}/sentry/auth`, 'sentry-auth', config.authToken);
+    await mkdir(dirname(filePath), { recursive: true, mode: 0o700 });
+    await writeFile(filePath, JSON.stringify({ ...config, authToken }, null, 2), {
+        encoding: 'utf-8',
+        mode: 0o600,
+    });
 }
 //# sourceMappingURL=sentry-store.js.map

package/dist/storage/session-state-store.js

@@ -5,6 +5,7 @@ import { join } from 'node:path';
 import { execSync } from 'node:child_process';
 import { readFile } from 'node:fs/promises';
 import { getUniqueTopLevelFrontmatterString } from '../engine/frontmatter-parser.js';
+import { reportClassifiedDegradation } from '../errors/classified-degradation.js';
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -35,7 +36,9 @@ export function getStagedFiles(projectPath) {
             .map((f) => f.trim())
             .filter((f) => f.length > 0);
     }
-    catch {
+    catch (error) {
+        // reliability-optional: GIT_SESSION_FILE_LIST — filesystem fallback runs next
+        reportClassifiedDegradation('GIT_SESSION_FILE_LIST', error);
         return [];
     }
 }
@@ -58,14 +61,18 @@ export async function getActiveSpecIds(projectPath) {
                     active.add(match[0]);
                 }
             }
-            catch {
-                // A single unreadable candidate must not suppress other valid active specs.
+            catch (error) {
+                // reliability-compat: UNREADABLE_SPEC_CANDIDATE — preserve other valid active specs
+                reportClassifiedDegradation('UNREADABLE_SPEC_CANDIDATE', error);
             }
         }
         return [...active];
     }
-    catch {
-        return [];
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return [];
+        }
+        throw error;
     }
 }
 // ---------------------------------------------------------------------------

package/dist/storage/session-store.js

@@ -24,8 +24,12 @@ async function listSessionFiles(projectId) {
         const entries = await readdir(dir);
         return entries.filter((f) => f.startsWith('session-') && f.endsWith('.json'));
     }
-    catch {
-        return [];
+    catch (error) {
+        if (error.code === 'ENOENT' ||
+            (error instanceof Error && error.message === 'ENOENT')) {
+            return [];
+        }
+        throw error;
     }
 }
 // --- public API ---
@@ -63,8 +67,12 @@ export async function deleteSession(projectId, sessionId) {
         await unlink(sessionFile(projectId, sessionId));
         return true;
     }
-    catch {
-        return false;
+    catch (error) {
+        if (error.code === 'ENOENT' ||
+            (error instanceof Error && error.message === 'ENOENT')) {
+            return false;
+        }
+        throw error;
     }
 }
 /** List sessions as lightweight items for display. */

package/dist/storage/skill-registry-storage.d.ts

@@ -1,6 +1,6 @@
 import type { SkillSource, SkillRegistryEntry, SkillRegistry } from '../types/skill-registry.js';
 export type { SkillSource, SkillRegistryEntry, SkillRegistry };
-export declare const REGISTRY_RELATIVE_PATH = ".planu/skill-registry.json";
+export declare const REGISTRY_RELATIVE_PATH = "planu/skill-registry.json";
 export declare const DEFAULT_TTL_DAYS = 30;
 export declare const ALL_SKILL_SOURCES: SkillSource[];
 /**

package/dist/storage/skill-registry-storage.js

@@ -3,14 +3,13 @@
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { withFileLock } from './file-mutex.js';
-import { safeJsonParse } from './base-store.js';
 function isValidRegistry(parsed) {
     return (parsed !== null && typeof parsed === 'object' && 'installed' in parsed && 'sources' in parsed);
 }
 // ---------------------------------------------------------------------------
 // Configuration constants (no hardcodes in function bodies)
 // ---------------------------------------------------------------------------
-export const REGISTRY_RELATIVE_PATH = '.planu/skill-registry.json';
+export const REGISTRY_RELATIVE_PATH = 'planu/skill-registry.json';
 export const DEFAULT_TTL_DAYS = 30;
 export const ALL_SKILL_SOURCES = ['superpowers', 'anthropic', 'local', 'community'];
 // ---------------------------------------------------------------------------
@@ -41,14 +40,15 @@ export async function readSkillRegistry(projectPath) {
     try {
         raw = await readFile(filePath, 'utf-8');
     }
-    catch {
-        // File does not exist
-        return emptyRegistry();
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return emptyRegistry();
+        }
+        throw error;
     }
-    const parsed = safeJsonParse(raw, null);
+    const parsed = JSON.parse(raw);
     if (!isValidRegistry(parsed)) {
-        console.warn(`[skill-registry] Corrupted registry at ${filePath} — falling back to empty`);
-        return emptyRegistry();
+        throw new Error(`Skill registry is corrupt: ${filePath}`);
     }
     return parsed;
 }
@@ -79,7 +79,7 @@ export async function writeSkillRegistryEntry(projectPath, entry) {
         let registry;
         try {
             const raw = await readFile(filePath, 'utf-8');
-            const parsed = safeJsonParse(raw, null);
+            const parsed = JSON.parse(raw);
             if (isValidRegistry(parsed)) {
                 registry = parsed;
             }
@@ -87,8 +87,10 @@ export async function writeSkillRegistryEntry(projectPath, entry) {
                 throw new Error('invalid');
             }
         }
-        catch {
-            // Missing or corrupt — start fresh
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                throw error;
+            }
             const now = new Date().toISOString();
             registry = {
                 createdAt: now,

package/dist/storage/slack-store.js

@@ -1,14 +1,16 @@
 // storage/slack-store.ts — Slack integration persistence (SPEC-292)
 import { join } from 'node:path';
-import { hashProjectPath, readJson, writeJson } from './base-store.js';
+import { hashProjectPath, projectDataDir, readJson, writeJson } from './base-store.js';
 import { withFileLock } from './file-mutex.js';
+import { deleteSecretField, resolveSecretField, storeSecretField, } from '../security/secret-field.js';
+import { writeSecureJson } from '../security/secure-json.js';
 // ---------------------------------------------------------------------------
 // Path helpers
 // ---------------------------------------------------------------------------
 const MAX_DELIVERIES = 20;
 function getProjectDir(projectPath) {
     const hash = hashProjectPath(projectPath);
-    return join('data', 'projects', hash);
+    return projectDataDir(hash);
 }
 function getConfigPath(projectPath) {
     return join(getProjectDir(projectPath), 'slack-config.json');
@@ -24,19 +26,22 @@ function getDeliveryLogPath(projectPath) {
  */
 export async function getSlackConfig(projectPath) {
     const config = await readJson(getConfigPath(projectPath), null);
-    return config;
+    return config ? { ...config, webhookUrl: await resolveSecretField(config.webhookUrl) } : null;
 }
 /**
  * Persist the Slack config for a project.
  */
 export async function saveSlackConfig(projectPath, config) {
-    await writeJson(getConfigPath(projectPath), config);
+    const webhookUrl = await storeSecretField(`${hashProjectPath(projectPath)}/slack/webhook`, 'slack-webhook', config.webhookUrl);
+    await writeSecureJson(getConfigPath(projectPath), { ...config, webhookUrl });
 }
 /**
  * Remove the Slack config for a project.
  */
 export async function removeSlackConfig(projectPath) {
-    await writeJson(getConfigPath(projectPath), null);
+    const config = await readJson(getConfigPath(projectPath), null);
+    await deleteSecretField(config?.webhookUrl);
+    await writeSecureJson(getConfigPath(projectPath), null);
 }
 /**
  * Read the last N delivery log entries for a project.

package/dist/storage/spec-store.js

@@ -1,7 +1,8 @@
-import { readCriticalJson, readJson, writeJson, projectDataDir } from './base-store.js';
-import { migrateLegacyDataDir } from './migrations/cwd-to-absolute.js';
+import { reportClassifiedDegradation } from '../errors/classified-degradation.js';
+import { CriticalJsonReadError, readCriticalJson, readJson, writeJson, projectDataDir, } from './base-store.js';
+import { decodeCriticalSchema, registerCriticalSchema } from './schema-registry.js';
+import { BoundaryFailure } from '../errors/error-taxonomy.js';
 import { withFileLock } from './file-mutex.js';
-import { discoverProjectDataFile } from './data-dir-discovery.js';
 import { computeHealthScore } from '../engine/spec-health-scorer.js';
 import { loadSpecContent } from '../engine/validation-loop.js';
 import { createHash, randomUUID } from 'node:crypto';
@@ -52,16 +53,27 @@ const STORE_LOCK_ID = '__project-spec-store__';
 const DEFAULT_POST_COMMIT_LEASE_MS = 30_000;
 const MAX_POST_COMMIT_ATTEMPTS = 3;
 const COMPLETED_OUTBOX_RETENTION = 20;
+registerCriticalSchema({
+    name: 'spec-store',
+    currentVersion: 1,
+    createDefault: () => [],
+    validate: (value) => Array.isArray(value),
+    migrate: (value, fromVersion) => {
+        if (fromVersion === 0 && Array.isArray(value)) {
+            return value;
+        }
+        throw new Error('[Planu] Unsupported spec-store schema migration');
+    },
+});
 async function withSpecMutationLock(projectId, fn) {
     return withFileLock(specsFile(projectId), async () => {
-        const lockRoot = projectDataDir(projectId);
         const deadline = Date.now() + STORE_LOCK_TIMEOUT_MS;
-        let handle = await acquireLock(lockRoot, STORE_LOCK_ID, {
+        let handle = await acquireLock(projectId, STORE_LOCK_ID, {
             reason: `spec-store mutation for ${projectId}`,
         });
         while (handle === null && Date.now() < deadline) {
             await new Promise((resolve) => setTimeout(resolve, STORE_LOCK_RETRY_MS));
-            handle = await acquireLock(lockRoot, STORE_LOCK_ID, {
+            handle = await acquireLock(projectId, STORE_LOCK_ID, {
                 reason: `spec-store mutation for ${projectId}`,
             });
         }
@@ -75,10 +87,8 @@ async function withSpecMutationLock(projectId, fn) {
         }
         finally {
             await releaseLock(handle).catch((error) => {
-                console.warn('[planu:spec-store] failed to release mutation lock', {
-                    projectId,
-                    error: error instanceof Error ? error.message : String(error),
-                });
+                // reliability-cleanup: SPEC_MUTATION_LOCK_RELEASE — mutation outcome is already durable
+                reportClassifiedDegradation('SPEC_MUTATION_LOCK_RELEASE', error);
             });
         }
     });
@@ -96,28 +106,25 @@ async function loadAll(projectId) {
     if (cached !== undefined) {
         return cached;
     }
-    // SPEC-1007: migrate legacy <cwd>/data/projects/{id} to absolute home once.
-    await migrateLegacyDataDir(projectId);
     const directFile = specsFile(projectId);
-    let raw = await readCriticalJson(directFile, [], {
-        validate: (value) => Array.isArray(value),
-        expectedDescription: 'an array of specs',
-    });
-    if (raw.length === 0) {
-        const discovered = await discoverProjectDataFile(projectId, 'specs.json');
-        if (discovered !== null && discovered !== directFile) {
-            raw = await readCriticalJson(discovered, [], {
-                validate: (value) => Array.isArray(value),
-                expectedDescription: 'an array of specs',
-            });
+    let persisted;
+    try {
+        persisted = await readCriticalJson(directFile, []);
+    }
+    catch (error) {
+        if (error instanceof CriticalJsonReadError) {
+            const cause = new BoundaryFailure('Corrupt', 'critical JSON parse', 'The persisted bytes did not contain a valid JSON document.');
+            throw new BoundaryFailure('Corrupt', 'read spec-store', 'Recover specs.json; Planu will not replace corrupt state with defaults.', cause);
         }
+        throw error;
     }
+    const raw = decodeCriticalSchema(persisted, 'spec-store').data;
     const specs = raw.map(normalizeSpec);
     specsCache.set(projectId, specs);
     return specs;
 }
 async function saveAll(projectId, specs) {
-    await writeJson(specsFile(projectId), specs);
+    await writeJson(specsFile(projectId), { schemaVersion: 1, data: specs });
     specsCache.set(projectId, specs);
 }
 /** Evict the cache for a project (e.g. after external file changes). */

package/dist/storage/status-store/file-lock.js

@@ -21,15 +21,37 @@ export async function withStatusLock(filePath, fn) {
         release = resolve;
     });
     lockQueues.set(filePath, next);
-    // Wait for previous lock with timeout
-    await Promise.race([
-        prev,
-        new Promise((_, reject) => setTimeout(() => {
-            const err = new Error(`[Planu] status_lock_timeout: could not acquire write-lock on ${filePath} within ${STATUS_LOCK_TIMEOUT_MS}ms`);
-            err.code = STATUS_LOCK_ERROR_CODE;
-            reject(err);
-        }, STATUS_LOCK_TIMEOUT_MS)),
-    ]);
+    let timeout;
+    try {
+        // Wait for previous lock with timeout. A timed-out waiter must still release its
+        // queue node or every waiter behind it would remain blocked forever.
+        await Promise.race([
+            prev,
+            new Promise((_, reject) => {
+                timeout = setTimeout(() => {
+                    const err = new Error(`[Planu] status_lock_timeout: could not acquire write-lock on ${filePath} within ${STATUS_LOCK_TIMEOUT_MS}ms`);
+                    err.code = STATUS_LOCK_ERROR_CODE;
+                    reject(err);
+                }, STATUS_LOCK_TIMEOUT_MS);
+            }),
+        ]);
+    }
+    catch (error) {
+        // Preserve exclusion: a later waiter is chained to `next`, so resolve this
+        // abandoned node only after the holder ahead of us has actually finished.
+        void prev.finally(() => {
+            release();
+            if (lockQueues.get(filePath) === next) {
+                lockQueues.delete(filePath);
+            }
+        });
+        throw error;
+    }
+    finally {
+        if (timeout) {
+            clearTimeout(timeout);
+        }
+    }
     try {
         return await fn();
     }

package/dist/storage/status-store/self-healing.js

@@ -6,6 +6,7 @@
 // partial write — i.e. JSON.parse fails at non-zero offset.
 import { readFile, writeFile, rename, mkdir, readdir } from 'node:fs/promises';
 import { join, dirname } from 'node:path';
+import { reportClassifiedDegradation } from '../../errors/classified-degradation.js';
 import { PLANU_VERSION } from '../../config/version.js';
 // ---------------------------------------------------------------------------
 // Helpers
@@ -98,7 +99,9 @@ export async function quarantineCorruptStatus(statusPath, projectPath) {
     try {
         await rename(statusPath, quarantinePath);
     }
-    catch {
+    catch (error) {
+        // reliability-compat: STATUS_QUARANTINE_CROSS_DEVICE — copy preserves corrupt evidence
+        reportClassifiedDegradation('STATUS_QUARANTINE_CROSS_DEVICE', error);
         // Fallback: copy + delete if rename fails (e.g. cross-device)
         const raw = await readFile(statusPath, 'utf-8');
         await writeFile(quarantinePath, raw, 'utf-8');
@@ -142,8 +145,9 @@ export async function rebuildStatusFromFrontmatters(params) {
     try {
         specDirs = await readdir(specsDir);
     }
-    catch {
-        // No specs dir — return empty state
+    catch (error) {
+        // reliability-compat: ABSENT_SPECS_DIRECTORY — an uninitialized project has empty state
+        reportClassifiedDegradation('ABSENT_SPECS_DIRECTORY', error);
     }
     for (const dir of specDirs) {
         const specPath = join(specsDir, dir, 'spec.md');
@@ -158,8 +162,9 @@ export async function rebuildStatusFromFrontmatters(params) {
                 byTypeResult[type] = (byTypeResult[type] ?? 0) + 1;
             }
         }
-        catch {
-            // Skip unreadable spec.md files
+        catch (error) {
+            // reliability-compat: UNREADABLE_SPEC_FILE — rebuild state from remaining readable specs
+            reportClassifiedDegradation('UNREADABLE_SPEC_FILE', error);
         }
     }
     return {

package/dist/storage/status-store/version-sync.js

@@ -19,9 +19,12 @@ export async function syncVersionField(statusPath, force = false) {
     try {
         raw = await readFile(statusPath, 'utf-8');
     }
-    catch {
-        syncedPaths.add(statusPath);
-        return { synced: false };
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            syncedPaths.add(statusPath);
+            return { synced: false };
+        }
+        throw error;
     }
     let parsed;
     try {
@@ -32,9 +35,8 @@ export async function syncVersionField(statusPath, force = false) {
         }
         parsed = p;
     }
-    catch {
-        syncedPaths.add(statusPath);
-        return { synced: false };
+    catch (error) {
+        throw new Error(`Status file is corrupt: ${statusPath}`, { cause: error });
     }
     const currentVersion = typeof parsed.version === 'string' ? parsed.version : undefined;
     if (currentVersion === PLANU_VERSION) {

package/dist/storage/steering-store.js

@@ -1,9 +1,9 @@
 // storage/steering-store.ts — SPEC-434: Persistence for steering generation results
 import { join } from 'node:path';
-import { hashProjectPath, readJson, writeJson } from './base-store.js';
+import { hashProjectPath, projectDataDir, readJson, writeJson } from './base-store.js';
 function steeringPath(projectPath) {
     const hash = hashProjectPath(projectPath);
-    return join('data', 'projects', hash, 'steering', 'result.json');
+    return join(projectDataDir(hash), 'steering', 'result.json');
 }
 /** Load the last steering generation result for a project, or null if not found. */
 export async function getSteeringResult(projectPath) {

package/dist/storage/storage-bundle.d.ts

@@ -0,0 +1,5 @@
+import type { StorageBundle, StorageBundleOptions } from '../types/storage-bundle.js';
+export type { StorageBundle, StorageBundleOptions } from '../types/storage-bundle.js';
+export declare function exportStorageBundle(projectId: string, outputPath: string, options?: StorageBundleOptions): Promise<StorageBundle>;
+export declare function importStorageBundle(inputPath: string, options?: StorageBundleOptions): Promise<StorageBundle>;
+//# sourceMappingURL=storage-bundle.d.ts.map