invar-tools 1.15.0__py3-none-any.whl → 1.15.2__py3-none-any.whl

invar/shell/pi_tools.py

@@ -35,6 +35,12 @@ def install_pi_tools(
     - invar_guard: Wrapper for invar guard command
     - invar_sig: Wrapper for invar sig command
     - invar_map: Wrapper for invar map command
+    - invar_doc_toc: Extract document structure
+    - invar_doc_read: Read specific section
+    - invar_doc_find: Find sections by pattern
+    - invar_doc_replace: Replace section content
+    - invar_doc_insert: Insert content relative to section
+    - invar_doc_delete: Delete section
     """
     tools_dir = project_path / PI_TOOLS_DIR
     tools_dir.mkdir(parents=True, exist_ok=True)
@@ -44,6 +50,7 @@ def install_pi_tools(
     console.print("    ✓ invar_guard - Smart verification (static + doctests + symbolic)")
     console.print("    ✓ invar_sig - Show function signatures and contracts")
     console.print("    ✓ invar_map - Symbol map with reference counts")
+    console.print("    ✓ 6 doc tools - Structured markdown editing (toc, read, find, replace, insert, delete)")
     console.print("")
 
     template_path = get_pi_tools_template_path()

invar/templates/pi-tools/invar/index.ts

@@ -7,16 +7,24 @@
 
 import { Type } from "@sinclair/typebox";
 import type { CustomToolFactory } from "@mariozechner/pi-coding-agent";
+import * as fs from "fs";
+import * as path from "path";
 
 const factory: CustomToolFactory = (pi) => {
-  // Helper to check if invar is available
-  async function checkInvarInstalled(): Promise<boolean> {
+  // Helper to resolve invar command (with uvx fallback)
+  async function resolveInvarCommand(): Promise<{ command: string; args: string[] }> {
+    // Try direct invar command first
     try {
       const result = await pi.exec("which", ["invar"]);
-      return result.exitCode === 0;
+      if (result.exitCode === 0) {
+        return { command: "invar", args: [] };
+      }
     } catch {
-      return false;
+      // Fall through to uvx
     }
+
+    // Fallback to uvx invar-tools
+    return { command: "uvx", args: ["invar-tools"] };
   }
 
   // Helper to validate path/target parameters (defense-in-depth)
@@ -58,12 +66,8 @@ const factory: CustomToolFactory = (pi) => {
         })),
       }),
       async execute(toolCallId, params, onUpdate, ctx, signal) {
-        const installed = await checkInvarInstalled();
-        if (!installed) {
-          throw new Error("Invar not installed. Run: pip install invar-tools");
-        }
-
-        const args = ["guard"];
+        const cmd = await resolveInvarCommand();
+        const args = [...cmd.args, "guard"];
 
         // Default is --changed (check modified files)
         if (params.changed === false) {
@@ -80,7 +84,7 @@ const factory: CustomToolFactory = (pi) => {
           args.push("--strict");
         }
 
-        const result = await pi.exec("invar", args, { cwd: pi.cwd, signal });
+        const result = await pi.exec(cmd.command, args, { cwd: pi.cwd, signal });
 
         if (result.killed) {
           throw new Error("Guard verification was cancelled");
@@ -111,16 +115,13 @@ const factory: CustomToolFactory = (pi) => {
         }),
       }),
       async execute(toolCallId, params, onUpdate, ctx, signal) {
-        const installed = await checkInvarInstalled();
-        if (!installed) {
-          throw new Error("Invar not installed. Run: pip install invar-tools");
-        }
+        const cmd = await resolveInvarCommand();
 
         if (!isValidPath(params.target)) {
           throw new Error("Invalid target path: contains unsafe characters or path traversal");
         }
 
-        const result = await pi.exec("invar", ["sig", params.target], {
+        const result = await pi.exec(cmd.command, [...cmd.args, "sig", params.target], {
           cwd: pi.cwd,
           signal,
         });
@@ -160,16 +161,13 @@ const factory: CustomToolFactory = (pi) => {
         })),
       }),
       async execute(toolCallId, params, onUpdate, ctx, signal) {
-        const installed = await checkInvarInstalled();
-        if (!installed) {
-          throw new Error("Invar not installed. Run: pip install invar-tools");
-        }
+        const cmd = await resolveInvarCommand();
 
         if (params.path && params.path !== "." && !isValidPath(params.path)) {
           throw new Error("Invalid path: contains unsafe characters or path traversal");
         }
 
-        const args = ["map"];
+        const args = [...cmd.args, "map"];
 
         if (params.path && params.path !== ".") {
           args.push(params.path);
@@ -179,7 +177,7 @@ const factory: CustomToolFactory = (pi) => {
           args.push("--top", params.top.toString());
         }
 
-        const result = await pi.exec("invar", args, {
+        const result = await pi.exec(cmd.command, args, {
           cwd: pi.cwd,
           signal,
         });
@@ -201,6 +199,395 @@ const factory: CustomToolFactory = (pi) => {
         };
       },
     },
+
+    // =========================================================================
+    // invar_doc_toc - Extract document structure (Table of Contents)
+    // =========================================================================
+    {
+      name: "invar_doc_toc",
+      label: "Invar Doc TOC",
+      description: "Extract document structure (Table of Contents) from markdown files. Shows headings hierarchy with line numbers and character counts. Use this INSTEAD of Read() to understand markdown structure.",
+      parameters: Type.Object({
+        file: Type.String({
+          description: "Path to markdown file",
+        }),
+        depth: Type.Optional(Type.Number({
+          description: "Maximum heading depth to include (1-6)",
+          default: 6,
+          minimum: 1,
+          maximum: 6,
+        })),
+      }),
+      async execute(toolCallId, params, onUpdate, ctx, signal) {
+        const cmd = await resolveInvarCommand();
+
+        if (!isValidPath(params.file)) {
+          throw new Error("Invalid file path: contains unsafe characters or path traversal");
+        }
+
+        const args = [...cmd.args, "doc", "toc", params.file];
+
+        if (params.depth && params.depth !== 6) {
+          args.push("--depth", params.depth.toString());
+        }
+
+        const result = await pi.exec(cmd.command, args, {
+          cwd: pi.cwd,
+          signal,
+        });
+
+        if (result.killed) {
+          throw new Error("Doc toc command was cancelled");
+        }
+
+        if (result.exitCode !== 0) {
+          throw new Error(`Failed to extract TOC: ${result.stderr}`);
+        }
+
+        return {
+          content: [{ type: "text", text: result.stdout }],
+          details: {
+            file: params.file,
+            depth: params.depth || 6,
+          },
+        };
+      },
+    },
+
+    // =========================================================================
+    // invar_doc_read - Read a specific section from a document
+    // =========================================================================
+    {
+      name: "invar_doc_read",
+      label: "Invar Doc Read",
+      description: "Read a specific section from a markdown document. Supports multiple addressing formats: slug path, fuzzy match, index (#0/#1), or line anchor (@48). Use this INSTEAD of Read() with manual line counting.",
+      parameters: Type.Object({
+        file: Type.String({
+          description: "Path to markdown file",
+        }),
+        section: Type.String({
+          description: "Section path: slug ('requirements/auth'), fuzzy ('auth'), index ('#0/#1'), or line ('@48')",
+        }),
+        children: Type.Optional(Type.Boolean({
+          description: "Include child sections in output",
+          default: true,
+        })),
+      }),
+      async execute(toolCallId, params, onUpdate, ctx, signal) {
+        const cmd = await resolveInvarCommand();
+
+        if (!isValidPath(params.file) || !isValidPath(params.section)) {
+          throw new Error("Invalid file or section path: contains unsafe characters or path traversal");
+        }
+
+        const args = [...cmd.args, "doc", "read", params.file, params.section, "--json"];
+
+        if (params.children === false) {
+          args.push("--no-children");
+        }
+
+        const result = await pi.exec(cmd.command, args, {
+          cwd: pi.cwd,
+          signal,
+        });
+
+        if (result.killed) {
+          throw new Error("Doc read command was cancelled");
+        }
+
+        if (result.exitCode !== 0) {
+          throw new Error(`Failed to read section: ${result.stderr}`);
+        }
+
+        return {
+          content: [{ type: "text", text: result.stdout }],
+          details: {
+            file: params.file,
+            section: params.section,
+          },
+        };
+      },
+    },
+
+    // =========================================================================
+    // invar_doc_find - Find sections matching a pattern
+    // =========================================================================
+    {
+      name: "invar_doc_find",
+      label: "Invar Doc Find",
+      description: "Find sections in markdown documents matching a pattern. Supports glob patterns for titles and optional content search. Use this INSTEAD of Grep in markdown files.",
+      parameters: Type.Object({
+        file: Type.String({
+          description: "Path to markdown file",
+        }),
+        pattern: Type.String({
+          description: "Title pattern (glob-style, e.g., '*auth*')",
+        }),
+        content: Type.Optional(Type.String({
+          description: "Optional content search pattern",
+        })),
+        level: Type.Optional(Type.Number({
+          description: "Filter by heading level (1-6)",
+          minimum: 1,
+          maximum: 6,
+        })),
+      }),
+      async execute(toolCallId, params, onUpdate, ctx, signal) {
+        const cmd = await resolveInvarCommand();
+
+        if (!isValidPath(params.file)) {
+          throw new Error("Invalid file path: contains unsafe characters or path traversal");
+        }
+
+        const args = [...cmd.args, "doc", "find", params.pattern, params.file, "--json"];
+
+        if (params.content) {
+          args.push("--content", params.content);
+        }
+
+        if (params.level) {
+          args.push("--level", params.level.toString());
+        }
+
+        const result = await pi.exec(cmd.command, args, {
+          cwd: pi.cwd,
+          signal,
+        });
+
+        if (result.killed) {
+          throw new Error("Doc find command was cancelled");
+        }
+
+        if (result.exitCode !== 0) {
+          throw new Error(`Failed to find sections: ${result.stderr}`);
+        }
+
+        return {
+          content: [{ type: "text", text: result.stdout }],
+          details: {
+            file: params.file,
+            pattern: params.pattern,
+          },
+        };
+      },
+    },
+
+    // =========================================================================
+    // invar_doc_replace - Replace a section's content
+    // =========================================================================
+    {
+      name: "invar_doc_replace",
+      label: "Invar Doc Replace",
+      description: "Replace a section's content in a markdown document. Use this INSTEAD of Edit()/Write() for section replacement.",
+      parameters: Type.Object({
+        file: Type.String({
+          description: "Path to markdown file",
+        }),
+        section: Type.String({
+          description: "Section path to replace (slug, fuzzy, index, or line anchor)",
+        }),
+        content: Type.String({
+          description: "New content to replace the section with",
+        }),
+        keep_heading: Type.Optional(Type.Boolean({
+          description: "If true, preserve the original heading line",
+          default: true,
+        })),
+      }),
+      async execute(toolCallId, params, onUpdate, ctx, signal) {
+        const cmd = await resolveInvarCommand();
+
+        if (!isValidPath(params.file) || !isValidPath(params.section)) {
+          throw new Error("Invalid file or section path: contains unsafe characters or path traversal");
+        }
+
+        // Write content to temporary file to avoid shell injection
+        const tmpFile = path.join(pi.cwd, `.invar-tmp-${Date.now()}.txt`);
+
+        try {
+          fs.writeFileSync(tmpFile, params.content, "utf-8");
+
+          const args = [
+            ...cmd.args,
+            "doc",
+            "replace",
+            params.file,
+            params.section,
+            "--content",
+            tmpFile,
+          ];
+
+          if (params.keep_heading === false) {
+            args.push("--no-keep-heading");
+          }
+
+          const result = await pi.exec(cmd.command, args, {
+            cwd: pi.cwd,
+            signal,
+          });
+
+          if (result.killed) {
+            throw new Error("Doc replace command was cancelled");
+          }
+
+          if (result.exitCode !== 0) {
+            throw new Error(`Failed to replace section: ${result.stderr}`);
+          }
+
+          return {
+            content: [{ type: "text", text: result.stdout || "Section replaced successfully" }],
+            details: {
+              file: params.file,
+              section: params.section,
+            },
+          };
+        } finally {
+          // Clean up temp file
+          try {
+            fs.unlinkSync(tmpFile);
+          } catch {
+            // Ignore cleanup errors
+          }
+        }
+      },
+    },
+
+    // =========================================================================
+    // invar_doc_insert - Insert new content relative to a section
+    // =========================================================================
+    {
+      name: "invar_doc_insert",
+      label: "Invar Doc Insert",
+      description: "Insert new content relative to a section in a markdown document. Use this INSTEAD of Edit()/Write() for section insertion.",
+      parameters: Type.Object({
+        file: Type.String({
+          description: "Path to markdown file",
+        }),
+        anchor: Type.String({
+          description: "Section path for the anchor (slug, fuzzy, index, or line anchor)",
+        }),
+        content: Type.String({
+          description: "Content to insert (include heading if new section)",
+        }),
+        position: Type.Optional(Type.String({
+          description: "Where to insert: 'before', 'after', 'first_child', 'last_child'",
+          default: "after",
+          enum: ["before", "after", "first_child", "last_child"],
+        })),
+      }),
+      async execute(toolCallId, params, onUpdate, ctx, signal) {
+        const cmd = await resolveInvarCommand();
+
+        if (!isValidPath(params.file) || !isValidPath(params.anchor)) {
+          throw new Error("Invalid file or anchor path: contains unsafe characters or path traversal");
+        }
+
+        // Write content to temporary file
+        const tmpFile = path.join(pi.cwd, `.invar-tmp-${Date.now()}.txt`);
+
+        try {
+          fs.writeFileSync(tmpFile, params.content, "utf-8");
+
+          const args = [
+            ...cmd.args,
+            "doc",
+            "insert",
+            params.file,
+            params.anchor,
+            "--content",
+            tmpFile,
+          ];
+
+          if (params.position && params.position !== "after") {
+            args.push("--position", params.position);
+          }
+
+          const result = await pi.exec(cmd.command, args, {
+            cwd: pi.cwd,
+            signal,
+          });
+
+          if (result.killed) {
+            throw new Error("Doc insert command was cancelled");
+          }
+
+          if (result.exitCode !== 0) {
+            throw new Error(`Failed to insert content: ${result.stderr}`);
+          }
+
+          return {
+            content: [{ type: "text", text: result.stdout || "Content inserted successfully" }],
+            details: {
+              file: params.file,
+              anchor: params.anchor,
+              position: params.position || "after",
+            },
+          };
+        } finally {
+          // Clean up temp file
+          try {
+            fs.unlinkSync(tmpFile);
+          } catch {
+            // Ignore cleanup errors
+          }
+        }
+      },
+    },
+
+    // =========================================================================
+    // invar_doc_delete - Delete a section from a document
+    // =========================================================================
+    {
+      name: "invar_doc_delete",
+      label: "Invar Doc Delete",
+      description: "Delete a section from a markdown document. Use this INSTEAD of Edit()/Write() for section deletion.",
+      parameters: Type.Object({
+        file: Type.String({
+          description: "Path to markdown file",
+        }),
+        section: Type.String({
+          description: "Section path to delete (slug, fuzzy, index, or line anchor)",
+        }),
+        children: Type.Optional(Type.Boolean({
+          description: "Include child sections in deletion",
+          default: true,
+        })),
+      }),
+      async execute(toolCallId, params, onUpdate, ctx, signal) {
+        const cmd = await resolveInvarCommand();
+
+        if (!isValidPath(params.file) || !isValidPath(params.section)) {
+          throw new Error("Invalid file or section path: contains unsafe characters or path traversal");
+        }
+
+        const args = [...cmd.args, "doc", "delete", params.file, params.section];
+
+        if (params.children === false) {
+          args.push("--no-children");
+        }
+
+        const result = await pi.exec(cmd.command, args, {
+          cwd: pi.cwd,
+          signal,
+        });
+
+        if (result.killed) {
+          throw new Error("Doc delete command was cancelled");
+        }
+
+        if (result.exitCode !== 0) {
+          throw new Error(`Failed to delete section: ${result.stderr}`);
+        }
+
+        return {
+          content: [{ type: "text", text: result.stdout || "Section deleted successfully" }],
+          details: {
+            file: params.file,
+            section: params.section,
+          },
+        };
+      },
+    },
   ];
 };
 

{invar_tools-1.15.0.dist-info → invar_tools-1.15.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: invar-tools
-Version: 1.15.0
+Version: 1.15.2
 Summary: AI-native software engineering tools with design-by-contract verification
 Project-URL: Homepage, https://github.com/tefx/invar
 Project-URL: Documentation, https://github.com/tefx/invar#readme

{invar_tools-1.15.0.dist-info → invar_tools-1.15.2.dist-info}/RECORD

@@ -72,7 +72,7 @@ invar/shell/mcp_config.py,sha256=-hC7Y5BGuVs285b6gBARk7ZyzVxHwPgXSyt_GoN0jfs,458
 invar/shell/mutation.py,sha256=Lfyk2b8j8-hxAq-iwAgQeOhr7Ci6c5tRF1TXe3CxQCs,8914
 invar/shell/pattern_integration.py,sha256=pRcjfq3NvMW_tvQCnaXZnD1k5AVEWK8CYOE2jN6VTro,7842
 invar/shell/pi_hooks.py,sha256=ulZc1sP8mTRJTBsjwFHQzUgg-h8ajRIMp7iF1Y4UUtw,6885
-invar/shell/pi_tools.py,sha256=_xTxE3zeEWSUm3IuuMziglkB_nL8NIco7kQ2nZkCMLU,3668
+invar/shell/pi_tools.py,sha256=a3ACDDXykFV8fUB5UpBmgMvppwkmLvT1k_BWm0IY47k,4068
 invar/shell/property_tests.py,sha256=N9JreyH5PqR89oF5yLcX7ZAV-Koyg5BKo-J05-GUPsA,9109
 invar/shell/py_refs.py,sha256=Vjz50lmt9prDBcBv4nkkODdiJ7_DKu5zO4UPZBjAfmM,4638
 invar/shell/skill_manager.py,sha256=Mr7Mh9rxPSKSAOTJCAM5ZHiG5nfUf6KQVCuD4LBNHSI,12440
@@ -143,7 +143,7 @@ invar/templates/onboard/assessment.md.jinja,sha256=EzqF0VUcxJZG2bVJLxTOyQlAERRbh
 invar/templates/onboard/roadmap.md.jinja,sha256=gmvZk4Hdwe0l3qSFV15QGcsr-OPMhsc6-1K9F2SFSIQ,3939
 invar/templates/onboard/patterns/python.md,sha256=3wwucAcQz0DlggtpqYo-ZCnmrXgBQ0aBgUHN_EZ1VW0,8681
 invar/templates/onboard/patterns/typescript.md,sha256=yOVfHtdAdjKkWNh66_dR7z2xEA4sggbIcCKthW-fqac,11983
-invar/templates/pi-tools/invar/index.ts,sha256=fhE3aGKk5VYcUdbeVMv-x3tqWHA0eVU641pytY06Bvg,6694
+invar/templates/pi-tools/invar/index.ts,sha256=tl2SZsbfYcTq7Zpk5T9gFxRtCE_PaFYVWi_GNHiaKzY,19722
 invar/templates/protocol/INVAR.md.jinja,sha256=t2ZIQZJvzDTJMrRw_ijUo6ScZmeNK0-nV-H7ztTIyQQ,1464
 invar/templates/protocol/python/architecture-examples.md,sha256=O96LH9WFpk7G9MrhSbifLS5pyibTIDG-_EGFF7g3V4M,1175
 invar/templates/protocol/python/contracts-syntax.md,sha256=Q6supTQ3tChVrlN7xhcdb3Q8VGIESxQLA-mQvrNIZmo,1162
@@ -181,10 +181,10 @@ invar/templates/skills/invar-reflect/template.md,sha256=Rr5hvbllvmd8jSLf_0ZjyKt6
 invar/templates/skills/investigate/SKILL.md.jinja,sha256=cp6TBEixBYh1rLeeHOR1yqEnFqv1NZYePORMnavLkQI,3231
 invar/templates/skills/propose/SKILL.md.jinja,sha256=6BuKiCqO1AEu3VtzMHy1QWGqr_xqG9eJlhbsKT4jev4,3463
 invar/templates/skills/review/SKILL.md.jinja,sha256=ET5mbdSe_eKgJbi2LbgFC-z1aviKcHOBw7J5Q28fr4U,14105
-invar_tools-1.15.0.dist-info/METADATA,sha256=Xm0Suh3a3jfCfDBqzsuYpuVRwT4dWxRF5-PnZDMgYas,28595
-invar_tools-1.15.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-invar_tools-1.15.0.dist-info/entry_points.txt,sha256=RwH_EhqgtFPsnO6RcrwrAb70Zyfb8Mh6uUtztWnUxGk,102
-invar_tools-1.15.0.dist-info/licenses/LICENSE,sha256=qeFksp4H4kfTgQxPCIu3OdagXyiZcgBlVfsQ6M5oFyk,10767
-invar_tools-1.15.0.dist-info/licenses/LICENSE-GPL,sha256=IvZfC6ZbP7CLjytoHVzvpDZpD-Z3R_qa1GdMdWlWQ6Q,35157
-invar_tools-1.15.0.dist-info/licenses/NOTICE,sha256=joEyMyFhFY8Vd8tTJ-a3SirI0m2Sd0WjzqYt3sdcglc,2561
-invar_tools-1.15.0.dist-info/RECORD,,
+invar_tools-1.15.2.dist-info/METADATA,sha256=hv_0ypXK9ZqotnGr7Ndo191bIKmZw-bA4sGeXpTgmwI,28595
+invar_tools-1.15.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+invar_tools-1.15.2.dist-info/entry_points.txt,sha256=RwH_EhqgtFPsnO6RcrwrAb70Zyfb8Mh6uUtztWnUxGk,102
+invar_tools-1.15.2.dist-info/licenses/LICENSE,sha256=qeFksp4H4kfTgQxPCIu3OdagXyiZcgBlVfsQ6M5oFyk,10767
+invar_tools-1.15.2.dist-info/licenses/LICENSE-GPL,sha256=IvZfC6ZbP7CLjytoHVzvpDZpD-Z3R_qa1GdMdWlWQ6Q,35157
+invar_tools-1.15.2.dist-info/licenses/NOTICE,sha256=joEyMyFhFY8Vd8tTJ-a3SirI0m2Sd0WjzqYt3sdcglc,2561
+invar_tools-1.15.2.dist-info/RECORD,,