@selfagency/beans-mcp 0.4.2 → 0.6.0

package/index.d.ts

@@ -3,7 +3,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 /**
  * Public types for beans-mcp-server
  */
-type SortMode = "status-priority-type-title" | "updated" | "created" | "id";
+type SortMode = 'status-priority-type-title' | 'updated' | 'created' | 'id';
 type BeanRecord = {
     id: string;
     slug: string;
@@ -38,6 +38,7 @@ declare const DEFAULT_MCP_PORT = 39173;
 declare const MAX_ID_LENGTH = 128;
 declare const MAX_TITLE_LENGTH = 1024;
 declare const MAX_METADATA_LENGTH = 128;
+declare const MAX_PATH_LENGTH = 1024;
 
 declare function sortBeansInternal(beans: BeanRecord[], mode: SortMode): BeanRecord[];
 
@@ -47,6 +48,11 @@ declare function sortBeansInternal(beans: BeanRecord[], mode: SortMode): BeanRec
  */
 interface BackendInterface {
     init(prefix?: string): Promise<Record<string, unknown>>;
+    archive?(): Promise<Record<string, unknown>>;
+    queryGraphql?(query: string, variables?: Record<string, unknown>): Promise<{
+        data: unknown;
+        errors?: GraphQLError[];
+    }>;
     list(options?: {
         status?: string[];
         type?: string[];
@@ -57,6 +63,8 @@ interface BackendInterface {
         type: string;
         status?: string;
         priority?: string;
+        /** Body markdown content. `description` is a deprecated alias. */
+        body?: string;
         description?: string;
         parent?: string;
     }): Promise<BeanRecord>;
@@ -77,6 +85,39 @@ interface BackendInterface {
         ifMatch?: string;
     }): Promise<BeanRecord>;
     delete(beanId: string): Promise<Record<string, unknown>>;
+    bulkCreate(beans: Array<{
+        title: string;
+        type: string;
+        status?: string;
+        priority?: string;
+        body?: string;
+        description?: string;
+        parent?: string;
+    }>, defaultParent?: string): Promise<Array<{
+        bean?: BeanRecord;
+        error?: string;
+    }>>;
+    bulkUpdate(beans: Array<{
+        beanId: string;
+        status?: string;
+        type?: string;
+        priority?: string;
+        parent?: string;
+        clearParent?: boolean;
+        blocking?: string[];
+        blockedBy?: string[];
+        body?: string;
+        bodyAppend?: string;
+        bodyReplace?: Array<{
+            old: string;
+            new: string;
+        }>;
+        ifMatch?: string;
+    }>, defaultParent?: string): Promise<Array<{
+        beanId: string;
+        bean?: BeanRecord;
+        error?: string;
+    }>>;
     openConfig(): Promise<{
         configPath: string;
         content: string;
@@ -99,6 +140,23 @@ interface BackendInterface {
         path: string;
         bytes: number;
     }>;
+    updateBeanFrontmatter(relativePath: string, updates: {
+        title?: string;
+        status?: string;
+        type?: string;
+        priority?: string;
+        parent_id?: string | null;
+        tags?: string[] | null;
+        blocking_ids?: string[] | null;
+        blocked_by_ids?: string[] | null;
+        pr?: string | null;
+        branch?: string | null;
+    }): Promise<{
+        path: string;
+        bytes: number;
+        updatedFields: string[];
+        frontmatter: Record<string, string | string[]>;
+    }>;
     createBeanFile(relativePath: string, content: string, options?: {
         overwrite?: boolean;
     }): Promise<{
@@ -120,6 +178,14 @@ declare class BeansCliBackend implements BackendInterface {
     private readonly cliPath;
     private readonly logDir?;
     constructor(workspaceRoot: string, cliPath: string, logDir?: string | undefined);
+    /** Full unfiltered records keyed by bean ID, stored under the fixed cache key `'all'`. */
+    private readonly _cache;
+    /** Last time the unfiltered cache entry `'all'` was fetched (ms). */
+    private readonly _cacheTime;
+    /** Short-circuit TTL: skip even the timestamp check within this window (ms). */
+    private static readonly BURST_TTL_MS;
+    /** Invalidate the unfiltered list cache so the next call does a full fetch. */
+    private invalidateCache;
     /**
      * Returns a safe environment for executing the Beans CLI,
      * whitelisting only necessary variables.
@@ -132,6 +198,11 @@ declare class BeansCliBackend implements BackendInterface {
      */
     private executeGraphQL;
     init(prefix?: string): Promise<Record<string, unknown>>;
+    archive(): Promise<Record<string, unknown>>;
+    queryGraphql(query: string, variables?: Record<string, unknown>): Promise<{
+        data: unknown;
+        errors?: GraphQLError[];
+    }>;
     list(options?: {
         status?: string[];
         type?: string[];
@@ -142,6 +213,7 @@ declare class BeansCliBackend implements BackendInterface {
         type: string;
         status?: string;
         priority?: string;
+        body?: string;
         description?: string;
         parent?: string;
     }): Promise<BeanRecord>;
@@ -162,6 +234,39 @@ declare class BeansCliBackend implements BackendInterface {
         ifMatch?: string;
     }): Promise<BeanRecord>;
     delete(beanId: string): Promise<Record<string, unknown>>;
+    bulkCreate(beans: Array<{
+        title: string;
+        type: string;
+        status?: string;
+        priority?: string;
+        body?: string;
+        description?: string;
+        parent?: string;
+    }>, defaultParent?: string): Promise<Array<{
+        bean?: BeanRecord;
+        error?: string;
+    }>>;
+    bulkUpdate(beans: Array<{
+        beanId: string;
+        status?: string;
+        type?: string;
+        priority?: string;
+        parent?: string;
+        clearParent?: boolean;
+        blocking?: string[];
+        blockedBy?: string[];
+        body?: string;
+        bodyAppend?: string;
+        bodyReplace?: Array<{
+            old: string;
+            new: string;
+        }>;
+        ifMatch?: string;
+    }>, defaultParent?: string): Promise<Array<{
+        beanId: string;
+        bean?: BeanRecord;
+        error?: string;
+    }>>;
     openConfig(): Promise<{
         configPath: string;
         content: string;
@@ -176,6 +281,36 @@ declare class BeansCliBackend implements BackendInterface {
         content: string;
         linesReturned: number;
     }>;
+    /**
+     * Split a YAML scalar value from any trailing inline comment.
+     * Understands single-quoted and double-quoted YAML strings so it won't
+     * mistake a `#` inside a quoted value for a comment delimiter.
+     */
+    private splitYamlInlineComment;
+    /** Returns true when `value` looks like a YAML block scalar indicator (`>`, `|`, `>-`, `|-`, etc.) */
+    private isYamlBlockScalarIndicator;
+    /** Escape a plain string for use inside a YAML double-quoted scalar. */
+    private escapeForYamlDoubleQuoted;
+    private shouldQuoteFrontmatterValue;
+    private parseFrontmatterLine;
+    private buildFrontmatterIndex;
+    private serializeFrontmatterValue;
+    private deserializeFrontmatterValue;
+    private splitFrontmatterDocument;
+    private parseFrontmatterFields;
+    private writeFileAtomically;
+    /**
+     * Normalise a raw YAML title value to a double-quoted scalar.
+     * Handles: empty, already double-quoted, single-quoted (unescaping `''`),
+     * block-scalar indicators, and plain unquoted values.
+     */
+    private normalizeFrontmatterTitleValue;
+    /**
+     * Ensure every `title:` line in YAML frontmatter is double-quoted.
+     * Handles already-quoted (single or double), multi-word, and special-char values.
+     * Preserves inline comments and handles both LF and CRLF line endings.
+     */
+    private quoteFrontmatterTitles;
     readBeanFile(relativePath: string): Promise<{
         path: string;
         content: string;
@@ -184,6 +319,23 @@ declare class BeansCliBackend implements BackendInterface {
         path: string;
         bytes: number;
     }>;
+    updateBeanFrontmatter(relativePath: string, updates: {
+        title?: string;
+        status?: string;
+        type?: string;
+        priority?: string;
+        parent_id?: string | null;
+        tags?: string[] | null;
+        blocking_ids?: string[] | null;
+        blocked_by_ids?: string[] | null;
+        pr?: string | null;
+        branch?: string | null;
+    }): Promise<{
+        path: string;
+        bytes: number;
+        updatedFields: string[];
+        frontmatter: Record<string, string | string[]>;
+    }>;
     createBeanFile(relativePath: string, content: string, options?: {
         overwrite?: boolean;
     }): Promise<{
@@ -235,4 +387,4 @@ declare function makeTextAndStructured<T extends Record<string, unknown>>(value:
     }[];
 };
 
-export { type BackendInterface, type BeanRecord, BeansCliBackend, DEFAULT_MCP_PORT, type GraphQLError, MAX_ID_LENGTH, MAX_METADATA_LENGTH, MAX_TITLE_LENGTH, type SortMode, createBeansMcpServer, isPathWithinRoot, makeTextAndStructured, parseCliArgs, sortBeansInternal as sortBeans, startBeansMcpServer };
+export { type BackendInterface, type BeanRecord, BeansCliBackend, DEFAULT_MCP_PORT, type GraphQLError, MAX_ID_LENGTH, MAX_METADATA_LENGTH, MAX_PATH_LENGTH, MAX_TITLE_LENGTH, type SortMode, createBeansMcpServer, isPathWithinRoot, makeTextAndStructured, parseCliArgs, sortBeansInternal as sortBeans, startBeansMcpServer };