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

package/dist/lib/mcp/handlers/parity.d.ts

@@ -0,0 +1,127 @@
+import { PII_COVERAGE } from '@attentionform/astra-engine';
+import { type McpSessionStore } from '../../session-store';
+import { handleComposeDocument } from '../../../tools/compose-document';
+import type { McpErrorShape } from '../errors';
+export interface AuditValidation {
+    valid: boolean;
+    errorCount: number;
+    errors: Array<{
+        description: string;
+        xPath?: string;
+    }>;
+}
+/**
+ * validate_document: strictly read-only preflight ISO audit. The verdict runs
+ * on an isolated fork (see serializeSessionFork): revision, dirty flag,
+ * normalizer log, disk bytes, and history are all untouched. Never throws —
+ * every failure maps to {ok:false,code,remedy}.
+ */
+export declare function handleValidateDocument(store: McpSessionStore, input: unknown): Promise<{
+    ok: true;
+    sessionId: string;
+    revision: number;
+    dirty: boolean;
+    validation: AuditValidation;
+    /** Repairs a save would make (e.g. children put in schema order); absent when none. */
+    pendingNormalizations?: string[];
+    /** Advice when normalize_document can repair errors in the document. */
+    normalizeHint?: string;
+} | McpErrorShape>;
+/**
+ * get_stats: token-cheap census over the live AST (pure read: no revision
+ * bump, no dirty flip). Counters come from computeDocStats in @attentionform/astra-engine —
+ * the same definition CLI stats prints — so the two surfaces cannot drift.
+ * Never throws.
+ */
+export declare function handleGetStats(store: McpSessionStore, input: unknown): Promise<{
+    ok: true;
+    sessionId: string;
+    revision: number;
+    dirty: boolean;
+    words: number;
+    paragraphs: number;
+    tables: number;
+    images: number;
+    pages: number;
+} | McpErrorShape>;
+export interface SanitizeDocumentOk {
+    ok: true;
+    sessionId: string;
+    revision: number;
+    dirty: boolean;
+    removedRSIDs: number;
+    purgedAuthors: number;
+    strippedExifBytes: number;
+    purgedPII: number;
+    bodyPII: number;
+    piiCoverage: typeof PII_COVERAGE;
+    piiNote: string;
+    acceptedRevisions: number;
+    strippedComments: number;
+    strippedMacros: string[];
+    macroParts: string[];
+    filesTouched: string[];
+    droppedRogue: string[];
+    revisionsPending: number;
+    revisionsRemedy?: string;
+    redoCleared?: boolean;
+    redoClearedWarning?: string;
+}
+/**
+ * sanitize_document: scrub the open session through the engine scrub path
+ * (validateSanitizeOptionsStrict + sanitizeDocxBuffer — the exact validator
+ * and buffer scrub CLI sanitize calls). The sanitized bytes replace the live
+ * package (snapshot restore on the same parser, AST refreshed in place), the
+ * revision bumps, and the redo chain clears (a fresh edit invalidates redo).
+ * Never throws.
+ */
+export declare function handleSanitizeDocument(store: McpSessionStore, input: unknown): Promise<SanitizeDocumentOk | McpErrorShape>;
+/**
+ * normalize_document: canonical repair of the open session through the core
+ * rezip hook (the hook CLI normalize drives). Heals the live DOM, refreshes
+ * the session view, then proves the result with a forked validation verdict.
+ * When the package is still invalid afterwards, the pre-run snapshot is
+ * restored (revision untouched) and the call fails closed with E_VALIDATION —
+ * the in-memory analogue of CLI normalize writing nothing on failure. Output
+ * bytes match CLI normalize on the same input. Never throws.
+ */
+export declare function handleNormalizeDocument(store: McpSessionStore, input: unknown): Promise<{
+    ok: true;
+    sessionId: string;
+    revision: number;
+    dirty: boolean;
+    normalized: string[];
+    preStateCommit?: string;
+    remaining: number;
+    rolledBack: {
+        rule: string;
+        reason: string;
+    }[];
+    validation: AuditValidation & {
+        tolerated?: true;
+        preExistingErrors?: number;
+        introducedErrors?: 0;
+    };
+    revisionsPending: number;
+    revisionsRemedy?: string;
+    redoCleared?: boolean;
+    redoClearedWarning?: string;
+} | McpErrorShape>;
+/**
+ * Jailed Markdown read for import_document. Verdict table mirrors the
+ * batch image-file read precedent: outside the workspace roots -> E_SANDBOX,
+ * missing/unreadable -> E_IO, oversize -> E_LIMIT, unusable -> E_VALIDATION.
+ * Symlinks are refused at open (O_NOFOLLOW) with containment re-checked after
+ * the read, so a swapped link cannot escape the jail mid-call.
+ */
+export declare function readImportMarkdownFile(rawPath: unknown, roots?: string[]): string;
+/**
+ * import_document: jailed file read + the existing compose pipeline, ingested
+ * into the OPEN session only (sessionId strictly required, never
+ * auto-created). Format table mirrors CLI import: .md/.markdown/.txt read as
+ * Markdown; .html/.htm refused with the CLI-identical verdict; .docx refused
+ * naming open_document; anything else refused as an unknown format. After the
+ * gates, the call delegates to handleComposeDocument itself, so the result is
+ * byte-equal to composing the same Markdown inline. Never throws.
+ */
+export declare function handleImportDocument(store: McpSessionStore, input: unknown): Promise<Awaited<ReturnType<typeof handleComposeDocument>>>;

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

@@ -0,0 +1,96 @@
+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;
+    /** Result of the validator gate: clean, or tolerated with the number of errors the file already had. */
+    validation: {
+        ok: true;
+    } | {
+        ok: false;
+        tolerated: true;
+        preExistingErrors: number;
+        introducedErrors: 0;
+        messages: 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;
+    /** Result of the validator gate: clean, or tolerated with the number of errors the file already had. */
+    validation: {
+        ok: true;
+    } | {
+        ok: false;
+        tolerated: true;
+        preExistingErrors: number;
+        introducedErrors: 0;
+        messages: 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;