claude-memory-explorer 0.1.0

package/dist/core/journal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal.js","sourceRoot":"","sources":["../../src/core/journal.ts"],"names":[],"mappings":"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"}

package/dist/core/lint.d.ts

@@ -0,0 +1,26 @@
+import { type ScanOptions } from "./scan.js";
+export declare const INDEX_LINE_CAP = 200;
+export declare const INDEX_BYTE_CAP: number;
+export type Severity = "error" | "warn" | "info";
+export interface LintIssue {
+    severity: Severity;
+    code: string;
+    projectSlug: string;
+    /** Absolute file path the issue is about, when applicable. */
+    filePath?: string;
+    message: string;
+    /** Optional remediation hint. */
+    hint?: string;
+}
+export interface LintOptions extends ScanOptions {
+    /** Restrict to projects whose slug includes this substring. */
+    projectFilter?: string;
+}
+export interface LintResult {
+    issues: LintIssue[];
+    /** Number of projects considered (post-filter). */
+    projectsScanned: number;
+    /** Number of memory files considered. */
+    filesScanned: number;
+}
+export declare function lintAll(opts?: LintOptions): LintResult;

package/dist/core/lint.js

@@ -0,0 +1,254 @@
+// Lint rules over the memory tree.
+//
+// Each rule produces zero or more `LintIssue`s with a stable `code`. The CLI
+// (or MCP) is free to filter by code or severity. We never mutate anything
+// here — lint is read-only.
+//
+// Severity scale:
+//   error  — confirmed problem (data loss, unusable file)
+//   warn   — likely problem (broken link, missing index when topic files exist)
+//   info   — informational (untyped file in memory dir, etc.)
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join, isAbsolute, resolve } from "node:path";
+import { scanAll } from "./scan.js";
+import { parseMemoryIndex, isInlineContentStyle } from "./memoryIndex.js";
+// Documented limits — content past either is silently dropped at session start.
+// Source: https://code.claude.com/docs/en/memory
+export const INDEX_LINE_CAP = 200;
+export const INDEX_BYTE_CAP = 25 * 1024; // 25 KB
+function readIndexSafely(memoryDir) {
+    const idxPath = join(memoryDir, "MEMORY.md");
+    if (!existsSync(idxPath))
+        return { index: null, readError: null };
+    try {
+        return { index: parseMemoryIndex(idxPath), readError: null };
+    }
+    catch (err) {
+        return {
+            index: null,
+            readError: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+function resolveLinkTarget(memoryDir, link) {
+    if (isAbsolute(link))
+        return link;
+    return resolve(memoryDir, link);
+}
+// Rule: MEMORY.md exceeds one of the documented caps. Content past the cap is
+// silently dropped, so this is severity: error.
+function lintIndexBloat(project, index) {
+    const issues = [];
+    const idxPath = join(project.path, "memory", "MEMORY.md");
+    if (index.lineCount > INDEX_LINE_CAP) {
+        issues.push({
+            severity: "error",
+            code: "index-line-cap",
+            projectSlug: project.slug,
+            filePath: idxPath,
+            message: `MEMORY.md is ${index.lineCount} lines; harness loads only the first ${INDEX_LINE_CAP}. ${index.lineCount - INDEX_LINE_CAP} lines are silently dropped.`,
+            hint: "Move detailed notes into separate topic files and reference them from MEMORY.md.",
+        });
+    }
+    if (index.byteSize > INDEX_BYTE_CAP) {
+        issues.push({
+            severity: "error",
+            code: "index-byte-cap",
+            projectSlug: project.slug,
+            filePath: idxPath,
+            message: `MEMORY.md is ${index.byteSize} bytes; harness loads only the first ${INDEX_BYTE_CAP} (25 KB).`,
+            hint: "Move detailed notes into separate topic files and reference them from MEMORY.md.",
+        });
+    }
+    return issues;
+}
+// Rule: a markdown link in MEMORY.md points at a path that doesn't exist.
+// Only check links that look like file references (end in .md or have no
+// scheme like http: — those are external).
+function lintDanglingRefs(project, index) {
+    const issues = [];
+    const memoryDir = join(project.path, "memory");
+    const idxPath = join(memoryDir, "MEMORY.md");
+    for (const link of index.links) {
+        // Skip external URLs and anchor-only links.
+        if (/^[a-z][a-z0-9+.-]*:/.test(link.target))
+            continue;
+        if (link.target.startsWith("#"))
+            continue;
+        if (!link.target.endsWith(".md"))
+            continue;
+        const resolved = resolveLinkTarget(memoryDir, link.target);
+        if (!existsSync(resolved)) {
+            issues.push({
+                severity: "warn",
+                code: "dangling-ref",
+                projectSlug: project.slug,
+                filePath: idxPath,
+                message: `MEMORY.md:${link.line} links to "${link.target}" but no such file exists.`,
+                hint: "Either create the file or remove the index entry.",
+            });
+        }
+    }
+    return issues;
+}
+// Rule: a topic file exists in memory/ but isn't referenced from MEMORY.md.
+// Only flag if MEMORY.md is using the pointer-style format — when it's inline
+// (no .md links at all), assume the user opted out of pointer indexing.
+function lintOrphans(project, index) {
+    if (isInlineContentStyle(index))
+        return [];
+    const issues = [];
+    const memoryDir = join(project.path, "memory");
+    const referenced = new Set();
+    for (const link of index.links) {
+        if (link.target.endsWith(".md")) {
+            referenced.add(resolveLinkTarget(memoryDir, link.target));
+        }
+    }
+    for (const m of project.memories) {
+        if (!referenced.has(m.filePath)) {
+            issues.push({
+                severity: "info",
+                code: "orphan-file",
+                projectSlug: project.slug,
+                filePath: m.filePath,
+                message: `${m.fileName} is not referenced from MEMORY.md.`,
+                hint: "Add a `- [Title](" + m.fileName + ")` line to MEMORY.md, or delete the file if it's stale.",
+            });
+        }
+    }
+    return issues;
+}
+// Rule: memory dir has topic files but no MEMORY.md index at all.
+function lintMissingIndex(project) {
+    if (project.hasIndex)
+        return [];
+    if (project.memories.length === 0)
+        return []; // Empty memory dir is fine.
+    return [
+        {
+            severity: "warn",
+            code: "missing-index",
+            projectSlug: project.slug,
+            filePath: join(project.path, "memory"),
+            message: `Project has ${project.memories.length} memory file(s) but no MEMORY.md index. Topic files load on demand but the session has no overview.`,
+            hint: "Create a MEMORY.md with one bullet per topic file.",
+        },
+    ];
+}
+// Rule: a markdown file in the memory dir has no recognized type (no
+// frontmatter type, no filename prefix). Informational — these are usually
+// human-written docs (ARCHITECTURE.md, etc.) that won't be touched by the
+// auto-memory system but are valid markdown.
+function lintUntypedFiles(project) {
+    const issues = [];
+    for (const m of project.memories) {
+        if (m.type !== "untyped")
+            continue;
+        issues.push({
+            severity: "info",
+            code: "untyped-file",
+            projectSlug: project.slug,
+            filePath: m.filePath,
+            message: `${m.fileName} has no frontmatter type and no recognized prefix; not loaded as auto-memory.`,
+            hint: "If this is human-written docs, that's fine. If it should be auto-memory, " +
+                "add a frontmatter block with `type: user|feedback|project|reference`.",
+        });
+    }
+    return issues;
+}
+// Rule: a memory file failed to parse during scan. We detect this by re-trying
+// the parse from disk for any file that the scan would have skipped. The scan
+// already wrote a warning; we promote it to an `error` lint issue here.
+function lintBrokenYaml(memoryDir, projectSlug, parsedFiles) {
+    // Build a set of paths the scan successfully parsed.
+    const parsed = new Set(parsedFiles.map((m) => m.filePath));
+    const issues = [];
+    // Re-list the dir and check for .md files (excluding MEMORY.md) that aren't
+    // in the parsed set.
+    let entries;
+    try {
+        entries = readdirSync(memoryDir);
+    }
+    catch {
+        return issues;
+    }
+    for (const name of entries) {
+        if (!name.endsWith(".md"))
+            continue;
+        if (name === "MEMORY.md")
+            continue;
+        const full = join(memoryDir, name);
+        if (parsed.has(full))
+            continue;
+        // Verify it's actually a file (not a directory — the dir-as-file edge case
+        // from the scan tests). If it's a regular file, this is a real parse fail.
+        let isFile = false;
+        try {
+            isFile = statSync(full).isFile();
+        }
+        catch {
+            // ignore
+        }
+        if (isFile) {
+            issues.push({
+                severity: "error",
+                code: "broken-yaml",
+                projectSlug,
+                filePath: full,
+                message: `${name} could not be parsed (likely malformed YAML frontmatter). Claude can't load this memory.`,
+                hint: "Open the frontmatter (between the `---` lines). Common cause: a value with unescaped quotes (e.g. `name: \"X\" in incidents`) or a colon inside an unquoted string. Wrap the whole value in single quotes to fix.",
+            });
+        }
+        else {
+            issues.push({
+                severity: "error",
+                code: "unreadable-file",
+                projectSlug,
+                filePath: full,
+                message: `${name} exists but is not a regular file.`,
+                hint: "Inspect manually — something unexpected is at this path.",
+            });
+        }
+    }
+    return issues;
+}
+export function lintAll(opts = {}) {
+    const projects = scanAll(opts).filter((p) => !opts.projectFilter || p.slug.includes(opts.projectFilter));
+    const issues = [];
+    let fileCount = 0;
+    for (const project of projects) {
+        fileCount += project.memories.length;
+        const memoryDir = join(project.path, "memory");
+        const { index, readError } = readIndexSafely(memoryDir);
+        if (readError) {
+            issues.push({
+                severity: "error",
+                code: "index-unreadable",
+                projectSlug: project.slug,
+                filePath: join(memoryDir, "MEMORY.md"),
+                message: `MEMORY.md exists but could not be read: ${readError}`,
+            });
+        }
+        if (index) {
+            issues.push(...lintIndexBloat(project, index));
+            issues.push(...lintDanglingRefs(project, index));
+            issues.push(...lintOrphans(project, index));
+        }
+        issues.push(...lintMissingIndex(project));
+        issues.push(...lintUntypedFiles(project));
+        issues.push(...lintBrokenYaml(memoryDir, project.slug, project.memories));
+    }
+    // Stable ordering: by project, then severity (error > warn > info), then code.
+    const SEV_ORDER = { error: 0, warn: 1, info: 2 };
+    issues.sort((a, b) => {
+        if (a.projectSlug !== b.projectSlug)
+            return a.projectSlug.localeCompare(b.projectSlug);
+        if (SEV_ORDER[a.severity] !== SEV_ORDER[b.severity]) {
+            return SEV_ORDER[a.severity] - SEV_ORDER[b.severity];
+        }
+        return a.code.localeCompare(b.code);
+    });
+    return { issues, projectsScanned: projects.length, filesScanned: fileCount };
+}
+//# sourceMappingURL=lint.js.map

package/dist/core/lint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lint.js","sourceRoot":"","sources":["../../src/core/lint.ts"],"names":[],"mappings":"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"}

package/dist/core/memoryIndex.d.ts

@@ -0,0 +1,42 @@
+export interface IndexLink {
+    /** Display text from `[title](...)`. */
+    title: string;
+    /** The link target, e.g. `user_git.md` or `./feedback.md`. */
+    target: string;
+    /** 1-indexed line where the link was found. */
+    line: number;
+}
+export interface ParsedIndex {
+    /** Full file body. */
+    rawText: string;
+    /** Number of lines (count of `\n` + 1, like wc -l + 1 for non-trailing-newline files). */
+    lineCount: number;
+    /** Byte size on disk. */
+    byteSize: number;
+    /** Last modified time. */
+    mtimeMs: number;
+    /** Every markdown link found in the file, in document order. */
+    links: IndexLink[];
+}
+export declare function parseMemoryIndex(filePath: string): ParsedIndex;
+/**
+ * Heuristic: an index is "inline-content style" when there are no markdown
+ * links pointing at sibling `.md` files. This avoids false-positive orphan
+ * warnings when the user is using the inline style on purpose.
+ */
+export declare function isInlineContentStyle(index: ParsedIndex): boolean;
+/**
+ * Remove every line in a MEMORY.md that references the given filename via a
+ * markdown link. Used by Phase 6 merge/promote when a topic file is deleted —
+ * we don't want to leave dangling pointers in the index.
+ *
+ * Conservative: only removes lines that contain the link `(<fileName>)`. If
+ * the line has unrelated content alongside, the whole line is still removed
+ * (the documented MEMORY.md style is "one bullet per topic file"). If the
+ * user has hand-edited their index with mixed content, they should review the
+ * dry-run diff before --apply.
+ */
+export declare function removeIndexEntry(content: string, fileName: string): {
+    content: string;
+    removedLines: number;
+};

package/dist/core/memoryIndex.js

@@ -0,0 +1,81 @@
+// Parses a `MEMORY.md` index file.
+//
+// Two real-world styles exist:
+//
+//   1. **Pointer-style** (the documented shape) — short lines, each a markdown
+//      link to a topic file:
+//        - [User Git Rules](user_git_rules.md)
+//        - [Feedback Testing](feedback_testing_style.md)
+//
+//   2. **Inline-content style** (what the harness actually writes most of the
+//      time) — full body text with headings and bullets, no links to sibling
+//      topic files.
+//
+// We don't pick one as "right" — we just record what's there and let the lint
+// rules decide what to flag.
+import { readFileSync, statSync } from "node:fs";
+const MD_LINK_RE = /\[([^\]]+)\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+export function parseMemoryIndex(filePath) {
+    const raw = readFileSync(filePath, "utf8");
+    const stats = statSync(filePath);
+    // Line count: number of \n characters + 1 (last line w/o newline still counts).
+    // Empty file → 1 line of 0 chars (matches Node's String.split("\n").length).
+    const lineCount = raw.length === 0 ? 0 : raw.split("\n").length;
+    const links = [];
+    const lines = raw.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        MD_LINK_RE.lastIndex = 0;
+        let m;
+        while ((m = MD_LINK_RE.exec(line)) !== null) {
+            links.push({ title: m[1], target: m[2], line: i + 1 });
+        }
+    }
+    return {
+        rawText: raw,
+        lineCount,
+        byteSize: Buffer.byteLength(raw, "utf8"),
+        mtimeMs: stats.mtimeMs,
+        links,
+    };
+}
+/**
+ * Heuristic: an index is "inline-content style" when there are no markdown
+ * links pointing at sibling `.md` files. This avoids false-positive orphan
+ * warnings when the user is using the inline style on purpose.
+ */
+export function isInlineContentStyle(index) {
+    return !index.links.some((l) => l.target.endsWith(".md"));
+}
+/**
+ * Remove every line in a MEMORY.md that references the given filename via a
+ * markdown link. Used by Phase 6 merge/promote when a topic file is deleted —
+ * we don't want to leave dangling pointers in the index.
+ *
+ * Conservative: only removes lines that contain the link `(<fileName>)`. If
+ * the line has unrelated content alongside, the whole line is still removed
+ * (the documented MEMORY.md style is "one bullet per topic file"). If the
+ * user has hand-edited their index with mixed content, they should review the
+ * dry-run diff before --apply.
+ */
+export function removeIndexEntry(content, fileName) {
+    const lines = content.split("\n");
+    const out = [];
+    let removed = 0;
+    // Match patterns: `(./fileName)` or `(fileName)` — anchored to a closing
+    // paren so we don't accidentally match a substring of a longer name.
+    const variants = [
+        `(${fileName})`,
+        `(./${fileName})`,
+    ];
+    for (const line of lines) {
+        const hit = variants.some((v) => line.includes(v));
+        if (hit) {
+            removed++;
+            continue;
+        }
+        out.push(line);
+    }
+    return { content: out.join("\n"), removedLines: removed };
+}
+//# sourceMappingURL=memoryIndex.js.map

package/dist/core/memoryIndex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memoryIndex.js","sourceRoot":"","sources":["../../src/core/memoryIndex.ts"],"names":[],"mappings":"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"}

package/dist/core/merge.d.ts

@@ -0,0 +1,19 @@
+import { type Plan } from "./plan.js";
+import type { DuplicateCluster } from "./dedupe.js";
+export interface MergePlanOptions {
+    /** Override which member id is treated as the keep target. */
+    keepId?: string;
+    /** When true, MEMORY.md indexes are not modified. */
+    skipIndexUpdate?: boolean;
+}
+export interface MergeSummary {
+    clusterId: string;
+    keepId: string;
+    deletedIds: string[];
+    indexesUpdated: string[];
+}
+export interface MergePlanResult {
+    plan: Plan;
+    summary: MergeSummary;
+}
+export declare function buildMergePlan(cluster: DuplicateCluster, opts?: MergePlanOptions): MergePlanResult;

package/dist/core/merge.js

@@ -0,0 +1,58 @@
+// Build a Plan that merges a duplicate cluster down to its representative.
+//
+// Inputs: a DuplicateCluster from Phase 4's `findDuplicates`.
+// Outputs: a Plan that, when applied:
+//   1. Deletes every non-representative member.
+//   2. For each affected project, removes the deleted file's pointer from
+//      MEMORY.md if present.
+//
+// The representative file is left untouched. Phase 5's applyPlan captures
+// inverses, so every merge is fully undoable via `memex undo`.
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { planBuilder } from "./plan.js";
+import { removeIndexEntry } from "./memoryIndex.js";
+export function buildMergePlan(cluster, opts = {}) {
+    const keepId = opts.keepId ?? cluster.representative.id;
+    const keep = cluster.members.find((m) => m.id === keepId);
+    if (!keep) {
+        throw new Error(`cluster ${cluster.id} has no member with id "${keepId}"; available: ${cluster.members
+            .map((m) => m.id)
+            .join(", ")}`);
+    }
+    const toDelete = cluster.members.filter((m) => m.id !== keepId);
+    const builder = planBuilder(`merge:${cluster.id}`, `Keep ${keepId}; delete ${toDelete.length} duplicate(s)` +
+        (opts.skipIndexUpdate ? "" : " and clean MEMORY.md references"));
+    const indexesUpdated = [];
+    for (const m of toDelete) {
+        builder.delete(m.filePath);
+        if (opts.skipIndexUpdate)
+            continue;
+        const memoryDir = dirname(m.filePath);
+        const indexPath = join(memoryDir, "MEMORY.md");
+        if (!existsSync(indexPath))
+            continue;
+        try {
+            const current = readFileSync(indexPath, "utf8");
+            const { content, removedLines } = removeIndexEntry(current, m.filePath.split("/").pop());
+            if (removedLines > 0) {
+                builder.write(indexPath, content);
+                indexesUpdated.push(indexPath);
+            }
+        }
+        catch {
+            // If we can't read the index, leave it alone — lint will surface
+            // any resulting dangling reference.
+        }
+    }
+    return {
+        plan: builder.build(),
+        summary: {
+            clusterId: cluster.id,
+            keepId,
+            deletedIds: toDelete.map((m) => m.id),
+            indexesUpdated,
+        },
+    };
+}
+//# sourceMappingURL=merge.js.map

package/dist/core/merge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge.js","sourceRoot":"","sources":["../../src/core/merge.ts"],"names":[],"mappings":"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"}

package/dist/core/parse.d.ts

@@ -0,0 +1,2 @@
+import { type Memory } from "./types.js";
+export declare function parseMemoryFile(filePath: string, projectSlug: string): Memory;

package/dist/core/parse.js

@@ -0,0 +1,84 @@
+// Parses a single memory markdown file into a Memory record.
+//
+// Tolerates three shapes seen in the wild:
+//   1. Full frontmatter with `type:` (the canonical auto-memory format)
+//   2. Frontmatter with unknown extra fields (e.g. `originSessionId:` written
+//      by some harness versions) — we preserve them all in `frontmatter`.
+//   3. Plain markdown with no frontmatter at all (humans drop ARCHITECTURE.md
+//      files into memory dirs). We classify these as "untyped".
+import { readFileSync, statSync } from "node:fs";
+import { basename } from "node:path";
+import matter from "gray-matter";
+import { MEMORY_TYPES } from "./types.js";
+const FILE_PREFIX_TO_TYPE = [
+    ["user_", "user"],
+    ["feedback_", "feedback"],
+    ["project_", "project"],
+    ["reference_", "reference"],
+];
+function detectTypeFromFilename(fileName) {
+    const lower = fileName.toLowerCase();
+    for (const [prefix, type] of FILE_PREFIX_TO_TYPE) {
+        if (lower.startsWith(prefix))
+            return type;
+    }
+    return null;
+}
+function asString(v) {
+    if (typeof v !== "string")
+        return null;
+    const trimmed = v.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function isValidType(v) {
+    return MEMORY_TYPES.includes(v);
+}
+export function parseMemoryFile(filePath, projectSlug) {
+    const raw = readFileSync(filePath, "utf8");
+    const stats = statSync(filePath);
+    const fileName = basename(filePath);
+    // gray-matter returns { content: <full>, data: {} } when there's no
+    // frontmatter at all, so this works for both shapes.
+    //
+    // Crucially: pass { cache: false }. gray-matter's default cache is keyed
+    // on file content and can return a successful parse on the *second* call
+    // for content that THREW on the first call — turning broken-YAML detection
+    // into a coin flip. The cache buys nothing here (we read each file once
+    // per scan) and corrupts results across multiple scans in one process.
+    // gray-matter's TS types don't expose `cache`, but the option is honored at
+    // runtime (and documented in the README). Cast to bypass the type gap.
+    const parsed = matter(raw, { cache: false });
+    const fm = (parsed.data ?? {});
+    const fmTypeRaw = asString(fm.type)?.toLowerCase();
+    let type;
+    let typeSource;
+    if (fmTypeRaw && isValidType(fmTypeRaw)) {
+        type = fmTypeRaw;
+        typeSource = "frontmatter";
+    }
+    else {
+        const fromName = detectTypeFromFilename(fileName);
+        if (fromName) {
+            type = fromName;
+            typeSource = "filename-prefix";
+        }
+        else {
+            type = "untyped";
+            typeSource = "unknown";
+        }
+    }
+    return {
+        id: `${projectSlug}/${fileName}`,
+        projectSlug,
+        filePath,
+        fileName,
+        type,
+        typeSource,
+        name: asString(fm.name),
+        description: asString(fm.description),
+        body: parsed.content.replace(/^\n+/, "").replace(/\n+$/, ""),
+        frontmatter: fm,
+        mtimeMs: stats.mtimeMs,
+    };
+}
+//# sourceMappingURL=parse.js.map

package/dist/core/parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.js","sourceRoot":"","sources":["../../src/core/parse.ts"],"names":[],"mappings":"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"}

package/dist/core/plan.d.ts

@@ -0,0 +1,34 @@
+export type OperationKind = "write" | "delete" | "ensure-dir";
+export type Operation = {
+    kind: "write";
+    /** Absolute path of the target file. */
+    path: string;
+    /** Full new contents (UTF-8). */
+    content: string;
+} | {
+    kind: "delete";
+    path: string;
+} | {
+    kind: "ensure-dir";
+    /** Directory to mkdir -p. */
+    path: string;
+};
+export interface Plan {
+    /** Stable id, used as journal filename. */
+    id: string;
+    /** Short label visible in `memex undo --list`. */
+    label: string;
+    /** Human-readable summary printed before --apply confirmation. */
+    description: string;
+    createdAt: string;
+    ops: Operation[];
+}
+export interface PlanBuilder {
+    build(): Plan;
+    write(path: string, content: string): PlanBuilder;
+    delete(path: string): PlanBuilder;
+    ensureDir(path: string): PlanBuilder;
+}
+export declare function planBuilder(label: string, description?: string): PlanBuilder;
+/** Pretty-print a plan for `--dry-run` output. */
+export declare function describePlan(plan: Plan): string;