@plebeiantech/lat.md 0.12.3-fork.1

package/templates/pi-extension.ts

@@ -0,0 +1,364 @@
+import { Type } from "@sinclair/typebox";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { getMarkdownTheme, keyHint } from "@mariozechner/pi-coding-agent";
+import type { Theme } from "@mariozechner/pi-tui";
+import { Box, Markdown, Text } from "@mariozechner/pi-tui";
+
+const PREVIEW_LINES = 4;
+
+function collapsibleResult(
+  result: { content: Array<{ type: string; text?: string }> },
+  options: { expanded: boolean; isPartial: boolean },
+  theme: Theme,
+) {
+  const text = result.content?.[0]?.type === "text" ? (result.content[0] as { type: "text"; text: string }).text : "";
+  if (!text) return new Text(theme.fg("dim", "(empty)"), 0, 0);
+  if (options.isPartial) return new Text(theme.fg("dim", "…"), 0, 0);
+  const mdTheme = getMarkdownTheme();
+  if (options.expanded) return new Markdown(text, 0, 0, mdTheme);
+
+  const lines = text.split("\n");
+  if (lines.length <= PREVIEW_LINES) return new Markdown(text, 0, 0, mdTheme);
+
+  const preview = lines.slice(0, PREVIEW_LINES).join("\n");
+  const remaining = lines.length - PREVIEW_LINES;
+  const hint = keyHint("expandTools", "to expand");
+  return new Text(
+    preview + "\n" +
+    theme.fg("dim", `… ${remaining} more lines (${hint})`),
+    0, 0,
+  );
+}
+
+/** Absolute path to the lat binary, injected by `lat init`. */
+const LAT = "__LAT_BIN__";
+
+function run(args: string[], cwd?: string): string {
+  const { execSync } = require("child_process") as typeof import("child_process");
+  return execSync(`${LAT} ${args.join(" ")}`, {
+    cwd: cwd ?? process.cwd(),
+    encoding: "utf-8",
+    timeout: 30_000,
+  });
+}
+
+function tryRun(args: string[]): string {
+  try {
+    return run(args);
+  } catch {
+    return "";
+  }
+}
+
+export default function (pi: ExtensionAPI) {
+  // ── Tools ──────────────────────────────────────────────────────────
+
+  pi.registerTool({
+    name: "lat_search",
+    label: "lat search",
+    description: "Semantic search across lat.md sections using embeddings",
+    promptSnippet: "Search lat.md documentation by meaning",
+    promptGuidelines: [
+      "Use before starting any task to find relevant design context",
+      "Search results include section IDs you can pass to lat_section",
+    ],
+    parameters: Type.Object({
+      query: Type.String({ description: "Search query in natural language" }),
+      limit: Type.Optional(
+        Type.Number({ description: "Max results (default 5)", default: 5 }),
+      ),
+    }),
+    async execute(_id, params) {
+      const args = ["search", JSON.stringify(params.query)];
+      if (params.limit) args.push("--limit", String(params.limit));
+      const output = tryRun(args);
+      return {
+        content: [{ type: "text", text: output || "No results found." }],
+      };
+    },
+    renderCall(args, theme) {
+      return new Text(
+        theme.fg("toolTitle", theme.bold("lat search ")) +
+        theme.fg("dim", `"${args.query}"`),
+        0, 0,
+      );
+    },
+    renderResult: collapsibleResult,
+  });
+
+  pi.registerTool({
+    name: "lat_section",
+    label: "lat section",
+    description:
+      "Show full content of a lat.md section with outgoing/incoming refs",
+    promptSnippet: "Read a specific lat.md section",
+    parameters: Type.Object({
+      query: Type.String({
+        description:
+          'Section ID or name (e.g. "cli#init", "Tests#User login")',
+      }),
+    }),
+    async execute(_id, params) {
+      const output = tryRun(["section", JSON.stringify(params.query)]);
+      return {
+        content: [
+          { type: "text", text: output || "Section not found." },
+        ],
+      };
+    },
+    renderCall(args, theme) {
+      return new Text(
+        theme.fg("toolTitle", theme.bold("lat section ")) +
+        theme.fg("dim", `"${args.query}"`),
+        0, 0,
+      );
+    },
+    renderResult: collapsibleResult,
+  });
+
+  pi.registerTool({
+    name: "lat_locate",
+    label: "lat locate",
+    description:
+      "Find a section by name (exact, subsection tail, or fuzzy match)",
+    promptSnippet: "Find a lat.md section by name",
+    parameters: Type.Object({
+      query: Type.String({ description: "Section name to locate" }),
+    }),
+    async execute(_id, params) {
+      const output = tryRun(["locate", JSON.stringify(params.query)]);
+      return {
+        content: [
+          { type: "text", text: output || "No sections matching query." },
+        ],
+      };
+    },
+    renderCall(args, theme) {
+      return new Text(
+        theme.fg("toolTitle", theme.bold("lat locate ")) +
+        theme.fg("dim", `"${args.query}"`),
+        0, 0,
+      );
+    },
+  });
+
+  pi.registerTool({
+    name: "lat_check",
+    label: "lat check",
+    description:
+      "Run full lat.md validation. Returns errors or 'All checks passed'",
+    promptSnippet: "Run full lat.md validation",
+    parameters: Type.Object({}),
+    async execute() {
+      try {
+        const output = run(["check"]);
+        return { content: [{ type: "text", text: output }] };
+      } catch (err: unknown) {
+        const e = err as { stdout?: string; stderr?: string };
+        return {
+          content: [{ type: "text", text: e.stdout || e.stderr || "Check failed" }],
+          isError: true,
+        };
+      }
+    },
+    renderCall(_args, theme) {
+      return new Text(
+        theme.fg("toolTitle", theme.bold("lat check")),
+        0, 0,
+      );
+    },
+  });
+
+  pi.registerTool({
+    name: "lat_expand",
+    label: "lat expand",
+    description:
+      "Expand [[refs]] in text to resolved file locations and context",
+    promptSnippet: "Resolve [[wiki links]] in text",
+    parameters: Type.Object({
+      text: Type.String({ description: "Text containing [[refs]] to expand" }),
+    }),
+    async execute(_id, params) {
+      const output = tryRun(["expand", JSON.stringify(params.text)]);
+      return {
+        content: [{ type: "text", text: output || params.text }],
+      };
+    },
+    renderCall(args, theme) {
+      const preview = args.text.length > 60 ? args.text.slice(0, 60) + "…" : args.text;
+      return new Text(
+        theme.fg("toolTitle", theme.bold("lat expand ")) +
+        theme.fg("dim", `"${preview}"`),
+        0, 0,
+      );
+    },
+  });
+
+  pi.registerTool({
+    name: "lat_refs",
+    label: "lat refs",
+    description: "Find what references a given section",
+    promptSnippet: "Find incoming references to a lat.md section",
+    parameters: Type.Object({
+      query: Type.String({
+        description: 'Section ID (e.g. "cli#init", "file#Section")',
+      }),
+    }),
+    async execute(_id, params) {
+      const output = tryRun(["refs", JSON.stringify(params.query)]);
+      return {
+        content: [{ type: "text", text: output || "No references found." }],
+      };
+    },
+    renderCall(args, theme) {
+      return new Text(
+        theme.fg("toolTitle", theme.bold("lat refs ")) +
+        theme.fg("dim", `"${args.query}"`),
+        0, 0,
+      );
+    },
+  });
+
+  // ── Message renderers ────────────────────────────────────────────
+
+  pi.registerMessageRenderer("lat-reminder", (message, { expanded }, theme) => {
+    const box = new Box(1, 1, (t) => theme.bg("customMessageBg", t));
+    if (expanded) {
+      box.addChild(new Text(theme.fg("accent", "lat.md"), 0, 0));
+      box.addChild(new Markdown(message.content, 0, 0, getMarkdownTheme()));
+    } else {
+      const hint = keyHint("expandTools", "to expand");
+      box.addChild(new Text(
+        theme.fg("accent", "lat.md") + " " +
+        theme.fg("dim", `Search lat.md before starting work. Keep lat.md/ focused. (${hint})`),
+        0, 0,
+      ));
+    }
+    return box;
+  });
+
+  pi.registerMessageRenderer("lat-check", (message, { expanded }, theme) => {
+    const box = new Box(1, 1, (t) => theme.bg("customMessageBg", t));
+    if (expanded) {
+      box.addChild(new Text(theme.fg("warning", "lat check"), 0, 0));
+      box.addChild(new Markdown(message.content, 0, 0, getMarkdownTheme()));
+    } else {
+      const hint = keyHint("expandTools", "to expand");
+      const firstLine = message.content.split("\n")[0];
+      box.addChild(new Text(
+        theme.fg("warning", "lat check") + " " +
+        theme.fg("dim", `${firstLine} (${hint})`),
+        0, 0,
+      ));
+    }
+    return box;
+  });
+
+  // ── Lifecycle hooks ────────────────────────────────────────────────
+  //
+  // Convention, not automated here: a code comment that explains WHY (a
+  // reason, trade-off, rejected alternative, or invariant) belongs in a
+  // lat.md/ section, with a `// @lat: [[section-id]]` pointer (comment-prefixed
+  // per language, naming the section in double brackets) left behind in the
+  // code. `lat hook claude PostToolUse` enforces this as a reminder after
+  // every Edit/Write in Claude Code and Codex; Pi has no per-edit hook wired
+  // up yet.
+
+  // Guard to prevent agent_end from firing twice per prompt (infinite loop)
+  let agentEndFired = false;
+
+  pi.on("before_agent_start", async () => {
+    agentEndFired = false;
+
+    const reminder = [
+      "Before starting work, run `lat_search` with one or more queries describing the user's intent.",
+      "ALWAYS do this, even when the task seems straightforward — search results may reveal critical design details, protocols, or constraints.",
+      "Use `lat_section` to read the full content of relevant matches.",
+      "Do not read files, write code, or run commands until you have searched.",
+      "",
+      "Remember: `lat.md/` must stay in sync with meaningful codebase state. If you change behavior, architecture, tests, or planned work, update the relevant current-state sections and run `lat_check` before finishing. Do not use `lat.md/` as a journal/changelog or add notes for insignificant details.",
+    ].join("\n");
+
+    return {
+      message: {
+        customType: "lat-reminder",
+        content: reminder,
+        display: true,
+      },
+    };
+  });
+
+  pi.on("agent_end", async () => {
+    // Don't fire twice per prompt — prevents infinite loop
+    if (agentEndFired) return;
+    agentEndFired = true;
+
+    // Run lat check
+    let checkOutput: string;
+    let checkFailed = false;
+    try {
+      checkOutput = run(["check"]);
+    } catch (err: unknown) {
+      checkFailed = true;
+      checkOutput = (err as { stdout?: string }).stdout || "";
+    }
+
+    // Run git diff --numstat to check if lat.md/ is in sync
+    let needsSync = false;
+    let codeLines = 0;
+    try {
+      const { execSync } = require("child_process") as typeof import("child_process");
+      const numstat = execSync("git diff HEAD --numstat", {
+        encoding: "utf-8",
+        cwd: process.cwd(),
+      });
+
+      let latMdLines = 0;
+      for (const line of numstat.split("\n")) {
+        const parts = line.split("\t");
+        if (parts.length < 3) continue;
+        const added = parseInt(parts[0], 10) || 0;
+        const removed = parseInt(parts[1], 10) || 0;
+        const file = parts[2];
+        const changed = added + removed;
+        if (file.startsWith("lat.md/")) {
+          latMdLines += changed;
+        } else if (/\.(ts|tsx|js|jsx|py|rs|go|c|h)$/.test(file)) {
+          codeLines += changed;
+        }
+      }
+
+      if (codeLines >= 5) {
+        const effectiveLatMd = latMdLines === 0 ? 0 : Math.max(latMdLines, 1);
+        needsSync = effectiveLatMd < codeLines * 0.05;
+      }
+    } catch {
+      // git not available or no HEAD — skip diff check
+    }
+
+    if (!checkFailed && !needsSync) return;
+
+    const parts: string[] = [];
+    if (checkFailed && needsSync) {
+      parts.push(
+        `\`lat check\` found errors AND the codebase has changes (${codeLines} lines) with no updates to \`lat.md/\`. Before finishing:`,
+        "",
+        "1. Update relevant current-state `lat.md/` sections if the changes affect behavior, architecture, tests, or plans; do not add journal/changelog notes.",
+        "2. Run `lat_check` until it passes.",
+      );
+    } else if (checkFailed) {
+      parts.push(
+        "`lat check` failed. Run `lat_check`, fix the errors, and repeat until it passes.",
+      );
+    } else {
+      parts.push(
+        `The codebase has changes (${codeLines} lines) but \`lat.md/\` was not updated. Review whether current-state \`lat.md/\` sections need updates; do not add journal/changelog notes just to satisfy this reminder. Run \`lat_search\` to find relevant sections and \`lat_check\` at the end.`,
+      );
+    }
+
+    pi.sendMessage(
+      { customType: "lat-check", content: parts.join("\n"), display: true },
+      { deliverAs: "followUp", triggerTurn: true },
+    );
+  });
+}

package/templates/skill/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: lat-md
+description: >-
+  Writing and maintaining lat.md documentation files — structured markdown that
+  describes a project's architecture, design decisions, and test specs. Use when
+  creating, editing, or reviewing files in the lat.md/ directory.
+---
+
+# lat.md Authoring Guide
+
+This skill covers the syntax, structure rules, and conventions for writing `lat.md/` files. Load it whenever you need to create or edit sections in the `lat.md/` directory.
+
+## What belongs in lat.md
+
+`lat.md/` files describe **what** the project does and **why** — domain concepts, key design decisions, business logic, and test specifications. They do NOT duplicate source code. Think of each section as an anchor that source code references back to.
+
+Treat `lat.md/` as a focused snapshot of the current state of affairs or planned features. Do not use it as a journal or changelog, and do not grow it just to record insignificant implementation details.
+
+Good candidates for sections:
+- Architecture decisions and their rationale
+- Domain concepts and business rules
+- API contracts and protocols
+- Test specifications (what is tested and why)
+- Non-obvious constraints or invariants
+
+Bad candidates:
+- Step-by-step code walkthroughs (the code itself is the walkthrough)
+- Auto-generated API docs (use tools for that)
+- Journal/changelog entries for each change
+- Temporary notes or TODOs
+- Insignificant implementation details that do not change the current-state model
+
+## Section structure
+
+Every section **must** have a leading paragraph — at least one sentence immediately after the heading, before any child headings or other block content.
+
+The first paragraph must be ≤250 characters (excluding `[[wiki link]]` content). This paragraph is the section's identity — it appears in search results, command output, and RAG context.
+
+```markdown
+# Good Section
+
+Brief overview of what this section documents and why it matters.
+
+More detail can go in subsequent paragraphs, code blocks, or lists.
+
+## Child heading
+
+Details about this child topic.
+```
+
+```markdown
+# Bad Section
+
+## Child heading
+
+This is invalid — "Bad Section" has no leading paragraph.
+```
+
+`lat check` enforces this rule.
+
+## Section IDs
+
+Sections are addressed by file path and heading chain:
+
+- **Full form**: `lat.md/path/to/file#Heading#SubHeading`
+- **Short form**: `file#Heading#SubHeading` (when the file stem is unique)
+
+Examples: `lat.md/tests/search#RAG Replay Tests`, `cli#init`, `parser#Wiki Links`.
+
+## Wiki links
+
+Cross-reference other sections or source code with `[[target]]` or `[[target|alias]]`.
+
+### Section links
+
+```markdown
+See [[cli#init]] for setup details.
+The parser validates [[parser#Wiki Links|wiki link syntax]].
+```
+
+### Source code links
+
+Reference functions, classes, constants, and methods in source files:
+
+```markdown
+[[src/config.ts#getConfigDir]]          — function
+[[src/server.ts#App#listen]]            — class method
+[[lib/utils.py#parse_args]]             — Python function
+[[src/lib.rs#Greeter#greet]]            — Rust impl method
+[[src/app.go#Greeter#Greet]]            — Go method
+[[src/app.h#Greeter]]                   — C struct
+```
+
+`lat check` validates that all targets exist.
+
+## Code refs
+
+Tie source code back to `lat.md/` sections with `@lat:` comments:
+
+```typescript
+// @lat: [[cli#init]]
+export function init() { ... }
+```
+
+```python
+# @lat: [[cli#init]]
+def init():
+    ...
+```
+
+Supported comment styles: `//` (JS/TS/Rust/Go/C) and `#` (Python).
+
+Place one `@lat:` comment per section, at the relevant code — not at the top of the file.
+
+## Test specs
+
+Describe tests as sections in `lat.md/` files. Add frontmatter to require that every leaf section has a matching `@lat:` comment in test code:
+
+```markdown
+---
+lat:
+  require-code-mention: true
+---
+# Tests
+
+Authentication test specifications.
+
+## User login
+
+Verify credential validation and error handling.
+
+### Rejects expired tokens
+
+Tokens past their expiry timestamp are rejected with 401, even if otherwise valid.
+
+### Handles missing password
+
+Login request without a password field returns 400 with a descriptive error.
+```
+
+Each test references its spec:
+
+```python
+# @lat: [[tests#User login#Rejects expired tokens]]
+def test_rejects_expired_tokens():
+    ...
+```
+
+Rules:
+- Every leaf section under `require-code-mention: true` must be referenced by exactly one `@lat:` comment
+- Every section MUST have a description — at least one sentence explaining what the test verifies and why
+- `lat check` flags unreferenced specs and dangling code refs
+
+## Frontmatter
+
+Optional YAML frontmatter at the top of `lat.md/` files:
+
+```yaml
+---
+lat:
+  require-code-mention: true
+---
+```
+
+Supported fields: `require-code-mention` for test spec enforcement, and `mode` for Diátaxis mode declaration.
+
+## Diátaxis modes
+
+Documents in `tutorials/`, `how-to/`, `reference/`, or `explanation/` under `lat.md/` are checked against their Diátaxis mode. Declare it with nested frontmatter:
+
+```yaml
+---
+lat:
+  mode: reference
+---
+```
+
+If the document is in one of the four mode directories, the declared mode must match that directory. Each mode enforces one shape rule: tutorials need an ordered list of steps and a stated outcome; how-to guides need an ordered list of steps; reference docs must not contain narrative prose (no second paragraph under a heading); explanations must not give imperative commands. `lat check mode` validates this.
+
+## Validation
+
+Always run `lat check` after editing `lat.md/` files. It validates:
+- All wiki links point to existing sections or source code symbols
+- All relative markdown links point to existing files
+- Full and collapsed reference-style links have definitions
+- All `@lat:` code refs point to existing sections
+- Every section has a leading paragraph (≤250 chars)
+- All `require-code-mention` leaf sections are referenced in code
+- Every `lat.md/` directory has an accurate index