repowiki-cli 0.5.0__py3-none-any.whl

repowiki/templates/en/knowledge_module_task.md

@@ -0,0 +1,33 @@
+---
+id: {{TASK_ID}}
+kind: knowledge_module
+phase: 2
+title: 知识模块：{{TITLE}}
+output: {{OUTPUT_DIR}}
+---
+
+# Task: write the knowledge module docs "{{TITLE}}"
+
+Write the following files into directory <b>{{OUTPUT_DIR_ABS}}</b>/ (repo-relative: {{OUTPUT_DIR}}/).
+**Write only files inside this directory.** `_module.yaml` is generated by the tool — do not write it by hand.
+
+## Module info
+- Title: {{TITLE}}
+- Scope: {{SCOPE}}
+- Child modules: {{CHILDREN}}
+
+## Files to write (each is a short doc, in English, keeping technical nouns verbatim)
+1. `overview.md` —— one or two sentences: what this module is and its role in the repository (example style: *graphiti_core is the shared Python kernel; docker-compose orchestrates the three runtime services — REST server, MCP server, and the Next.js web UI.*)
+2. `tech-stack.md` —— one paragraph listing the key languages/frameworks/build tools/storages.
+3. `architecture.md` —— 3~6 bullets on internal structure and external contracts (call chains, orchestration entry points, cross-process contracts).
+4. `configuration-and-commands.md` —— one paragraph with this module's specific run/build/debug commands (if none: "no special commands, see the root README").
+5. `coding-conventions.md` (optional) —— only if the module has clear, consistent coding conventions: 3~5 bullets.
+
+## Requirements
+- Read the key files under scope before writing; content must match the real code.
+- No heading levels (these are fragment docs — plain text/bullets only).
+- Keep it tight: overview 1~2 sentences, tech stack 1~3 sentences, architecture 3~6 bullets.
+
+While writing, run `repowiki touch <repo path> --task {{TASK_ID}}` every few minutes to renew your claim (long tasks are otherwise reclaimed).
+
+When done run: `repowiki check <repo path> --task {{TASK_ID}}`

repowiki/templates/en/knowledge_module_update_task.md

@@ -0,0 +1,36 @@
+---
+id: {{TASK_ID}}
+kind: knowledge_module
+phase: 2
+title: Knowledge module: {{TITLE}} (incremental update)
+output: {{OUTPUT_DIR}}
+---
+
+# Task: incrementally update the knowledge module docs "{{TITLE}}"
+
+Module directory: <b>{{OUTPUT_DIR_ABS}}</b> (repo-relative: {{OUTPUT_DIR}}).
+**Write only the three docs inside this directory; never touch repository sources or other knowledge outputs.**
+
+## Module info
+- Scope: {{SCOPE}}
+
+## Files changed since last generation (only those falling inside the module scope; re-read their current content)
+{{CHANGED_FILES}}
+
+## Files to rewrite (each is a short doc, in English)
+1. `overview.md` —— one or two sentences: what this module is and its role in the repository.
+2. `tech-stack.md` —— one paragraph listing the key languages/frameworks/build tools/storages.
+3. `architecture.md` —— 3~6 bullets on internal structure and external contracts (call chains, orchestration entry points, cross-process contracts).
+
+## Update rules
+1. Fix outdated descriptions against the changed files; docs unaffected by the changes may stay as-is (but must still exist and be non-empty).
+2. Keep it tight: overview 1~2 sentences, tech stack 1~3 sentences, architecture 3~6 bullets.
+3. Reference repository files by relative path; no emoji/tables.
+
+## Hard checks
+All three files (`overview.md`/`tech-stack.md`/`architecture.md`) exist and are non-empty.
+
+While writing, run `repowiki touch <repo> --task {{TASK_ID}}` every few minutes to renew
+your claim (long tasks get reclaimed otherwise).
+
+When done run: `repowiki check <repo> --task {{TASK_ID}}`

repowiki/templates/en/knowledge_task.md

@@ -0,0 +1,65 @@
+---
+id: knowledge-plan
+kind: knowledge_plan
+phase: 2
+title: 知识库规划（modules + cards）
+output: state/knowledge.json
+---
+
+# Task: plan the repository knowledge base (module tree + mechanism card list)
+
+Your only output is one JSON file: `.repowiki/state/knowledge.json`.
+**Do not write any cards or module docs; do not modify any other repository files.**
+
+## Repository info
+- Repo name: {{REPO_NAME}}
+- Key files: {{KEY_FILES}}
+
+## File tree (truncated)
+```
+{{TREE_SUMMARY}}
+```
+
+## Output language
+Write every human-readable field (`title`) in **English**, keeping technical proper nouns verbatim.
+
+## JSON Schema
+```json
+{
+  "modules": [
+    {
+      "id": "m01",
+      "title": "<module title (English, may contain technical proper nouns)>",
+      "scope": ["<repo path prefix this module covers, e.g. src/core/>"],
+      "children": ["<child module id>"],
+      "depends_on": ["<other module id this depends on>"],
+      "related_to": ["<related module id>"]
+    }
+  ],
+  "cards": [
+    {
+      "id": "k01",
+      "title": "<card title, e.g.: Configuration system — layered YAML + pydantic-settings loading>",
+      "category": "<one id from the category list above>",
+      "scope": ["**"],
+      "source_files": ["<repo-relative path>", "..."]
+    }
+  ]
+}
+```
+
+## Planning rules
+1. Modules = clearly bounded subsystems/sub-packages of the repository (2~8 is a good range, 1~2 levels). The root module covers the whole repository; sub-modules divide by scope path. Root ids m01…, sub-ids m0101…; a sub-module appears both in its parent's `children` and in the top-level `modules` list.
+2. Mechanism cards capture cross-cutting mechanisms; `category` must come from the list below ({{CATEGORY_COUNT}} categories). Only create cards for mechanisms that really exist and are worth documenting (0~2 per category; prefer fewer, better ones):
+
+{{CATEGORY_BLOCK}}
+3. Card titles are self-contained (mechanism + key technology) and globally unique; `source_files` are the core files implementing the mechanism (2~8, must really exist).
+4. Cards and modules are independent: cards describe "mechanisms", modules describe "structure".
+
+## Self-check
+- [ ] JSON parses; module/card ids and titles unique
+- [ ] every id referenced by children/depends_on/related_to exists
+- [ ] scope and source_files paths really exist
+- [ ] category uses only the enum values from the list above
+
+When done run: `repowiki check <repo path> --task knowledge-plan`

repowiki/templates/en/overview_task.md

@@ -0,0 +1,35 @@
+---
+id: overview
+kind: overview
+phase: 3
+title: Wiki 总览（wiki_overview）
+output: {{OUTPUT}}
+---
+
+# Task: write the repository wiki overview
+
+Write the overview to: <b>{{OUTPUT_ABS}}</b> (repo-relative: {{OUTPUT}}).
+**Write only this one file.** It is embedded verbatim as the `wiki_overview` field of `repowiki-metadata.json`.
+
+## Inputs
+- Repository: {{REPO_NAME}}
+- Chapter tree (each chapter's page titles and page_briefs):
+
+```
+{{CATALOG_TREE}}
+```
+
+- Skim a few representative pages (under `.repowiki/{{LOCALE}}/content/`) before writing.
+
+## Content requirements (plain markdown, no YAML front matter)
+1. The H1 is "{{REPO_NAME}} Wiki Overview".
+2. 2~4 paragraphs on the repository's positioning and core value (objective tone).
+3. A "Section Navigation" section: for each chapter in the tree, `chapter title —— one-sentence description` (bullet list, plain text, no links).
+4. A "How to Use This Wiki" section: suggested reading order (newcomer path vs contributor path).
+
+## Style
+{{STYLE}}
+
+While writing, run `repowiki touch <repo path> --task {{TASK_ID}}` every few minutes to renew your claim (long tasks are otherwise reclaimed).
+
+When done run: `repowiki check <repo path> --task overview`

repowiki/templates/en/overview_update_task.md

@@ -0,0 +1,50 @@
+---
+id: {{TASK_ID}}
+kind: overview
+phase: 3
+title: Wiki Overview (incremental update)
+output: {{OUTPUT}}
+---
+
+# Task: incrementally refresh the repository wiki overview
+
+Code has changed and the overview must follow. Write the refreshed overview to:
+<b>{{OUTPUT_ABS}}</b> (repo-relative: {{OUTPUT}}).
+**Rewrite only this file** (current content under "Current overview" below), keeping the
+existing structure and length — do not start from scratch.
+
+## Inputs
+- Repository: {{REPO_NAME}}
+- Files changed since the last generation:
+```
+{{CHANGED_FILES}}
+```
+- Current catalog tree (chapter/subpage titles with page_briefs; if sections were added
+  or removed, "Section Navigation" must reflect it):
+
+```
+{{CATALOG_TREE}}
+```
+
+## Current overview (to refresh)
+```
+{{OLD_OVERVIEW}}
+```
+
+## Content requirements (plain markdown, no YAML front matter)
+1. Keep the H1 as "{{REPO_NAME}} Wiki Overview".
+2. Keep the existing paragraph structure: repo positioning & core value, `Section
+   Navigation`, `How to Use This Wiki` — all three are required; modify only the parts
+   the changes touch — added/removed sections must be reflected in "Section Navigation",
+   major mechanism changes in the positioning paragraphs.
+3. Do not add "Update Summary" or similar sections; the overview is not a page — keep it
+   tight.
+4. No YAML front matter, no cross-page links.
+
+## Style
+{{STYLE}}
+
+While writing, run `repowiki touch <repo-path> --task {{TASK_ID}}` every few minutes to
+renew your claim (prevents reclamation on long tasks).
+
+When done run: `repowiki check <repo-path> --task {{TASK_ID}}`

repowiki/templates/en/page_task.md

@@ -0,0 +1,45 @@
+---
+id: {{TASK_ID}}
+kind: page
+phase: 2
+title: {{TITLE}}
+output: {{OUTPUT}}
+hint_files:
+{{HINT_FILES_YAML}}
+---
+
+# Task: write the wiki page "{{TITLE}}"
+
+Write the finished page to: <b>{{OUTPUT_ABS}}</b> (repo-relative: {{OUTPUT}}).
+**Write only this one file; never modify repository sources or other wiki pages.**
+
+## Page positioning
+- Chapter path: {{CHAPTER_PATH}}
+- Page summary: {{SUMMARY}}
+- Points this page must cover (page_brief):
+{{PAGE_BRIEF}}
+
+## Reference files (read them before writing; cited line numbers must come from their real content)
+{{HINT_FILES}}
+
+## Sibling pages (other page titles under the same parent chapter — for orientation only; never link them)
+{{SIBLINGS}}
+
+## Page template (follow this skeleton strictly; replace <> placeholders with real content, keep the section order)
+{{PAGE_TEMPLATE}}
+
+## Style & diagram rules (mandatory)
+{{STYLE}}
+
+## Hard checks (the validator enforces each one; violations fail the task)
+1. Exactly one H1, equal to "{{TITLE}}".
+2. The `<cite>` block lists the files this page actually references (`[file name](file://repo-relative path)` format, 3~15 files).
+3. The "Contents" anchors must match the real section headings (GitHub-style anchors: lowercase, punctuation dropped, spaces → `-`).
+4. After the Introduction, every section ends with "Section sources"; every mermaid diagram is followed by "Diagram sources"; link format `[path:Lx-Ly](file://path#Lx-Ly)` with line numbers within the file's real length.
+5. At least 2 mermaid diagrams (a structure diagram + a sequence/dependency diagram).
+6. Beyond the required sections above you may add "Appendix: <topic>" sections as needed.
+7. Never link any other page under `.repowiki/`.
+
+While writing, run `repowiki touch <repo path> --task {{TASK_ID}}` every few minutes to renew your claim (long tasks are otherwise reclaimed).
+
+When done run: `repowiki check <repo path> --task {{TASK_ID}}`

repowiki/templates/en/page_template.md

@@ -0,0 +1,113 @@
+# {{TITLE}}
+
+<cite>
+**Files referenced by this page**
+- [<file name>](file://<repo-relative path>)
+- [<file name>](file://<repo-relative path>)
+</cite>
+
+## Contents
+1. [Introduction](#introduction)
+2. [Project Structure](#project-structure)
+3. [Core Components](#core-components)
+4. [Architecture Overview](#architecture-overview)
+5. [Detailed Component Analysis](#detailed-component-analysis)
+6. [Dependency Analysis](#dependency-analysis)
+7. [Performance and Consistency Considerations](#performance-and-consistency-considerations)
+8. [Troubleshooting Guide](#troubleshooting-guide)
+9. [Conclusion](#conclusion)
+
+## Introduction
+<One paragraph: what this page's topic is, what problem it solves, where it lives in the repository.>
+
+## Project Structure
+<Repository directories/files relevant to this chapter (bullet list, plain-text paths).>
+
+```mermaid
+graph TB
+subgraph "Layer name"
+A["Component<br/>file.py"]
+B["Component<br/>file.py"]
+end
+A --> B
+```
+
+Diagram sources
+- [<path>:<start>-<end>](file://<path>#L<start>-L<end>)
+
+Section sources
+- [<path>:<start>-<end>](file://<path>#L<start>-L<end>)
+
+## Core Components
+- <component/concept name>: <one-sentence responsibility>
+
+Section sources
+- [<path>:<start>-<end>](file://<path>#L<start>-L<end>)
+
+## Architecture Overview
+<One paragraph + a sequence diagram describing the runtime interaction or data flow of this topic.>
+
+```mermaid
+sequenceDiagram
+participant Client as "Caller"
+participant API as "Entry layer"
+participant Core as "Core layer"
+Client->>API : "request"
+API->>Core : "invoke"
+Core-->>API : "result"
+API-->>Client : "response"
+```
+
+Diagram sources
+- [<path>:<start>-<end>](file://<path>#L<start>-L<end>)
+
+Section sources
+- [<path>:<start>-<end>](file://<path>#L<start>-L<end>)
+
+## Detailed Component Analysis
+### <sub-component / sub-topic 1>
+- Responsibility: <...>
+- Key behaviors: <...>
+- Implementation notes: <...>
+
+Section sources
+- [<path>:<start>-<end>](file://<path>#L<start>-L<end>)
+
+### <sub-component / sub-topic 2>
+- ...
+
+Section sources
+- [<path>:<start>-<end>](file://<path>#L<start>-L<end>)
+
+## Dependency Analysis
+- <upstream/downstream dependencies (bullet list).>
+
+```mermaid
+graph LR
+A["Module A"] --> B["Module B"]
+B --> C["External dependency"]
+```
+
+Diagram sources
+- [<path>:<start>-<end>](file://<path>#L<start>-L<end>)
+
+Section sources
+- [<path>:<start>-<end>](file://<path>#L<start>-L<end>)
+
+## Performance and Consistency Considerations
+- <performance characteristics, concurrency, caching, consistency trade-offs (bullet list).>
+
+Section sources
+- [<path>:<start>-<end>](file://<path>#L<start>-L<end>)
+
+## Troubleshooting Guide
+- <common error/symptom → cause → how to locate → relevant code location.>
+
+Section sources
+- [<path>:<start>-<end>](file://<path>#L<start>-L<end>)
+
+## Conclusion
+<One paragraph: the topic's positioning, correct usage, and caveats.>
+
+Section sources
+- [<path>:<start>-<end>](file://<path>#L<start>-L<end>)

repowiki/templates/en/update_task.md

@@ -0,0 +1,49 @@
+---
+id: {{TASK_ID}}
+kind: page_update
+phase: 2
+title: {{TITLE}}（增量更新）
+output: {{OUTPUT}}
+hint_files:
+{{HINT_FILES_YAML}}
+---
+
+# Task: incrementally update the wiki page "{{TITLE}}"
+
+Rewrite the full updated page to: <b>{{OUTPUT_ABS}}</b> (repo-relative: {{OUTPUT}}).
+**Write only this one file; never modify repository sources or other wiki pages.**
+
+## Files changed since the last generation (the basis of this update; re-read their current content)
+{{CHANGED_FILES}}
+
+## Points this page must cover (page_brief, still valid)
+{{PAGE_BRIEF}}
+
+## Current page in full (update on top of it; keep whatever is still correct)
+```markdown
+{{OLD_PAGE}}
+```
+
+## Update rules
+1. Right after the `<cite>` block and before the table of contents, insert one section:
+
+   ```markdown
+   ## Update Summary
+
+   **Changed content**
+   - <state concretely which part was updated because of which file change, e.g.: API endpoint path updated, migrated from /old to /new>
+   ```
+
+2. Fix outdated descriptions, line ranges, and diagrams against the changed files; keep unaffected sections as-is.
+3. Add an "Update Summary" entry to the "Contents" list (before "Introduction").
+4. If there was a major improvement, you may append an `**Updated**` marker to the relevant item in the "Conclusion" section.
+5. Everything else — structure, style, citation rules — is identical to first generation:
+
+{{STYLE}}
+
+## Hard checks
+Same as first generation (H1 = "{{TITLE}}", all required sections present, "Update Summary" present, section/diagram source links real with line numbers in range, ≥2 mermaid diagrams, zero page-to-page links).
+
+While writing, run `repowiki touch <repo path> --task {{TASK_ID}}` every few minutes to renew your claim (long tasks are otherwise reclaimed).
+
+When done run: `repowiki check <repo path> --task {{TASK_ID}}`