@zosmaai/pi-llm-wiki 0.1.2 → 0.2.0

package/.coderabbit.yaml

@@ -0,0 +1,43 @@
+# CodeRabbit AI Code Review Configuration
+# Docs: https://docs.coderabbit.ai/guides/configure-coderabbit
+
+language: en-US
+early_access: false
+reviews:
+  profile: assertive
+  request_changes_workflow: true
+  high_level_summary: true
+  poem: false
+  review_status: true
+  collapse_walkthrough: false
+  auto_review:
+    enabled: true
+    ignore_title_keywords:
+      - "chore"
+      - "WIP"
+      - "wip"
+    drafts: false
+    base_branches:
+      - main
+  path_instructions:
+    - path: "extensions/**/*.ts"
+      instructions: |
+        Review TypeScript extension files for pi coding agent. Check that:
+        1. Tools use pi.registerTool() with TypeBox schemas
+        2. Error handling uses try/catch with proper messages
+        3. Unused parameters use underscore prefix or are removed
+        4. File exports a default function receiving ExtensionAPI
+    - path: "skills/**/SKILL.md"
+      instructions: |
+        Review SKILL.md for pi. Verify:
+        1. Frontmatter follows Agent Skills spec (name, description)
+        2. Workflows are clearly documented with steps
+        3. Golden rules and conventions are explicit
+    - path: "prompts/**/*.md"
+      instructions: |
+        Review prompt templates. Verify:
+        1. Frontmatter has description, args, section, topLevelCli
+        2. Instructions are actionable and clear
+
+chat:
+  auto_reply: true

package/.github/workflows/ci.yml

@@ -2,9 +2,9 @@ name: CI
 
 on:
   push:
-    branches: [main, master]
+    branches: [main]
   pull_request:
-    branches: [main, master]
+    branches: [main]
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
@@ -33,12 +33,13 @@ jobs:
       - name: Lint
         run: npm run lint
 
-      - name: Run Tests
-        run: npm test
+      - name: Run Tests with Coverage
+        run: npm run test:coverage
 
-      - name: Upload Coverage
+      - name: Upload Coverage to Codecov
         if: ${{ matrix.node-version == 22 && github.event_name == 'push' }}
-        uses: actions/upload-artifact@v4
+        uses: codecov/codecov-action@v5
         with:
-          name: coverage
-          path: coverage/
+          files: ./coverage/lcov.info
+          fail_ci_if_error: false
+          verbose: true

package/.github/workflows/codeql.yml

@@ -0,0 +1,39 @@
+name: "CodeQL"
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: "0 6 * * 1" # Every Monday at 6 AM
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      packages: read
+      actions: read
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - language: javascript-typescript
+            build-mode: none
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: github/codeql-action/init@v3
+        with:
+          languages: ${{ matrix.language }}
+          build-mode: ${{ matrix.build-mode }}
+          queries: security-and-quality
+
+      - uses: github/codeql-action/analyze@v3
+        with:
+          category: "/language:${{ matrix.language }}"

package/.github/workflows/release.yml

@@ -39,7 +39,9 @@ jobs:
         run: echo "VERSION=${GITHUB_REF_NAME#v}" >> $GITHUB_OUTPUT
 
       - name: Update package.json version
-        run: npm version ${{ steps.version.outputs.VERSION }} --no-git-tag-version --allow-same-version
+        run: |
+          node -e "const p=require('./package.json'); p.version='${{ steps.version.outputs.VERSION }}'; require('fs').writeFileSync('./package.json', JSON.stringify(p, null, 2)+'\n')"
+          npx biome check --fix package.json 2>&1
 
       - name: Generate Release Notes
         id: notes
@@ -57,7 +59,7 @@ jobs:
       - name: Create GitHub Release
         uses: softprops/action-gh-release@v2
         with:
-          name: "@zosmaai/pi-llm-wiki v${{ steps.version.outputs.VERSION }}"
+          name: "v${{ steps.version.outputs.VERSION }}"
           body: |
             ## 📦 @zosmaai/pi-llm-wiki v${{ steps.version.outputs.VERSION }}
 
@@ -70,7 +72,7 @@ jobs:
 
             ### What's Included
             - **Skill**: Self-maintaining wiki schema (SKILL.md)
-            - **Extension**: 5 TypeScript tools (wiki_ingest, wiki_status_report, wiki_lint_report, wiki_discover_sources, wiki_watch)
+            - **Extension**: 10 TypeScript tools (wiki_bootstrap, wiki_capture_source, wiki_ingest, wiki_ensure_page, wiki_search, wiki_lint, wiki_status, wiki_rebuild_meta, wiki_log_event, wiki_watch)
             - **Prompt Templates**: 8 slash commands (/wiki:init, :ingest, :query, :lint, :discover, :run, :status, :digest)
-            - **Templates**: INDEX.md, LOG.md, DASHBOARD.md, config.yaml, 4 page templates
+            - **Templates**: INDEX.md, LOG.md, DASHBOARD.md, config.yaml, 5 page templates
           generate_release_notes: false

package/AGENTS.md

@@ -0,0 +1,57 @@
+# AGENTS.md
+
+Instructions for AI agents working on this codebase.
+
+## Project
+
+`@zosmaai/pi-llm-wiki` — A pi package that implements Andrej Karpathy's LLM Wiki pattern as a self-maintaining knowledge base.
+
+## Tech Stack
+
+- TypeScript (ES2022, ESM)
+- Vitest for testing
+- Biome for linting/formatting
+- GitHub Actions for CI
+- npm for publishing
+
+## File Layout
+
+```
+├── extensions/llm-wiki/     # TypeScript extension (10 tools + guardrails)
+│   ├── index.ts             # Entry point
+│   └── lib/                 # tools.ts, metadata.ts, guardrails.ts, utils.ts, source-packet.ts
+├── skills/llm-wiki/         # SKILL.md + templates
+├── prompts/                 # 8 slash command templates
+├── test/                    # Vitest tests
+├── docs/                    # Documentation
+└── scripts/                 # release.js
+```
+
+## Conventions
+
+- Use `node:fs/promises` for async file I/O, not sync
+- Prefer small, pure functions in `lib/`
+- Extension tools must have: name, label, description, promptSnippet, promptGuidelines, parameters (TypeBox), execute
+- Guardrails block `raw/**` and `meta/**` edits at the tool_call hook level
+- Metadata auto-rebuilds on `turn_end` after `wiki/**` edits
+- Source IDs: `SRC-YYYY-MM-DD-NNN`
+- Page filenames: `kebab-case.md`
+- Wikilinks: folder-qualified, e.g. `[[concepts/retrieval-augmented-generation]]`
+
+## Testing
+
+```bash
+npm test              # run tests
+npm run test:coverage # run with coverage
+npm run typecheck     # TypeScript check
+npm run lint          # biome check
+```
+
+## Release
+
+```bash
+npm run release:patch  # or minor/major
+npm run release:push   # push tags
+```
+
+Never edit `package.json` version manually — use the release script.

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.2.0] - 2026-04-28
+
+### Added
+
+- **4-layer architecture**: raw/, wiki/, meta/, .wiki/ with explicit ownership rules
+- **Source packets**: Structured capture with manifest.json, original/, extracted.md, attachments/
+- **10 custom tools** (up from 5): wiki_bootstrap, wiki_capture_source, wiki_ingest, wiki_ensure_page, wiki_search, wiki_lint, wiki_status, wiki_rebuild_meta, wiki_log_event, wiki_watch
+- **Auto-generated metadata**: registry.json, backlinks.json, index.md, log.md, events.jsonl
+- **Guardrails**: Extension blocks direct edits to raw/** and meta/** via tool_call hook
+- **Auto-rebuild**: Metadata rebuilds automatically after wiki/\*\* edits via turn_end hook
+- **Batch ingest**: wiki_ingest returns source batches with extracted content previews
+- **Improved lint**: Orphans, missing pages, contradictions, knowledge gaps with auto_fix option
+- **Release scripts**: Automated semver bumping, changelog updates, git tagging
+- **Coverage reporting**: v8 coverage in CI with lcov output
+
+### Changed
+
+- Extension moved from single file to modular directory structure (extensions/llm-wiki/)
+- Skill reduced from ~500 lines to ~150 lines — principles over mechanics
+- Metadata is now machine-owned; LLM never edits INDEX.md or LOG.md manually
+- Source IDs use stable format SRC-YYYY-MM-DD-NNN for rename-safe citations
+
+### Removed
+
+- Manual INDEX.md/LOG.md maintenance from skill workflows
+- Legacy flat raw/articles/ structure (replaced by structured source packets)

package/CONTRIBUTING.md

@@ -0,0 +1,43 @@
+# Contributing
+
+## Local Setup
+
+```bash
+git clone https://github.com/zosmaai/pi-llm-wiki.git
+cd pi-llm-wiki
+npm install
+pi install ./
+```
+
+## Development
+
+```bash
+npm run test           # run tests
+npm run test:coverage  # run tests with coverage report
+npm run typecheck      # TypeScript type check
+npm run lint           # biome lint check
+npm run lint:fix       # auto-fix lint issues
+```
+
+## Release Process
+
+```bash
+npm run release:patch  # bump patch version
+npm run release:minor  # bump minor version
+npm run release:major  # bump major version
+npm run release:push   # push to origin with tags
+```
+
+The release script:
+
+1. Verifies clean git tree and `main` branch
+2. Runs typecheck, lint, and tests
+3. Bumps version in `package.json`
+4. Updates `CHANGELOG.md`
+5. Commits and tags
+
+CI handles npm publish on tag push.
+
+## License
+
+MIT

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zosmaai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.