@planu/cli 4.13.0 → 5.0.0

package/dist/engine/spec-migrator/canonical-deduplicator.js

@@ -0,0 +1,479 @@
+/* eslint-disable max-lines, max-lines-per-function, complexity -- one audited administrative transaction */
+import { createHash } from 'node:crypto';
+import { mkdir as mkdirFs, readFile as readFileFs } from 'node:fs/promises';
+import { join, relative, resolve } from 'node:path';
+import { atomicWriteFile } from '../safety/atomic-write-file.js';
+import { projectDataDir } from '../../storage/base-store.js';
+import { invalidateSpecsCache, validateCanonicalSpecRows, withCanonicalSpecRepairLock, } from '../../storage/spec-store.js';
+function digest(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function canonicalJson(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+function privateFailure(message) {
+    return new Error(`[Planu] Canonical repair blocked: ${message}`);
+}
+function repairPaths(projectId) {
+    const root = projectDataDir(projectId);
+    return { store: join(root, 'specs.json'), dir: join(root, 'repairs', 'spec-id-dedup') };
+}
+function isContained(parent, child) {
+    const rel = relative(resolve(parent), resolve(child));
+    return rel !== '' && !rel.startsWith('..') && !rel.includes('/../');
+}
+function artifactPath(projectId, artifactId) {
+    const { dir } = repairPaths(projectId);
+    if (!artifactId.startsWith('repairs/spec-id-dedup/')) {
+        throw privateFailure('repair artifact is outside the project repair directory');
+    }
+    const candidate = resolve(projectDataDir(projectId), artifactId);
+    if (!isContained(dir, candidate)) {
+        throw privateFailure('repair artifact is outside the project repair directory');
+    }
+    return candidate;
+}
+function parseRawStore(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw.toString('utf8'));
+    }
+    catch {
+        throw privateFailure('store is not valid JSON');
+    }
+    if (Array.isArray(parsed)) {
+        return { envelope: false, rows: parsed };
+    }
+    if (parsed && typeof parsed === 'object' && Array.isArray(parsed.data)) {
+        return { envelope: true, rows: parsed.data };
+    }
+    throw privateFailure('store shape is invalid');
+}
+function serializeStore(store, rows) {
+    return Buffer.from(canonicalJson(store.envelope ? { schemaVersion: 1, data: rows } : rows), 'utf8');
+}
+function requireString(value, label) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw privateFailure(`${label} is missing`);
+    }
+    return value;
+}
+function validateManifest(manifest, requestedProjectId) {
+    if (manifest.projectId !== requestedProjectId) {
+        throw privateFailure('manifest project does not match requested project');
+    }
+    if (!/^[a-f0-9]{64}$/.test(manifest.sourceDigest)) {
+        throw privateFailure('manifest source digest is invalid');
+    }
+    if (!manifest.sourceProjectAliases.includes(manifest.canonicalSourceProjectAlias) ||
+        manifest.canonicalSourceProjectAlias.length === 0) {
+        throw privateFailure('canonical source alias is not declared');
+    }
+    if (new Set(manifest.foreignOwnerSingletonIds).size !== manifest.foreignOwnerSingletonIds.length) {
+        throw privateFailure('foreign singleton IDs are duplicated');
+    }
+    for (const override of Object.values(manifest.lifecycleOverrides ?? {})) {
+        if (override.reason.length < 100 || !override.canonicalUuid) {
+            throw privateFailure('lifecycle override is incomplete');
+        }
+    }
+}
+function identityFieldsAgree(rows) {
+    const first = rows[0];
+    return (first !== undefined &&
+        rows.every((row) => row.id === first.id &&
+            row.title === first.title &&
+            row.slug === first.slug &&
+            row.specPath === first.specPath));
+}
+function validateRawUuidIdentities(rows) {
+    const identities = new Set();
+    for (const row of rows) {
+        const primary = requireString(row.uuid, 'primary UUID');
+        for (const identity of [primary, ...(row.uuidAliases ?? [])]) {
+            const normalized = requireString(identity, 'UUID alias');
+            if (identities.has(normalized)) {
+                throw privateFailure('raw UUID identity is repeated or ambiguous');
+            }
+            identities.add(normalized);
+        }
+    }
+}
+function planPayload(plan) {
+    return {
+        changed: plan.changed,
+        projectId: plan.projectId,
+        sourceDigest: plan.sourceDigest,
+        manifestDigest: plan.manifestDigest,
+        resultDigest: plan.resultDigest,
+        duplicateGroups: plan.duplicateGroups,
+        foreignOwnerSingletons: plan.foreignOwnerSingletons,
+        fieldChanges: plan.fieldChanges,
+        artifactId: plan.artifactId,
+    };
+}
+/** Pure planner. It does not read or write the canonical store. */
+export function buildCanonicalRepairPlan(raw, manifest, manifestDigest = digest(canonicalJson(manifest)), requestedProjectId = manifest.projectId) {
+    validateManifest(manifest, requestedProjectId);
+    const sourceDigest = digest(raw);
+    if (sourceDigest !== manifest.sourceDigest) {
+        const repaired = parseRawStore(raw);
+        try {
+            validateCanonicalSpecRows(requestedProjectId, repaired.rows);
+            const unchanged = {
+                changed: false,
+                projectId: requestedProjectId,
+                sourceDigest,
+                manifestDigest,
+                resultDigest: sourceDigest,
+                duplicateGroups: 0,
+                foreignOwnerSingletons: 0,
+                fieldChanges: [],
+                artifactId: `repairs/spec-id-dedup/${sourceDigest}.dry-run.json`,
+            };
+            return {
+                ...unchanged,
+                planDigest: digest(canonicalJson(planPayload(unchanged))),
+                resultBytes: raw,
+            };
+        }
+        catch {
+            throw privateFailure('source digest does not match manifest');
+        }
+    }
+    const store = parseRawStore(raw);
+    validateRawUuidIdentities(store.rows);
+    const groups = new Map();
+    for (const row of store.rows) {
+        const id = requireString(row.id, 'spec ID');
+        const group = groups.get(id);
+        if (group) {
+            group.push(row);
+        }
+        else {
+            groups.set(id, [row]);
+        }
+    }
+    const fieldChanges = [];
+    const nextRows = [];
+    const listedSingletons = new Set(manifest.foreignOwnerSingletonIds);
+    let duplicates = 0;
+    let singletonChanges = 0;
+    for (const [id, rows] of groups) {
+        const row = rows[0];
+        if (!row) {
+            throw privateFailure('empty duplicate group');
+        }
+        if (rows.length === 1) {
+            if (row.projectId === requestedProjectId) {
+                nextRows.push({ ...row });
+                continue;
+            }
+            if (!listedSingletons.delete(id) || !manifest.sourceProjectAliases.includes(row.projectId)) {
+                throw privateFailure('foreign singleton is not explicitly authorized');
+            }
+            nextRows.push({ ...row, projectId: requestedProjectId });
+            singletonChanges += 1;
+            fieldChanges.push({ id, field: 'projectId', from: row.projectId, to: requestedProjectId });
+            continue;
+        }
+        duplicates += 1;
+        if (!identityFieldsAgree(rows)) {
+            throw privateFailure('duplicate group has incompatible identity fields');
+        }
+        const canonicalRows = rows.filter((candidate) => candidate.projectId === manifest.canonicalSourceProjectAlias);
+        if (canonicalRows.length !== 1) {
+            throw privateFailure('duplicate group must have exactly one canonical-source row');
+        }
+        const canonical = canonicalRows[0];
+        if (!canonical) {
+            throw privateFailure('canonical-source row is missing');
+        }
+        const primaryUuid = requireString(canonical.uuid, 'canonical UUID');
+        const statuses = new Set(rows.map((candidate) => candidate.status));
+        const override = manifest.lifecycleOverrides?.[id];
+        if (statuses.size > 1) {
+            if (!override) {
+                throw privateFailure('lifecycle disagreement has no valid override');
+            }
+            if (override.canonicalUuid !== primaryUuid ||
+                override.retainedStatus !== canonical.status ||
+                override.reason.length < 100) {
+                throw privateFailure('lifecycle disagreement has no valid override');
+            }
+        }
+        const aliases = new Set(canonical.uuidAliases ?? []);
+        for (const candidate of rows) {
+            const candidateUuid = requireString(candidate.uuid, 'duplicate UUID');
+            if (candidate !== canonical) {
+                if (!manifest.sourceProjectAliases.includes(candidate.projectId)) {
+                    throw privateFailure('duplicate row has an unknown source project alias');
+                }
+                aliases.add(candidateUuid);
+                for (const alias of candidate.uuidAliases ?? []) {
+                    aliases.add(alias);
+                }
+                for (const field of ['technicalPath', 'progressPath']) {
+                    if (candidate[field] !== canonical[field]) {
+                        fieldChanges.push({
+                            id,
+                            field,
+                            from: candidate[field] ?? null,
+                            to: canonical[field] ?? null,
+                        });
+                    }
+                }
+            }
+        }
+        aliases.delete(primaryUuid);
+        nextRows.push({
+            ...canonical,
+            projectId: requestedProjectId,
+            ...(aliases.size > 0
+                ? { uuidAliases: [...aliases].sort((left, right) => left.localeCompare(right)) }
+                : {}),
+        });
+        fieldChanges.push({
+            id,
+            field: 'projectId',
+            from: canonical.projectId,
+            to: requestedProjectId,
+        });
+    }
+    if (listedSingletons.size > 0) {
+        throw privateFailure('manifest lists a missing foreign singleton');
+    }
+    validateCanonicalSpecRows(requestedProjectId, nextRows);
+    const resultBytes = serializeStore(store, nextRows);
+    const base = {
+        changed: duplicates > 0 || singletonChanges > 0,
+        projectId: requestedProjectId,
+        sourceDigest,
+        manifestDigest,
+        resultDigest: digest(resultBytes),
+        duplicateGroups: duplicates,
+        foreignOwnerSingletons: singletonChanges,
+        fieldChanges,
+        artifactId: `repairs/spec-id-dedup/${sourceDigest}.dry-run.json`,
+    };
+    return { ...base, planDigest: digest(canonicalJson(planPayload(base))), resultBytes };
+}
+function toPrivateReport(plan) {
+    return {
+        schemaVersion: 1,
+        ...planPayload(plan),
+        planDigest: plan.planDigest,
+    };
+}
+function buildReceipt(plan, raw, review, authorizationReason, manifest) {
+    const source = parseRawStore(raw).rows;
+    const groups = new Map();
+    for (const row of source) {
+        const group = groups.get(row.id);
+        if (group) {
+            group.push(row);
+        }
+        else {
+            groups.set(row.id, [row]);
+        }
+    }
+    const removedRows = [];
+    const singletonOwnershipChanges = [];
+    const retainedUuids = [];
+    const aliasesAdded = [];
+    for (const [id, rows] of groups) {
+        if (rows.length === 1) {
+            const only = rows[0];
+            if (!only) {
+                throw privateFailure('singleton row is missing');
+            }
+            if (only.projectId !== manifest.projectId) {
+                singletonOwnershipChanges.push({
+                    id,
+                    beforeProjectId: only.projectId,
+                    afterProjectId: manifest.projectId,
+                });
+            }
+            continue;
+        }
+        const canonical = rows.find((row) => row.projectId === manifest.canonicalSourceProjectAlias);
+        if (!canonical) {
+            throw privateFailure('canonical-source row is missing');
+        }
+        retainedUuids.push({ id, uuid: canonical.uuid });
+        const aliases = rows
+            .filter((row) => row !== canonical)
+            .flatMap((row) => [row.uuid, ...(row.uuidAliases ?? [])])
+            .filter((uuid) => typeof uuid === 'string' && uuid.length > 0)
+            .sort((left, right) => left.localeCompare(right));
+        aliasesAdded.push({ id, aliases });
+        removedRows.push(...rows.filter((row) => row !== canonical));
+    }
+    return {
+        schemaVersion: 1,
+        state: 'prepared',
+        projectId: manifest.projectId,
+        reviewer: review.reviewer,
+        verdict: review.verdict,
+        authorizationReason,
+        sourceDigest: plan.sourceDigest,
+        manifestDigest: plan.manifestDigest,
+        planDigest: plan.planDigest,
+        resultDigest: plan.resultDigest,
+        backupArtifactId: `repairs/spec-id-dedup/${plan.sourceDigest}.backup.json`,
+        backupDigest: digest(raw),
+        removedRows,
+        singletonOwnershipChanges,
+        retainedUuids,
+        aliasesAdded,
+        fieldChanges: plan.fieldChanges,
+    };
+}
+function validateApplyInput(plan, input, review) {
+    const authorizationReason = input.authorizationReason;
+    if (authorizationReason === undefined || authorizationReason.length < 100) {
+        throw privateFailure('authorization reason is too short');
+    }
+    if (input.expectedSourceDigest !== plan.sourceDigest ||
+        input.expectedManifestDigest !== plan.manifestDigest ||
+        input.expectedPlanDigest !== plan.planDigest ||
+        input.expectedResultDigest !== plan.resultDigest) {
+        throw privateFailure('reviewed digest does not match current plan');
+    }
+    if (review.reviewer !== 'planu-data-repair-reviewer' ||
+        review.verdict !== 'approved' ||
+        review.sourceDigest !== plan.sourceDigest ||
+        review.manifestDigest !== plan.manifestDigest ||
+        review.planDigest !== plan.planDigest ||
+        review.resultDigest !== plan.resultDigest) {
+        throw privateFailure('independent review evidence is invalid');
+    }
+    return authorizationReason;
+}
+function ioFor(io) {
+    return {
+        readFile: io?.readFile ?? ((path) => readFileFs(path)),
+        writeAtomic: io?.writeAtomic ?? ((path, bytes) => atomicWriteFile(path, bytes, { mode: 0o600 })),
+        mkdir: io?.mkdir ??
+            (async (path) => {
+                await mkdirFs(path, { recursive: true });
+            }),
+        withLock: io?.withLock ?? withCanonicalSpecRepairLock,
+    };
+}
+async function readJsonArtifact(path, label, io) {
+    try {
+        return JSON.parse((await io.readFile(path)).toString('utf8'));
+    }
+    catch {
+        throw privateFailure(`${label} is unreadable`);
+    }
+}
+/** Runs dry-run or the explicitly authorized, lock-protected repair. */
+export async function repairDuplicateSpecIds(input) {
+    const io = ioFor(input.io);
+    const manifestBytes = await io.readFile(input.manifestPath).catch(() => {
+        throw privateFailure('manifest is unreadable');
+    });
+    let manifest;
+    try {
+        manifest = JSON.parse(manifestBytes.toString('utf8'));
+    }
+    catch {
+        throw privateFailure('manifest is not valid JSON');
+    }
+    // This binding intentionally precedes every canonical store read and write.
+    validateManifest(manifest, input.projectId);
+    const manifestDigest = digest(manifestBytes);
+    const paths = repairPaths(input.projectId);
+    if (input.dryRun === true) {
+        const raw = await io.readFile(paths.store);
+        const plan = buildCanonicalRepairPlan(raw, manifest, manifestDigest, input.projectId);
+        await io.mkdir(paths.dir);
+        await io.writeAtomic(artifactPath(input.projectId, plan.artifactId), canonicalJson(toPrivateReport(plan)));
+        return plan;
+    }
+    if (!input.reviewPath) {
+        throw privateFailure('apply requires review evidence');
+    }
+    const review = await readJsonArtifact(input.reviewPath, 'review evidence', io);
+    return io.withLock(input.projectId, async () => {
+        const raw = await io.readFile(paths.store);
+        const plan = buildCanonicalRepairPlan(raw, manifest, manifestDigest, input.projectId);
+        if (!plan.changed) {
+            return plan;
+        }
+        const authorizationReason = validateApplyInput(plan, input, review);
+        const receipt = buildReceipt(plan, raw, review, authorizationReason, manifest);
+        const backupPath = artifactPath(input.projectId, receipt.backupArtifactId);
+        const receiptId = `repairs/spec-id-dedup/${plan.sourceDigest}.receipt.json`;
+        const receiptPath = artifactPath(input.projectId, receiptId);
+        await io.mkdir(paths.dir);
+        await io.writeAtomic(backupPath, raw);
+        await io.writeAtomic(receiptPath, canonicalJson(receipt));
+        await io.writeAtomic(paths.store, plan.resultBytes);
+        try {
+            await io.writeAtomic(receiptPath, canonicalJson({ ...receipt, state: 'committed' }));
+        }
+        catch {
+            invalidateSpecsCache(input.projectId);
+            return { ...plan, finalizationDegraded: true };
+        }
+        invalidateSpecsCache(input.projectId);
+        return plan;
+    });
+}
+function isValidReceipt(value, projectId) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const receipt = value;
+    return (receipt.schemaVersion === 1 &&
+        receipt.projectId === projectId &&
+        (receipt.state === 'prepared' || receipt.state === 'committed') &&
+        typeof receipt.sourceDigest === 'string' &&
+        /^[a-f0-9]{64}$/.test(receipt.sourceDigest) &&
+        typeof receipt.manifestDigest === 'string' &&
+        /^[a-f0-9]{64}$/.test(receipt.manifestDigest) &&
+        typeof receipt.planDigest === 'string' &&
+        /^[a-f0-9]{64}$/.test(receipt.planDigest) &&
+        typeof receipt.resultDigest === 'string' &&
+        /^[a-f0-9]{64}$/.test(receipt.resultDigest) &&
+        typeof receipt.backupDigest === 'string' &&
+        /^[a-f0-9]{64}$/.test(receipt.backupDigest) &&
+        typeof receipt.backupArtifactId === 'string' &&
+        receipt.backupArtifactId.length > 0);
+}
+export async function rollbackCanonicalRepair(projectId, receiptPath) {
+    const paths = repairPaths(projectId);
+    if (!isContained(paths.dir, receiptPath)) {
+        throw privateFailure('receipt is outside the project repair directory');
+    }
+    const io = ioFor(undefined);
+    const receipt = await readJsonArtifact(receiptPath, 'receipt', io);
+    if (!isValidReceipt(receipt, projectId)) {
+        throw privateFailure('receipt schema, project, state, or digest is invalid');
+    }
+    const backupPath = artifactPath(projectId, receipt.backupArtifactId);
+    return withCanonicalSpecRepairLock(projectId, async () => {
+        const current = await io.readFile(paths.store);
+        if (digest(current) !== receipt.resultDigest) {
+            throw privateFailure('rollback source does not match committed result');
+        }
+        const backup = await io.readFile(backupPath).catch(() => {
+            throw privateFailure('backup is unreadable');
+        });
+        if (digest(backup) !== receipt.backupDigest) {
+            throw privateFailure('backup digest does not match receipt');
+        }
+        await io.writeAtomic(paths.store, backup);
+        invalidateSpecsCache(projectId);
+    });
+}
+export const CANONICAL_DEDUPLICATOR_INTERNALS = {
+    digest,
+    parseRawStore,
+    artifactPath,
+    isContained,
+};
+//# sourceMappingURL=canonical-deduplicator.js.map

package/dist/engine/spec-migrator/drift-detector.js

@@ -3,15 +3,7 @@ import { readdir, stat, access, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { isOldFormat } from './lean-migration.js';
 import { isNativeActive, fastScanSpecs } from '../core-bridge.js';
-/** Files considered non-canonical in planu/ root (mirrors planu-root-cleaner.ts logic). */
-const CANONICAL_ROOT_FILES = new Set([
-    'status.json',
-    'conventions.json',
-    'index.html',
-    'roadmap.html',
-]);
-const CANONICAL_ROOT_DIRS = new Set(['specs']);
-const CANONICAL_SPEC_FILES = new Set(['spec.md']);
+import { isCanonicalPlanuRootDir, isCanonicalPlanuRootFile, isCanonicalSpecFile, } from './planu-canonical-policy.js';
 async function scanPlanuRoot(projectPath) {
     const rootFiles = [];
     const planuDir = join(projectPath, 'planu');
@@ -22,11 +14,11 @@ async function scanPlanuRoot(projectPath) {
             try {
                 const info = await stat(fullPath);
                 if (info.isDirectory()) {
-                    if (!CANONICAL_ROOT_DIRS.has(entry)) {
+                    if (!isCanonicalPlanuRootDir(entry)) {
                         rootFiles.push(entry);
                     }
                 }
-                else if (!CANONICAL_ROOT_FILES.has(entry)) {
+                else if (!isCanonicalPlanuRootFile(entry)) {
                     rootFiles.push(entry);
                 }
             }
@@ -56,7 +48,7 @@ async function scanSpecDirs(specsDir, specDirEntries, unifiedSpecs, leanSpecs) {
             const specId = idMatch?.[1]?.toUpperCase() ?? entry;
             const specFiles = await readdir(specPath);
             for (const file of specFiles) {
-                if (!CANONICAL_SPEC_FILES.has(file)) {
+                if (!isCanonicalSpecFile(file)) {
                     rootFiles.push(`${entry}/${file}`);
                 }
             }
@@ -115,7 +107,7 @@ export async function detectDrift(projectPath) {
                 }
                 const specFiles = await readdir(specPath);
                 for (const file of specFiles) {
-                    if (!CANONICAL_SPEC_FILES.has(file)) {
+                    if (!isCanonicalSpecFile(file)) {
                         rootFiles.push(`${entry}/${file}`);
                     }
                 }

package/dist/engine/spec-migrator/filesystem-import.d.ts

@@ -1,14 +1,10 @@
-import type { Spec } from '../../types/index.js';
+import type { FilesystemImportDeps, FilesystemImportResult } from '../../types/index.js';
 /**
  * Import specs that exist on disk (planu/specs/) but are missing from the store.
  * Reads frontmatter from each spec.md and creates a minimal Spec record in the store.
  * This ensures list_specs returns ALL specs, not just those created via create_spec.
  */
-export declare function importFilesystemSpecs(projectPath: string, deps: {
-    listSpecs: (projectId: string) => Promise<Spec[]>;
-    createSpec: (projectId: string, spec: Spec) => Promise<Spec>;
-}, projectId: string): Promise<{
-    importedCount: number;
-    errors: string[];
-}>;
+export declare function importFilesystemSpecs(projectPath: string, deps: FilesystemImportDeps, projectId: string, options?: {
+    strictPortableContract?: boolean;
+}): Promise<FilesystemImportResult>;
 //# sourceMappingURL=filesystem-import.d.ts.map