mewkit 1.7.0 → 1.8.0

package/dist/orchviz/plan/collector.js

@@ -0,0 +1,173 @@
+/**
+ * PlanCollector — read the active plan (or a slug-targeted plan) with mtime-keyed cache.
+ *
+ * Per red-team H3 (orchviz redesign): cache key is `(planDirMtime, max(phaseFileMtime))`.
+ * Cache invalidates the moment any plan file is touched on disk — no stale window.
+ * A 60s time-based fallback exists for paranoia (e.g., filesystems with broken mtime).
+ *
+ * Per R2-3: cache is plain Map<string, CacheEntry> keyed by slug-or-"__active".
+ * Soft-reset if map.size > 50. NO LRU, NO 16-entry cap, NO evict-oldest.
+ *
+ * Per R2-8: PlanSnapshot shape includes phaseEtags (not etag) and error tag.
+ * Read-only is the default behavior. Set MEOWKIT_ORCHVIZ_WRITABLE=1 to opt
+ * into write mode. Legacy MEOWKIT_ORCHVIZ_READONLY=0 continues to enable
+ * writes for backwards compatibility with existing user setups.
+ */
+import * as path from "node:path";
+import * as fs from "node:fs";
+import { findActivePlan } from "./find-active-plan.js";
+import { planMtimeKey, readPlan } from "./index.js";
+import { computeAllPhaseEtags } from "./etag.js";
+import { SLUG_RE } from "./plan-constants.js";
+import { createLogger } from "../logger.js";
+const log = createLogger("PlanCollector");
+const FALLBACK_TIMEOUT_MS = 60_000;
+const CACHE_SOFT_RESET_THRESHOLD = 50;
+const ACTIVE_KEY = "__active";
+/**
+ * Read-only is the default. Precedence (highest first):
+ *   1. MEOWKIT_ORCHVIZ_READONLY=1   forces readonly (defensive lock)
+ *   2. MEOWKIT_ORCHVIZ_WRITABLE=1   opts into writes (preferred opt-in)
+ *   3. MEOWKIT_ORCHVIZ_READONLY=0   opts into writes (legacy compat)
+ *   4. otherwise                   readonly
+ */
+export function isOrchvizReadonly() {
+    if (process.env.MEOWKIT_ORCHVIZ_READONLY === "1")
+        return true;
+    if (process.env.MEOWKIT_ORCHVIZ_WRITABLE === "1")
+        return false;
+    if (process.env.MEOWKIT_ORCHVIZ_READONLY === "0")
+        return false;
+    return true;
+}
+export class PlanCollector {
+    projectRoot;
+    cache = new Map();
+    /** Cached `realpathSync(plansDir)` — constant per-projectRoot, avoids syscall per slug poll. */
+    resolvedPlansDir = null;
+    constructor(projectRoot) {
+        this.projectRoot = projectRoot;
+    }
+    snapshot(slug) {
+        const isReadonly = isOrchvizReadonly();
+        const generatedAt = new Date().toISOString();
+        if (slug !== undefined) {
+            return this.snapshotBySlug(slug, isReadonly, generatedAt);
+        }
+        return this.snapshotActive(isReadonly, generatedAt);
+    }
+    snapshotActive(isReadonly, generatedAt) {
+        const planDir = findActivePlan(this.projectRoot);
+        const mtimeKey = planDir ? planMtimeKey(planDir) : null;
+        const now = Date.now();
+        const cached = this.cache.get(ACTIVE_KEY);
+        if (cached &&
+            cached.mtimeKey === mtimeKey &&
+            now - cached.at < FALLBACK_TIMEOUT_MS) {
+            return { ...cached.snapshot, readonly: isReadonly, generatedAt };
+        }
+        const plan = planDir ? readPlan(planDir) : null;
+        const phaseEtags = planDir ? computeAllPhaseEtags(planDir) : null;
+        const snapshot = {
+            plan,
+            phaseEtags,
+            readonly: isReadonly,
+            generatedAt,
+        };
+        this.writeCache(ACTIVE_KEY, snapshot, mtimeKey, now);
+        return snapshot;
+    }
+    snapshotBySlug(slug, isReadonly, generatedAt) {
+        // Validate slug regex BEFORE any path resolution (defense vs traversal)
+        if (!SLUG_RE.test(slug)) {
+            return {
+                plan: null,
+                phaseEtags: null,
+                readonly: isReadonly,
+                generatedAt,
+                error: "invalid-slug",
+            };
+        }
+        const plansDir = path.join(this.projectRoot, "tasks", "plans");
+        const planDir = path.join(plansDir, slug);
+        // Boundary check via realpath — cached per-process (constant per projectRoot).
+        // macOS /var→/private/var symlink resolves once.
+        if (this.resolvedPlansDir === null) {
+            try {
+                this.resolvedPlansDir = fs.realpathSync(plansDir);
+            }
+            catch {
+                return {
+                    plan: null,
+                    phaseEtags: null,
+                    readonly: isReadonly,
+                    generatedAt,
+                    error: "not-found",
+                };
+            }
+        }
+        const boundary = this.resolvedPlansDir + path.sep;
+        let resolved;
+        try {
+            resolved = fs.realpathSync(planDir);
+        }
+        catch {
+            return {
+                plan: null,
+                phaseEtags: null,
+                readonly: isReadonly,
+                generatedAt,
+                error: "not-found",
+            };
+        }
+        if (!(resolved + path.sep).startsWith(boundary)) {
+            log.warn(`slug boundary violation: ${slug} -> ${resolved}`);
+            return {
+                plan: null,
+                phaseEtags: null,
+                readonly: isReadonly,
+                generatedAt,
+                error: "forbidden-path",
+            };
+        }
+        const mtimeKey = planMtimeKey(planDir);
+        const now = Date.now();
+        const cached = this.cache.get(slug);
+        if (cached &&
+            cached.mtimeKey === mtimeKey &&
+            now - cached.at < FALLBACK_TIMEOUT_MS) {
+            return { ...cached.snapshot, readonly: isReadonly, generatedAt };
+        }
+        const plan = readPlan(planDir);
+        if (!plan) {
+            return {
+                plan: null,
+                phaseEtags: null,
+                readonly: isReadonly,
+                generatedAt,
+                error: "not-found",
+            };
+        }
+        const phaseEtags = computeAllPhaseEtags(planDir);
+        const snapshot = {
+            plan,
+            phaseEtags,
+            readonly: isReadonly,
+            generatedAt,
+        };
+        this.writeCache(slug, snapshot, mtimeKey, now);
+        return snapshot;
+    }
+    /** Soft-reset the cache if it grows too large, then insert the new entry (R2-3). */
+    writeCache(key, snapshot, mtimeKey, now) {
+        if (this.cache.size >= CACHE_SOFT_RESET_THRESHOLD) {
+            this.cache.clear();
+        }
+        this.cache.set(key, { snapshot, mtimeKey, at: now });
+    }
+    invalidate() {
+        this.cache.clear();
+        // resolvedPlansDir is per-projectRoot and never changes; do NOT clear.
+    }
+}
+//# sourceMappingURL=collector.js.map

package/dist/orchviz/plan/collector.js.map

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

package/dist/orchviz/plan/etag.d.ts

@@ -0,0 +1,24 @@
+/**
+ * ETag helpers — per-phase-file sha256 hash.
+ *
+ * Per red-team H2 / R2-2: ETag scope is per-FILE, NOT a bundle hash.
+ * Concurrent writes to different phases do not produce false 409s.
+ *
+ * computePhaseFileEtag(phaseFilePath) → 64-char lowercase hex sha256.
+ * Missing file → "" (not an error; caller decides how to handle absent files).
+ *
+ * computeAllPhaseEtags(planDir) → Record<phaseNumber, hex64>
+ * for every phase-NN-*.md in the directory.
+ */
+/**
+ * Compute sha256 of a single phase file's bytes.
+ * Returns 64-char lowercase hex, or "" if the file cannot be read.
+ */
+export declare function computePhaseFileEtag(phaseFilePath: string): string;
+/**
+ * Compute etags for every phase-NN-*.md file in planDir.
+ * Returns a Record keyed by phase number (integer).
+ * Missing or unreadable files are omitted.
+ */
+export declare function computeAllPhaseEtags(planDir: string): Record<number, string>;
+//# sourceMappingURL=etag.d.ts.map

package/dist/orchviz/plan/etag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"etag.d.ts","sourceRoot":"","sources":["../../../src/orchviz/plan/etag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAQlE;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAmB5E"}

package/dist/orchviz/plan/etag.js

@@ -0,0 +1,58 @@
+/**
+ * ETag helpers — per-phase-file sha256 hash.
+ *
+ * Per red-team H2 / R2-2: ETag scope is per-FILE, NOT a bundle hash.
+ * Concurrent writes to different phases do not produce false 409s.
+ *
+ * computePhaseFileEtag(phaseFilePath) → 64-char lowercase hex sha256.
+ * Missing file → "" (not an error; caller decides how to handle absent files).
+ *
+ * computeAllPhaseEtags(planDir) → Record<phaseNumber, hex64>
+ * for every phase-NN-*.md in the directory.
+ */
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { PHASE_FILE_NUM_RE } from "./plan-constants.js";
+/**
+ * Compute sha256 of a single phase file's bytes.
+ * Returns 64-char lowercase hex, or "" if the file cannot be read.
+ */
+export function computePhaseFileEtag(phaseFilePath) {
+    let buf;
+    try {
+        buf = fs.readFileSync(phaseFilePath);
+    }
+    catch {
+        return "";
+    }
+    return crypto.createHash("sha256").update(buf).digest("hex");
+}
+/**
+ * Compute etags for every phase-NN-*.md file in planDir.
+ * Returns a Record keyed by phase number (integer).
+ * Missing or unreadable files are omitted.
+ */
+export function computeAllPhaseEtags(planDir) {
+    let entries;
+    try {
+        entries = fs.readdirSync(planDir);
+    }
+    catch {
+        return {};
+    }
+    const out = {};
+    for (const name of entries) {
+        const m = name.match(PHASE_FILE_NUM_RE);
+        if (!m)
+            continue;
+        const phaseNum = parseInt(m[1], 10);
+        const filePath = path.join(planDir, name);
+        const etag = computePhaseFileEtag(filePath);
+        if (etag !== "") {
+            out[phaseNum] = etag;
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=etag.js.map

package/dist/orchviz/plan/etag.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"etag.js","sourceRoot":"","sources":["../../../src/orchviz/plan/etag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AACtC,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAExD;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,aAAqB;IACzD,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACJ,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,aAAa,CAAC,CAAC;IACtC,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,EAAE,CAAC;IACX,CAAC;IACD,OAAO,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC9D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAe;IACnD,IAAI,OAAiB,CAAC;IACtB,IAAI,CAAC;QACJ,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IACnC,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,EAAE,CAAC;IACX,CAAC;IACD,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;QACxC,IAAI,CAAC,CAAC;YAAE,SAAS;QACjB,MAAM,QAAQ,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACpC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAC1C,MAAM,IAAI,GAAG,oBAAoB,CAAC,QAAQ,CAAC,CAAC;QAC5C,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;YACjB,GAAG,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC;QACtB,CAAC;IACF,CAAC;IACD,OAAO,GAAG,CAAC;AACZ,CAAC"}

package/dist/orchviz/plan/find-active-plan.d.ts

@@ -0,0 +1,9 @@
+/**
+ * findActivePlan — discover the most-recent non-archived plan dir.
+ *
+ * Per red-team C1 (orchviz redesign plan): every candidate path is realpath-resolved
+ * and asserted to live inside `${projectRoot}/tasks/plans/`. Symlinks pointing
+ * outside the boundary are rejected to prevent path-disclosure via /api/plan.
+ */
+export declare function findActivePlan(projectRoot: string): string | null;
+//# sourceMappingURL=find-active-plan.d.ts.map

package/dist/orchviz/plan/find-active-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-active-plan.d.ts","sourceRoot":"","sources":["../../../src/orchviz/plan/find-active-plan.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAeH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAiDjE"}

package/dist/orchviz/plan/find-active-plan.js

@@ -0,0 +1,90 @@
+/**
+ * findActivePlan — discover the most-recent non-archived plan dir.
+ *
+ * Per red-team C1 (orchviz redesign plan): every candidate path is realpath-resolved
+ * and asserted to live inside `${projectRoot}/tasks/plans/`. Symlinks pointing
+ * outside the boundary are rejected to prevent path-disclosure via /api/plan.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import yaml from "js-yaml";
+import { FRONTMATTER_RE } from "./plan-constants.js";
+import { createLogger } from "../logger.js";
+const log = createLogger("PlanFinder");
+export function findActivePlan(projectRoot) {
+    const plansDir = path.join(projectRoot, "tasks", "plans");
+    let resolvedPlansDir;
+    try {
+        resolvedPlansDir = fs.realpathSync(plansDir);
+    }
+    catch {
+        return null;
+    }
+    const boundary = resolvedPlansDir + path.sep;
+    let entries;
+    try {
+        entries = fs.readdirSync(plansDir, { withFileTypes: true });
+    }
+    catch {
+        return null;
+    }
+    const candidates = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const dir = path.join(plansDir, entry.name);
+        const planFile = path.join(dir, "plan.md");
+        // Boundary check (red-team C1)
+        let resolved;
+        try {
+            resolved = fs.realpathSync(dir);
+        }
+        catch {
+            continue;
+        }
+        if (!(resolved + path.sep).startsWith(boundary)) {
+            log.warn(`rejecting plan dir outside boundary: ${dir} -> ${resolved}`);
+            continue;
+        }
+        let stat;
+        try {
+            stat = fs.statSync(planFile);
+        }
+        catch {
+            continue;
+        }
+        if (!stat.isFile())
+            continue;
+        if (isArchived(planFile))
+            continue;
+        candidates.push({ dir, mtimeMs: stat.mtimeMs });
+    }
+    if (candidates.length === 0)
+        return null;
+    candidates.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    return candidates[0].dir;
+}
+function isArchived(planFile) {
+    let raw;
+    try {
+        raw = fs.readFileSync(planFile, "utf-8");
+    }
+    catch {
+        return false;
+    }
+    const fmMatch = raw.match(FRONTMATTER_RE);
+    if (!fmMatch)
+        return false;
+    let parsed;
+    try {
+        parsed = yaml.load(fmMatch[1], { schema: yaml.FAILSAFE_SCHEMA });
+    }
+    catch {
+        return false;
+    }
+    if (!parsed || typeof parsed !== "object")
+        return false;
+    const status = parsed.status;
+    return typeof status === "string" && status.toLowerCase() === "archived";
+}
+//# sourceMappingURL=find-active-plan.js.map

package/dist/orchviz/plan/find-active-plan.js.map

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

package/dist/orchviz/plan/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * orchviz plan parser — orchestrator for plan + phase files.
+ *
+ * Public API:
+ *   - findActivePlan(projectRoot)
+ *   - readPlan(planDir)
+ *
+ * Read-only by design. v1.1 does not write to plan files.
+ */
+import type { PlanState } from "./types.js";
+export type { PhaseState, PhaseStatus, PlanState, PlanStatus, PlanSummary, TodoItem } from "./types.js";
+export { findActivePlan } from "./find-active-plan.js";
+export { parsePlanFile, type PlanScaffold } from "./parse-plan-file.js";
+export { parsePhaseFile } from "./parse-phase-file.js";
+export { listPlans } from "./list-plans.js";
+export { computePhaseFileEtag, computeAllPhaseEtags } from "./etag.js";
+export declare function readPlan(planDir: string): PlanState | null;
+/**
+ * Compute a cache key from filesystem mtimes (red-team H3).
+ * Returns a string like "1730403600000:1730403700000" or null if planDir gone.
+ */
+export declare function planMtimeKey(planDir: string): string | null;
+//# sourceMappingURL=index.d.ts.map

package/dist/orchviz/plan/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/orchviz/plan/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAc,SAAS,EAAE,MAAM,YAAY,CAAC;AAGxD,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACxG,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACxE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAQvE,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CA6C1D;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAa3D"}

package/dist/orchviz/plan/index.js

@@ -0,0 +1,91 @@
+/**
+ * orchviz plan parser — orchestrator for plan + phase files.
+ *
+ * Public API:
+ *   - findActivePlan(projectRoot)
+ *   - readPlan(planDir)
+ *
+ * Read-only by design. v1.1 does not write to plan files.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { PHASE_FILE_RE } from "./plan-constants.js";
+export { findActivePlan } from "./find-active-plan.js";
+export { parsePlanFile } from "./parse-plan-file.js";
+export { parsePhaseFile } from "./parse-phase-file.js";
+export { listPlans } from "./list-plans.js";
+export { computePhaseFileEtag, computeAllPhaseEtags } from "./etag.js";
+import { parsePlanFile } from "./parse-plan-file.js";
+import { parsePhaseFile } from "./parse-phase-file.js";
+import { createLogger } from "../logger.js";
+const log = createLogger("PlanReader");
+export function readPlan(planDir) {
+    const scaffold = parsePlanFile(planDir);
+    if (!scaffold)
+        return null;
+    // Use realpathSync for boundary so macOS /var→/private/var symlink doesn't break check
+    let resolvedPlanDir;
+    try {
+        resolvedPlanDir = fs.realpathSync(planDir);
+    }
+    catch {
+        return null;
+    }
+    const boundary = resolvedPlanDir + path.sep;
+    let entries;
+    try {
+        entries = fs.readdirSync(planDir);
+    }
+    catch {
+        return null;
+    }
+    const phaseFiles = [];
+    for (const name of entries) {
+        if (!PHASE_FILE_RE.test(name))
+            continue;
+        const full = path.join(planDir, name);
+        // Boundary check (red-team C1) — defense in depth even though planDir already checked.
+        let resolved;
+        try {
+            resolved = fs.realpathSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (!resolved.startsWith(boundary)) {
+            log.warn(`rejecting phase file outside boundary: ${full}`);
+            continue;
+        }
+        phaseFiles.push(full);
+    }
+    const phases = [];
+    for (const filePath of phaseFiles) {
+        const phase = parsePhaseFile(filePath);
+        if (phase)
+            phases.push(phase);
+    }
+    phases.sort((a, b) => a.number - b.number);
+    return { ...scaffold, phases };
+}
+/**
+ * Compute a cache key from filesystem mtimes (red-team H3).
+ * Returns a string like "1730403600000:1730403700000" or null if planDir gone.
+ */
+export function planMtimeKey(planDir) {
+    try {
+        const planStat = fs.statSync(path.join(planDir, "plan.md"));
+        let maxPhaseMtime = 0;
+        for (const name of fs.readdirSync(planDir)) {
+            if (!PHASE_FILE_RE.test(name))
+                continue;
+            const stat = fs.statSync(path.join(planDir, name));
+            if (stat.mtimeMs > maxPhaseMtime)
+                maxPhaseMtime = stat.mtimeMs;
+        }
+        return `${planStat.mtimeMs}:${maxPhaseMtime}`;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/orchviz/plan/index.js.map

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

package/dist/orchviz/plan/list-plans.d.ts

@@ -0,0 +1,19 @@
+/**
+ * listPlans — enumerate all non-archived plan dirs in tasks/plans/.
+ *
+ * Per red-team SEC#6: realpath boundary check is applied to EVERY subdir before
+ * any file inside is read. This mirrors the check in findActivePlan.
+ *
+ * Returns up to `limit` (default 100) PlanSummary objects sorted by plan.md
+ * mtimeMs descending (most recently modified first).
+ */
+import type { PlanSummary } from "./types.js";
+export interface ListPlansOptions {
+    limit?: number;
+}
+/**
+ * List all non-archived plans in projectRoot/tasks/plans/.
+ * Each candidate subdir is realpath-checked against the boundary before read.
+ */
+export declare function listPlans(projectRoot: string, opts?: ListPlansOptions): PlanSummary[];
+//# sourceMappingURL=list-plans.d.ts.map

package/dist/orchviz/plan/list-plans.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-plans.d.ts","sourceRoot":"","sources":["../../../src/orchviz/plan/list-plans.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EAAc,WAAW,EAAE,MAAM,YAAY,CAAC;AAoE1D,MAAM,WAAW,gBAAgB;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,GAAE,gBAAqB,GAAG,WAAW,EAAE,CAyEzF"}