housekeeping and fiona skill overhaul
This commit is contained in:
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: Fiona-Assistant Agent Rules
|
||||
version: 1.7.0
|
||||
title: LLM Agent Rules
|
||||
name: Fiona-Assistant Development Agent Rules
|
||||
version: 1.9.1
|
||||
title: Agents
|
||||
type: summary
|
||||
created: 2025-09-23
|
||||
updated: 2026-09-30
|
||||
@@ -9,7 +9,7 @@ tags: [agents, rules, guidelines, llm, ai]
|
||||
sources: []
|
||||
---
|
||||
|
||||
# Fiona-Assistant LLM Agent Rules
|
||||
# Agents
|
||||
|
||||
- [1. Overview](#1-overview)
|
||||
- [1.1 Rule References](#11-rule-references)
|
||||
@@ -128,6 +128,9 @@ bumps versions (step 5). It skips the test and implementation steps.
|
||||
### 2.4 Commit
|
||||
|
||||
- *NEVER* commit without explicit permission!
|
||||
- This rule covers this repository only. A deployed wiki commits
|
||||
after each ingest cycle and housekeeping pass
|
||||
([SPEC](./SPEC.md) 3.3.3).
|
||||
|
||||
---
|
||||
|
||||
@@ -419,6 +422,22 @@ llm:
|
||||
- reasoning: high # when the model reports a level
|
||||
contested: true
|
||||
contradictions: [other-page-slug]
|
||||
# written by wiki ingest (SPEC 7.25), optional:
|
||||
status: raw | refined
|
||||
source_meta: {author: Name} # metadata read from the source
|
||||
ingest: # provenance; every key always present
|
||||
origin: https://host/path # URL or file path of the source
|
||||
origin_kind: url | file
|
||||
final_url: null # URL after redirects
|
||||
fetched: YYYY-MM-DDTHH:MM:SSZ
|
||||
media_type: text/html
|
||||
size_bytes: 0
|
||||
sha256: <64 lowercase hex> # of the raw copy; never hand-edited
|
||||
raw_reused: false
|
||||
converter: html # converter name, or agent
|
||||
conversion: complete | partial
|
||||
warnings: []
|
||||
tool: fiona-assistant <version>
|
||||
---
|
||||
```
|
||||
|
||||
|
||||
@@ -17,6 +17,7 @@ from fiona.logging_config import setup_logging
|
||||
from fiona.mdoctor.mdoctor import main as mdoctor_main
|
||||
from fiona.python_ruff.python_ruff import main as python_ruff_main
|
||||
from fiona.wiki.graph_generator import wiki_graph_main
|
||||
from fiona.wiki.housekeeping import housekeeping_main
|
||||
from fiona.wiki.sanity_manager import sanity_main
|
||||
from fiona.wiki.update_manager import check_update_main, update_main
|
||||
from fiona.wiki.wiki import wiki_init
|
||||
@@ -279,6 +280,23 @@ def main():
|
||||
help="Disable tracking of external links"
|
||||
)
|
||||
|
||||
# AI/LLM: fiona-assistant housekeeping (SPEC 4.15)
|
||||
housekeeping_parser = subparsers.add_parser(
|
||||
"housekeeping",
|
||||
help="Run the wiki maintenance routine and report what needs work"
|
||||
)
|
||||
housekeeping_parser.add_argument(
|
||||
"directory",
|
||||
nargs="?",
|
||||
default=".",
|
||||
help="Wiki directory (default: current directory)"
|
||||
)
|
||||
housekeeping_parser.add_argument(
|
||||
"--json",
|
||||
action="store_true",
|
||||
help="Output results in JSON format"
|
||||
)
|
||||
|
||||
args = parser.parse_args()
|
||||
setup_logging()
|
||||
logging.getLogger(__name__).debug("fiona-assistant command: %s", args.command)
|
||||
@@ -394,6 +412,8 @@ def main():
|
||||
else:
|
||||
wiki_parser.print_help()
|
||||
sys.exit(1)
|
||||
elif args.command == "housekeeping":
|
||||
sys.exit(housekeeping_main(directory=args.directory, json_output=args.json))
|
||||
else:
|
||||
parser.print_help()
|
||||
sys.exit(1)
|
||||
|
||||
@@ -1,27 +1,34 @@
|
||||
---
|
||||
name: llm-wiki-agent-rules
|
||||
title: LLM Wiki Agent Rules
|
||||
version: 1.2.0
|
||||
version: 1.3.0
|
||||
created: 2025-09-23
|
||||
updated: 2026-09-29
|
||||
updated: 2026-09-30
|
||||
type: summary
|
||||
---
|
||||
|
||||
# LLM Wiki Agent Rules
|
||||
|
||||
This file is the entry point for an LLM working in an llm-wiki.
|
||||
It states only what must be true before any skill is loaded.
|
||||
This directory is an llm-wiki: a persistent knowledge base of
|
||||
interlinked markdown. The user brings sources and questions. You
|
||||
compile each source once into wiki pages, keep the cross-references
|
||||
current, and answer from those pages. The pattern is
|
||||
[llm-wiki-mod](./utils/skills/fiona/llm-wiki-mod.md). The wiki's
|
||||
domain, tags, and directory tree are in [schema](./wiki/schema.md).
|
||||
|
||||
This file states only what must be true before any skill is loaded.
|
||||
Commands, lint codes, and the edit workflow live in the Fiona skill.
|
||||
|
||||
- [1. Load the Fiona skill](#1-load-the-fiona-skill)
|
||||
- [2. What an llm-wiki is](#2-what-an-llm-wiki-is)
|
||||
- [3. Boundaries](#3-boundaries)
|
||||
- [4. History](#4-history)
|
||||
|
||||
## 1. Load the Fiona skill
|
||||
|
||||
If the Fiona skill is not already part of the system prompt, read
|
||||
[Fiona skill](./utils/skills/fiona/SKILL.md) and follow it for the
|
||||
rest of the session.
|
||||
rest of the session. It loads llm-wiki-mod.
|
||||
|
||||
When that skill is already loaded, do not read it again. This file
|
||||
does not repeat it.
|
||||
@@ -42,8 +49,16 @@ Fiona skill, not this file.
|
||||
These hold even before the skill is loaded:
|
||||
|
||||
- `personal/` is read-only. Never create, edit, or delete there.
|
||||
- `raw/` is read-only. Never edit archived sources.
|
||||
- `raw/` is the archive. Add a new source there. Never edit, move,
|
||||
or delete a file already there.
|
||||
- Synthesized pages belong under `wiki/`.
|
||||
- `ingest/` is only the drop zone for files waiting to be parsed.
|
||||
- Do not commit, snapshot, restore, clean, or undo unless the user
|
||||
asked.
|
||||
|
||||
## 4. History
|
||||
|
||||
Git is the wiki's history. After each ingest cycle and each
|
||||
housekeeping pass (lint fixes, index or TOC updates, page moves),
|
||||
commit with `fiona-assistant git save --description TEXT`.
|
||||
|
||||
`git clean`, `git undo`, and `git restore` discard work. Run them
|
||||
only when the user asks.
|
||||
|
||||
@@ -1,12 +1,19 @@
|
||||
---
|
||||
name: map
|
||||
version: 1.0.0
|
||||
title: Map Script
|
||||
version: 1.1.0
|
||||
title: Script Map
|
||||
type: summary
|
||||
created: 2025-09-23
|
||||
updated: 2026-09-24
|
||||
updated: 2026-09-30
|
||||
---
|
||||
|
||||
# Map Script
|
||||
# Script Map
|
||||
|
||||
Mapping utility script.
|
||||
Catalog of the reusable scripts in this folder. Read it before
|
||||
writing a new script, and add a row when you add one. The rules for
|
||||
writing a script are in the
|
||||
[Fiona skill](../skills/fiona/SKILL.md#write-reusable-scripts).
|
||||
|
||||
| Script | Purpose | Usage | Added |
|
||||
| --- | --- | --- | --- |
|
||||
| `example.py` | Placeholder that prints a greeting. | `python utils/scripts/example.py` | 2025-09-23 |
|
||||
|
||||
@@ -4,7 +4,7 @@ category: productivity
|
||||
description: Operate an llm-wiki with the fiona-assistant CLI.
|
||||
author: nvaldez
|
||||
license: MIT
|
||||
version: 1.4.0
|
||||
version: 1.9.0
|
||||
updated: 2026-09-30
|
||||
---
|
||||
|
||||
@@ -18,6 +18,7 @@ You maintain an llm-wiki. The command for that work is
|
||||
[markdown rules](./markdown_rules.md).
|
||||
|
||||
- [Load llm-wiki-mod](#load-llm-wiki-mod)
|
||||
- [You own the wiki](#you-own-the-wiki)
|
||||
- [1. Before a command](#1-before-a-command)
|
||||
- [2. Install](#2-install)
|
||||
- [3. Which command](#3-which-command)
|
||||
@@ -33,6 +34,8 @@ You maintain an llm-wiki. The command for that work is
|
||||
- [13. Frontmatter](#13-frontmatter)
|
||||
- [14. Checks with no own command](#14-checks-with-no-own-command)
|
||||
- [15. Do not call](#15-do-not-call)
|
||||
- [16. Ingest cycle](#16-ingest-cycle)
|
||||
- [17. Housekeeping](#17-housekeeping)
|
||||
|
||||
## Load llm-wiki-mod
|
||||
|
||||
@@ -41,6 +44,97 @@ raw sources, the wiki, the schema, and ingest, query, and lint.
|
||||
If it is not already in context, read it before any wiki work.
|
||||
When it is already loaded, do not read it again.
|
||||
|
||||
## You own the wiki
|
||||
|
||||
You are responsible for this wiki: what it says, how it is
|
||||
organized, how pages link, and its history. The `fiona-assistant`
|
||||
tools own nothing. They do the repeated, mechanical work cheaply,
|
||||
so your tokens go to reading sources and making judgments. A tool
|
||||
is a helper you direct, not an authority you defer to.
|
||||
|
||||
- A clean tool run is evidence, not a verdict. `wiki sanity`
|
||||
passing means the style, frontmatter, and links are valid. It
|
||||
does not mean a page is true, current, complete, or in the right
|
||||
place. Read the pages.
|
||||
- Treat tool output as a draft. When a tool gets something wrong,
|
||||
such as a bad title, a lost table, or the wrong folder, fix the
|
||||
result within the rules (section 16.3), or re-run it with better
|
||||
arguments.
|
||||
- Decisions stay with you: what a page says, what it links to,
|
||||
which claims conflict, how confident the page is, and when a
|
||||
source is too complex for a converter (section 16.2).
|
||||
- When no tool fits, do the work yourself. Do not bend a tool to a
|
||||
job it was not built for, and do not invent flags (section 15).
|
||||
- When a tool fails or misbehaves, tell the user the command and
|
||||
its output. Do not work around it silently.
|
||||
|
||||
### Write reusable scripts
|
||||
|
||||
When you repeat the same mechanical step and no `fiona-assistant`
|
||||
command covers it, write a script under
|
||||
[utils/scripts](../../scripts/map.md) instead of redoing it by hand
|
||||
each time. Tokens spent once on a script are saved on every later
|
||||
run, and the next session can reuse it.
|
||||
|
||||
1. Read the [script map](../../scripts/map.md) first. Extend an
|
||||
existing script before writing a new one.
|
||||
2. One job per script. Name the file in `snake_case.py`.
|
||||
3. Use the standard library first. A third-party import must already
|
||||
be installed with `fiona-assistant`, or be approved by the user.
|
||||
4. Start with a module docstring: purpose, inputs, outputs, and one
|
||||
example call. Parse arguments with `argparse`, so `--help` works.
|
||||
5. Take the wiki root as an argument, defaulting to `.`. Print
|
||||
results on stdout, with `--json` when you will parse them. Send
|
||||
diagnostics through `logging` to stderr.
|
||||
6. Keep it deterministic. No network access unless that is the
|
||||
script's job and the user agreed. Never write under `raw/` or
|
||||
`personal/`. A script that writes files offers `--dry-run`.
|
||||
7. Add a row to the [script map](../../scripts/map.md). Run
|
||||
`fiona-assistant python-ruff chklint utils/scripts`. Append a
|
||||
line to `wiki/log.md`.
|
||||
8. When a script proves useful in general, suggest to the user that
|
||||
it become a `fiona-assistant` command.
|
||||
|
||||
### Save after every ingest cycle and housekeeping pass
|
||||
|
||||
When an ingest cycle ends (section 16.4, with sanity passing), run:
|
||||
|
||||
```text
|
||||
fiona-assistant git save --description "ingest <slug>: <what the source is>"
|
||||
```
|
||||
|
||||
After a housekeeping pass (lint fixes, index, log, or TOC updates,
|
||||
page moves, template updates), with sanity passing, run:
|
||||
|
||||
```text
|
||||
fiona-assistant git save --description "housekeeping: <what changed>"
|
||||
```
|
||||
|
||||
This is a standing instruction. You do not need to ask each time.
|
||||
It is the step that makes the wiki's history usable:
|
||||
|
||||
- **One source, one commit.** The raw copy, the page, the index
|
||||
entry, the log line, and every concept or entity page the source
|
||||
changed land together. `git log` becomes the record of what
|
||||
entered the wiki, when, and from where.
|
||||
- **Reviewable.** The user can run `git show` on that commit and see
|
||||
exactly how one source changed the wiki, and check your synthesis
|
||||
against it.
|
||||
- **Recoverable.** A bad refinement can be undone or restored
|
||||
without losing other work. That only holds when each cycle is its
|
||||
own commit. Batched or skipped saves mix sources, so one undo
|
||||
drops unrelated work.
|
||||
- **Proof behind the log.** `wiki/log.md` says what happened. The
|
||||
commit holds the before and after state that proves it.
|
||||
|
||||
Before saving, run `fiona-assistant git status`. `save` stages
|
||||
everything in the tree. When it shows changes that are not from
|
||||
this cycle, ask the user before saving. When sanity fails, fix it
|
||||
first, or ask. A duplicate ingest writes nothing, so `save`
|
||||
refusing a clean tree is expected. This standing instruction
|
||||
covers `save` only. `snapshot`, `restore`, `clean`, and `undo`
|
||||
still need the user's request.
|
||||
|
||||
## 1. Before a command
|
||||
|
||||
Run from the wiki root, the directory that contains
|
||||
@@ -50,9 +144,10 @@ parent directories for the wiki root. `librarian toc file *`
|
||||
looks for `fiona-settings.json` in the current directory, then
|
||||
in subdirectories.
|
||||
|
||||
`personal/` and `raw/` are read-only, including the directory
|
||||
itself. Never create, edit, or delete there. Never point a fixer
|
||||
at them.
|
||||
`personal/` is read-only, including the directory itself. Never
|
||||
create, edit, or delete there. `raw/` is the archive: you may add a
|
||||
new source file (section 16.2), but never edit, move, or delete a
|
||||
file already there. Never point a fixer at either.
|
||||
|
||||
`librarian` and `mdoctor` also exist as their own console scripts.
|
||||
Call them through `fiona-assistant` so one binary covers every
|
||||
@@ -68,18 +163,13 @@ warnings as the lint report.
|
||||
python -m pip install fiona-assistant
|
||||
```
|
||||
|
||||
From a checkout of this repository:
|
||||
|
||||
```text
|
||||
python -m pip install -e .
|
||||
```
|
||||
|
||||
`fiona-assistant` with no command prints help and exits 0.
|
||||
|
||||
## 3. Which command
|
||||
|
||||
| Question | Command |
|
||||
| --- | --- |
|
||||
| Maintain the wiki: what needs work? | `housekeeping --json`, then section 17 |
|
||||
| Is this wiki healthy? | `wiki sanity --json --non-interactive` |
|
||||
| Markdown style on files I edited? | `mdoctor chklint <dir>` |
|
||||
| Auto-fix markdown style? | `mdoctor fix <writable-dir>` |
|
||||
@@ -88,9 +178,12 @@ python -m pip install -e .
|
||||
| Python under the wiki? | `python-ruff chklint <dir>` |
|
||||
| New files or new headings? | `librarian toc` and `librarian toc file` |
|
||||
| What links to what? | `wiki graph` |
|
||||
| New source, a URL or a file? | `wiki ingest <source> --json`, then section 16 |
|
||||
| Ingested pages not refined yet? | `wiki ingest --pending --json` |
|
||||
| Empty directory, start a wiki? | `wiki init <dir>` |
|
||||
| Template behind the installed package? | `wiki check-update`, then `wiki update --dry-run` |
|
||||
| User asked to save wiki edits? | `git save --description TEXT` |
|
||||
| A `*-update.md` file appeared? | Merge it, section 17.1 |
|
||||
| Ingest or housekeeping done? | `git save --description TEXT` |
|
||||
|
||||
Prefix every row with `fiona-assistant`.
|
||||
|
||||
@@ -106,10 +199,10 @@ fiona-assistant wiki init [directory]
|
||||
|
||||
Copies the template, substitutes `DATE_PLACEHOLDER` with today's
|
||||
UTC date, creates a git repo, and commits `Initial llm-wiki commit`.
|
||||
`.gitignore` starts from the fiona-assistant repository ignore
|
||||
file and includes `personal/`. An existing `.gitignore` keeps its
|
||||
lines; missing patterns are appended. Paths matched by that
|
||||
repository ignore file are not copied. `personal/` is gitignored.
|
||||
`.gitignore` starts from the packaged default ignore patterns and
|
||||
includes `personal/`. An existing `.gitignore` keeps its lines;
|
||||
missing patterns are appended. Paths matched by those default
|
||||
patterns are not copied. `personal/` is gitignored.
|
||||
|
||||
Success stdout:
|
||||
|
||||
@@ -135,14 +228,29 @@ When something differs, the lines that apply:
|
||||
|
||||
```text
|
||||
Files to update: <N>
|
||||
Conflicts (owner copy kept): <N>
|
||||
- <path> (<current> -> <template>) -> <stem>-update.md
|
||||
Directories to add: <N>
|
||||
Files to add: <N>
|
||||
Total: <N> file(s) need attention
|
||||
Files skipped (locally modified): <N>
|
||||
```
|
||||
|
||||
`--json` prints one object with `files_to_update`, `files_to_add`,
|
||||
`directories_to_add`, `files_skipped`, `total`, and `has_updates`.
|
||||
A file that lacks a version on either side is compared by SHA-256. Equal
|
||||
hashes mean up to date. Different hashes print the first 8 hex
|
||||
digits of each side instead of versions:
|
||||
|
||||
```text
|
||||
- utils/scripts/example.py (sha256 1a2b3c4d -> 9f8e7d6c)
|
||||
```
|
||||
|
||||
`--json` prints one object with `files_to_update`, `conflicts`,
|
||||
`files_to_add`, `directories_to_add`, `files_skipped`, `total`, and
|
||||
`has_updates`. Each conflict has `path`, `update_path`,
|
||||
`current_version`, and `template_version`. Entries in
|
||||
`files_to_update` and `conflicts` also carry `current_sha256` and
|
||||
`template_sha256`: the full hash, or `null` when versions were
|
||||
compared.
|
||||
|
||||
### 4.3. update
|
||||
|
||||
@@ -150,10 +258,18 @@ Files skipped (locally modified): <N>
|
||||
fiona-assistant wiki update [directory] [--dry-run] [-y|--yes] [-f|--force] [--json]
|
||||
```
|
||||
|
||||
Updates drifted core files and adds missing ones. Never deletes
|
||||
user files. Never writes inside `personal/` or `raw/`. Never
|
||||
writes anything under `wiki/` (seeded at init, then filled by the
|
||||
LLM). Never writes a path matched by `.gitignore`.
|
||||
Updates drifted non-markdown core files (settings are deep-merged,
|
||||
the owner's values win) and adds missing core files. Never deletes
|
||||
user files. Never writes inside `personal/` or `raw/`. Never adds
|
||||
or overwrites anything under `wiki/` (seeded at init, then filled
|
||||
by the LLM). Never writes a path matched by `.gitignore`.
|
||||
|
||||
Never overwrites an existing markdown file. When the template has a
|
||||
newer version of one, such as `AGENTS.md`, `wiki/index.md`,
|
||||
`wiki/log.md`, or `wiki/schema.md`, the owner's file stays as it is
|
||||
and the template is written beside it as `<stem>-update.md`
|
||||
(`AGENTS-update.md`, `wiki/schema-update.md`). You merge it during
|
||||
housekeeping (section 17.1).
|
||||
|
||||
Run `--dry-run` first. It prints the plan, writes nothing, and
|
||||
exits 0. Without `--yes` or `--force` the command prompts. On a
|
||||
@@ -163,9 +279,12 @@ Pass `--yes` only after the user agrees to the dry run.
|
||||
Success stdout:
|
||||
|
||||
```text
|
||||
Update complete: <U> file(s) updated, <A> added, <S> skipped.
|
||||
Update complete: <U> file(s) updated, <A> added, <C> conflict(s), <S> skipped.
|
||||
```
|
||||
|
||||
When `<C>` is not zero, the next line tells you to run
|
||||
`fiona-assistant housekeeping`.
|
||||
|
||||
### 4.4. sanity
|
||||
|
||||
```text
|
||||
@@ -202,6 +321,68 @@ Also: `--include-pattern`, `--exclude-pattern`,
|
||||
`--external-links` / `--no-external-links`.
|
||||
`--json` is an alias for `--format json`.
|
||||
|
||||
### 4.6. ingest
|
||||
|
||||
Planned. Run `fiona-assistant wiki ingest --help`
|
||||
first. When the subcommand does not exist, do every step of
|
||||
section 16 by hand.
|
||||
|
||||
```text
|
||||
fiona-assistant wiki ingest <source> [--wiki DIR] [-r|--raw PATH] [-t|--target PATH] [--raw-only] [-f|--force] [--dry-run] [--json]
|
||||
fiona-assistant wiki ingest --pending [--wiki DIR] [--json]
|
||||
```
|
||||
|
||||
`<source>` is an `http://` or `https://` URL, or a file path. The
|
||||
tool is the first phase of an ingest:
|
||||
|
||||
- A URL is downloaded into `ingest/` as whatever it is: HTML, PDF,
|
||||
text. No credentials are sent.
|
||||
- The file is archived under `raw/`. A file in `ingest/` is moved.
|
||||
Any other file is copied. Nothing already in `raw/` is changed.
|
||||
- Before archiving, its SHA-256 is compared with every file in
|
||||
`raw/`. Identical bytes are never archived twice: the existing
|
||||
copy is reused (`raw_reused: true`). When a page already cites
|
||||
that copy, nothing is written and `duplicate_page` names it.
|
||||
- The archive is converted to markdown and written as one page
|
||||
with `status: raw`, `confidence: zero`, and `llm.model: none`.
|
||||
- One line is appended to `wiki/log.md`.
|
||||
|
||||
It does not refine the page, edit `wiki/index.md`, or touch any
|
||||
other page. That is your phase, section 16.
|
||||
|
||||
| Flag | Use |
|
||||
| --- | --- |
|
||||
| `-r`, `--raw PATH` | Place the raw copy, relative to `raw/`. A directory (`-r jenkins/tl153`) or a file name with an extension. |
|
||||
| `-t`, `--target PATH` | Place the page, relative to `wiki/`. A directory (`-t concepts`) or a `.md` file name. |
|
||||
| `--raw-only` | Archive only. Use it when you will convert by hand. |
|
||||
| `-f`, `--force` | Replace an existing page. Ask the user first when that page is refined. |
|
||||
| `--dry-run` | Print the plan. Writes nothing in the wiki. A URL is still downloaded, to a temporary directory. |
|
||||
| `--pending` | List pages still at `status: raw`. |
|
||||
|
||||
Defaults: raw copies go to `raw/articles/` (HTML, text, markdown),
|
||||
`raw/papers/` (PDF), or `raw/other/` (no converter). Pages go to
|
||||
`wiki/sources/<slug>.md`. Use `-r` to group related sources, and
|
||||
`-t` when the user names a place or the source belongs beside
|
||||
existing pages.
|
||||
|
||||
| Converter | Handles | Loses |
|
||||
| --- | --- | --- |
|
||||
| `markdown` | `.md` | Nothing. Source frontmatter moves to `source_meta`. |
|
||||
| `text` | `.txt`, `.log` | Structure. The body is one fenced `text` block. |
|
||||
| `html` | web pages | Navigation, scripts, and anything drawn by JavaScript. |
|
||||
| `pdf` | PDFs with a text layer | Tables, images, columns, and scanned pages. |
|
||||
|
||||
Pass `--json` and read the object: `raw_path`, `page_path`,
|
||||
`sha256`, `raw_reused`, `duplicate_page`, `converter`,
|
||||
`conversion` (`complete`, `partial`, `none`), and `warnings`. The
|
||||
page frontmatter carries the same facts in its `ingest` map.
|
||||
|
||||
| Exit | Meaning | Next |
|
||||
| --- | --- | --- |
|
||||
| 0 | Page written, `--raw-only`, or a duplicate | Read `duplicate_page`, `conversion`, and `warnings`, then section 16.1. |
|
||||
| 1 | Error on stderr, nothing written | Fix the argument, or fetch the source another way (section 16.2). |
|
||||
| 3 | Raw copy archived, no page | Convert by hand (section 16.2). |
|
||||
|
||||
## 5. librarian
|
||||
|
||||
`fiona-assistant librarian` with no subcommand lists `.`.
|
||||
@@ -344,9 +525,12 @@ JSN004 duplicate keys, JSN005 key order, JSN006 line length.
|
||||
## 10. git
|
||||
|
||||
These commands act on the git repository that contains the current
|
||||
directory. Run them from the wiki root. Run them only when the
|
||||
user asked. `fiona-assistant git` with no subcommand prints help
|
||||
and exits 1.
|
||||
directory. Run them from the wiki root. `save` runs after each
|
||||
ingest cycle and housekeeping pass, without asking
|
||||
([save rule](#save-after-every-ingest-cycle-and-housekeeping-pass)).
|
||||
`snapshot`, `restore`, `clean`, and `undo` run only on the user's
|
||||
request. `fiona-assistant git` with no subcommand prints help and
|
||||
exits 1.
|
||||
|
||||
```text
|
||||
fiona-assistant git status
|
||||
@@ -423,6 +607,8 @@ After you edit a page:
|
||||
8. If you touched Python, `fiona-assistant python-ruff chklint <dir>`.
|
||||
9. Before you call the wiki healthy,
|
||||
`fiona-assistant wiki sanity . --json --non-interactive`.
|
||||
10. When sanity passes, save
|
||||
([save rule](#save-after-every-ingest-cycle-and-housekeeping-pass)).
|
||||
|
||||
Relative markdown links must point at a real file. Wikilinks
|
||||
`[[page]]` must match a markdown file stem. Both are checked by
|
||||
@@ -432,7 +618,8 @@ style.
|
||||
|
||||
Ingest drops files in `ingest/`. Archive sources under `raw/` and
|
||||
do not edit them after that. Synthesized pages go under `wiki/`
|
||||
(`concepts/`, `entities/`, `comparisons/`, `queries/`).
|
||||
(`concepts/`, `entities/`, `comparisons/`, `queries/`). The full
|
||||
ingest is section 16.
|
||||
|
||||
## 13. Frontmatter
|
||||
|
||||
@@ -458,6 +645,8 @@ in the same edit. fmlint enforces `name` and `version` only.
|
||||
| `contested` | wiki pages | `true` when a claim is disputed, otherwise `false`. |
|
||||
| `contradictions` | wiki pages | Other page slugs that disagree. `[]` when none. |
|
||||
| `description` | SKILL.md only | Required when the file name is `SKILL.md`. |
|
||||
| `status` | ingested pages | `raw` from `wiki ingest`. You set `refined` (section 16.4). |
|
||||
| `ingest`, `source_meta` | ingested pages | Written by `wiki ingest`. Check them (section 16.3). Keep them when you refine. |
|
||||
|
||||
### Quality signals
|
||||
|
||||
@@ -516,7 +705,235 @@ These are not implemented. Do not invent flags for them.
|
||||
- `fiona-assistant pycustomlint`
|
||||
- `fiona-assistant python-ruff fix`
|
||||
|
||||
On a checkout of the fiona-assistant product repository, tests and
|
||||
the product gate are `python scripts/run_tests.py` and
|
||||
`python scripts/run_sanity.py --non-interactive`. Those are not wiki
|
||||
commands. A wiki uses `fiona-assistant wiki sanity`.
|
||||
`fiona-assistant wiki ingest` is planned. Call it only after
|
||||
`fiona-assistant wiki ingest --help` succeeds. Otherwise follow
|
||||
section 16 by hand.
|
||||
|
||||
## 16. Ingest cycle
|
||||
|
||||
An ingest has two phases. `wiki ingest` (section 4.6) converts the
|
||||
source into a page at `status: raw`. You refine that page to
|
||||
`status: refined`. The ingest is done only when both phases are
|
||||
done. The pattern is section 3.1 of
|
||||
[llm-wiki-mod](./llm-wiki-mod.md).
|
||||
|
||||
### 16.1. Convert
|
||||
|
||||
1. When the raw or page location is not obvious, run
|
||||
`fiona-assistant wiki ingest <source> --dry-run --json` and
|
||||
check `raw_path` and `page_path`.
|
||||
2. Run `fiona-assistant wiki ingest <source> --json`, with `-r` and
|
||||
`-t` when needed.
|
||||
3. Read the result. When `duplicate_page` is set, the same bytes
|
||||
are already archived and ingested. Nothing was written. Refine
|
||||
that page if it is still `status: raw`, else stop and tell the
|
||||
user which page holds the source. Use `--force` only when the
|
||||
user wants it converted again.
|
||||
4. On exit 0 with `conversion: complete` and no warning that lost
|
||||
content, check the metadata (section 16.3), then refine
|
||||
(section 16.4). Otherwise decide with section 16.2.
|
||||
|
||||
### 16.2. Convert by hand
|
||||
|
||||
The tool is the default, not a rule. You decide when the source is
|
||||
too complex for it and read the source yourself. Convert by hand
|
||||
when:
|
||||
|
||||
- The command exited 3: no converter, or conversion failed.
|
||||
- `conversion` is `partial` and the warnings show lost text: no text
|
||||
layer (a scanned PDF), no text content (a page drawn by JavaScript
|
||||
or a login page), or pages with no text.
|
||||
- Layout carries the meaning: tables, multi-column papers, forms,
|
||||
slides, spreadsheets, diagrams, or a bundle of logs.
|
||||
- The download failed on authentication (401, 403, or a login page
|
||||
in the body). Fetch the source with a tool that has access, save
|
||||
it into `ingest/`, and ingest that file.
|
||||
|
||||
How:
|
||||
|
||||
1. Make sure the raw copy exists. When it does not, run
|
||||
`fiona-assistant wiki ingest <file> --raw-only --json`. Without
|
||||
the tool, first compute the file's SHA-256 (`sha256sum <file>`,
|
||||
or `Get-FileHash -Algorithm SHA256 <file>` in PowerShell) and
|
||||
compare it with the files under `raw/` of the same size and with
|
||||
`ingest.sha256` in `wiki/` pages. Reuse a match. Do not archive
|
||||
the same bytes twice. With no match, copy the file (move it when
|
||||
it is in `ingest/`) to the default folder in section 4.6, under
|
||||
a lowercase hyphenated name that is not taken.
|
||||
2. Read the raw file with your own tools. Never edit it.
|
||||
3. Write the page where the tool would have put it, with the
|
||||
complete frontmatter in section 16.5. Set
|
||||
`ingest.converter: agent`, and fill `sha256`, `size_bytes`,
|
||||
`media_type`, and `fetched` from the raw file.
|
||||
4. You may write the refined page in one pass. Then follow
|
||||
section 16.4 from step 3.
|
||||
|
||||
When the tool archived the wrong file or to the wrong place, tell
|
||||
the user. Do not move or delete anything under `raw/`.
|
||||
|
||||
### 16.3. Check the metadata
|
||||
|
||||
The tool fills every key in section 16.5, but it reads the source
|
||||
mechanically. Check the frontmatter against the source before you
|
||||
refine, and fix what is wrong.
|
||||
|
||||
| Key | Check | May edit |
|
||||
| --- | --- | --- |
|
||||
| `title` | The real title, not a site name, a file name, or `Untitled`. | yes |
|
||||
| `type` | Usually `summary` for a source page. | yes |
|
||||
| `tags` | From the schema taxonomy. | yes |
|
||||
| `sources` | Points at the raw file, and that file exists. | only when wrong |
|
||||
| `source_meta` | Author, dates, and description match the source. Add values the converter missed, such as a date printed in the body. | yes |
|
||||
| `ingest.conversion` | `partial` when you see lost text, tables, or pages. | yes |
|
||||
| `ingest.warnings` | Add what you found lost. Leave the tool's lines. | yes |
|
||||
| `ingest.origin`, `origin_kind`, `final_url` | Match the URL or path the user gave. | only when wrong |
|
||||
| `ingest.sha256`, `size_bytes`, `media_type`, `fetched`, `tool` | Facts computed by the tool. | no |
|
||||
|
||||
Verify `ingest.sha256` against the raw file with `sha256sum` or
|
||||
`Get-FileHash`. When a computed fact is wrong, re-run the ingest
|
||||
with `--force` or tell the user. Do not hand-edit it. Bump the page
|
||||
`version` patch and `updated` when you edit the metadata.
|
||||
|
||||
### 16.4. Refine
|
||||
|
||||
1. `fiona-assistant wiki ingest --pending --json` lists the pages
|
||||
still at `status: raw`. Without the tool, search `wiki/` for
|
||||
`status: raw`. Check each page's metadata first (section 16.3).
|
||||
2. Read the page and the source it cites. Open the raw file when
|
||||
`ingest.conversion` is `partial` or a claim looks garbled.
|
||||
3. Rewrite the page as a source summary:
|
||||
- The first paragraph says what the source is and why it matters.
|
||||
- Keep facts, numbers, decisions, dates, and names. Keep a short
|
||||
code or log excerpt when it backs a claim.
|
||||
- Drop boilerplate: menus, cookie notices, repeated headers and
|
||||
footers, page numbers.
|
||||
- Stay under the 200-line split rule in the schema. Detail stays
|
||||
in the raw file, which `sources` cites.
|
||||
4. Add at least two outbound links, as the schema asks. Link the
|
||||
concept and entity pages the source touches.
|
||||
5. Update or create those concept and entity pages, using the page
|
||||
thresholds in the schema. When the source disagrees with a page,
|
||||
set `contested` and `contradictions` on both.
|
||||
6. When the page belongs elsewhere, move it and fix every inbound
|
||||
link.
|
||||
7. Set the frontmatter: `status: refined`, `version: 1.0.0`,
|
||||
`updated`, `type`, `tags` from the taxonomy, and the quality
|
||||
signals from section 13 with your model in `llm`. Keep
|
||||
`sources`, `source_meta`, and every `ingest` key.
|
||||
8. Add the page to `wiki/index.md`. Append
|
||||
`- YYYY-MM-DD - refined <page path> from <raw path>` to
|
||||
`wiki/log.md`.
|
||||
9. Run the work loop in section 12, ending with `wiki sanity`.
|
||||
|
||||
The ingest is done when no page is left at `status: raw` and sanity
|
||||
passes. Then save it
|
||||
([save rule](#save-after-every-ingest-cycle-and-housekeeping-pass)).
|
||||
|
||||
### 16.5. Raw page frontmatter
|
||||
|
||||
`wiki ingest` writes every key below, even when a value is empty
|
||||
(`[]`, `{}`, or `null`). Write the same when you convert by hand.
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: <slug>
|
||||
version: 0.1.0
|
||||
title: <title>
|
||||
created: YYYY-MM-DD
|
||||
updated: YYYY-MM-DD
|
||||
type: summary
|
||||
status: raw
|
||||
sources: [raw/<category>/<slug>.<ext>]
|
||||
source_meta: {author: <name>}
|
||||
ingest:
|
||||
origin: <url or file path>
|
||||
origin_kind: url
|
||||
final_url: null
|
||||
fetched: YYYY-MM-DDTHH:MM:SSZ
|
||||
media_type: text/html
|
||||
size_bytes: 0
|
||||
sha256: <64 lowercase hex>
|
||||
raw_reused: false
|
||||
converter: <converter name, or agent>
|
||||
conversion: complete
|
||||
warnings: []
|
||||
tool: fiona-assistant <version>
|
||||
tags: []
|
||||
confidence: zero
|
||||
llm:
|
||||
- model: none
|
||||
contested: false
|
||||
contradictions: []
|
||||
---
|
||||
```
|
||||
|
||||
When you write it by hand, set `llm.model` to your model and
|
||||
`confidence` from section 13.
|
||||
|
||||
## 17. Housekeeping
|
||||
|
||||
```text
|
||||
fiona-assistant housekeeping [directory] [--json]
|
||||
```
|
||||
|
||||
One call runs the maintenance routine and tells you what needs work.
|
||||
Run it when the user asks for maintenance, after `wiki update`, and
|
||||
before you call the wiki healthy. It writes only `wiki_graph.html`.
|
||||
It never runs `wiki update`, merges, or fixes anything. That is
|
||||
your part.
|
||||
|
||||
| Step | Status when not clean | You do |
|
||||
| --- | --- | --- |
|
||||
| `check-update` | `WARN`: the template has updates, conflicts, or additions | Ask the user, then `wiki update --dry-run` and `wiki update --yes`. |
|
||||
| `merge` | `FAIL`: a `*-update.md` file exists | Section 17.1. |
|
||||
| `ingest` | `WARN`: a page under `wiki/` is at `status: raw` | Refine it, section 16.4. |
|
||||
| `sanity` | `FAIL`: a `wiki sanity` violation | Fix it, section 12. |
|
||||
| `graph` | `WARN`: a page under `wiki/` has no link in or out | Link it from a related page or from `wiki/index.md`. |
|
||||
|
||||
Every step runs, even after one fails. Exit 0 when no step is
|
||||
`FAIL`; `WARN` steps do not fail the run. Pass `--json` and read
|
||||
`steps[].status`, `details`, and `next`: `next` is the action to
|
||||
take. The human report ends with `HOUSEKEEPING PASSED`, or
|
||||
`HOUSEKEEPING FAILED - <N> step(s) need attention: <names>`.
|
||||
|
||||
Work through the `FAIL` steps, then run housekeeping again until it
|
||||
passes. Fix a `WARN` when the user's task covers it; otherwise
|
||||
report it. Then save the pass
|
||||
([save rule](#save-after-every-ingest-cycle-and-housekeeping-pass)).
|
||||
|
||||
### 17.1. Merge an update file
|
||||
|
||||
`wiki update` yields to the owner. When the packaged template has a
|
||||
newer version of a markdown file the owner may have edited, such as
|
||||
`AGENTS.md`, `wiki/index.md`, `wiki/log.md`, or `wiki/schema.md`,
|
||||
the owner's file stays as it is and the template is written beside
|
||||
it as `<stem>-update.md`. `AGENTS-update.md` belongs to
|
||||
`AGENTS.md`; `wiki/schema-update.md` belongs to `wiki/schema.md`.
|
||||
The update file is the new template text, as `wiki init` would
|
||||
write it. You decide how the two become one file:
|
||||
|
||||
1. Read both files. Compare them, for example with
|
||||
`git diff --no-index <file> <stem>-update.md`.
|
||||
2. Keep every owner edit: their wording, tags, sections, index
|
||||
entries, and log lines. The owner wins where the two disagree on
|
||||
content.
|
||||
3. Take what the template adds or corrects: new sections, new
|
||||
rules, new frontmatter fields, and fixed command names, flags,
|
||||
or paths. A tool contract (a command, a flag, a required field)
|
||||
comes from the template.
|
||||
4. For `wiki/index.md` and `wiki/log.md`, keep the owner's entries.
|
||||
Take only new structure from the template. Never replace the
|
||||
owner's entries with the template's.
|
||||
5. Set `version` to at least the update file's `version`, and
|
||||
`updated` to today. Keep the owner's `created`. A lower version
|
||||
brings the conflict back on the next `wiki update`.
|
||||
6. Delete the update file.
|
||||
7. Append `- YYYY-MM-DD - merged <stem>-update.md into <file>` to
|
||||
`wiki/log.md`, and bump that file.
|
||||
8. Run `fiona-assistant housekeeping` again. `merge` passes when no
|
||||
update file is left.
|
||||
|
||||
When you cannot tell whether an owner edit or a template change
|
||||
should win, ask the user. Do not delete an update file you have not
|
||||
merged unless the user says to drop it. When the target file is
|
||||
missing, ask the user whether to restore it from the update file.
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: llm-wiki-mod
|
||||
title: LLM Wiki Pattern
|
||||
version: 1.2.0
|
||||
version: 1.4.0
|
||||
updated: 2026-09-30
|
||||
type: concept
|
||||
tags: [wiki, schema]
|
||||
@@ -40,7 +40,8 @@ Three layers. The directory tree in
|
||||
|
||||
### 2.1. Raw sources
|
||||
|
||||
`raw/` is the archive. The agent reads it and does not edit it.
|
||||
`raw/` is the archive. The agent adds new sources there and never
|
||||
edits, moves, or deletes one already archived.
|
||||
`ingest/` is the drop zone for files that still need parsing.
|
||||
`personal/` holds user notes and is read-only, including the
|
||||
directory itself.
|
||||
@@ -76,6 +77,12 @@ should be checked before the next file.
|
||||
After the archive step, the source lives under `raw/` and is not
|
||||
edited again.
|
||||
|
||||
An ingest has two phases. A tool fetches the source, archives it
|
||||
under `raw/`, and converts it into a page marked `status: raw`.
|
||||
The agent then refines that page, updates the pages it touches,
|
||||
and marks it `status: refined`. The steps are section 16 of the
|
||||
[Fiona skill](./SKILL.md).
|
||||
|
||||
### 3.2. Query
|
||||
|
||||
Ask against the wiki. The agent reads the index, opens the pages
|
||||
@@ -107,26 +114,16 @@ dated bullet:
|
||||
Bump `version` and `updated` on `log.md` when appending. The log
|
||||
is the timeline of ingests, queries, and lint passes.
|
||||
|
||||
Git holds the before and after of each entry. Every ingest cycle
|
||||
and every housekeeping pass ends in one commit, so one source or
|
||||
one cleanup can be reviewed or undone on its own.
|
||||
|
||||
## 5. Page rules
|
||||
|
||||
These match [schema](../../../wiki/schema.md). Where this file and
|
||||
the schema disagree, the schema wins.
|
||||
|
||||
- File names are lowercase, with hyphens, and without spaces.
|
||||
- Every markdown file has frontmatter. `name` and `version` are required.
|
||||
- Every page under `wiki/` also requires `confidence`, `llm`,
|
||||
`contested`, and `contradictions`. How to set them is section 13
|
||||
of the [Fiona skill](./SKILL.md).
|
||||
- Optional fields are `title`, `created`, `updated`, `type`, `tags`, and `sources`.
|
||||
- `type` is `entity`, `concept`, `comparison`, `query`, `summary`, or `toc`.
|
||||
- Tags come from the taxonomy in the schema.
|
||||
- Bump `version` on every edit. Set `updated` to the edit date.
|
||||
- Patch for a clarification, minor for a new section, major for a breaking change.
|
||||
- Use a relative markdown link between pages.
|
||||
- A relative link resolves to a file. A wikilink matches a markdown file stem.
|
||||
- A new page is listed in the index. Each action is one line in the log.
|
||||
- Create a page when a concept is in two or more sources, or is central to one.
|
||||
- Split a page that grows past 200 lines.
|
||||
File names, frontmatter, tags, links, and when to create or split
|
||||
a page are in [schema](../../../wiki/schema.md). How to fill the
|
||||
frontmatter and the quality signals is section 13 of the
|
||||
[Fiona skill](./SKILL.md). This file does not repeat them.
|
||||
|
||||
## 6. Why this works
|
||||
|
||||
|
||||
@@ -1,10 +1,15 @@
|
||||
---
|
||||
name: index
|
||||
title: Wiki Index
|
||||
version: 1.0.0
|
||||
version: 1.1.0
|
||||
type: summary
|
||||
created: 2025-09-23
|
||||
updated: 2026-09-24
|
||||
updated: 2026-09-30
|
||||
confidence: trusted
|
||||
llm:
|
||||
- model: none
|
||||
contested: false
|
||||
contradictions: []
|
||||
---
|
||||
|
||||
# Wiki Index
|
||||
|
||||
@@ -1,13 +1,13 @@
|
||||
---
|
||||
name: log
|
||||
title: Wiki Log
|
||||
version: 1.2.10
|
||||
version: 2.0.0
|
||||
type: summary
|
||||
created: 2025-09-23
|
||||
updated: 2026-09-30
|
||||
created: DATE_PLACEHOLDER
|
||||
updated: DATE_PLACEHOLDER
|
||||
confidence: trusted
|
||||
llm:
|
||||
- model: grok-4.7
|
||||
- model: none
|
||||
contested: false
|
||||
contradictions: []
|
||||
---
|
||||
@@ -16,72 +16,4 @@ contradictions: []
|
||||
|
||||
Chronological tracking of all actions performed on the wiki.
|
||||
|
||||
- 2026-09-25 - Reconciled the frontmatter schemas: `name`/`version` required,
|
||||
`title` optional, `toc` added to allowed types (SPEC 6.2,
|
||||
project agent rule 10.1, schema.md v1.1.0); stamped frontmatter on
|
||||
`personal/README.md` and `raw/README.md`.
|
||||
- 2026-09-25 - Renumbered AGENTS.md rules into numbered sections (rule 8 is
|
||||
now rule 10.1); updated cross-references in SPEC.md, todo.md, run_sanity.py,
|
||||
and schema.md.
|
||||
- 2026-09-25 - Sectionized the llm-wiki AGENTS.md with numbered sections
|
||||
(1. Pre-requisites through 6. Boundaries) and a matching TOC; bumped it
|
||||
to v1.1.0.
|
||||
- 2026-09-25 - Added project agent rule 3.1 (rule references use the
|
||||
`project agent rule N.M` form, renamed from `fiona project rule`);
|
||||
updated cross-references in SPEC.md, todo.md, run_sanity.py, and
|
||||
schema.md to the new form.
|
||||
- 2026-09-26 - Updated the root AGENTS.md structure diagram to match reality
|
||||
(llm-wiki lives at `src/llm-wiki/`; `src/` also contains `wiki/`,
|
||||
`run_tests.py`, `run_sanity.py`, `settings_dev.json`, `utils.sh`,
|
||||
`install_packages.sh`); declared `wiki/schema.md` the final source of
|
||||
truth for the llm-wiki directory structure; added the missing
|
||||
`wiki/logs/` and `wiki/sources/` entries to the schema.md diagram
|
||||
(schema.md v1.2.0).
|
||||
- 2026-09-26 - Added the missing SPEC 7.16.3 reference to the
|
||||
fiona-settings framework todo item in `todo.md`.
|
||||
- 2026-09-27 - Restored the run_sanity progress heartbeat on the shared
|
||||
SanityRunner engine (SPEC 7.16.1): `run_all` gained optional
|
||||
`progress` and `heartbeat` callbacks plus INFO lifecycle logging;
|
||||
run_sanity passes stdout callbacks (DONE markers and WAITING lines)
|
||||
while wiki sanity output stays unchanged. Fixed the two ruff
|
||||
violations from the engine refactor (I001 in test_sanity_runner,
|
||||
PERF102 in wiki/sanity_manager); marked the todo.md heartbeat item
|
||||
done and updated SPEC 7.16.1 accordingly.
|
||||
- 2026-09-27 - Sped up the pytest sanity check (64s -> 14s with
|
||||
coverage): added session-scoped `pristine_wiki` and
|
||||
`pristine_check_results` fixtures plus a `minimal_wiki` fixture to
|
||||
src/tests/conftest.py, and rewired test_sanity_manager.py and the
|
||||
wiki-sanity tests in test_fiona_main.py onto them, so the full
|
||||
template is sanity-checked once per session instead of 13 times;
|
||||
also fixed the missing trailing newline in todo.md (MD047).
|
||||
- 2026-09-27 - Added live per-check progress bars to run_sanity
|
||||
(SPEC 7.16.2): interactive mode renders a block of progress bars
|
||||
in place (ANSI cursor-up and line-clear), non-interactive mode
|
||||
(--non-interactive or pipe) prints plain status lines every
|
||||
`interval` seconds. Progress is set in settings_dev.json's
|
||||
`progress` section with `interval` and `expected-seconds` keys.
|
||||
- 2026-09-29 - Retargeted spec citations in this log, `todo.md`, and
|
||||
the code to the current section numbers.
|
||||
- 2026-09-29 - Moved the template to `src/fiona/data/llm_wiki/` as
|
||||
package data (no importable `llm-wiki` package). Fiona skill v1.2.1.
|
||||
- 2026-09-29 - Restored the development lifecycle as project agent
|
||||
rule 2.1 (AGENTS.md v1.4.1) and linked the python-tdd skill.
|
||||
- 2026-09-29 - PYC001 allows a module-level if/else import before
|
||||
the first function or class, for OS selection (SPEC 6.4.2,
|
||||
v0.40.0).
|
||||
- 2026-09-29 - llm-wiki AGENTS.md (v1.2.0) is a short entry point
|
||||
that loads the Fiona skill when it is not already in the system
|
||||
prompt. Fiona skill v1.2.0 documents the fiona-assistant CLI and
|
||||
loads llm-wiki-mod into context when that file is not already
|
||||
loaded. Root AGENTS.md v1.3.3 points wiki tasks at that skill.
|
||||
- 2026-09-29 - Aligned `utils/skills/fiona/llm-wiki-mod.md` (v1.1.0)
|
||||
to the schema: canonical frontmatter, the raw / wiki / schema
|
||||
layers, and the index, log, and page rules. Commands stay in
|
||||
the Fiona skill.
|
||||
- 2026-09-30 - Quality signals are required on pages under `wiki/`:
|
||||
`confidence`, `llm` (`model`, and `reasoning` when reported),
|
||||
`contested`, and `contradictions`. Fiona skill v1.3.0 teaches
|
||||
how to set them. fmlint still enforces `name` and `version` only
|
||||
(SPEC 6.2.3, schema v1.3.0).
|
||||
- 2026-09-30 - Clarified that a markdown link is `[text](url)` in the
|
||||
schema conventions (schema v1.3.2).
|
||||
- DATE_PLACEHOLDER - Initialized the llm-wiki.
|
||||
|
||||
@@ -1,14 +1,14 @@
|
||||
---
|
||||
name: llm-wiki-schema
|
||||
title: LLM Wiki Schema
|
||||
version: 1.3.2
|
||||
version: 1.6.0
|
||||
created: 2025-09-18
|
||||
updated: 2026-09-30
|
||||
type: summary
|
||||
tags: [wiki, schema]
|
||||
confidence: trusted
|
||||
llm:
|
||||
- model: grok-4.7
|
||||
- model: claude-opus-5.5
|
||||
contested: false
|
||||
contradictions: []
|
||||
---
|
||||
@@ -17,7 +17,8 @@ contradictions: []
|
||||
|
||||
## Domain
|
||||
|
||||
Personal knowledge base and inventory management.
|
||||
A personal knowledge base. Replace this line with the wiki's subject
|
||||
and extend the tag taxonomy to match it.
|
||||
|
||||
## Conventions
|
||||
|
||||
@@ -25,11 +26,13 @@ Personal knowledge base and inventory management.
|
||||
- Every page starts with YAML frontmatter. Required on every file:
|
||||
`name`, `version`. Required on pages under `wiki/`: `confidence`,
|
||||
`llm`, `contested`, `contradictions`. Optional: `title`, `created`,
|
||||
`updated`, `type`, `tags`, `sources`.
|
||||
`updated`, `type`, `tags`, `sources`. Ingested pages also carry
|
||||
`status`, `source_meta`, and the `ingest` provenance map.
|
||||
- Use markdown links (`[text](url)`) to link between pages (minimum 2 outbound links per page).
|
||||
- When updating a page, always bump the `updated` date.
|
||||
- When updating a page, bump `version` and set `updated` to the edit date.
|
||||
- Every new page must be added to `index.md` under the correct section.
|
||||
- Every action must be appended to `log.md`.
|
||||
- Every action must be appended to `log.md`. In the first edit of a
|
||||
new year, move the previous year's entries to `logs/log-YYYY.md`.
|
||||
|
||||
## Frontmatter
|
||||
|
||||
@@ -37,9 +40,8 @@ Personal knowledge base and inventory management.
|
||||
`wiki/` also requires the quality signals `confidence`, `llm`,
|
||||
`contested`, and `contradictions`. How to set them is section 13 of
|
||||
the [Fiona skill](../utils/skills/fiona/SKILL.md). All other fields
|
||||
are optional. This is the single canonical frontmatter schema,
|
||||
identical to project agent rule 10.1 (see SPEC 6.2). fmlint enforces
|
||||
`name` and `version` only.
|
||||
are optional. This is the single canonical frontmatter schema.
|
||||
fmlint enforces `name` and `version` only.
|
||||
|
||||
```yaml
|
||||
---
|
||||
@@ -58,13 +60,27 @@ llm:
|
||||
- reasoning: high # when the model reports a level
|
||||
contested: true
|
||||
contradictions: [other-page-slug]
|
||||
# written by wiki ingest (Fiona skill section 16):
|
||||
status: raw | refined
|
||||
source_meta: {author: Name} # metadata read from the source
|
||||
ingest: # provenance; every key always present
|
||||
origin: https://host/path # URL or file path of the source
|
||||
origin_kind: url | file
|
||||
final_url: null # URL after redirects
|
||||
fetched: YYYY-MM-DDTHH:MM:SSZ
|
||||
media_type: text/html
|
||||
size_bytes: 0
|
||||
sha256: <64 lowercase hex> # of the raw copy; never hand-edited
|
||||
raw_reused: false
|
||||
converter: html # converter name, or agent
|
||||
conversion: complete | partial
|
||||
warnings: []
|
||||
tool: fiona-assistant <version>
|
||||
---
|
||||
```
|
||||
|
||||
## Tag Taxonomy
|
||||
|
||||
- inventory
|
||||
- box
|
||||
- wiki
|
||||
- schema
|
||||
|
||||
@@ -73,7 +89,7 @@ contradictions: [other-page-slug]
|
||||
- Create a page when an entity/concept appears in 2+ sources OR is central to
|
||||
one source.
|
||||
- Split pages over 200 lines.
|
||||
- Archive superseded pages to `_archive/`.
|
||||
- Move superseded pages to `wiki/_archive/` and fix every inbound link.
|
||||
|
||||
## Directory Structure
|
||||
|
||||
@@ -89,7 +105,8 @@ llm-wiki/
|
||||
│ ├── articles/ # Web articles, clippings
|
||||
│ ├── papers/ # PDFs, arXiv papers
|
||||
│ ├── transcripts/ # Meeting notes, interviews
|
||||
│ └── assets/ # Images, diagrams referenced by sources
|
||||
│ ├── assets/ # Images, diagrams referenced by sources
|
||||
│ └── other/ # Ingested files no converter handles
|
||||
├── utils/
|
||||
│ ├── personas/ # Agent personas configurations
|
||||
│ ├── scripts/ # Reusable utility scripts
|
||||
@@ -104,12 +121,13 @@ llm-wiki/
|
||||
│ ├── comparisons/ # Layer 2: Side-by-side analyses
|
||||
│ ├── queries/ # Layer 2: Filed query results worth keeping
|
||||
│ ├── sources/ # Layer 2: Source material backing wiki pages
|
||||
│ └── logs/ # Archived log files rotated out of log.md
|
||||
│ ├── logs/ # Archived log files rotated out of log.md
|
||||
│ └── _archive/ # Superseded pages, created when first needed
|
||||
└── table_of_contents.md # Auto-generated navigation index for quick lookup
|
||||
```
|
||||
|
||||
- **Layer 1 — Raw Sources:** `raw/` at the wiki root. The agent reads but never
|
||||
modifies these.
|
||||
- **Layer 1 — Raw Sources:** `raw/` at the wiki root. The agent adds new
|
||||
sources and never modifies existing ones.
|
||||
- **Layer 2 — The Wiki:** Agent-owned markdown files. Created, updated, and
|
||||
cross-referenced by the agent.
|
||||
- **Layer 3 — The Schema:** `SCHEMA.md` defines structure, conventions, and tag taxonomy.
|
||||
- **Layer 3 — The Schema:** `wiki/schema.md` (this file) defines structure, conventions, and tag taxonomy.
|
||||
|
||||
@@ -74,7 +74,7 @@ class GitTool:
|
||||
# Check for modified/staged files
|
||||
if self.repo.is_dirty():
|
||||
return False
|
||||
|
||||
|
||||
# Check for untracked files
|
||||
untracked = self.repo.untracked_files
|
||||
return len(untracked) == 0
|
||||
@@ -171,7 +171,7 @@ class GitTool:
|
||||
tag for tag in self.repo.tags
|
||||
if tag.name.endswith(f"_{tag_name}") or tag.name == tag_name
|
||||
]
|
||||
|
||||
|
||||
if matching_tags:
|
||||
# Sort by commit date descending and take the most recent
|
||||
matching_tags.sort(
|
||||
@@ -179,7 +179,7 @@ class GitTool:
|
||||
reverse=True
|
||||
)
|
||||
tag_ref = matching_tags[0]
|
||||
|
||||
|
||||
if tag_ref is None:
|
||||
raise git.GitCommandError(
|
||||
f"Tag '{tag_name}' does not exist."
|
||||
@@ -190,7 +190,7 @@ class GitTool:
|
||||
|
||||
# Restore the tag's tree into the working directory and index
|
||||
self.repo.git.checkout(tag_ref.commit, "--", ".")
|
||||
|
||||
|
||||
# Create a new commit with the restored state
|
||||
new_commit = self.repo.index.commit(restore_message)
|
||||
|
||||
@@ -289,23 +289,23 @@ class GitTool:
|
||||
git.InvalidGitRepositoryError: If git initialization fails.
|
||||
"""
|
||||
repo_path = pathlib.Path(repo_path).resolve()
|
||||
|
||||
|
||||
# Initialize the repo
|
||||
repo = GitTool.init_repo(repo_path)
|
||||
|
||||
# CURSOR: 2026-09-30 - seed .gitignore from the repository ignore file.
|
||||
|
||||
# AI/LLM: 2026-09-30 - seed .gitignore from the repository ignore file.
|
||||
ensure_wiki_gitignore(repo_path)
|
||||
|
||||
# Add all files and make initial commit
|
||||
repo.git.add("--all")
|
||||
repo.index.commit(initial_message)
|
||||
|
||||
|
||||
return repo
|
||||
|
||||
|
||||
def main(): # pragma: no cover
|
||||
"""Command-line interface for the GitTool.
|
||||
|
||||
|
||||
Note: CLI is tested via integration tests through fiona-assistant git commands.
|
||||
"""
|
||||
parser = argparse.ArgumentParser(
|
||||
|
||||
@@ -0,0 +1,340 @@
|
||||
"""Wiki housekeeping routine (SPEC 4.15, 7.26).
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - one call for LLM wiki maintenance.
|
||||
|
||||
`fiona-assistant housekeeping` runs the maintenance steps in a fixed
|
||||
order and reports, per step, a status (`PASS`, `WARN`, `FAIL`), a
|
||||
summary, detail lines, and the next actions for the LLM. The routine
|
||||
gathers what needs work; it writes only `wiki_graph.html`.
|
||||
|
||||
Steps, in order (`STEP_NAMES`):
|
||||
|
||||
- `check-update`: core files behind the packaged template (read-only).
|
||||
- `merge`: `*-update.md` files that `wiki update` left for a merge.
|
||||
- `ingest`: pages under `wiki/` still at `status: raw`.
|
||||
- `sanity`: every `wiki sanity` check.
|
||||
- `graph`: regenerate `wiki_graph.html` and list orphan pages.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import contextlib
|
||||
import io
|
||||
import json
|
||||
import os
|
||||
import sys
|
||||
import tempfile
|
||||
from collections.abc import Callable
|
||||
from pathlib import Path
|
||||
|
||||
from fiona.librarian.md_frontmatter import FrontmatterError, parse_frontmatter
|
||||
from fiona.wiki.graph_generator import wiki_graph_main
|
||||
from fiona.wiki.sanity_manager import SETTINGS_FILE, run_wiki_checks
|
||||
from fiona.wiki.update_manager import UPDATE_SUFFIX, check_wiki_updates
|
||||
|
||||
STEP_NAMES = ("check-update", "merge", "ingest", "sanity", "graph")
|
||||
GRAPH_FILE = "wiki_graph.html"
|
||||
UPDATE_FILE_SUFFIX = f"{UPDATE_SUFFIX}.md"
|
||||
# AI/LLM: read-only zones sit at the wiki root; .git is skipped anywhere
|
||||
ROOT_SKIP_DIRS = frozenset({"personal", "raw"})
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Helpers
|
||||
# =============================================================================
|
||||
|
||||
def _step(name: str, status: str, summary: str, details: list[str] | None = None,
|
||||
next_steps: list[str] | None = None) -> dict:
|
||||
"""Build one step result.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - shared step shape (SPEC 4.15).
|
||||
"""
|
||||
return {
|
||||
"name": name,
|
||||
"status": status,
|
||||
"summary": summary,
|
||||
"details": details or [],
|
||||
"next": next_steps or [],
|
||||
}
|
||||
|
||||
|
||||
def _relative(path: str | Path, wiki_root: Path) -> str:
|
||||
"""Return a path relative to the wiki root, with `/` separators.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - report paths from the wiki root.
|
||||
"""
|
||||
return Path(os.path.relpath(path, wiki_root)).as_posix()
|
||||
|
||||
|
||||
def _frontmatter(path: Path) -> dict:
|
||||
"""Return a page's frontmatter, or an empty dict when it cannot be read.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - sanity reports broken YAML itself.
|
||||
"""
|
||||
try:
|
||||
frontmatter = parse_frontmatter(path)
|
||||
except (FrontmatterError, UnicodeDecodeError):
|
||||
return {}
|
||||
return frontmatter if isinstance(frontmatter, dict) else {}
|
||||
|
||||
|
||||
def _markdown_files(wiki_root: Path, subdir: str = "") -> list[Path]:
|
||||
"""List markdown files outside read-only zones and `.git`, sorted.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - pruned walk for the merge and ingest steps.
|
||||
|
||||
Args:
|
||||
wiki_root: Root path of the wiki.
|
||||
subdir: Optional directory, relative to the root, to walk instead.
|
||||
|
||||
Returns:
|
||||
list[Path]: Markdown files found.
|
||||
"""
|
||||
start = wiki_root / subdir
|
||||
found = []
|
||||
for current, dirs, files in os.walk(start):
|
||||
at_root = Path(current) == wiki_root
|
||||
dirs[:] = [
|
||||
name for name in dirs
|
||||
if name != ".git" and not (at_root and name in ROOT_SKIP_DIRS)
|
||||
]
|
||||
found.extend(Path(current) / name for name in files if name.endswith(".md"))
|
||||
return sorted(found)
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Steps
|
||||
# =============================================================================
|
||||
|
||||
def check_update_step(wiki_root: Path) -> dict:
|
||||
"""Report core files behind the template without writing (SPEC 7.26.2).
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - read-only wiki check-update.
|
||||
"""
|
||||
summary = check_wiki_updates(wiki_root)
|
||||
details = [f"update: {_relative(r.file_path, wiki_root)}" for r in summary.files_to_update]
|
||||
details += [
|
||||
f"conflict: {_relative(r.file_path, wiki_root)} -> {_relative(r.update_path, wiki_root)}"
|
||||
for r in summary.conflicts
|
||||
]
|
||||
details += [f"add: {path.as_posix()}" for path in summary.files_to_add]
|
||||
text = (
|
||||
f"{len(summary.files_to_update)} update(s), {len(summary.conflicts)} conflict(s), "
|
||||
f"{len(summary.files_to_add)} addition(s)"
|
||||
)
|
||||
if not details:
|
||||
return _step("check-update", "PASS", text)
|
||||
return _step("check-update", "WARN", text, details, [
|
||||
"Ask the user, then run fiona-assistant wiki update --dry-run and wiki update --yes."
|
||||
])
|
||||
|
||||
|
||||
def merge_step(wiki_root: Path) -> dict:
|
||||
"""List update files that wait for an LLM merge (SPEC 7.26.3).
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - pending *-update.md merges.
|
||||
"""
|
||||
details, actions = [], []
|
||||
for update_file in _markdown_files(wiki_root):
|
||||
if not update_file.name.endswith(UPDATE_FILE_SUFFIX):
|
||||
continue
|
||||
target = update_file.with_name(
|
||||
update_file.name[: -len(UPDATE_FILE_SUFFIX)] + ".md"
|
||||
)
|
||||
update_rel = _relative(update_file, wiki_root)
|
||||
target_rel = _relative(target, wiki_root)
|
||||
missing = "" if target.exists() else " (target missing)"
|
||||
details.append(f"{update_rel} -> {target_rel}{missing}")
|
||||
version = _frontmatter(update_file).get("version") or "the template version"
|
||||
actions.append(
|
||||
f"Merge {update_rel} into {target_rel}: keep the owner's edits, "
|
||||
f"take the template changes, set version to at least {version}, "
|
||||
f"then delete {update_rel}."
|
||||
)
|
||||
text = f"{len(details)} update file(s) wait for a merge"
|
||||
return _step("merge", "FAIL" if details else "PASS", text, details, actions)
|
||||
|
||||
|
||||
def ingest_step(wiki_root: Path) -> dict:
|
||||
"""List pages under wiki/ still at `status: raw` (SPEC 7.26.4).
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - pages waiting for a refine.
|
||||
"""
|
||||
pages = [
|
||||
_relative(page, wiki_root)
|
||||
for page in _markdown_files(wiki_root, "wiki")
|
||||
if _frontmatter(page).get("status") == "raw"
|
||||
]
|
||||
text = f"{len(pages)} raw page(s)"
|
||||
if not pages:
|
||||
return _step("ingest", "PASS", text)
|
||||
return _step("ingest", "WARN", text, pages,
|
||||
["Refine each raw page, then set status: refined."])
|
||||
|
||||
|
||||
def sanity_step(wiki_root: Path) -> dict:
|
||||
"""Run every wiki sanity check without the progress display (SPEC 7.26.5).
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - failing check reports as details.
|
||||
"""
|
||||
results = run_wiki_checks(wiki_root)
|
||||
failing = {name: check for name, check in results["checks"].items() if check["result"]}
|
||||
text = f"{results['total_violations']} violation(s) in {len(failing)} check(s)"
|
||||
if not failing:
|
||||
return _step("sanity", "PASS", text)
|
||||
details = [
|
||||
f"{name}: {line.strip().removeprefix('- ')}"
|
||||
for name, check in failing.items()
|
||||
for line in check["stdout"].splitlines()
|
||||
if line.strip()
|
||||
]
|
||||
return _step("sanity", "FAIL", text, details,
|
||||
["Fix the violations, then run fiona-assistant housekeeping again."])
|
||||
|
||||
|
||||
def graph_step(wiki_root: Path) -> dict:
|
||||
"""Write wiki_graph.html at the wiki root and list orphans (SPEC 7.26.6).
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - graph plus orphan pages under wiki/.
|
||||
"""
|
||||
captured = io.StringIO()
|
||||
with tempfile.TemporaryDirectory() as temp_dir:
|
||||
graph_json = Path(temp_dir) / "graph.json"
|
||||
with contextlib.redirect_stdout(captured), contextlib.redirect_stderr(captured):
|
||||
code = wiki_graph_main(str(wiki_root), output=str(graph_json), format_type="json")
|
||||
if code == 0:
|
||||
code = wiki_graph_main(str(wiki_root), output=str(wiki_root / GRAPH_FILE))
|
||||
if code != 0:
|
||||
error = captured.getvalue().strip() or f"wiki graph exited {code}"
|
||||
return _step("graph", "FAIL", f"could not write {GRAPH_FILE}",
|
||||
error.splitlines())
|
||||
data = json.loads(graph_json.read_text(encoding="utf-8"))
|
||||
|
||||
orphans = sorted(
|
||||
rel for rel in (_relative(path, wiki_root) for path in data["orphans"])
|
||||
if rel.startswith("wiki/") and not rel.endswith(UPDATE_FILE_SUFFIX)
|
||||
)
|
||||
text = (
|
||||
f"wrote {GRAPH_FILE} ({data['metadata']['file_count']} nodes, "
|
||||
f"{len(data['edges'])} edges)"
|
||||
)
|
||||
if not orphans:
|
||||
return _step("graph", "PASS", text)
|
||||
return _step("graph", "WARN", text, [f"orphan: {rel}" for rel in orphans],
|
||||
["Link each orphan page from a related page or from wiki/index.md."])
|
||||
|
||||
|
||||
STEPS: tuple[Callable[[Path], dict], ...] = (
|
||||
check_update_step,
|
||||
merge_step,
|
||||
ingest_step,
|
||||
sanity_step,
|
||||
graph_step,
|
||||
)
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Routine and Report
|
||||
# =============================================================================
|
||||
|
||||
def run_housekeeping(directory: str | Path = ".") -> dict:
|
||||
"""Run every housekeeping step over a wiki (SPEC 7.26.1).
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - every step runs, even after a FAIL.
|
||||
|
||||
Args:
|
||||
directory: The wiki directory. Defaults to the current directory.
|
||||
|
||||
Returns:
|
||||
dict: `target` (resolved path), `steps` (one result per step,
|
||||
in `STEP_NAMES` order), and `passed` (no step is `FAIL`).
|
||||
|
||||
Raises:
|
||||
FileNotFoundError: If the directory does not exist.
|
||||
NotADirectoryError: If the directory is not an llm-wiki directory.
|
||||
"""
|
||||
wiki_root = Path(directory).resolve()
|
||||
if not wiki_root.exists():
|
||||
raise FileNotFoundError(f"Directory not found: {directory}")
|
||||
if not (wiki_root / SETTINGS_FILE).exists():
|
||||
raise NotADirectoryError(f"Directory '{directory}' is not an llm-wiki directory")
|
||||
|
||||
steps = [step(wiki_root) for step in STEPS]
|
||||
return {
|
||||
"target": wiki_root,
|
||||
"steps": steps,
|
||||
"passed": all(step["status"] != "FAIL" for step in steps),
|
||||
}
|
||||
|
||||
|
||||
def format_housekeeping_report(results: dict) -> str:
|
||||
"""Format housekeeping results for humans and LLMs (SPEC 4.15).
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - step blocks, next steps, verdict.
|
||||
|
||||
Args:
|
||||
results: The dict returned by run_housekeeping.
|
||||
|
||||
Returns:
|
||||
str: The report text.
|
||||
"""
|
||||
lines = ["Housekeeping Report", f"TARGET: {results['target']}", ""]
|
||||
for step in results["steps"]:
|
||||
lines.append(f"[{step['status']}] {step['name']}: {step['summary']}")
|
||||
lines.extend(f" - {detail}" for detail in step["details"])
|
||||
|
||||
actions = list(dict.fromkeys(a for step in results["steps"] for a in step["next"]))
|
||||
if actions:
|
||||
lines.extend(["", "Next steps:"])
|
||||
lines.extend(f" - {action}" for action in actions)
|
||||
|
||||
failing = [step["name"] for step in results["steps"] if step["status"] == "FAIL"]
|
||||
lines.append("")
|
||||
if failing:
|
||||
lines.append(
|
||||
f"HOUSEKEEPING FAILED - {len(failing)} step(s) need attention: "
|
||||
f"{', '.join(failing)}"
|
||||
)
|
||||
else:
|
||||
lines.append("HOUSEKEEPING PASSED")
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
def housekeeping_main(directory: str = ".", json_output: bool = False) -> int:
|
||||
"""Main function for the 'housekeeping' CLI command.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - exit 1 on any FAIL step.
|
||||
|
||||
Args:
|
||||
directory: Wiki directory (default: current directory).
|
||||
json_output: If True, print the results as one JSON object.
|
||||
|
||||
Returns:
|
||||
int: 0 when no step is `FAIL`, 1 otherwise or on an invalid wiki.
|
||||
"""
|
||||
try:
|
||||
results = run_housekeeping(directory)
|
||||
except (FileNotFoundError, NotADirectoryError) as error:
|
||||
print(f"Error: {error}", file=sys.stderr)
|
||||
return 1
|
||||
|
||||
if json_output:
|
||||
print(json.dumps({**results, "target": str(results["target"])}, indent=2))
|
||||
else:
|
||||
print(format_housekeeping_report(results))
|
||||
return 0 if results["passed"] else 1
|
||||
|
||||
|
||||
__all__ = [
|
||||
"GRAPH_FILE",
|
||||
"STEPS",
|
||||
"STEP_NAMES",
|
||||
"check_update_step",
|
||||
"format_housekeeping_report",
|
||||
"graph_step",
|
||||
"housekeeping_main",
|
||||
"ingest_step",
|
||||
"merge_step",
|
||||
"run_housekeeping",
|
||||
"sanity_step",
|
||||
]
|
||||
@@ -1,6 +1,6 @@
|
||||
"""Gitignore patterns shared by wiki init and wiki update.
|
||||
|
||||
Generated by CURSOR: 2026-09-30 - seed wiki ignores from the repository file.
|
||||
Generated by AI/LLM: 2026-09-30 - seed wiki ignores from the repository file.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
@@ -16,7 +16,7 @@ _PERSONAL_PATTERN = "personal/"
|
||||
def gitignore_patterns_from_text(text: str) -> list[str]:
|
||||
"""Return ignore patterns from gitignore text.
|
||||
|
||||
Generated by CURSOR: 2026-09-30 - drop blanks and comments.
|
||||
Generated by AI/LLM: 2026-09-30 - drop blanks and comments.
|
||||
|
||||
Args:
|
||||
text: Contents of a .gitignore file.
|
||||
@@ -35,7 +35,7 @@ def gitignore_patterns_from_text(text: str) -> list[str]:
|
||||
def path_is_ignored(relpath: str, patterns: list[str]) -> bool:
|
||||
"""Return whether a relative posix path matches any gitignore pattern.
|
||||
|
||||
Generated by CURSOR: 2026-09-30 - match unanchored names and directory prefixes.
|
||||
Generated by AI/LLM: 2026-09-30 - match unanchored names and directory prefixes.
|
||||
|
||||
A pattern with no slash matches any path segment. A trailing slash matches
|
||||
a directory and everything under it. ``*`` does not cross a directory
|
||||
@@ -66,7 +66,7 @@ def _pattern_matches(relpath: str, pattern: str) -> bool:
|
||||
def repository_gitignore_path() -> pathlib.Path | None:
|
||||
"""Find the fiona-assistant repository .gitignore, if this tree has one.
|
||||
|
||||
Generated by CURSOR: 2026-09-30 - prefer the source checkout over package data.
|
||||
Generated by AI/LLM: 2026-09-30 - prefer the source checkout over package data.
|
||||
|
||||
Returns:
|
||||
Path to the repository .gitignore, or None when this install is not
|
||||
@@ -87,7 +87,7 @@ def repository_gitignore_path() -> pathlib.Path | None:
|
||||
def packaged_gitignore_path() -> pathlib.Path | None:
|
||||
"""Return the packaged copy of the repository .gitignore, if present.
|
||||
|
||||
Generated by CURSOR: 2026-09-30 - fallback for an installed wheel.
|
||||
Generated by AI/LLM: 2026-09-30 - fallback for an installed wheel.
|
||||
|
||||
Returns:
|
||||
Path to ``fiona/data/default.gitignore``, or None when it is absent.
|
||||
@@ -102,7 +102,7 @@ def packaged_gitignore_path() -> pathlib.Path | None:
|
||||
def repository_gitignore_text() -> str:
|
||||
"""Load the ignore file that seeds a wiki, as LF text.
|
||||
|
||||
Generated by CURSOR: 2026-09-30 - repository file, then packaged copy.
|
||||
Generated by AI/LLM: 2026-09-30 - repository file, then packaged copy.
|
||||
|
||||
Returns:
|
||||
Ignore file text ending in a newline.
|
||||
@@ -122,7 +122,7 @@ def repository_gitignore_text() -> str:
|
||||
def wiki_gitignore_patterns() -> list[str]:
|
||||
"""Return patterns written into a wiki, repository set plus personal/.
|
||||
|
||||
Generated by CURSOR: 2026-09-30 - personal/ stays untracked after init.
|
||||
Generated by AI/LLM: 2026-09-30 - personal/ stays untracked after init.
|
||||
|
||||
Returns:
|
||||
Ignore patterns in write order.
|
||||
@@ -136,7 +136,7 @@ def wiki_gitignore_patterns() -> list[str]:
|
||||
def wiki_gitignore_text() -> str:
|
||||
"""Return the full .gitignore body for a wiki that does not have one yet.
|
||||
|
||||
Generated by CURSOR: 2026-09-30 - repository text plus personal/ when missing.
|
||||
Generated by AI/LLM: 2026-09-30 - repository text plus personal/ when missing.
|
||||
|
||||
Returns:
|
||||
File body ending in a newline.
|
||||
@@ -150,7 +150,7 @@ def wiki_gitignore_text() -> str:
|
||||
def ensure_wiki_gitignore(directory: pathlib.Path) -> None:
|
||||
"""Create .gitignore or append patterns that are not already listed.
|
||||
|
||||
Generated by CURSOR: 2026-09-30 - put or append the repository ignores.
|
||||
Generated by AI/LLM: 2026-09-30 - put or append the repository ignores.
|
||||
|
||||
Args:
|
||||
directory: Wiki root that should contain .gitignore.
|
||||
|
||||
@@ -8,6 +8,8 @@ The module handles:
|
||||
- Comparing wiki core files against template versions
|
||||
- Identifying files that need updates
|
||||
- Special handling for settings files (preserving user customizations)
|
||||
- Yielding to the owner's markdown: a newer template is written beside
|
||||
the file as `<stem>-update.md` for the LLM to merge (SPEC 7.2.11)
|
||||
- Presenting update summaries to users
|
||||
"""
|
||||
|
||||
@@ -49,6 +51,8 @@ class FileComparisonResult:
|
||||
is_new_file: bool = False
|
||||
is_settings_file: bool = False
|
||||
is_locally_modified: bool = False
|
||||
is_conflict: bool = False
|
||||
update_path: Path | None = None
|
||||
|
||||
def __post_init__(self):
|
||||
"""Validate the comparison result."""
|
||||
@@ -64,6 +68,7 @@ class UpdateSummary:
|
||||
files_to_add: list[Path] = field(default_factory=list)
|
||||
directories_to_add: list[Path] = field(default_factory=list)
|
||||
files_skipped: list[FileComparisonResult] = field(default_factory=list)
|
||||
conflicts: list[FileComparisonResult] = field(default_factory=list)
|
||||
settings_file: Path | None = None
|
||||
|
||||
@property
|
||||
@@ -71,12 +76,13 @@ class UpdateSummary:
|
||||
"""Check if there are any updates needed."""
|
||||
return bool(
|
||||
self.files_to_update or self.files_to_add or self.directories_to_add
|
||||
or self.conflicts
|
||||
)
|
||||
|
||||
@property
|
||||
def total_files(self) -> int:
|
||||
"""Get the total number of files to update/add."""
|
||||
return len(self.files_to_update) + len(self.files_to_add)
|
||||
"""Get the total number of files to update, add, or write as conflicts."""
|
||||
return len(self.files_to_update) + len(self.files_to_add) + len(self.conflicts)
|
||||
|
||||
|
||||
# =============================================================================
|
||||
@@ -108,6 +114,9 @@ SETTINGS_FILE = "fiona-settings.json"
|
||||
# Read-only zones that should never be modified
|
||||
READ_ONLY_ZONES = ["personal/", "raw/"]
|
||||
|
||||
# CURSOR: stem suffix of the file that carries a newer template (SPEC 7.2.11.1)
|
||||
UPDATE_SUFFIX = "-update"
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Helper Functions
|
||||
@@ -124,6 +133,20 @@ def get_llm_wiki_source_path() -> Path:
|
||||
return llm_wiki_template()
|
||||
|
||||
|
||||
def update_file_path(file_path: Path) -> Path:
|
||||
"""Return the sibling update file for a core file (SPEC 7.2.11.1).
|
||||
|
||||
Generated by CURSOR: 2026-09-30 - `AGENTS.md` gives `AGENTS-update.md`.
|
||||
|
||||
Args:
|
||||
file_path: The owner's core file.
|
||||
|
||||
Returns:
|
||||
Path: `<stem>-update<suffix>` in the same directory.
|
||||
"""
|
||||
return file_path.with_name(f"{file_path.stem}{UPDATE_SUFFIX}{file_path.suffix}")
|
||||
|
||||
|
||||
def calculate_sha256(file_path: Path) -> str:
|
||||
"""Calculate SHA256 hash of a file.
|
||||
|
||||
@@ -228,6 +251,26 @@ def is_version_newer(candidate: str, baseline: str) -> bool:
|
||||
return candidate > baseline
|
||||
|
||||
|
||||
def template_sha256(template_path: Path) -> str:
|
||||
"""Hash the text wiki init would write for a template file (SPEC 7.2.12).
|
||||
|
||||
Generated by CURSOR: 2026-09-30 - DATE_PLACEHOLDER expanded, endings kept.
|
||||
|
||||
Args:
|
||||
template_path: Path to the template file.
|
||||
|
||||
Returns:
|
||||
str: SHA-256 hex digest of the expanded UTF-8 text, or of the raw
|
||||
bytes when the file is not UTF-8 text.
|
||||
"""
|
||||
try:
|
||||
with open(template_path, encoding="utf-8", newline="") as handle:
|
||||
text = replace_date_placeholders(handle.read())
|
||||
except UnicodeDecodeError:
|
||||
return calculate_sha256(template_path)
|
||||
return hashlib.sha256(text.encode("utf-8")).hexdigest()
|
||||
|
||||
|
||||
def _content_differs(wiki_file: Path, template_file: Path) -> bool:
|
||||
"""Compare a wiki file against its template, placeholder-expanded.
|
||||
|
||||
@@ -256,11 +299,16 @@ def _content_differs(wiki_file: Path, template_file: Path) -> bool:
|
||||
def compare_md_file(file_path: Path, template_path: Path) -> FileComparisonResult:
|
||||
"""Compare a markdown file against its template version using frontmatter.
|
||||
|
||||
Classification (SPEC 7.2):
|
||||
- template version newer -> needs update
|
||||
Classification (SPEC 7.2.1). An existing markdown file is never
|
||||
overwritten:
|
||||
- template version newer -> conflict, the template goes to the
|
||||
`<stem>-update.md` sibling (SPEC 7.2.11)
|
||||
- wiki version newer or content diverged at the same version -> locally
|
||||
modified (skipped and reported by the update run)
|
||||
- files without version frontmatter fall back to a content comparison
|
||||
- files without version frontmatter compare SHA-256 and are a conflict
|
||||
when the hashes differ (SPEC 7.2.12)
|
||||
|
||||
Modified by CURSOR: 2026-09-30 - SHA-256 compare when a version is missing.
|
||||
|
||||
Args:
|
||||
file_path: Path to the current wiki file.
|
||||
@@ -281,15 +329,17 @@ def compare_md_file(file_path: Path, template_path: Path) -> FileComparisonResul
|
||||
)
|
||||
|
||||
if current_version is None or template_version is None:
|
||||
result.needs_update = _content_differs(file_path, template_path)
|
||||
return result
|
||||
|
||||
if is_version_newer(template_version, current_version):
|
||||
result.needs_update = True
|
||||
result.current_hash = calculate_sha256(file_path)
|
||||
result.template_hash = template_sha256(template_path)
|
||||
result.is_conflict = result.current_hash != result.template_hash
|
||||
elif is_version_newer(template_version, current_version):
|
||||
result.is_conflict = True
|
||||
elif is_version_newer(current_version, template_version) or _content_differs(
|
||||
file_path, template_path
|
||||
):
|
||||
result.is_locally_modified = True
|
||||
if result.is_conflict:
|
||||
result.update_path = update_file_path(file_path)
|
||||
return result
|
||||
|
||||
|
||||
@@ -298,6 +348,8 @@ def compare_non_md_file(file_path: Path, template_path: Path) -> FileComparisonR
|
||||
|
||||
This is used for files without version tagging (e.g., JSON files).
|
||||
|
||||
Modified by CURSOR: 2026-09-30 - template side hashes init's text (7.2.12).
|
||||
|
||||
Args:
|
||||
file_path: Path to the current wiki file.
|
||||
template_path: Path to the template file in the package.
|
||||
@@ -310,7 +362,7 @@ def compare_non_md_file(file_path: Path, template_path: Path) -> FileComparisonR
|
||||
is_core_file=True,
|
||||
has_template_version=False,
|
||||
current_hash=calculate_sha256(file_path),
|
||||
template_hash=calculate_sha256(template_path),
|
||||
template_hash=template_sha256(template_path),
|
||||
)
|
||||
result.needs_update = result.current_hash != result.template_hash
|
||||
return result
|
||||
@@ -384,12 +436,26 @@ def _excluded_from_update(relative: Path, wiki_root: Path, patterns: list[str])
|
||||
Paths under ``wiki/`` are seeded only by wiki init. Read-only zones and
|
||||
gitignore matches are never written or reported.
|
||||
"""
|
||||
return _is_wiki_page_path(relative) or _is_protected(relative, wiki_root, patterns)
|
||||
|
||||
|
||||
def _is_wiki_page_path(relative: Path) -> bool:
|
||||
"""Return whether a template-relative path is ``wiki/`` or under it.
|
||||
|
||||
Generated by CURSOR: 2026-09-30 - wiki/ pages only ever get conflicts.
|
||||
"""
|
||||
rel = relative.as_posix()
|
||||
if rel == "wiki" or rel.startswith("wiki/"):
|
||||
return True
|
||||
return rel == "wiki" or rel.startswith("wiki/")
|
||||
|
||||
|
||||
def _is_protected(relative: Path, wiki_root: Path, patterns: list[str]) -> bool:
|
||||
"""Return whether a path is in a read-only zone or gitignored.
|
||||
|
||||
Generated by CURSOR: 2026-09-30 - split out of _excluded_from_update.
|
||||
"""
|
||||
if is_read_only_file(wiki_root / relative, wiki_root):
|
||||
return True
|
||||
return path_is_ignored(rel, patterns)
|
||||
return path_is_ignored(relative.as_posix(), patterns)
|
||||
|
||||
|
||||
def find_missing_core_files(wiki_root: Path, template_dir: Path) -> list[Path]:
|
||||
@@ -490,7 +556,11 @@ def check_wiki_updates(directory: str | Path = ".") -> UpdateSummary:
|
||||
|
||||
for relative in get_all_template_files(template_dir):
|
||||
wiki_file = wiki_root / relative
|
||||
if _excluded_from_update(relative, wiki_root, patterns):
|
||||
if _is_protected(relative, wiki_root, patterns):
|
||||
continue
|
||||
# CURSOR: under wiki/ only an existing markdown page can conflict (SPEC 7.2.9)
|
||||
wiki_page = _is_wiki_page_path(relative)
|
||||
if wiki_page and (relative.suffix != ".md" or not wiki_file.exists()):
|
||||
continue
|
||||
|
||||
template_file = template_dir / relative
|
||||
@@ -506,7 +576,11 @@ def check_wiki_updates(directory: str | Path = ".") -> UpdateSummary:
|
||||
else:
|
||||
result = compare_non_md_file(wiki_file, template_file)
|
||||
|
||||
if result.needs_update:
|
||||
if result.is_conflict:
|
||||
summary.conflicts.append(result)
|
||||
elif wiki_page:
|
||||
continue
|
||||
elif result.needs_update:
|
||||
summary.files_to_update.append(result)
|
||||
if result.is_settings_file:
|
||||
summary.settings_file = wiki_file
|
||||
@@ -518,6 +592,23 @@ def check_wiki_updates(directory: str | Path = ".") -> UpdateSummary:
|
||||
return summary
|
||||
|
||||
|
||||
SHORT_HASH_LENGTH = 8
|
||||
|
||||
|
||||
def _change_detail(result: FileComparisonResult) -> str:
|
||||
"""Return the ` (current -> template)` detail for one report line.
|
||||
|
||||
Generated by CURSOR: 2026-09-30 - versions, else short SHA-256 (7.2.12.2).
|
||||
"""
|
||||
if result.current_version and result.template_version:
|
||||
return f" ({result.current_version} -> {result.template_version})"
|
||||
if result.current_hash and result.template_hash:
|
||||
current = result.current_hash[:SHORT_HASH_LENGTH]
|
||||
template = result.template_hash[:SHORT_HASH_LENGTH]
|
||||
return f" (sha256 {current} -> {template})"
|
||||
return ""
|
||||
|
||||
|
||||
def format_check_update_output(summary: UpdateSummary) -> str:
|
||||
"""Format the check-update summary for human-readable output.
|
||||
|
||||
@@ -534,11 +625,17 @@ def format_check_update_output(summary: UpdateSummary) -> str:
|
||||
else:
|
||||
lines.append(f"Files to update: {len(summary.files_to_update)}")
|
||||
for result in summary.files_to_update:
|
||||
detail = ""
|
||||
if result.current_version and result.template_version:
|
||||
detail = f" ({result.current_version} -> {result.template_version})"
|
||||
detail = _change_detail(result)
|
||||
lines.append(f" - {result.file_path.as_posix()}{detail}")
|
||||
|
||||
if summary.conflicts:
|
||||
lines.append(f"Conflicts (owner copy kept): {len(summary.conflicts)}")
|
||||
for result in summary.conflicts:
|
||||
detail = _change_detail(result)
|
||||
lines.append(
|
||||
f" - {result.file_path.as_posix()}{detail} -> {result.update_path.name}"
|
||||
)
|
||||
|
||||
if summary.directories_to_add:
|
||||
lines.append(f"Directories to add: {len(summary.directories_to_add)}")
|
||||
for directory in summary.directories_to_add:
|
||||
@@ -590,8 +687,12 @@ def update_core_files(directory: str | Path = ".", force: bool = False, yes: boo
|
||||
- When force=True or yes=True, updates all identified files without prompting.
|
||||
- When neither flag is set, presents list of files and prompts for y/n.
|
||||
- Never overwrites files in read-only zones.
|
||||
- Never overwrites an existing markdown file; a conflict writes the
|
||||
template to its `<stem>-update.md` sibling (SPEC 7.2.11).
|
||||
- Settings files are updated with user customizations preserved.
|
||||
- Returns summary of all updated files.
|
||||
|
||||
Modified by CURSOR: 2026-09-30 - write update files for conflicts.
|
||||
"""
|
||||
wiki_root = Path(directory).resolve()
|
||||
|
||||
@@ -630,6 +731,10 @@ def update_core_files(directory: str | Path = ".", force: bool = False, yes: boo
|
||||
else:
|
||||
_copy_file(template_dir / relative, result.file_path)
|
||||
|
||||
for result in summary.conflicts:
|
||||
relative = result.file_path.relative_to(wiki_root)
|
||||
_copy_file(template_dir / relative, result.update_path)
|
||||
|
||||
# Report locally-modified files that were skipped
|
||||
if verbose and summary.files_skipped:
|
||||
print("Skipped locally-modified files:")
|
||||
@@ -722,10 +827,23 @@ def check_update_main(directory: str = ".", json_output: bool = False) -> int:
|
||||
"path": str(result.file_path),
|
||||
"current_version": result.current_version,
|
||||
"template_version": result.template_version,
|
||||
"current_sha256": result.current_hash,
|
||||
"template_sha256": result.template_hash,
|
||||
"is_settings_file": result.is_settings_file,
|
||||
}
|
||||
for result in summary.files_to_update
|
||||
],
|
||||
"conflicts": [
|
||||
{
|
||||
"path": str(result.file_path),
|
||||
"update_path": str(result.update_path),
|
||||
"current_version": result.current_version,
|
||||
"template_version": result.template_version,
|
||||
"current_sha256": result.current_hash,
|
||||
"template_sha256": result.template_hash,
|
||||
}
|
||||
for result in summary.conflicts
|
||||
],
|
||||
"files_to_add": [str(p) for p in summary.files_to_add],
|
||||
"directories_to_add": [
|
||||
str(p) for p in summary.directories_to_add
|
||||
@@ -798,6 +916,10 @@ def update_main(
|
||||
"directories_added": [
|
||||
str(p) for p in summary.directories_to_add
|
||||
],
|
||||
"conflicts": [
|
||||
{"path": str(result.file_path), "update_path": str(result.update_path)}
|
||||
for result in summary.conflicts
|
||||
],
|
||||
"files_skipped": [
|
||||
str(result.file_path) for result in summary.files_skipped
|
||||
],
|
||||
@@ -808,8 +930,14 @@ def update_main(
|
||||
print(
|
||||
f"Update complete: {len(summary.files_to_update)} file(s) "
|
||||
f"updated, {len(summary.files_to_add)} added, "
|
||||
f"{len(summary.conflicts)} conflict(s), "
|
||||
f"{len(summary.files_skipped)} skipped."
|
||||
)
|
||||
if summary.conflicts:
|
||||
print(
|
||||
"Merge each <stem>-update.md into its file: "
|
||||
"run fiona-assistant housekeeping."
|
||||
)
|
||||
|
||||
return 0
|
||||
|
||||
@@ -830,6 +958,7 @@ __all__ = [
|
||||
"CORE_FILES",
|
||||
"READ_ONLY_ZONES",
|
||||
"SETTINGS_FILE",
|
||||
"UPDATE_SUFFIX",
|
||||
"FileComparisonResult",
|
||||
"UpdateSummary",
|
||||
"calculate_sha256",
|
||||
@@ -848,5 +977,6 @@ __all__ = [
|
||||
"is_read_only_file",
|
||||
"is_version_newer",
|
||||
"update_core_files",
|
||||
"update_file_path",
|
||||
"update_main",
|
||||
]
|
||||
|
||||
@@ -95,7 +95,7 @@ def _copy_children(source: Path, destination: Path, template_root: Path,
|
||||
"""Copy every non-ignored child of source into destination."""
|
||||
for item in source.iterdir():
|
||||
relative = item.relative_to(template_root).as_posix()
|
||||
# CURSOR: repository .gitignore matches (byte-code caches and the like)
|
||||
# AI/LLM: repository .gitignore matches (byte-code caches and the like)
|
||||
# are not copied into a wiki.
|
||||
if any(path_matches(pattern, relative) for pattern in ignore_patterns):
|
||||
continue
|
||||
@@ -111,17 +111,21 @@ def _copy_children(source: Path, destination: Path, template_root: Path,
|
||||
|
||||
|
||||
def _copy_file(source_item: Path, dest_item: Path) -> None:
|
||||
"""Copy one file, replacing date placeholders in text files."""
|
||||
"""Copy one file, replacing date placeholders in text files.
|
||||
|
||||
Modified by AI/LLM: 2026-09-30 - keep the template's line endings, so a
|
||||
Windows copy hashes the same as the template (SPEC 7.2.5).
|
||||
"""
|
||||
# Read the file content
|
||||
try:
|
||||
with open(source_item, "r", encoding="utf-8") as f:
|
||||
with open(source_item, "r", encoding="utf-8", newline="") as f:
|
||||
content = f.read()
|
||||
|
||||
# Replace date placeholders if present
|
||||
content = replace_date_placeholders(content)
|
||||
|
||||
# Write to destination
|
||||
with open(dest_item, "w", encoding="utf-8") as f:
|
||||
with open(dest_item, "w", encoding="utf-8", newline="") as f:
|
||||
f.write(content)
|
||||
except (UnicodeDecodeError, PermissionError):
|
||||
# For binary files or files with permission issues, use shutil.copy2
|
||||
|
||||
@@ -160,7 +160,7 @@ class TestConstellationThemes:
|
||||
|
||||
Generated by AI/LLM: 2026-09-29 - dark theme beside grayscale.
|
||||
Modified by AI/LLM: 2026-09-30 - night slate instead of black.
|
||||
Modified by CURSOR: 2026-09-30 - dark theme mid and high node colors.
|
||||
Modified by AI/LLM: 2026-09-30 - dark theme mid and high node colors.
|
||||
"""
|
||||
themes = load_constellation_themes()
|
||||
dark = themes["dark"]
|
||||
|
||||
@@ -0,0 +1,265 @@
|
||||
"""Tests for fiona-assistant housekeeping (SPEC 4.15, 7.26).
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - housekeeping routine tests.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import hashlib
|
||||
import json
|
||||
import shutil
|
||||
from pathlib import Path
|
||||
from unittest.mock import patch
|
||||
|
||||
import pytest
|
||||
|
||||
from fiona.__main__ import main
|
||||
from fiona.wiki.housekeeping import (
|
||||
STEP_NAMES,
|
||||
format_housekeeping_report,
|
||||
housekeeping_main,
|
||||
run_housekeeping,
|
||||
)
|
||||
from fiona.wiki.wiki import get_llm_wiki_source_path
|
||||
|
||||
|
||||
def _page(path: Path, name: str, version: str = "1.0.0", extra: str = "",
|
||||
body: str = "") -> None:
|
||||
"""Write a small markdown page with frontmatter at path."""
|
||||
path.parent.mkdir(parents=True, exist_ok=True)
|
||||
text = f"---\nname: {name}\nversion: {version}\n{extra}---\n\n# {name.capitalize()}\n"
|
||||
path.write_text(text + (f"\n{body}" if body else ""), encoding="utf-8")
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def hk_wiki(tmp_path, monkeypatch):
|
||||
"""A clean two-page wiki and a template that matches it."""
|
||||
template = tmp_path / "template"
|
||||
wiki = tmp_path / "wiki"
|
||||
settings = get_llm_wiki_source_path() / "fiona-settings.json"
|
||||
for root in (template, wiki):
|
||||
root.mkdir()
|
||||
shutil.copy2(settings, root / "fiona-settings.json")
|
||||
_page(root / "AGENTS.md", "agents", "2.0.0", body="See [index](./wiki/index.md).\n")
|
||||
_page(root / "wiki" / "index.md", "index", body="See [a](./a.md).\n")
|
||||
_page(wiki / "wiki" / "a.md", "a", body="Back to [index](./index.md).\n")
|
||||
monkeypatch.setattr(
|
||||
"fiona.wiki.update_manager.get_llm_wiki_source_path", lambda: template
|
||||
)
|
||||
return wiki
|
||||
|
||||
|
||||
def _step(results: dict, name: str) -> dict:
|
||||
"""Return the named step from a housekeeping result."""
|
||||
return next(step for step in results["steps"] if step["name"] == name)
|
||||
|
||||
|
||||
def _hashes(root: Path) -> dict:
|
||||
"""Map every file under root to its SHA-256."""
|
||||
return {
|
||||
path: hashlib.sha256(path.read_bytes()).hexdigest()
|
||||
for path in root.rglob("*") if path.is_file()
|
||||
}
|
||||
|
||||
|
||||
class TestRunHousekeeping:
|
||||
"""Tests for the housekeeping steps (SPEC 7.26)."""
|
||||
|
||||
def test_steps_run_in_order(self, hk_wiki):
|
||||
results = run_housekeeping(hk_wiki)
|
||||
|
||||
assert [step["name"] for step in results["steps"]] == list(STEP_NAMES)
|
||||
assert STEP_NAMES == ("check-update", "merge", "ingest", "sanity", "graph")
|
||||
|
||||
def test_clean_wiki_passes(self, hk_wiki):
|
||||
results = run_housekeeping(hk_wiki)
|
||||
|
||||
assert results["passed"] is True
|
||||
assert {step["status"] for step in results["steps"]} == {"PASS"}
|
||||
|
||||
def test_conflict_is_warn_and_writes_nothing(self, hk_wiki):
|
||||
"""SPEC 7.26.2: check-update reports conflicts without writing."""
|
||||
_page(hk_wiki / "AGENTS.md", "agents", "1.0.0", body="See [index](./wiki/index.md).\n")
|
||||
|
||||
step = _step(run_housekeeping(hk_wiki), "check-update")
|
||||
|
||||
assert step["status"] == "WARN"
|
||||
assert step["summary"] == "0 update(s), 1 conflict(s), 0 addition(s)"
|
||||
assert "conflict: AGENTS.md -> AGENTS-update.md" in step["details"]
|
||||
assert step["next"] == [
|
||||
"Ask the user, then run fiona-assistant wiki update --dry-run and wiki update --yes."
|
||||
]
|
||||
assert not (hk_wiki / "AGENTS-update.md").exists()
|
||||
|
||||
def test_pending_update_file_fails_merge(self, hk_wiki):
|
||||
"""SPEC 7.26.3: every *-update.md waits for a merge."""
|
||||
_page(hk_wiki / "wiki" / "schema-update.md", "schema", "1.5.0")
|
||||
_page(hk_wiki / "orphan-update.md", "orphan")
|
||||
|
||||
step = _step(run_housekeeping(hk_wiki), "merge")
|
||||
|
||||
assert step["status"] == "FAIL"
|
||||
assert step["summary"] == "2 update file(s) wait for a merge"
|
||||
assert "wiki/schema-update.md -> wiki/schema.md (target missing)" in step["details"]
|
||||
assert "orphan-update.md -> orphan.md (target missing)" in step["details"]
|
||||
assert any("1.5.0" in action and "wiki/schema-update.md" in action
|
||||
for action in step["next"])
|
||||
|
||||
def test_merge_detail_without_missing_target(self, hk_wiki):
|
||||
_page(hk_wiki / "AGENTS-update.md", "agents", "3.0.0")
|
||||
|
||||
step = _step(run_housekeeping(hk_wiki), "merge")
|
||||
|
||||
assert step["details"] == ["AGENTS-update.md -> AGENTS.md"]
|
||||
|
||||
def test_update_file_without_version_names_template_version(self, hk_wiki):
|
||||
(hk_wiki / "AGENTS-update.md").write_text("# no frontmatter\n", encoding="utf-8")
|
||||
|
||||
step = _step(run_housekeeping(hk_wiki), "merge")
|
||||
|
||||
assert "at least the template version" in step["next"][0]
|
||||
|
||||
def test_read_only_zones_are_not_scanned_for_update_files(self, hk_wiki):
|
||||
_page(hk_wiki / "raw" / "note-update.md", "note")
|
||||
_page(hk_wiki / "personal" / "note-update.md", "note")
|
||||
|
||||
step = _step(run_housekeeping(hk_wiki), "merge")
|
||||
|
||||
assert step["status"] == "PASS"
|
||||
|
||||
def test_raw_page_is_ingest_warn(self, hk_wiki):
|
||||
"""SPEC 7.26.4: pages at status: raw wait for a refine."""
|
||||
_page(hk_wiki / "wiki" / "sources" / "s.md", "s", extra="status: raw\n",
|
||||
body="From [index](../index.md).\n")
|
||||
|
||||
step = _step(run_housekeeping(hk_wiki), "ingest")
|
||||
|
||||
assert step["status"] == "WARN"
|
||||
assert step["details"] == ["wiki/sources/s.md"]
|
||||
assert step["next"] == ["Refine each raw page, then set status: refined."]
|
||||
|
||||
def test_dead_link_fails_sanity(self, hk_wiki):
|
||||
"""SPEC 7.26.5: a sanity violation is FAIL with the report lines."""
|
||||
_page(hk_wiki / "wiki" / "a.md", "a", body="See [gone](./gone.md).\n")
|
||||
|
||||
step = _step(run_housekeeping(hk_wiki), "sanity")
|
||||
|
||||
assert step["status"] == "FAIL"
|
||||
assert step["summary"] == "1 violation(s) in 1 check(s)"
|
||||
assert any("a.md" in line for line in step["details"])
|
||||
|
||||
def test_graph_written_and_orphans_warned(self, hk_wiki):
|
||||
"""SPEC 7.26.6: the graph lands at the wiki root; orphans warn."""
|
||||
_page(hk_wiki / "wiki" / "lonely.md", "lonely")
|
||||
_page(hk_wiki / "wiki" / "lonely-update.md", "lonely")
|
||||
|
||||
step = _step(run_housekeeping(hk_wiki), "graph")
|
||||
|
||||
assert (hk_wiki / "wiki_graph.html").is_file()
|
||||
assert step["status"] == "WARN"
|
||||
assert step["summary"].startswith("wrote wiki_graph.html (")
|
||||
assert step["details"] == ["orphan: wiki/lonely.md"]
|
||||
|
||||
def test_graph_error_is_fail(self, hk_wiki):
|
||||
with patch("fiona.wiki.housekeeping.wiki_graph_main", return_value=1):
|
||||
step = _step(run_housekeeping(hk_wiki), "graph")
|
||||
|
||||
assert step["status"] == "FAIL"
|
||||
|
||||
def test_every_step_runs_after_a_failure(self, hk_wiki):
|
||||
"""SPEC 7.26.1: merge and sanity fail, graph still runs."""
|
||||
_page(hk_wiki / "AGENTS-update.md", "agents", "3.0.0")
|
||||
_page(hk_wiki / "wiki" / "a.md", "a", body="See [gone](./gone.md).\n")
|
||||
|
||||
results = run_housekeeping(hk_wiki)
|
||||
|
||||
assert _step(results, "merge")["status"] == "FAIL"
|
||||
assert _step(results, "sanity")["status"] == "FAIL"
|
||||
assert (hk_wiki / "wiki_graph.html").is_file()
|
||||
assert results["passed"] is False
|
||||
|
||||
def test_only_graph_is_written(self, hk_wiki):
|
||||
"""SPEC 7.26.7: housekeeping changes nothing but wiki_graph.html."""
|
||||
_page(hk_wiki / "AGENTS.md", "agents", "1.0.0", body="See [index](./wiki/index.md).\n")
|
||||
before = _hashes(hk_wiki)
|
||||
|
||||
run_housekeeping(hk_wiki)
|
||||
|
||||
after = _hashes(hk_wiki)
|
||||
after.pop(hk_wiki / "wiki_graph.html")
|
||||
assert after == before
|
||||
|
||||
def test_missing_directory_raises(self, tmp_path):
|
||||
with pytest.raises(FileNotFoundError, match="Directory not found"):
|
||||
run_housekeeping(tmp_path / "nope")
|
||||
|
||||
def test_non_wiki_raises(self, tmp_path):
|
||||
with pytest.raises(NotADirectoryError, match="not an llm-wiki directory"):
|
||||
run_housekeeping(tmp_path)
|
||||
|
||||
|
||||
class TestHousekeepingReport:
|
||||
"""Tests for the human and JSON output (SPEC 4.15, 7.26.8)."""
|
||||
|
||||
def test_human_report_passes(self, hk_wiki):
|
||||
report = format_housekeeping_report(run_housekeeping(hk_wiki))
|
||||
|
||||
assert report.startswith(f"Housekeeping Report\nTARGET: {hk_wiki.resolve()}\n")
|
||||
assert "[PASS] merge: 0 update file(s) wait for a merge" in report
|
||||
assert "Next steps:" not in report
|
||||
assert report.endswith("HOUSEKEEPING PASSED")
|
||||
|
||||
def test_human_report_fails_with_next_steps(self, hk_wiki):
|
||||
_page(hk_wiki / "AGENTS-update.md", "agents", "3.0.0")
|
||||
|
||||
report = format_housekeeping_report(run_housekeeping(hk_wiki))
|
||||
|
||||
assert "[FAIL] merge: 1 update file(s) wait for a merge" in report
|
||||
assert " - AGENTS-update.md -> AGENTS.md" in report
|
||||
assert "Next steps:\n - Merge AGENTS-update.md into AGENTS.md" in report
|
||||
assert report.endswith("HOUSEKEEPING FAILED - 1 step(s) need attention: merge")
|
||||
|
||||
def test_next_steps_have_no_repeats(self):
|
||||
results = {
|
||||
"target": Path("/w"),
|
||||
"passed": True,
|
||||
"steps": [
|
||||
{"name": "a", "status": "WARN", "summary": "s", "details": [], "next": ["x"]},
|
||||
{"name": "b", "status": "WARN", "summary": "s", "details": [], "next": ["x"]},
|
||||
],
|
||||
}
|
||||
|
||||
assert format_housekeeping_report(results).count(" - x") == 1
|
||||
|
||||
def test_json_warn_only_passes(self, hk_wiki, capsys):
|
||||
_page(hk_wiki / "wiki" / "lonely.md", "lonely")
|
||||
|
||||
code = housekeeping_main(str(hk_wiki), json_output=True)
|
||||
|
||||
output = json.loads(capsys.readouterr().out)
|
||||
assert code == 0
|
||||
assert output["passed"] is True
|
||||
assert output["target"] == str(hk_wiki.resolve())
|
||||
assert _step(output, "graph")["status"] == "WARN"
|
||||
|
||||
def test_main_exits_1_on_fail(self, hk_wiki, capsys):
|
||||
_page(hk_wiki / "AGENTS-update.md", "agents", "3.0.0")
|
||||
|
||||
assert housekeeping_main(str(hk_wiki)) == 1
|
||||
assert "HOUSEKEEPING FAILED" in capsys.readouterr().out
|
||||
|
||||
def test_main_reports_non_wiki(self, tmp_path, capsys):
|
||||
assert housekeeping_main(str(tmp_path)) == 1
|
||||
assert "is not an llm-wiki directory" in capsys.readouterr().err
|
||||
|
||||
|
||||
class TestHousekeepingCli:
|
||||
"""Tests for the fiona-assistant housekeeping command."""
|
||||
|
||||
def test_cli_dispatches(self, hk_wiki, capsys):
|
||||
argv = ["fiona-assistant", "housekeeping", str(hk_wiki), "--json"]
|
||||
with patch("sys.argv", argv), pytest.raises(SystemExit) as exc_info:
|
||||
main()
|
||||
|
||||
assert exc_info.value.code == 0
|
||||
assert json.loads(capsys.readouterr().out)["passed"] is True
|
||||
@@ -1,6 +1,6 @@
|
||||
"""Tests for wiki gitignore seeding and matching.
|
||||
|
||||
Generated by CURSOR: 2026-09-30 - cover repository ignore patterns.
|
||||
Generated by AI/LLM: 2026-09-30 - cover repository ignore patterns.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
@@ -0,0 +1,68 @@
|
||||
"""Tests for the deployed-wiki rules in the llm-wiki template (SPEC 3.3).
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - the template is self-contained and
|
||||
tells a deployed wiki to commit after ingest and housekeeping.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import pathlib
|
||||
import re
|
||||
|
||||
import pytest
|
||||
|
||||
from fiona.paths import llm_wiki_template
|
||||
|
||||
TEMPLATE = llm_wiki_template()
|
||||
AGENTS = TEMPLATE / "AGENTS.md"
|
||||
SKILL = TEMPLATE / "utils" / "skills" / "fiona" / "SKILL.md"
|
||||
LOG = TEMPLATE / "wiki" / "log.md"
|
||||
|
||||
|
||||
def _body(path: pathlib.Path) -> str:
|
||||
"""Return the markdown text after the frontmatter block.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - drop frontmatter before content checks.
|
||||
"""
|
||||
text = path.read_text(encoding="utf-8")
|
||||
return text.split("---", 2)[2] if text.startswith("---") else text
|
||||
|
||||
|
||||
@pytest.mark.parametrize("path", sorted(TEMPLATE.rglob("*.md")), ids=str)
|
||||
@pytest.mark.parametrize("needle", ["SPEC", "project agent rule", "scripts/run_"])
|
||||
def test_template_markdown_has_no_outside_reference(path: pathlib.Path, needle: str) -> None:
|
||||
"""SPEC 3.3.1: template markdown never cites files outside the template.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - a deployed wiki only has the template.
|
||||
"""
|
||||
assert needle not in path.read_text(encoding="utf-8")
|
||||
|
||||
|
||||
@pytest.mark.parametrize("link", ["./utils/skills/fiona/SKILL.md", "./utils/skills/fiona/llm-wiki-mod.md"])
|
||||
def test_agents_links_skill_and_concept(link: str) -> None:
|
||||
"""SPEC 3.3.2: the entry point links the Fiona skill and llm-wiki-mod.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - AGENTS.md is the wiki entry point.
|
||||
"""
|
||||
assert f"]({link})" in AGENTS.read_text(encoding="utf-8")
|
||||
|
||||
|
||||
@pytest.mark.parametrize("path", [AGENTS, SKILL], ids=["AGENTS", "SKILL"])
|
||||
def test_deployed_wiki_commits_after_ingest(path: pathlib.Path) -> None:
|
||||
"""SPEC 3.3.3: save after ingest and housekeeping, not only when asked.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - commits are the wiki's history.
|
||||
"""
|
||||
text = " ".join(path.read_text(encoding="utf-8").split())
|
||||
assert "git save" in text
|
||||
assert not re.search(r"(commit|Run them)[^.]*only when the user asked", text)
|
||||
assert "Do not commit" not in text
|
||||
|
||||
|
||||
def test_seed_log_has_one_entry() -> None:
|
||||
"""SPEC 3.3.4: a new wiki's log starts with one seed bullet.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - no product history in a new wiki.
|
||||
"""
|
||||
bullets = [line for line in _body(LOG).splitlines() if line.startswith("- ")]
|
||||
assert bullets == ["- DATE_PLACEHOLDER - Initialized the llm-wiki."]
|
||||
+332
-76
@@ -13,6 +13,7 @@ from __future__ import annotations
|
||||
|
||||
import hashlib
|
||||
import json
|
||||
import re
|
||||
import shutil
|
||||
import sys
|
||||
import tempfile
|
||||
@@ -46,6 +47,7 @@ from fiona.wiki.update_manager import (
|
||||
update_core_files,
|
||||
update_main,
|
||||
)
|
||||
from fiona.wiki.wiki import _copy_file
|
||||
|
||||
# =============================================================================
|
||||
# Fixtures
|
||||
@@ -57,11 +59,11 @@ def temp_wiki_dir():
|
||||
with tempfile.TemporaryDirectory() as tmpdir:
|
||||
wiki_dir = Path(tmpdir) / "test_wiki"
|
||||
wiki_dir.mkdir()
|
||||
|
||||
|
||||
# Create a basic fiona-settings.json to mark it as an llm-wiki
|
||||
settings_file = wiki_dir / "fiona-settings.json"
|
||||
settings_file.write_text(json.dumps({"markdown": {"pymarkdown": {}}}, indent=2))
|
||||
|
||||
|
||||
yield wiki_dir
|
||||
|
||||
|
||||
@@ -71,17 +73,17 @@ def temp_template_dir():
|
||||
with tempfile.TemporaryDirectory() as tmpdir:
|
||||
template_dir = Path(tmpdir) / "template"
|
||||
template_dir.mkdir()
|
||||
|
||||
|
||||
# Create some template files
|
||||
(template_dir / "AGENTS.md").write_text("---\nname: AGENTS\nversion: 1.0.0\n---\n# Agents")
|
||||
(template_dir / "README.md").write_text("---\nname: README\nversion: 1.0.0\n---\n# README")
|
||||
(template_dir / "fiona-settings.json").write_text(json.dumps({"version": "1.0.0"}, indent=2))
|
||||
|
||||
|
||||
# Create subdirectory
|
||||
wiki_subdir = template_dir / "wiki"
|
||||
wiki_subdir.mkdir()
|
||||
(wiki_subdir / "index.md").write_text("---\nname: index\nversion: 1.0.0\n---\n# Index")
|
||||
|
||||
|
||||
yield template_dir
|
||||
|
||||
|
||||
@@ -90,19 +92,19 @@ def mock_wiki_root():
|
||||
"""Create a mock wiki root with some files."""
|
||||
with tempfile.TemporaryDirectory() as tmpdir:
|
||||
wiki_root = Path(tmpdir)
|
||||
|
||||
|
||||
# Create core files
|
||||
(wiki_root / "AGENTS.md").write_text("---\nname: AGENTS\nversion: 1.0.0\n---\n# Agents")
|
||||
(wiki_root / "fiona-settings.json").write_text(json.dumps({"version": "1.0.0"}, indent=2))
|
||||
|
||||
|
||||
# Create user file (not core)
|
||||
(wiki_root / "user_notes.md").write_text("# User Notes")
|
||||
|
||||
|
||||
# Create read-only zone
|
||||
personal_dir = wiki_root / "personal"
|
||||
personal_dir.mkdir()
|
||||
(personal_dir / "private.md").write_text("# Private")
|
||||
|
||||
|
||||
yield wiki_root
|
||||
|
||||
|
||||
@@ -116,7 +118,7 @@ class TestFileComparisonResult:
|
||||
def test_default_values(self):
|
||||
"""Test that default values are set correctly."""
|
||||
result = FileComparisonResult(file_path=Path("/test/file.md"))
|
||||
|
||||
|
||||
assert result.file_path == Path("/test/file.md")
|
||||
assert result.is_core_file is False
|
||||
assert result.has_template_version is False
|
||||
@@ -131,7 +133,7 @@ class TestFileComparisonResult:
|
||||
def test_needs_update_when_new_file(self):
|
||||
"""Test that new files are marked as needing update."""
|
||||
result = FileComparisonResult(file_path=Path("/test/file.md"), is_new_file=True)
|
||||
|
||||
|
||||
assert result.needs_update is True
|
||||
|
||||
def test_custom_values(self):
|
||||
@@ -144,7 +146,7 @@ class TestFileComparisonResult:
|
||||
template_version="2.0.0",
|
||||
needs_update=True
|
||||
)
|
||||
|
||||
|
||||
assert result.is_core_file is True
|
||||
assert result.has_template_version is True
|
||||
assert result.current_version == "1.0.0"
|
||||
@@ -158,7 +160,7 @@ class TestUpdateSummary:
|
||||
def test_empty_summary(self):
|
||||
"""Test empty update summary."""
|
||||
summary = UpdateSummary()
|
||||
|
||||
|
||||
assert summary.files_to_update == []
|
||||
assert summary.files_to_add == []
|
||||
assert summary.settings_file is None
|
||||
@@ -175,12 +177,12 @@ class TestUpdateSummary:
|
||||
file_path=Path("/test/file2.md"),
|
||||
needs_update=True
|
||||
)
|
||||
|
||||
|
||||
summary = UpdateSummary(
|
||||
files_to_update=[result1, result2],
|
||||
files_to_add=[Path("/test/new_file.md")]
|
||||
)
|
||||
|
||||
|
||||
assert len(summary.files_to_update) == 2
|
||||
assert len(summary.files_to_add) == 1
|
||||
assert summary.has_updates is True
|
||||
@@ -191,7 +193,7 @@ class TestUpdateSummary:
|
||||
summary = UpdateSummary(
|
||||
settings_file=Path("/test/fiona-settings.json")
|
||||
)
|
||||
|
||||
|
||||
assert summary.settings_file == Path("/test/fiona-settings.json")
|
||||
|
||||
|
||||
@@ -206,12 +208,12 @@ class TestCalculateSha256:
|
||||
"""Test SHA256 hash calculation for a file."""
|
||||
test_file = tmp_path / "test.txt"
|
||||
test_file.write_text("test content")
|
||||
|
||||
|
||||
result = calculate_sha256(test_file)
|
||||
|
||||
|
||||
# Calculate expected hash
|
||||
expected = hashlib.sha256(b"test content").hexdigest()
|
||||
|
||||
|
||||
assert result == expected
|
||||
assert len(result) == 64 # SHA256 hash is 64 hex characters
|
||||
|
||||
@@ -261,7 +263,7 @@ class TestIsReadOnlyFile:
|
||||
personal_dir.mkdir()
|
||||
file_path = personal_dir / "private.md"
|
||||
file_path.write_text("test")
|
||||
|
||||
|
||||
assert is_read_only_file(file_path, temp_wiki_dir) is True
|
||||
|
||||
def test_raw_zone(self, temp_wiki_dir):
|
||||
@@ -270,14 +272,14 @@ class TestIsReadOnlyFile:
|
||||
raw_dir.mkdir()
|
||||
file_path = raw_dir / "data.json"
|
||||
file_path.write_text("test")
|
||||
|
||||
|
||||
assert is_read_only_file(file_path, temp_wiki_dir) is True
|
||||
|
||||
def test_non_read_only_file(self, temp_wiki_dir):
|
||||
"""Test that files outside read-only zones are not read-only."""
|
||||
file_path = temp_wiki_dir / "AGENTS.md"
|
||||
file_path.write_text("test")
|
||||
|
||||
|
||||
assert is_read_only_file(file_path, temp_wiki_dir) is False
|
||||
|
||||
def test_file_outside_wiki_not_read_only(self, temp_wiki_dir):
|
||||
@@ -314,13 +316,13 @@ class TestCompareMdFile:
|
||||
"""Test comparing files with identical versions."""
|
||||
wiki_file = tmp_path / "file.md"
|
||||
template_file = tmp_path / "template.md"
|
||||
|
||||
|
||||
content = "---\nname: Test\nversion: 1.0.0\n---\n# Content"
|
||||
wiki_file.write_text(content)
|
||||
template_file.write_text(content)
|
||||
|
||||
|
||||
result = compare_md_file(wiki_file, template_file)
|
||||
|
||||
|
||||
assert result.file_path == wiki_file
|
||||
assert result.is_core_file is True
|
||||
assert result.has_template_version is True
|
||||
@@ -330,15 +332,15 @@ class TestCompareMdFile:
|
||||
"""Test comparing files with different versions."""
|
||||
wiki_file = tmp_path / "file.md"
|
||||
template_file = tmp_path / "template.md"
|
||||
|
||||
|
||||
wiki_content = "---\nname: Test\nversion: 1.0.0\n---\n# Content"
|
||||
template_content = "---\nname: Test\nversion: 2.0.0\n---\n# Content"
|
||||
|
||||
|
||||
wiki_file.write_text(wiki_content)
|
||||
template_file.write_text(template_content)
|
||||
|
||||
|
||||
result = compare_md_file(wiki_file, template_file)
|
||||
|
||||
|
||||
assert result.file_path == wiki_file
|
||||
assert result.is_core_file is True
|
||||
|
||||
@@ -350,13 +352,13 @@ class TestCompareNonMdFile:
|
||||
"""Test comparing JSON files using hash."""
|
||||
wiki_file = tmp_path / "settings.json"
|
||||
template_file = tmp_path / "template_settings.json"
|
||||
|
||||
|
||||
content = json.dumps({"version": "1.0.0"}, indent=2)
|
||||
wiki_file.write_text(content)
|
||||
template_file.write_text(content)
|
||||
|
||||
|
||||
result = compare_non_md_file(wiki_file, template_file)
|
||||
|
||||
|
||||
assert result.file_path == wiki_file
|
||||
assert result.is_core_file is True
|
||||
assert result.has_template_version is False
|
||||
@@ -369,15 +371,15 @@ class TestCompareSettingsFile:
|
||||
"""Test comparing settings files."""
|
||||
wiki_settings = tmp_path / "fiona-settings.json"
|
||||
template_settings = tmp_path / "template_settings.json"
|
||||
|
||||
|
||||
wiki_content = json.dumps({"version": "1.0.0", "custom": "value"}, indent=2)
|
||||
template_content = json.dumps({"version": "2.0.0", "new_setting": "new"}, indent=2)
|
||||
|
||||
|
||||
wiki_settings.write_text(wiki_content)
|
||||
template_settings.write_text(template_content)
|
||||
|
||||
|
||||
result = compare_settings_file(wiki_settings, template_settings)
|
||||
|
||||
|
||||
assert result.file_path == wiki_settings
|
||||
assert result.is_core_file is True
|
||||
assert result.is_settings_file is True
|
||||
@@ -393,7 +395,7 @@ class TestGetAllTemplateFiles:
|
||||
def test_get_all_template_files(self, temp_template_dir):
|
||||
"""Test getting all files from template directory."""
|
||||
files = get_all_template_files(temp_template_dir)
|
||||
|
||||
|
||||
# Should return a list (may be empty in stub)
|
||||
assert isinstance(files, list)
|
||||
|
||||
@@ -405,9 +407,9 @@ class TestFindMissingCoreFiles:
|
||||
"""Test finding files that exist in template but not in wiki."""
|
||||
# Create a file in template that doesn't exist in wiki
|
||||
(temp_template_dir / "new_file.md").write_text("---\nname: New\nversion: 1.0.0\n---\n# New")
|
||||
|
||||
|
||||
missing = find_missing_core_files(temp_wiki_dir, temp_template_dir)
|
||||
|
||||
|
||||
# Should return a list (may be empty in stub)
|
||||
assert isinstance(missing, list)
|
||||
|
||||
@@ -423,9 +425,19 @@ class TestCheckWikiUpdates:
|
||||
"""Test checking a pristine wiki (no updates needed)."""
|
||||
# A wiki created by init should have no updates needed
|
||||
summary = check_wiki_updates(str(temp_wiki_dir))
|
||||
|
||||
|
||||
assert isinstance(summary, UpdateSummary)
|
||||
|
||||
def test_real_init_is_up_to_date(self, pristine_wiki):
|
||||
"""Test a real wiki init reports nothing to update on any OS (SPEC 7.2.5).
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - init must keep template line endings.
|
||||
"""
|
||||
summary = check_wiki_updates(pristine_wiki)
|
||||
|
||||
assert [r.file_path.name for r in summary.files_to_update] == []
|
||||
assert summary.has_updates is False
|
||||
|
||||
def test_check_nonexistent_directory(self):
|
||||
"""Test checking a non-existent directory."""
|
||||
with pytest.raises(FileNotFoundError):
|
||||
@@ -436,7 +448,7 @@ class TestCheckWikiUpdates:
|
||||
# Create a directory without fiona-settings.json
|
||||
non_wiki_dir = tmp_path / "non_wiki"
|
||||
non_wiki_dir.mkdir()
|
||||
|
||||
|
||||
with pytest.raises(NotADirectoryError):
|
||||
check_wiki_updates(str(non_wiki_dir))
|
||||
|
||||
@@ -447,10 +459,10 @@ class TestCheckWikiUpdates:
|
||||
wiki_dir = tmp_path / "wiki"
|
||||
wiki_dir.mkdir()
|
||||
(wiki_dir / "fiona-settings.json").write_text(json.dumps({}))
|
||||
|
||||
|
||||
# Mock get_llm_wiki_source_path to return non-existent path
|
||||
mock_get_source.return_value = Path("/nonexistent/template")
|
||||
|
||||
|
||||
with pytest.raises(FileNotFoundError, match="Template directory not found"):
|
||||
check_wiki_updates(str(wiki_dir))
|
||||
|
||||
@@ -466,7 +478,7 @@ class TestFormatCheckUpdateOutput:
|
||||
"""Test formatting an empty summary."""
|
||||
summary = UpdateSummary()
|
||||
output = format_check_update_output(summary)
|
||||
|
||||
|
||||
assert "Wiki is up to date" in output
|
||||
|
||||
def test_format_summary_with_updates(self):
|
||||
@@ -479,9 +491,9 @@ class TestFormatCheckUpdateOutput:
|
||||
files_to_update=[result],
|
||||
files_to_add=[Path("/test/new_file.md")]
|
||||
)
|
||||
|
||||
|
||||
output = format_check_update_output(summary)
|
||||
|
||||
|
||||
assert "Files to update: 1" in output
|
||||
assert "Files to add: 1" in output
|
||||
assert "Total: 2" in output
|
||||
@@ -497,13 +509,13 @@ class TestUpdateCoreFiles:
|
||||
def test_update_no_changes_needed(self, temp_wiki_dir):
|
||||
"""Test updating when no changes are needed."""
|
||||
summary = update_core_files(str(temp_wiki_dir), force=True)
|
||||
|
||||
|
||||
assert isinstance(summary, UpdateSummary)
|
||||
|
||||
def test_update_with_force(self, temp_wiki_dir):
|
||||
"""Test updating with force flag."""
|
||||
summary = update_core_files(str(temp_wiki_dir), force=True)
|
||||
|
||||
|
||||
assert isinstance(summary, UpdateSummary)
|
||||
|
||||
def test_update_without_force_raises(self, temp_wiki_dir):
|
||||
@@ -530,22 +542,22 @@ class TestCopySettingsWithPreservation:
|
||||
"""Test that user settings are preserved during update."""
|
||||
wiki_settings = tmp_path / "wiki_settings.json"
|
||||
template_settings = tmp_path / "template_settings.json"
|
||||
|
||||
|
||||
wiki_content = json.dumps({
|
||||
"version": "1.0.0",
|
||||
"markdown": {"pymarkdown": {"line_length": 120}},
|
||||
"user_custom": "value"
|
||||
}, indent=2)
|
||||
|
||||
|
||||
template_content = json.dumps({
|
||||
"version": "2.0.0",
|
||||
"markdown": {"pymarkdown": {"line_length": 100}},
|
||||
"new_setting": "new"
|
||||
}, indent=2)
|
||||
|
||||
|
||||
wiki_settings.write_text(wiki_content)
|
||||
template_settings.write_text(template_content)
|
||||
|
||||
|
||||
# This is a stub, so it just shouldn't crash
|
||||
copy_settings_with_preservation(wiki_settings, template_settings)
|
||||
|
||||
@@ -560,19 +572,19 @@ class TestCheckUpdateMain:
|
||||
def test_check_update_main_default(self, temp_wiki_dir):
|
||||
"""Test check-update main with default arguments."""
|
||||
result = check_update_main(directory=str(temp_wiki_dir))
|
||||
|
||||
|
||||
assert result == 0
|
||||
|
||||
def test_check_update_main_json(self, temp_wiki_dir):
|
||||
"""Test check-update main with JSON output."""
|
||||
result = check_update_main(directory=str(temp_wiki_dir), json_output=True)
|
||||
|
||||
|
||||
assert result == 0
|
||||
|
||||
def test_check_update_main_nonexistent(self):
|
||||
"""Test check-update main with non-existent directory."""
|
||||
result = check_update_main(directory="/nonexistent")
|
||||
|
||||
|
||||
assert result == 1
|
||||
|
||||
|
||||
@@ -630,7 +642,7 @@ class TestUpdateMain:
|
||||
def test_update_main_nonexistent(self):
|
||||
"""Test update main with non-existent directory."""
|
||||
result = update_main(directory="/nonexistent")
|
||||
|
||||
|
||||
assert result == 1
|
||||
|
||||
@patch("fiona.wiki.update_manager.update_core_files")
|
||||
@@ -640,12 +652,12 @@ class TestUpdateMain:
|
||||
wiki_dir = tmp_path / "wiki"
|
||||
wiki_dir.mkdir()
|
||||
(wiki_dir / "fiona-settings.json").write_text(json.dumps({}))
|
||||
|
||||
|
||||
# Mock update_core_files to raise RuntimeError
|
||||
mock_update.side_effect = RuntimeError("Test error")
|
||||
|
||||
|
||||
result = update_main(directory=str(wiki_dir))
|
||||
|
||||
|
||||
assert result == 1
|
||||
|
||||
|
||||
@@ -767,7 +779,8 @@ class TestCompareMdFileVersions:
|
||||
assert result.current_version == "1.0.0"
|
||||
assert result.template_version == "1.0.0"
|
||||
|
||||
def test_newer_template_needs_update(self, tmp_path):
|
||||
def test_newer_template_is_conflict(self, tmp_path):
|
||||
"""Test a newer template is a conflict, never an overwrite (SPEC 7.2.1.1)."""
|
||||
wiki_file = tmp_path / "file.md"
|
||||
template_file = tmp_path / "template.md"
|
||||
_write_md(wiki_file, "1.0.0", body="# Old\n")
|
||||
@@ -775,7 +788,9 @@ class TestCompareMdFileVersions:
|
||||
|
||||
result = compare_md_file(wiki_file, template_file)
|
||||
|
||||
assert result.needs_update is True
|
||||
assert result.needs_update is False
|
||||
assert result.is_conflict is True
|
||||
assert result.update_path == tmp_path / "file-update.md"
|
||||
assert result.is_locally_modified is False
|
||||
assert result.current_version == "1.0.0"
|
||||
assert result.template_version == "2.0.0"
|
||||
@@ -808,11 +823,13 @@ class TestCompareMdFileVersions:
|
||||
wiki_file.write_text("plain text\n", encoding="utf-8")
|
||||
template_file.write_text("plain text\n", encoding="utf-8")
|
||||
|
||||
assert compare_md_file(wiki_file, template_file).needs_update is False
|
||||
assert compare_md_file(wiki_file, template_file).is_conflict is False
|
||||
|
||||
template_file.write_text("changed text\n", encoding="utf-8")
|
||||
|
||||
assert compare_md_file(wiki_file, template_file).needs_update is True
|
||||
result = compare_md_file(wiki_file, template_file)
|
||||
assert result.is_conflict is True
|
||||
assert result.needs_update is False
|
||||
|
||||
|
||||
class TestCompareNonMdFileHashes:
|
||||
@@ -990,18 +1007,41 @@ class TestCheckWikiUpdatesImplemented:
|
||||
assert summary.files_skipped == []
|
||||
assert summary.directories_to_add == []
|
||||
|
||||
def test_outdated_md_reported_with_versions(self, template_wiki_pair):
|
||||
def test_outdated_md_reported_as_conflict(self, template_wiki_pair):
|
||||
_template, wiki = template_wiki_pair
|
||||
_write_md(wiki / "AGENTS.md", "1.0.0", body="# Agents v1\n", name="agents")
|
||||
|
||||
summary = check_wiki_updates(str(wiki))
|
||||
|
||||
assert summary.has_updates is True
|
||||
assert len(summary.files_to_update) == 1
|
||||
result = summary.files_to_update[0]
|
||||
assert summary.files_to_update == []
|
||||
assert len(summary.conflicts) == 1
|
||||
result = summary.conflicts[0]
|
||||
assert result.file_path == (wiki / "AGENTS.md").resolve()
|
||||
assert result.update_path == (wiki / "AGENTS-update.md").resolve()
|
||||
assert result.current_version == "1.0.0"
|
||||
assert result.template_version == "2.0.0"
|
||||
assert not (wiki / "AGENTS-update.md").exists()
|
||||
|
||||
def test_wiki_page_older_than_template_is_conflict(self, template_wiki_pair):
|
||||
"""Test an older wiki/ template page is a conflict (SPEC 7.2.9)."""
|
||||
_template, wiki = template_wiki_pair
|
||||
_write_md(wiki / "wiki" / "index.md", "0.1.0", body="# User index\n", name="index")
|
||||
|
||||
summary = check_wiki_updates(str(wiki))
|
||||
|
||||
assert [r.update_path for r in summary.conflicts] == [
|
||||
(wiki / "wiki" / "index-update.md").resolve()
|
||||
]
|
||||
|
||||
def test_conflict_clears_at_template_version(self, template_wiki_pair):
|
||||
"""Test a merged file at the template version is no conflict (SPEC 7.2.11.4)."""
|
||||
_template, wiki = template_wiki_pair
|
||||
_write_md(wiki / "AGENTS.md", "2.0.0", body="# Merged agents\n", name="agents")
|
||||
|
||||
summary = check_wiki_updates(str(wiki))
|
||||
|
||||
assert summary.conflicts == []
|
||||
|
||||
def test_missing_file_reported_as_add(self, template_wiki_pair):
|
||||
_template, wiki = template_wiki_pair
|
||||
@@ -1073,16 +1113,18 @@ class TestCheckWikiUpdatesImplemented:
|
||||
assert summary.has_updates is False
|
||||
|
||||
def test_wiki_pages_stay_out_of_the_report(self, template_wiki_pair):
|
||||
"""Test an edited wiki page is not an update, add, or skip."""
|
||||
"""Test a newer wiki page is not an update, add, skip, or conflict."""
|
||||
_template, wiki = template_wiki_pair
|
||||
_write_md(
|
||||
wiki / "wiki" / "index.md", "0.1.0", body="# User index\n", name="index"
|
||||
wiki / "wiki" / "index.md", "3.0.0", body="# User index\n", name="index"
|
||||
)
|
||||
(wiki / "wiki" / "queries" / ".gitkeep").write_text("local", encoding="utf-8")
|
||||
|
||||
summary = check_wiki_updates(str(wiki))
|
||||
|
||||
reported = [result.file_path.as_posix() for result in summary.files_to_update]
|
||||
reported += [result.file_path.as_posix() for result in summary.files_skipped]
|
||||
reported += [result.file_path.as_posix() for result in summary.conflicts]
|
||||
reported += [path.as_posix() for path in summary.files_to_add]
|
||||
reported += [path.as_posix() for path in summary.directories_to_add]
|
||||
assert not any(
|
||||
@@ -1142,16 +1184,59 @@ class TestCheckWikiUpdatesImplemented:
|
||||
class TestUpdateCoreFilesImplemented:
|
||||
"""Tests for performing the actual update."""
|
||||
|
||||
def test_yes_updates_outdated_file(self, template_wiki_pair):
|
||||
def test_yes_keeps_outdated_file_and_writes_update_file(self, template_wiki_pair):
|
||||
"""Test update yields to the owner and writes AGENTS-update.md (SPEC 7.2.6)."""
|
||||
_template, wiki = template_wiki_pair
|
||||
_write_md(wiki / "AGENTS.md", "1.0.0", body="# Agents v1\n", name="agents")
|
||||
owner = "---\nname: agents\nversion: 1.0.0\n---\n# Agents v1\n"
|
||||
(wiki / "AGENTS.md").write_text(owner, encoding="utf-8")
|
||||
|
||||
summary = update_core_files(str(wiki), yes=True)
|
||||
|
||||
assert (wiki / "AGENTS.md").read_text(encoding="utf-8") == (
|
||||
assert (wiki / "AGENTS.md").read_text(encoding="utf-8") == owner
|
||||
assert (wiki / "AGENTS-update.md").read_text(encoding="utf-8") == (
|
||||
"---\nname: agents\nversion: 2.0.0\n---\n# Agents v2\n"
|
||||
)
|
||||
assert len(summary.files_to_update) == 1
|
||||
assert len(summary.conflicts) == 1
|
||||
assert summary.files_to_update == []
|
||||
|
||||
def test_update_file_expands_date_placeholder(self, template_wiki_pair):
|
||||
"""Test the update file holds the expanded template (SPEC 7.2.11.2)."""
|
||||
template, wiki = template_wiki_pair
|
||||
_write_md(
|
||||
template / "README.md", "2.0.0",
|
||||
body="updated: DATE_PLACEHOLDER\n", name="readme",
|
||||
)
|
||||
|
||||
update_core_files(str(wiki), yes=True)
|
||||
first = (wiki / "README-update.md").read_bytes()
|
||||
update_core_files(str(wiki), yes=True)
|
||||
|
||||
assert b"DATE_PLACEHOLDER" not in first
|
||||
assert (wiki / "README-update.md").read_bytes() == first
|
||||
assert sorted(p.name for p in wiki.glob("*-update.md")) == ["README-update.md"]
|
||||
|
||||
def test_dry_run_writes_no_update_file(self, template_wiki_pair):
|
||||
"""Test --dry-run lists the conflict and writes nothing (SPEC 7.2.11.3)."""
|
||||
_template, wiki = template_wiki_pair
|
||||
_write_md(wiki / "AGENTS.md", "1.0.0", body="# Agents v1\n", name="agents")
|
||||
|
||||
assert update_main(directory=str(wiki), dry_run=True) == 0
|
||||
|
||||
assert list(wiki.rglob("*-update.md")) == []
|
||||
|
||||
def test_wiki_schema_conflict_writes_only_its_update_file(self, template_wiki_pair):
|
||||
"""Test a wiki/ conflict writes one sibling update file (SPEC 7.2.11.1)."""
|
||||
template, wiki = template_wiki_pair
|
||||
_write_md(template / "wiki" / "schema.md", "1.5.0", body="# Schema\n", name="schema")
|
||||
owner = "---\nname: schema\nversion: 1.4.0\n---\n# My tags\n"
|
||||
(wiki / "wiki" / "schema.md").write_text(owner, encoding="utf-8")
|
||||
before = {p for p in wiki.rglob("*") if p.is_file()}
|
||||
|
||||
update_core_files(str(wiki), yes=True)
|
||||
|
||||
after = {p for p in wiki.rglob("*") if p.is_file()}
|
||||
assert after - before == {wiki / "wiki" / "schema-update.md"}
|
||||
assert (wiki / "wiki" / "schema.md").read_text(encoding="utf-8") == owner
|
||||
|
||||
def test_yes_adds_missing_file_and_directory(self, template_wiki_pair):
|
||||
template, wiki = template_wiki_pair
|
||||
@@ -1177,6 +1262,9 @@ class TestUpdateCoreFilesImplemented:
|
||||
update_core_files(str(wiki), yes=True)
|
||||
|
||||
assert (wiki / "wiki" / "index.md").read_text(encoding="utf-8") == user
|
||||
assert (wiki / "wiki" / "index-update.md").read_text(encoding="utf-8") == (
|
||||
"---\nname: index\nversion: 1.0.0\n---\n# Index\n"
|
||||
)
|
||||
assert not (wiki / "wiki" / "queries").exists()
|
||||
|
||||
def test_yes_leaves_gitignored_file_unchanged(self, template_wiki_pair):
|
||||
@@ -1248,7 +1336,7 @@ class TestUpdateCoreFilesImplemented:
|
||||
|
||||
update_core_files(str(wiki))
|
||||
|
||||
assert "version: 2.0.0" in (wiki / "AGENTS.md").read_text(encoding="utf-8")
|
||||
assert "version: 2.0.0" in (wiki / "AGENTS-update.md").read_text(encoding="utf-8")
|
||||
|
||||
def test_interactive_confirmation_declined(
|
||||
self, template_wiki_pair, monkeypatch
|
||||
@@ -1300,8 +1388,12 @@ class TestCheckUpdateMainJson:
|
||||
|
||||
assert result == 0
|
||||
assert output["has_updates"] is True
|
||||
assert output["files_to_update"][0]["current_version"] == "1.0.0"
|
||||
assert output["files_to_update"][0]["template_version"] == "2.0.0"
|
||||
assert output["files_to_update"] == []
|
||||
conflict = output["conflicts"][0]
|
||||
assert conflict["current_version"] == "1.0.0"
|
||||
assert conflict["template_version"] == "2.0.0"
|
||||
assert conflict["update_path"].endswith("AGENTS-update.md")
|
||||
assert output["total"] == 1
|
||||
|
||||
def test_json_reports_skipped_files(self, template_wiki_pair, capsys):
|
||||
_template, wiki = template_wiki_pair
|
||||
@@ -1341,10 +1433,24 @@ class TestUpdateMainJsonImplemented:
|
||||
output = json.loads(capsys.readouterr().out)
|
||||
|
||||
assert result == 0
|
||||
assert len(output["files_updated"]) == 1
|
||||
assert output["files_updated"] == []
|
||||
assert len(output["files_added"]) == 1
|
||||
assert output["conflicts"][0]["update_path"].endswith("AGENTS-update.md")
|
||||
assert output["files_skipped"] == []
|
||||
|
||||
def test_human_output_reports_conflicts(self, template_wiki_pair, capsys):
|
||||
"""Test the success line counts conflicts and names housekeeping."""
|
||||
_template, wiki = template_wiki_pair
|
||||
_write_md(wiki / "AGENTS.md", "1.0.0", body="# Agents v1\n", name="agents")
|
||||
|
||||
assert update_main(directory=str(wiki), yes=True) == 0
|
||||
|
||||
out = capsys.readouterr().out
|
||||
assert "Conflicts (owner copy kept): 1" in out
|
||||
assert "AGENTS.md (1.0.0 -> 2.0.0) -> AGENTS-update.md" in out
|
||||
assert "0 file(s) updated, 0 added, 1 conflict(s), 0 skipped." in out
|
||||
assert "run fiona-assistant housekeeping" in out
|
||||
|
||||
|
||||
class TestFormatCheckUpdateOutputSkipped:
|
||||
"""Tests for skipped files in the formatted output."""
|
||||
@@ -1372,3 +1478,153 @@ class TestFormatCheckUpdateOutputSkipped:
|
||||
|
||||
assert "Wiki is up to date" in output
|
||||
assert "Files skipped" in output
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# SHA-256 comparison for files without a version (SPEC 7.2.12)
|
||||
# Generated by AI/LLM: 2026-09-30 - hash compare and short-hash report.
|
||||
# =============================================================================
|
||||
|
||||
HEX64 = r"^[0-9a-f]{64}$"
|
||||
|
||||
|
||||
def _sha(text: str) -> str:
|
||||
"""Return the SHA-256 hex digest of UTF-8 text."""
|
||||
return hashlib.sha256(text.encode("utf-8")).hexdigest()
|
||||
|
||||
|
||||
class TestSha256Comparison:
|
||||
"""Tests for hash comparison of files without a version."""
|
||||
|
||||
def test_date_placeholder_template_matches_init_copy(self, tmp_path):
|
||||
"""A template with DATE_PLACEHOLDER matches its init copy (SPEC 7.2.12.1)."""
|
||||
template_file = tmp_path / "template.py"
|
||||
wiki_file = tmp_path / "example.py"
|
||||
template_file.write_text("# created DATE_PLACEHOLDER\n", encoding="utf-8", newline="\n")
|
||||
_copy_file(template_file, wiki_file)
|
||||
|
||||
result = compare_non_md_file(wiki_file, template_file)
|
||||
|
||||
assert result.needs_update is False
|
||||
assert result.current_hash == result.template_hash
|
||||
|
||||
def test_binary_template_hashes_raw_bytes(self, tmp_path):
|
||||
template_file = tmp_path / "template.bin"
|
||||
wiki_file = tmp_path / "blob.bin"
|
||||
template_file.write_bytes(b"\xff\xfe\x00DATE_PLACEHOLDER")
|
||||
wiki_file.write_bytes(b"\xff\xfe\x00DATE_PLACEHOLDER")
|
||||
|
||||
result = compare_non_md_file(wiki_file, template_file)
|
||||
|
||||
assert result.needs_update is False
|
||||
assert result.template_hash == calculate_sha256(template_file)
|
||||
|
||||
def test_unversioned_md_equal_is_up_to_date(self, tmp_path):
|
||||
wiki_file = tmp_path / "file.md"
|
||||
template_file = tmp_path / "template.md"
|
||||
wiki_file.write_text("plain\n", encoding="utf-8", newline="\n")
|
||||
template_file.write_text("plain\n", encoding="utf-8", newline="\n")
|
||||
|
||||
result = compare_md_file(wiki_file, template_file)
|
||||
|
||||
assert result.is_conflict is False
|
||||
assert result.current_hash == _sha("plain\n")
|
||||
assert result.template_hash == _sha("plain\n")
|
||||
|
||||
def test_unversioned_md_differs_is_conflict_with_hashes(self, tmp_path):
|
||||
wiki_file = tmp_path / "file.md"
|
||||
template_file = tmp_path / "template.md"
|
||||
wiki_file.write_text("mine\n", encoding="utf-8", newline="\n")
|
||||
template_file.write_text("theirs\n", encoding="utf-8", newline="\n")
|
||||
|
||||
result = compare_md_file(wiki_file, template_file)
|
||||
|
||||
assert result.is_conflict is True
|
||||
assert result.current_hash == _sha("mine\n")
|
||||
assert result.template_hash == _sha("theirs\n")
|
||||
|
||||
def test_versioned_md_has_no_hashes(self, tmp_path):
|
||||
wiki_file = tmp_path / "file.md"
|
||||
template_file = tmp_path / "template.md"
|
||||
_write_md(wiki_file, "1.0.0")
|
||||
_write_md(template_file, "2.0.0")
|
||||
|
||||
result = compare_md_file(wiki_file, template_file)
|
||||
|
||||
assert result.current_hash is None
|
||||
assert result.template_hash is None
|
||||
|
||||
|
||||
class TestSha256Report:
|
||||
"""Tests for the short-hash detail in the update report (SPEC 7.2.12.2)."""
|
||||
|
||||
def test_update_line_shows_short_hashes(self):
|
||||
result = FileComparisonResult(
|
||||
file_path=Path("utils/scripts/example.py"),
|
||||
current_hash="1a2b3c4d" + "0" * 56,
|
||||
template_hash="9f8e7d6c" + "0" * 56,
|
||||
needs_update=True,
|
||||
)
|
||||
output = format_check_update_output(UpdateSummary(files_to_update=[result]))
|
||||
|
||||
assert "example.py (sha256 1a2b3c4d -> 9f8e7d6c)" in output
|
||||
assert "0" * 56 not in output
|
||||
|
||||
def test_conflict_line_shows_short_hashes(self):
|
||||
result = FileComparisonResult(
|
||||
file_path=Path("notes.md"),
|
||||
current_hash="aaaaaaaa" + "1" * 56,
|
||||
template_hash="bbbbbbbb" + "1" * 56,
|
||||
is_conflict=True,
|
||||
update_path=Path("notes-update.md"),
|
||||
)
|
||||
output = format_check_update_output(UpdateSummary(conflicts=[result]))
|
||||
|
||||
assert "notes.md (sha256 aaaaaaaa -> bbbbbbbb) -> notes-update.md" in output
|
||||
|
||||
def test_version_line_keeps_versions(self):
|
||||
result = FileComparisonResult(
|
||||
file_path=Path("AGENTS.md"),
|
||||
current_version="1.0.0",
|
||||
template_version="2.0.0",
|
||||
is_conflict=True,
|
||||
update_path=Path("AGENTS-update.md"),
|
||||
)
|
||||
output = format_check_update_output(UpdateSummary(conflicts=[result]))
|
||||
|
||||
assert "AGENTS.md (1.0.0 -> 2.0.0) -> AGENTS-update.md" in output
|
||||
assert "sha256" not in output
|
||||
|
||||
def test_drifted_script_listed_with_hashes(self, template_wiki_pair, capsys):
|
||||
template, wiki = template_wiki_pair
|
||||
script = Path("utils") / "scripts" / "example.py"
|
||||
(template / script).parent.mkdir(parents=True, exist_ok=True)
|
||||
(template / script).write_text("print('new')\n", encoding="utf-8", newline="\n")
|
||||
(wiki / script).parent.mkdir(parents=True, exist_ok=True)
|
||||
(wiki / script).write_text("print('old')\n", encoding="utf-8", newline="\n")
|
||||
|
||||
assert check_update_main(directory=str(wiki)) == 0
|
||||
|
||||
out = capsys.readouterr().out
|
||||
short_cur = _sha("print('old')\n")[:8]
|
||||
short_tmpl = _sha("print('new')\n")[:8]
|
||||
assert f"(sha256 {short_cur} -> {short_tmpl})" in out
|
||||
|
||||
def test_json_carries_full_hashes(self, template_wiki_pair, capsys):
|
||||
template, wiki = template_wiki_pair
|
||||
script = Path("utils") / "scripts" / "example.py"
|
||||
(template / script).parent.mkdir(parents=True, exist_ok=True)
|
||||
(template / script).write_text("print('new')\n", encoding="utf-8", newline="\n")
|
||||
(wiki / script).parent.mkdir(parents=True, exist_ok=True)
|
||||
(wiki / script).write_text("print('old')\n", encoding="utf-8", newline="\n")
|
||||
_write_md(wiki / "AGENTS.md", "1.0.0", body="# Agents v1\n", name="agents")
|
||||
|
||||
assert check_update_main(directory=str(wiki), json_output=True) == 0
|
||||
output = json.loads(capsys.readouterr().out)
|
||||
|
||||
entry = output["files_to_update"][0]
|
||||
assert re.match(HEX64, entry["current_sha256"])
|
||||
assert entry["template_sha256"] == _sha("print('new')\n")
|
||||
conflict = output["conflicts"][0]
|
||||
assert conflict["current_sha256"] is None
|
||||
assert conflict["template_sha256"] is None
|
||||
|
||||
Reference in New Issue
Block a user