@attentionform/astra-mcp-server 0.0.0-stage → 0.1.0

package/dist/lib/mcp/handlers/save-close.d.ts

@@ -0,0 +1,76 @@
+import { type StyleWarning } from '@attentionform/astra-engine';
+import type { McpSessionStore } from '../../session-store';
+import type { McpErrorShape } from '../errors';
+import type { ChangedValue } from '../diff';
+/**
+ * Validating save — throwing core.
+ * M2 contract (consistent, tested):
+ * - executeSaveDocument THROWS on every failure (invalid input E_VALIDATION,
+ *   unknown/expired session E_SESSION, sandbox escape E_SANDBOX, invalid
+ *   package E_VALIDATION, write failure E_IO). All throws carry {code,remedy}.
+ * - handleSaveDocument NEVER throws: it wraps this core and maps every throw
+ *   to the {ok:false,code,remedy} return contract. Tool transport MUST go
+ *   through handleSaveDocument (single source of truth).
+ * Never writes corruption: OOXML validation gates the write, and the save
+ * target is jailed (M3) before any mkdir/write.
+ */
+export declare function executeSaveDocument(store: McpSessionStore, input: unknown): Promise<{
+    ok: true;
+    sessionId: string;
+    path: string;
+    revision: number;
+    commitOid: string;
+    commitMessage: string;
+    /** R-1: pending tracked revisions (w:ins + w:del) in the saved package. */
+    revisionsPending: number;
+    /** R-1: accept remedy, present only when revisionsPending > 0. */
+    revisionsRemedy?: string;
+    /** Advisory old→new value summaries (saved baseline -> live just saved; bounded, see CHANGED_VALUES_MAX). */
+    changedValues: ChangedValue[];
+    /** True when the count or per-string cap truncated changedValues. */
+    changedValuesTruncated: boolean;
+    /** Present when no baseline was computable (new target / unreadable bytes). */
+    changedValuesReason?: string;
+    /** Normalizer rewrites applied by this save (display-only core log). */
+    normalized: string[];
+    /**
+     * Advisory style findings under the session guide (never blocking).
+     * Absent when no guide is attached (guide-less saves stay byte-identical).
+     */
+    styleWarnings?: StyleWarning[];
+}>;
+/**
+ * M2: return-contract wrapper — NEVER throws.
+ * Maps every executeSaveDocument throw to {ok:false,code,remedy} so tool
+ * transport sees a single consistent shape. Tested: invalid input, sandbox
+ * escape, unknown session, and validation failure all return (never throw).
+ */
+export declare function handleSaveDocument(store: McpSessionStore, input: unknown): Promise<{
+    ok: true;
+    sessionId: string;
+    path: string;
+    revision: number;
+    commitOid: string;
+    commitMessage: string;
+    /** R-1: pending tracked revisions (w:ins + w:del) in the saved package. */
+    revisionsPending: number;
+    /** R-1: accept remedy, present only when revisionsPending > 0. */
+    revisionsRemedy?: string;
+    /** Advisory old→new value summaries (saved baseline -> live just saved; bounded). */
+    changedValues: ChangedValue[];
+    /** True when the count or per-string cap truncated changedValues. */
+    changedValuesTruncated: boolean;
+    /** Present when no baseline was computable. */
+    changedValuesReason?: string;
+    /** Normalizer rewrites applied by this save (display-only core log). */
+    normalized: string[];
+    /** Advisory style findings under the session guide (absent without a guide). */
+    styleWarnings?: StyleWarning[];
+} | McpErrorShape>;
+export declare function handleCloseDocument(store: McpSessionStore, input: unknown): Promise<{
+    ok: true;
+    sessionId: string;
+    dirty: boolean;
+    discardedRevisions: number;
+    warning?: string;
+} | McpErrorShape>;

package/dist/lib/mcp/handlers/search-batch.d.ts

@@ -0,0 +1,55 @@
+import { type McpSessionStore } from '../../session-store';
+import type { McpErrorShape } from '../errors';
+import type { BatchOpCreatedIds } from '../diff';
+/**
+ * Phase C-3 bounds: regex patterns longer than this are rejected
+ * fail-closed (the base query cap is 500; regex gets a tighter bound).
+ */
+export declare const SEARCH_REGEX_MAX_PATTERN = 200;
+/** Phase C-3: wall-clock budget for one regex evaluation pass over the AST. */
+export declare const SEARCH_REGEX_TIME_BUDGET_MS = 500;
+/** Generic remedy for regex search failures (no pattern echo, no hit hint). */
+export declare const SEARCH_REGEX_GENERIC_REMEDY = "Fix the regular-expression syntax and retry, or omit regex:true for a literal substring search.";
+export declare function handleSearchContent(store: McpSessionStore, input: unknown): Promise<{
+    ok: true;
+    sessionId: string;
+    matches: Array<{
+        id: string;
+        preview: string;
+        cells?: string[];
+    }>;
+    results: Array<{
+        id: string;
+        preview: string;
+        cells?: string[];
+    }>;
+    hint?: string;
+} | McpErrorShape>;
+export declare function handleExecuteBatch(store: McpSessionStore, input: unknown): Promise<{
+    ok: true;
+    sessionId: string;
+    appliedCount: number;
+    revision: number;
+    skippedIds: string[];
+    /** Advisory table warnings (additive, never a failure). */
+    warnings: string[];
+    /** New node ids created by this batch, in post-batch document order. */
+    createdNodeIds: string[];
+    /** Per-op attribution (client `id` claims are exact; remainder best-effort). */
+    results: BatchOpCreatedIds[];
+    /** R-1: pending tracked revisions (w:ins + w:del) remaining after the batch. */
+    revisionsPending: number;
+    /** R-1: accept remedy, present only when revisionsPending > 0. */
+    revisionsRemedy?: string;
+    /** R-14: advisory chart stale body refs (same shape [{nodeId, preview}]). Additive, never a failure. */
+    possiblyStaleBodyRefs: {
+        nodeId: string;
+        preview: string;
+    }[];
+    /** Normalizer rewrites reported for this batch (display-only core log). */
+    normalized: string[];
+    /** True only when this batch dropped a non-empty redo stack (absent otherwise). */
+    redoCleared?: boolean;
+    /** Names the dropped redo depth (present only when redoCleared). */
+    redoClearedWarning?: string;
+} | McpErrorShape>;

package/dist/lib/mcp/normalize-read.d.ts

@@ -0,0 +1,11 @@
+export type NormalizedRewrite = string;
+/** Display-only read of an engine result's `normalized` report ([] when absent). */
+export declare function readEngineNormalized(res: unknown): NormalizedRewrite[];
+/** Display-only read of the core's own normalizer log ([] when absent). */
+export declare function readParserNormalizations(parser: unknown): NormalizedRewrite[];
+/**
+ * Merge core logs across the rezips one save performs (gate rezip + save
+ * rezip), dropping exact duplicates. The gate's internal rezip already heals
+ * and logs, so reading only the final rezip would report a dishonest zero.
+ */
+export declare function mergeNormalized(...lists: string[][]): string[];

package/dist/lib/mcp/registry.d.ts

@@ -0,0 +1,12 @@
+import { handleOpenDocument, handleInspectDocument } from './handlers/open-inspect';
+import { handleSearchContent, handleExecuteBatch } from './handlers/search-batch';
+import { handleSaveDocument, handleCloseDocument } from './handlers/save-close';
+/** Lean-6 dispatch table (handlers above; research intentionally absent). */
+export declare const LEAN6_HANDLERS: {
+    readonly open_document: typeof handleOpenDocument;
+    readonly inspect_document: typeof handleInspectDocument;
+    readonly search_content: typeof handleSearchContent;
+    readonly execute_batch: typeof handleExecuteBatch;
+    readonly save_document: typeof handleSaveDocument;
+    readonly close_document: typeof handleCloseDocument;
+};

package/dist/lib/mcp/schema-dump.d.ts

@@ -0,0 +1,24 @@
+export declare const SCHEMA_STAMP_KEY = "x-generated-from";
+export declare function getServerVersion(): string;
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    schema: unknown;
+}
+export declare function getToolDefinitions(): ToolDefinition[];
+export declare function buildStamp(version: string): string;
+export declare function generateSchemasToDir(targetDir: string, version?: string): {
+    written: string[];
+    count: number;
+};
+export interface SchemaMismatch {
+    file: string;
+    stamped: string;
+    expected: string;
+}
+export declare function checkSchemasInDir(dir: string, expectedVersion?: string): {
+    ok: boolean;
+    mismatches: SchemaMismatch[];
+    checked: number;
+};
+export declare function formatMismatchWarning(mismatches: SchemaMismatch[]): string;