@ambitresearch/genie 1.3.1

package/dist/middleware/plan-guard.js

@@ -0,0 +1,190 @@
+/**
+ * `withPlanGuard` — centralised plan-vs-write guard middleware (M1-13,
+ * DRO-239).
+ *
+ * BEFORE this file, every plan-gated verb (`write_files`, `delete_files`) had
+ * to reimplement the same four checks — planId presence, planId existence,
+ * planId expiry, and per-path glob membership. When they drifted (as they
+ * already had: `write_files` split path-outside-plan into `"glob"` vs
+ * `"escapesLocalDir"` sub-reasons while `delete_files` used a single message,
+ * and only `plan.ts` emitted a structured audit log), a request that would be
+ * rejected by one verb could slip through another with the same shape.
+ *
+ * This middleware makes the guard one seam: every plan-gated tool wraps its
+ * handler in `withPlanGuard(...)`, and the four checks (AC2 (a)–(d)) live
+ * here, produce one canonical JSON-RPC `-32602 InvalidParams`-shaped payload
+ * (AC3), and emit one canonical `plan.guard.reject` audit line (AC6). The
+ * refactored write/delete tools stop re-implementing these checks entirely.
+ *
+ * Tool-side error taxonomies (e.g. `write_files`' `PayloadTooLargeError`,
+ * `delete_files`' `DeleteFailed`) stay in the tools — this middleware only
+ * owns the plan-boundary check, matching the issue's scope ("one middleware
+ * so every write/delete/register/unregister call funnels through identical
+ * validation"), and stops at that boundary so tools remain responsible for
+ * their own downstream error shapes.
+ */
+import { getPlan, pathMatchesGlobs, PlanNotFoundError } from "../plans/index.js";
+// ─── AC3: canonical JSON-RPC-shaped rejection payload ────────────────────
+/**
+ * Build the structured tool-result for a rejection. Mirrors the JSON-RPC
+ * `-32602 InvalidParams` error object (`{ code, message, data }`) exactly, so
+ * an MCP client can parse the tool response as JSON and branch on
+ * `code`/`data.reason` the same way it would branch on a wire-level error —
+ * without needing to know which specific tool it called.
+ *
+ * `isError: true` makes the SDK surface this as a tool failure (not a
+ * regular result) so the client's `isError` check trips.
+ */
+function guardErrorResult(message, reason, extra = {}) {
+    const data = { reason };
+    if (extra.planId !== undefined)
+        data.planId = extra.planId;
+    if (extra.path !== undefined)
+        data.path = extra.path;
+    const payload = { code: -32602, message, data };
+    return {
+        isError: true,
+        content: [{ type: "text", text: JSON.stringify(payload) }],
+    };
+}
+// ─── AC6: structured plan.guard.reject audit log ─────────────────────────
+/**
+ * Emit an audit-log line to stderr (never stdout — on the stdio MCP
+ * transport, stdout IS the protocol stream and a stray line there corrupts
+ * every client's message framing; `plan.ts` follows the same convention for
+ * its `plan.created` event, see the comment there).
+ *
+ * Only the guard's own metadata is logged: `event`, `planId` (when known),
+ * `reason`, `path` (when path-specific). Never the file contents, `data`
+ * payloads, `localPath` bytes, or anything else that came off the wire — a
+ * plan-boundary rejection is a security-relevant event, and the log is what
+ * an operator inspects afterwards; leaking the rejected payload defeats the
+ * point.
+ */
+function logGuardReject(planId, reason, path) {
+    const line = { event: "plan.guard.reject", reason };
+    if (planId !== undefined)
+        line.planId = planId;
+    if (path !== undefined)
+        line.path = path;
+    process.stderr.write(JSON.stringify(line) + "\n");
+}
+// ─── Path extraction ─────────────────────────────────────────────────────
+/**
+ * Default path extractor for the two shipping tool shapes:
+ *   - `mode: "writes"` (write_files) → `args.files[].path`
+ *   - `mode: "deletes"` (delete_files) → `args[pathsKey ?? "paths"]` as a `string[]`
+ *
+ * A malformed shape (e.g. `files` isn't an array) is treated as "no paths to
+ * check": the guard will then delegate to the wrapped handler, which owns
+ * shape validation via its Zod input schema (see `deleteFilesArgsSchema` in
+ * delete_files.ts, `fileInputSchema` in write_files.ts). This split matches
+ * the wrapped tools' own precedent — plan checks answer "is this authorised?",
+ * shape checks answer "is this well-formed?" — and keeps the guard from
+ * needing to know each tool's input schema.
+ */
+function defaultExtractPaths(args, mode, pathsKey) {
+    if (typeof args !== "object" || args === null)
+        return [];
+    if (mode === "writes") {
+        const files = args.files;
+        if (!Array.isArray(files))
+            return [];
+        const out = [];
+        for (const file of files) {
+            if (typeof file === "object" &&
+                file !== null &&
+                typeof file.path === "string") {
+                out.push(file.path);
+            }
+        }
+        return out;
+    }
+    // mode === "deletes"
+    const key = pathsKey ?? "paths";
+    const paths = args[key];
+    if (!Array.isArray(paths))
+        return [];
+    return paths.filter((p) => typeof p === "string");
+}
+// ─── The guard itself ────────────────────────────────────────────────────
+/**
+ * Wrap a plan-gated tool handler so every call funnels through one plan-vs-
+ * write validation seam.
+ *
+ * Order of checks — matches AC2 (a)→(d), and is intentionally the same order
+ * the tool would fail-fast on today:
+ *
+ *   1. **planId present** (AC2(a)) — string, non-empty. Missing values are
+ *      rejected before touching the plan registry: a `getPlan("")` would
+ *      throw as "not found", which would lose the distinction the reason
+ *      enum draws between "you forgot to send a planId" and "the planId you
+ *      sent doesn't match any plan we have." Clients act on those
+ *      differently (the first is a client bug; the second may be an expired
+ *      capability grant that needs re-issuing).
+ *
+ *   2. **planId exists + not expired** (AC2(b)+(c)) — `getPlan` throws
+ *      `PlanNotFoundError` for both, so they surface as one `planNotFound`
+ *      reason (see the enum comment above for why).
+ *
+ *   3. **path matches plan globs** (AC2(d)) — every extracted path is
+ *      checked against `plan.writes` or `plan.deletes` per `options.mode`.
+ *      Fails on the FIRST offending path: the exact offending path is
+ *      surfaced (both in the returned payload and the audit log), so an
+ *      operator investigating a rejection knows which specific path
+ *      tripped the guard without having to diff the whole request against
+ *      the plan's glob list.
+ *
+ * Only if all three pass does the wrapped handler run — with the resolved
+ * plan handed through in `ctx.plan`, so it doesn't re-fetch (see
+ * `PlanGuardContext`).
+ *
+ * Non-guard errors (a `getPlan` throw that isn't `PlanNotFoundError`, or
+ * a handler throw) are NOT swallowed — they propagate as-is, so a
+ * disk-corrupt plan snapshot or an internal handler bug is still visible to
+ * the transport layer (as an MCP internal error), rather than being masked
+ * as a plan-boundary rejection.
+ */
+export function withPlanGuard(options, handler) {
+    return async (args) => {
+        // AC2(a) — planId presence.
+        const planIdRaw = args?.planId;
+        if (typeof planIdRaw !== "string" || planIdRaw.length === 0) {
+            logGuardReject(undefined, "planIdMissing");
+            return guardErrorResult("planId is required: every plan-gated call must present a planId returned by mcp__genie__plan.", "planIdMissing");
+        }
+        const planId = planIdRaw;
+        // AC2(b)+(c) — planId exists + not expired. `getPlan` collapses both into
+        // one PlanNotFoundError; anything else (disk read failure, corrupt JSON,
+        // …) is genuinely internal and should propagate rather than masquerade
+        // as a plan-boundary rejection.
+        let plan;
+        try {
+            plan = await getPlan(planId);
+        }
+        catch (error) {
+            if (error instanceof PlanNotFoundError) {
+                logGuardReject(planId, "planNotFound");
+                return guardErrorResult(`Plan "${planId}" not found or expired. Plans expire after 1h of inactivity — request a new one via mcp__genie__plan.`, "planNotFound", { planId });
+            }
+            throw error;
+        }
+        // AC2(d) — path membership.
+        //
+        // `extractPaths` is opt-in (for non-standard input shapes); otherwise
+        // fall back to the default extractor per mode.
+        const paths = options.extractPaths
+            ? options.extractPaths(args)
+            : defaultExtractPaths(args, options.mode, options.pathsKey);
+        const globs = options.mode === "writes" ? plan.writes : plan.deletes;
+        for (const path of paths) {
+            if (!pathMatchesGlobs(path, globs)) {
+                logGuardReject(planId, "pathOutsidePlan", path);
+                return guardErrorResult(`Path "${path}" is not covered by the plan's ${options.mode}.`, "pathOutsidePlan", { planId, path });
+            }
+        }
+        // Passthrough — hand the resolved plan to the wrapped handler.
+        return handler(args, { plan });
+    };
+}
+//# sourceMappingURL=plan-guard.js.map

package/dist/middleware/plan-guard.js.map

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

package/dist/plans/index.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Plan registry and state management.
+ *
+ * A plan is the single user-visible permission grant that locks `writes`,
+ * `deletes`, and `localDir`. Plans persist to disk at
+ * `${GENIE_HOME}/plans/<planId>.json` so they survive server restarts.
+ *
+ * Plans expire after 1 hour of inactivity (configurable via GENIE_PLAN_TTL).
+ */
+/** Max number of write patterns allowed per plan. */
+export declare const MAX_WRITES = 256;
+/** Max number of wildcards per glob pattern. */
+export declare const MAX_WILDCARDS = 3;
+/** Default plan TTL in milliseconds (1 hour). */
+export declare const DEFAULT_PLAN_TTL: number;
+/** Environment variable to override plan TTL. */
+export declare const PLAN_TTL_ENV = "GENIE_PLAN_TTL";
+/** True if `planId` has the UUID shape every real plan uses. */
+export declare function isValidPlanId(planId: string): boolean;
+/** Plan state persisted to disk. */
+export interface PlanState {
+    planId: string;
+    kitId: string;
+    writes: string[];
+    deletes: string[];
+    localDir: string;
+    createdAt: string;
+    lastAccessedAt: string;
+}
+/** Error thrown when too many write patterns are provided. */
+export declare class TooManyWritesError extends Error {
+    readonly count: number;
+    constructor(count: number);
+}
+/** Error thrown when a glob pattern has too many wildcards. */
+export declare class TooComplexGlobError extends Error {
+    readonly pattern: string;
+    readonly wildcardCount: number;
+    constructor(pattern: string, wildcardCount: number);
+}
+/** Error thrown when a plan is not found or has expired. */
+export declare class PlanNotFoundError extends Error {
+    readonly planId: string;
+    constructor(planId: string);
+}
+/** Validate glob patterns against complexity limits. */
+export declare function validateGlobPatterns(patterns: string[]): void;
+/** Get the plan TTL in milliseconds. */
+export declare function getPlanTTL(): number;
+/** Create a new plan and persist it. */
+export declare function createPlan(kitId: string, writes: string[], deletes: string[], localDir: string): Promise<PlanState>;
+/** Retrieve a plan by ID, checking expiry. */
+export declare function getPlan(planId: string): Promise<PlanState>;
+/** Check if a path matches any glob pattern in the plan. */
+export declare function pathMatchesGlobs(path: string, globs: string[]): boolean;
+/**
+ * Validate that a path is inside the plan's localDir.
+ *
+ * Uses `path.relative`/`path.isAbsolute` rather than a string check against a
+ * hard-coded "/" separator, so containment is correct across platforms (POSIX
+ * and Windows) — mirrors `safePath` in `store/local.ts` and `read_file.ts`.
+ *
+ * A relative `path` is resolved against `localDir` (the RFC's base for
+ * resolving `localPath` in `write_files`), NOT against `process.cwd()` — so
+ * containment stays correct even when the server's cwd differs from localDir.
+ * An absolute `path` is checked as-is.
+ */
+export declare function isPathInsideLocalDir(path: string, localDir: string): boolean;
+/** Clear expired plans from the registry and disk (housekeeping). */
+export declare function pruneExpiredPlans(): Promise<number>;
+//# sourceMappingURL=index.d.ts.map

package/dist/plans/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/plans/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAgBH,qDAAqD;AACrD,eAAO,MAAM,UAAU,MAAM,CAAC;AAE9B,gDAAgD;AAChD,eAAO,MAAM,aAAa,IAAI,CAAC;AAE/B,iDAAiD;AACjD,eAAO,MAAM,gBAAgB,QAAiB,CAAC;AAE/C,iDAAiD;AACjD,eAAO,MAAM,YAAY,mBAAmB,CAAC;AAU7C,gEAAgE;AAChE,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAErD;AAED,oCAAoC;AACpC,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,8DAA8D;AAC9D,qBAAa,kBAAmB,SAAQ,KAAK;aACf,KAAK,EAAE,MAAM;gBAAb,KAAK,EAAE,MAAM;CAI1C;AAED,+DAA+D;AAC/D,qBAAa,mBAAoB,SAAQ,KAAK;aAE1B,OAAO,EAAE,MAAM;aACf,aAAa,EAAE,MAAM;gBADrB,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,MAAM;CAQxC;AAED,4DAA4D;AAC5D,qBAAa,iBAAkB,SAAQ,KAAK;aACd,MAAM,EAAE,MAAM;gBAAd,MAAM,EAAE,MAAM;CAI3C;AASD,wDAAwD;AACxD,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,CAO7D;AAWD,wCAAwC;AACxC,wBAAgB,UAAU,IAAI,MAAM,CASnC;AA4CD,wCAAwC;AACxC,wBAAsB,UAAU,CAC9B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EAAE,EAChB,OAAO,EAAE,MAAM,EAAE,EACjB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,SAAS,CAAC,CA6BpB;AAED,8CAA8C;AAC9C,wBAAsB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CA6ChE;AAED,4DAA4D;AAC5D,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAEvE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAa5E;AAED,qEAAqE;AACrE,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC,CAezD"}

package/dist/plans/index.js

@@ -0,0 +1,252 @@
+/**
+ * Plan registry and state management.
+ *
+ * A plan is the single user-visible permission grant that locks `writes`,
+ * `deletes`, and `localDir`. Plans persist to disk at
+ * `${GENIE_HOME}/plans/<planId>.json` so they survive server restarts.
+ *
+ * Plans expire after 1 hour of inactivity (configurable via GENIE_PLAN_TTL).
+ */
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+// micromatch is CJS-only and assigns its named helpers (isMatch, braces, …)
+// as properties on the exported function itself, rather than as separate
+// `module.exports.foo = ...` assignments. Node's cjs-module-lexer can't
+// statically see those, so both a namespace import (`import * as
+// micromatch`) and a named import (`import { isMatch }`) fail at runtime
+// under real Node ESM (`import * as` silently yields `{default, "module.exports"}`
+// with no `isMatch`; a named import throws SyntaxError at load time) even
+// though Vitest's esbuild-based transform papers over it in tests. A default
+// import is the one shape that works both under esbuild and real Node ESM.
+import micromatch from "micromatch";
+/** Max number of write patterns allowed per plan. */
+export const MAX_WRITES = 256;
+/** Max number of wildcards per glob pattern. */
+export const MAX_WILDCARDS = 3;
+/** Default plan TTL in milliseconds (1 hour). */
+export const DEFAULT_PLAN_TTL = 60 * 60 * 1000;
+/** Environment variable to override plan TTL. */
+export const PLAN_TTL_ENV = "GENIE_PLAN_TTL";
+/**
+ * Plan IDs are always UUIDs (see `createPlan` → `randomUUID`). Validating the
+ * shape up front lets `getPlan` reject a malformed/hostile `planId` — e.g. a
+ * path-traversal value like `"../../x"` — before it is ever interpolated into a
+ * `${GENIE_HOME}/plans/<planId>.json` disk path.
+ */
+const PLAN_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** True if `planId` has the UUID shape every real plan uses. */
+export function isValidPlanId(planId) {
+    return PLAN_ID_PATTERN.test(planId);
+}
+/** Error thrown when too many write patterns are provided. */
+export class TooManyWritesError extends Error {
+    count;
+    constructor(count) {
+        super(`Too many write patterns: ${count}. Maximum allowed is ${MAX_WRITES}.`);
+        this.count = count;
+        this.name = "TooManyWritesError";
+    }
+}
+/** Error thrown when a glob pattern has too many wildcards. */
+export class TooComplexGlobError extends Error {
+    pattern;
+    wildcardCount;
+    constructor(pattern, wildcardCount) {
+        super(`Glob pattern "${pattern}" has ${wildcardCount} wildcards. ` +
+            `Maximum allowed is ${MAX_WILDCARDS}.`);
+        this.pattern = pattern;
+        this.wildcardCount = wildcardCount;
+        this.name = "TooComplexGlobError";
+    }
+}
+/** Error thrown when a plan is not found or has expired. */
+export class PlanNotFoundError extends Error {
+    planId;
+    constructor(planId) {
+        super(`Plan "${planId}" not found or expired.`);
+        this.planId = planId;
+        this.name = "PlanNotFoundError";
+    }
+}
+/** Count wildcards in a glob pattern. */
+function countWildcards(pattern) {
+    // Count * and ** (double-asterisk counts as one wildcard for this rule)
+    const stars = pattern.match(/\*+/g) || [];
+    return stars.length;
+}
+/** Validate glob patterns against complexity limits. */
+export function validateGlobPatterns(patterns) {
+    for (const pattern of patterns) {
+        const wildcardCount = countWildcards(pattern);
+        if (wildcardCount > MAX_WILDCARDS) {
+            throw new TooComplexGlobError(pattern, wildcardCount);
+        }
+    }
+}
+/** In-memory plan registry. */
+const planRegistry = new Map();
+/** Get the plans directory path from GENIE_HOME. */
+function getPlansDir() {
+    const home = process.env.GENIE_HOME || resolve(process.cwd(), ".genie");
+    return resolve(home, "plans");
+}
+/** Get the plan TTL in milliseconds. */
+export function getPlanTTL() {
+    const envTTL = process.env[PLAN_TTL_ENV];
+    if (envTTL) {
+        const parsed = parseInt(envTTL, 10);
+        if (!isNaN(parsed) && parsed > 0) {
+            return parsed;
+        }
+    }
+    return DEFAULT_PLAN_TTL;
+}
+/** Load a plan from disk. Returns null if missing or unreadable/corrupt. */
+async function loadPlanFromDisk(planId) {
+    const plansDir = getPlansDir();
+    const planPath = resolve(plansDir, `${planId}.json`);
+    try {
+        const content = await readFile(planPath, "utf-8");
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+/** Save a plan to disk. */
+async function savePlanToDisk(state) {
+    const plansDir = getPlansDir();
+    await mkdir(plansDir, { recursive: true });
+    const planPath = resolve(plansDir, `${state.planId}.json`);
+    await writeFile(planPath, JSON.stringify(state, null, 2), "utf-8");
+}
+/** Delete a plan's disk snapshot, if any. Missing file is not an error. */
+async function deletePlanFromDisk(planId) {
+    const plansDir = getPlansDir();
+    const planPath = resolve(plansDir, `${planId}.json`);
+    try {
+        await unlink(planPath);
+    }
+    catch {
+        // Already gone (or never persisted) — nothing to clean up.
+    }
+}
+/** Check if a plan has expired based on TTL. */
+function isPlanExpired(state) {
+    const ttl = getPlanTTL();
+    const lastAccessed = new Date(state.lastAccessedAt).getTime();
+    const now = Date.now();
+    return now - lastAccessed > ttl;
+}
+/** Create a new plan and persist it. */
+export async function createPlan(kitId, writes, deletes, localDir) {
+    // Validate write count
+    if (writes.length > MAX_WRITES) {
+        throw new TooManyWritesError(writes.length);
+    }
+    // Validate glob complexity
+    validateGlobPatterns(writes);
+    validateGlobPatterns(deletes);
+    // Create plan state
+    const planId = randomUUID();
+    const now = new Date().toISOString();
+    const state = {
+        planId,
+        kitId,
+        writes,
+        deletes,
+        localDir,
+        createdAt: now,
+        lastAccessedAt: now,
+    };
+    // Store in registry and persist
+    planRegistry.set(planId, state);
+    await savePlanToDisk(state);
+    return state;
+}
+/** Retrieve a plan by ID, checking expiry. */
+export async function getPlan(planId) {
+    // Reject a malformed/hostile planId before it ever touches a disk path.
+    // Every real plan id is a UUID; anything else (e.g. a "../../x" traversal
+    // value) cannot correspond to a plan we created, so treat it as not-found.
+    if (!isValidPlanId(planId)) {
+        throw new PlanNotFoundError(planId);
+    }
+    // Check in-memory registry first
+    let state = planRegistry.get(planId);
+    // Fall back to disk if not in memory
+    if (!state) {
+        state = await loadPlanFromDisk(planId);
+        if (state) {
+            // Defense in depth: the on-disk JSON is untrusted (a tampered snapshot
+            // could carry a `planId` that differs from the file it was read from,
+            // e.g. a traversal value that `savePlanToDisk` would later write outside
+            // the plans dir). Only trust a snapshot whose embedded id matches the id
+            // we looked up.
+            if (state.planId !== planId) {
+                throw new PlanNotFoundError(planId);
+            }
+            planRegistry.set(planId, state);
+        }
+    }
+    if (!state) {
+        throw new PlanNotFoundError(planId);
+    }
+    // Check expiry
+    if (isPlanExpired(state)) {
+        planRegistry.delete(planId);
+        // Clean up the on-disk snapshot too, so expired plans don't accumulate
+        // indefinitely under `${GENIE_HOME}/plans/`.
+        await deletePlanFromDisk(planId);
+        throw new PlanNotFoundError(planId);
+    }
+    // Update last accessed time
+    state.lastAccessedAt = new Date().toISOString();
+    await savePlanToDisk(state);
+    return state;
+}
+/** Check if a path matches any glob pattern in the plan. */
+export function pathMatchesGlobs(path, globs) {
+    return micromatch.isMatch(path, globs, { dot: true });
+}
+/**
+ * Validate that a path is inside the plan's localDir.
+ *
+ * Uses `path.relative`/`path.isAbsolute` rather than a string check against a
+ * hard-coded "/" separator, so containment is correct across platforms (POSIX
+ * and Windows) — mirrors `safePath` in `store/local.ts` and `read_file.ts`.
+ *
+ * A relative `path` is resolved against `localDir` (the RFC's base for
+ * resolving `localPath` in `write_files`), NOT against `process.cwd()` — so
+ * containment stays correct even when the server's cwd differs from localDir.
+ * An absolute `path` is checked as-is.
+ */
+export function isPathInsideLocalDir(path, localDir) {
+    const resolvedLocalDir = resolve(localDir);
+    const resolvedPath = resolve(resolvedLocalDir, path);
+    // Identical paths are trivially "inside".
+    if (resolvedPath === resolvedLocalDir) {
+        return true;
+    }
+    const rel = relative(resolvedLocalDir, resolvedPath);
+    // `rel` escapes localDir if it's ".." itself, starts with a ".." segment,
+    // or is absolute (e.g. a different drive on Windows).
+    return rel !== "" && rel !== ".." && !rel.startsWith(".." + sep) && !isAbsolute(rel);
+}
+/** Clear expired plans from the registry and disk (housekeeping). */
+export async function pruneExpiredPlans() {
+    let pruned = 0;
+    const now = Date.now();
+    const ttl = getPlanTTL();
+    for (const [planId, state] of planRegistry.entries()) {
+        const lastAccessed = new Date(state.lastAccessedAt).getTime();
+        if (now - lastAccessed > ttl) {
+            planRegistry.delete(planId);
+            await deletePlanFromDisk(planId);
+            pruned++;
+        }
+    }
+    return pruned;
+}
+//# sourceMappingURL=index.js.map

package/dist/plans/index.js.map

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

package/dist/schemas/component.schema.json

@@ -0,0 +1,114 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://genie.dev/schema/component.schema.json",
+  "title": "GenieComponent",
+  "description": "The file set + manifest metadata conjure/refine demand from the configured LLM endpoint via response_format.json_schema (M2-02).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "componentName",
+    "group",
+    "files",
+    "manifestEntry"
+  ],
+  "definitions": {
+    "Viewport": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "width",
+        "height"
+      ],
+      "properties": {
+        "width": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 4096
+        },
+        "height": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 4096
+        }
+      }
+    }
+  },
+  "properties": {
+    "componentName": {
+      "type": "string",
+      "description": "PascalCase component name, e.g. \"Button\".",
+      "pattern": "^[A-Z][A-Za-z0-9]{1,63}$"
+    },
+    "group": {
+      "type": "string",
+      "description": "Kebab-case UI-kit group/category, e.g. \"actions\".",
+      "pattern": "^[a-z0-9-]{1,32}$"
+    },
+    "files": {
+      "type": "array",
+      "description": "The component's file set (e.g. <Name>.jsx, <Name>.tsx, <Name>.d.ts, <Name>.prompt.md, <Name>.html, meta.json) — at least one must be a <Name>.html preview file (AC5).",
+      "minItems": 1,
+      "maxItems": 12,
+      "contains": {
+        "type": "object",
+        "properties": {
+          "path": {
+            "type": "string",
+            "pattern": "^components/[a-z0-9-]+/([A-Z][A-Za-z0-9]{1,63})/\\1\\.html$"
+          }
+        }
+      },
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "path",
+          "content",
+          "mimeType"
+        ],
+        "properties": {
+          "path": {
+            "type": "string",
+            "description": "Kit-relative path under components/<group>/<Name>/.",
+            "pattern": "^components/[a-z0-9-]+/[A-Z][A-Za-z0-9]+/[A-Za-z0-9._-]+$"
+          },
+          "content": {
+            "type": "string",
+            "description": "Full file contents (AC5: an <Name>.html entry's content must begin with the @genie marker — checked post-hoc by M3-01/M2-07, not by this schema).",
+            "minLength": 1,
+            "maxLength": 65536
+          },
+          "mimeType": {
+            "type": "string",
+            "description": "MIME type of `content`, e.g. \"text/html\".",
+            "pattern": "^[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]*/[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]*$"
+          }
+        }
+      }
+    },
+    "manifestEntry": {
+      "type": "object",
+      "description": "Metadata the manifest compiler (M3-03) needs to add this card to .genie/manifest.json without re-deriving it from the files themselves.",
+      "additionalProperties": false,
+      "required": [
+        "viewport"
+      ],
+      "properties": {
+        "viewport": {
+          "$ref": "#/definitions/Viewport"
+        },
+        "subtitle": {
+          "type": "string",
+          "maxLength": 256
+        },
+        "tags": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "maxItems": 16
+        }
+      }
+    }
+  }
+}