wiki update fix, themes versioning, readme refactor, graph ignore

This commit is contained in:
nvaldez
2026-10-01 16:58:19 +02:00
parent c45d4f1d2a
commit 44029aee90
15 changed files with 4453 additions and 3813 deletions
+366 -320
View File
@@ -1,90 +1,361 @@
# Fiona-Assistant
LLM Wiki Tool Helper for LLM Agents/Hives
> Your LLM agent writes the wiki. Fiona keeps it clean.
Fiona-Assistant is a command-line toolkit designed to manage, organize, and
maintain LLM wiki content with minimal AI token dependence. It combines
script-based automation with structured workflows to help LLM Agents and
Hives efficiently manage documentation, markdown files, and code quality.
Fiona-Assistant is a command-line toolkit for running an **llm-wiki**: a
folder of interlinked markdown that an AI agent builds and maintains for
you. You bring sources (web pages, PDFs, notes) and questions. The agent
compiles them into wiki pages. Fiona does every deterministic part of the
job: it scaffolds the wiki, ingests and archives sources, lints markdown,
frontmatter, Python, and JSON, checks links, draws a link graph, versions
everything in git, and tells the agent exactly what to fix next.
The result: the agent spends its tokens on reading and writing, not on
listing files, chasing broken links, or reformatting tables.
```bash
python -m pip install fiona-assistant
fiona-assistant wiki init my-wiki
cd my-wiki
fiona-assistant wiki ingest https://example.com/article.html
fiona-assistant housekeeping
```
---
## Overview
## Table of Contents
### Purpose
- [Why Fiona](#why-fiona)
- [Features](#features)
- [Quick Start](#quick-start)
- [How It Works](#how-it-works)
- [Command Reference](#command-reference)
- [Output Built for Agents](#output-built-for-agents)
- [Roadmap](#roadmap)
- [Development](#development)
- [Documentation](#documentation)
- [License](#license)
Fiona-Assistant serves as a **standalone MD/scripts/docs organizer** and
**LLM wiki management helper** that:
---
- **Reduces AI Token Usage**: Uses deterministic scripts and tools to handle
wiki management tasks that don't require LLM intelligence
- **Maintains Wiki Structure**: Enforces consistent organization of markdown
files, concepts, and raw source materials
- **Validates Content Quality**: Provides linting and diagnosis tools for markdown and Python code
- **Enables Script-Based Workflows**: Automates repetitive wiki maintenance tasks through CLI commands
## Why Fiona
### Core Philosophy
An LLM agent can maintain a knowledge base, but left alone it wastes
context on chores and slowly breaks things: dead links, missing
frontmatter, wrapped table rows, orphan pages, overwritten sources.
> Use scripts for deterministic tasks, reserve AI tokens for creative and analytical work
Fiona fixes that split of work:
The toolkit is designed to be **AI-friendly** - outputs are formatted in
consistent, parseable structures that LLMs can easily read and process.
| The agent does | Fiona does |
| --- | --- |
| Reads sources and writes synthesized pages | Fetches, archives, and converts sources to markdown |
| Decides what links to what | Finds dead links, dead wikilinks, and orphan pages |
| Refines raw pages | Lints markdown, frontmatter, Python, and JSON |
| Answers your questions from the wiki | Commits, snapshots, and restores wiki history |
| Merges template updates | Detects template updates and never overwrites your files |
> Use scripts for deterministic tasks. Reserve AI tokens for creative and
> analytical work.
---
## Features
### Tool Suite
### Wiki in one command
| Tool | Purpose | Key Capabilities |
| ---- | ------- | ---------------- |
| **Librarian** | Wiki content management | List files, scan directories, organize MD content |
| **MDoctor** | Markdown diagnosis | Lint markdown files using PyMarkdown, detect formatting issues |
| **Python-Ruff** | Code quality | Lint Python files using Ruff, enforce code standards |
| **Generate-TOC** | Table of contents | Auto-generate nested TOC from markdown headers |
`fiona-assistant wiki init` creates a ready-to-use llm-wiki: directory
layout, settings, agent rules (`AGENTS.md`), page schema, index, log, and
bundled agent skills. It also creates a git repository and makes the
first commit, with `personal/` kept out of version control.
### Wiki Structure Support
### Source ingestion
Fiona-Assistant understands and maintains the [LLM Wiki directory structure](./src/fiona/data/llm_wiki/AGENTS.md):
`fiona-assistant wiki ingest <url-or-file>` turns a source into a wiki page
in one step:
```text
llm-wiki/
├── ingest/ # Input zone: files to be processed
├── raw/ # Archived source materials (read-only)
│ ├── articles/
│ ├── papers/
│ ├── transcripts/
│ └── assets/
├── wiki/ # Processed content
│ └── concepts/ # Synthesized concept notes
├── personal/ # User notes (read-only for agents)
└── utils/ # Utility scripts
```
- Downloads the URL or reads the local file
- Archives an untouched copy under `raw/` (duplicates are detected by
SHA-256, so the same bytes are never stored twice)
- Converts it to markdown (HTML, PDF, plain text, and markdown ship today)
- Writes a page under `wiki/` with full provenance in its frontmatter and
`status: raw`, so the agent knows it still needs refining
- Appends the action to `wiki/log.md`
`wiki ingest --pending` lists every page still waiting to be refined.
### One-call maintenance
`fiona-assistant housekeeping` runs the whole maintenance routine and
prints a to-do list for the agent:
- **check-update**: is the packaged template newer than this wiki?
- **merge**: which `*-update.md` files are waiting to be merged?
- **ingest**: which pages are still `status: raw`?
- **sanity**: which lint checks fail, and where?
- **graph**: regenerates `wiki_graph.html` and lists orphan pages
It only reads, except for writing the graph. Every finding comes with a
concrete "next step" the agent can act on. Add `--json` for machine use.
### Quality checks
`fiona-assistant wiki sanity` runs five checks in parallel and gives one
pass/fail verdict:
| Check | What it catches |
| --- | --- |
| `markdownlint` | Markdown style, via PyMarkdown |
| `frontmatter_lint` | Missing or malformed YAML frontmatter (`name`, `version`, and more) |
| `python-ruff` | Python issues in wiki scripts, via Ruff |
| `mdlinter` | Dead links, dead `[[wikilinks]]`, and table rows split across lines |
| `jsonlint` | JSON syntax, indentation, trailing commas, duplicate keys |
Each linter is also available on its own, and `mdoctor fix` and
`json-lint fix` repair what they can automatically.
### Interactive link graph
`fiona-assistant wiki graph` writes a single self-contained HTML file
that shows how your pages link to each other. Nodes are scored by how
many different pages point at them, so hub pages stand out. It
understands markdown links and `[[wikilinks]]`, shows external URLs, and
flags broken links and orphans. `--format json` exports the same graph
for other tools.
### Safe template updates
As Fiona improves, so does its wiki template. `wiki check-update` shows
what changed, and `wiki update` brings your wiki up to date without ever
overwriting a file you own. When both sides changed, Fiona writes
`<name>-update.md` next to your file and `housekeeping` tells the agent
to merge it.
### Git history built in
`fiona-assistant git` wraps the operations an agent needs, with
timestamped commit messages:
- `save` commits all current edits
- `snapshot <name>` commits and tags a restore point
- `restore <name>` returns to a snapshot without losing history
- `undo`, `clean`, and `status` for everyday recovery
### Guardrails
- `personal/` and `raw/` are read-only for every automated tool. Ingest
may add new files to `raw/`; it never changes an existing one.
- Commands that need a decision prompt on a terminal and accept
`--yes`, `--force`, or `--non-interactive` for unattended runs.
- Respects `.gitignore` when scanning.
### Table of contents generation
`fiona-assistant librarian toc` builds `table_of_contents.md` for a folder
tree. `librarian toc file <path>` keeps an in-file TOC under the H1 up to
date, with optional section numbering (`--sectionized`).
---
## Installation
## Quick Start
### Quick Install (Production)
### 1. Install
Requires Python 3.11 or newer.
```bash
python -m pip install fiona-assistant
```
### Development Setup
### 2. Create a wiki
- **Clone the repository:**
```bash
fiona-assistant wiki init my-wiki
cd my-wiki
```
### 3. Point your agent at it
Open the folder in your AI coding agent (Cursor, Claude Code, or any
agent that reads `AGENTS.md`). The bundled `AGENTS.md` loads the Fiona
skill, which teaches the agent the ingest, refine, and housekeeping
workflow and when to call each command.
### 4. Feed it sources
```bash
fiona-assistant wiki ingest https://example.com/post.html
fiona-assistant wiki ingest ./notes/meeting.pdf
```
Then ask the agent to refine the new pages.
### 5. Keep it healthy
```bash
fiona-assistant housekeeping
fiona-assistant git save --description "ingest meeting notes"
```
---
## How It Works
A wiki created by Fiona has this layout:
```text
my-wiki/
├── AGENTS.md # Entry point for the agent; loads the Fiona skill
├── fiona-settings.json # Marks the wiki root; tool settings
├── ingest/ # Drop zone for files waiting to be parsed
├── raw/ # Immutable archive of original sources
│ ├── articles/
│ ├── papers/
│ ├── transcripts/
│ ├── assets/
│ └── other/
├── wiki/ # Pages the agent writes and maintains
│ ├── schema.md # Page types, tags, conventions
│ ├── index.md # Content catalog
│ ├── log.md # Append-only action log
│ ├── concepts/
│ ├── entities/
│ ├── comparisons/
│ ├── queries/
│ └── sources/
├── personal/ # Your own notes (read-only for agents, untracked)
└── utils/ # Agent skills, personas, and helper scripts
```
The cycle is:
- **Ingest**: `wiki ingest` archives a source in `raw/` and writes a raw
page in `wiki/`.
- **Refine**: the agent rewrites the page, links it to related pages, and
sets `status: refined`.
- **Maintain**: `housekeeping` reports what needs attention; the agent
fixes it.
- **Save**: `git save` records the change.
The full page schema lives in the template's
[schema](./src/fiona/data/llm_wiki/wiki/schema.md).
---
## Command Reference
Run `fiona-assistant --help` or `fiona-assistant <command> --help` for all
flags. Commands that take an optional directory default to the current
directory.
### Wiki lifecycle
| Command | What it does |
| --- | --- |
| `wiki init [dir]` | Create a new llm-wiki with git history |
| `wiki ingest <source>` | Fetch, archive, and convert a URL or file into a raw page |
| `wiki ingest --pending` | List pages still marked `status: raw` |
| `wiki sanity [dir]` | Run every quality check; exit 1 on failure |
| `wiki graph [dir]` | Write `wiki_graph.html` (or JSON with `--format json`) |
| `wiki check-update [dir]` | Show what a template update would change |
| `wiki update [dir]` | Apply a template update (`--dry-run`, `--yes`) |
| `housekeeping [dir]` | Run the full maintenance routine and list next steps |
### Linters
| Command | What it does |
| --- | --- |
| `mdoctor chklint [dir]` | Markdown lint via PyMarkdown |
| `mdoctor fix [dir]` | Auto-fix markdown lint violations |
| `fmlint chklint [dir]` | Frontmatter lint |
| `python-ruff chklint [dir]` | Python lint via Ruff |
| `json-lint chklint [dir]` | JSON lint |
| `json-lint fix [dir]` | Auto-fix JSON indentation and trailing commas |
### Files and TOC
| Command | What it does |
| --- | --- |
| `librarian list [dir]` | List files in a directory |
| `librarian toc [dir]` | Write `table_of_contents.md` (`--recursive-toc`, `--exclude REGEX`) |
| `librarian toc file <path>` | Write an in-file TOC below the H1 (`--sectionized`) |
| `librarian toc file '*'` | Update in-file TOCs for every markdown file in the wiki |
### Git
| Command | What it does |
| --- | --- |
| `git save --description TEXT` | Commit all edits |
| `git snapshot <name> --description TEXT` | Commit and tag a restore point |
| `git restore <name>` | Restore a snapshot as a new commit |
| `git undo` | Drop the last commit |
| `git clean` | Discard uncommitted edits |
| `git status` | Show whether the tree is clean |
Every command above is run as `fiona-assistant <command>`. The
`librarian` and `mdoctor` tools are also installed as standalone
commands.
---
## Output Built for Agents
Every report uses the same shape: a header, the target, rule
definitions, findings per file with line and column, and a summary. An
agent can parse it without guessing, and a human can skim it.
```text
Markdown Lint Violations
TARGET: wiki
- DEFINITIONS:
- MDL001: Dead Link, Relative markdown link does not resolve to an existing file
- MDL002: Dead Wiki Link, Wiki-internal link does not resolve to any md page in the wiki
- FILE: wiki/concepts/retrieval.md
- MDL001 line 12: ../sources/old-paper.md does not exist
- MDL002 line 30: [[embeddings]] does not resolve to any page
- SUMMARY:
- Total files with violations: 1
- Total violations: 2
```
`wiki sanity`, `housekeeping`, `wiki ingest`, `wiki check-update`, and
`wiki update` also accept `--json` for structured output.
---
## Roadmap
Planned work, tracked with requirements and acceptance criteria in
[SPEC](./SPEC.md) and prioritized in [todo](./todo.md):
| Feature | What it will do |
| --- | --- |
| Wiki root discovery | Run any command from a subfolder; Fiona finds the nearest `fiona-settings.json` |
| Backup | One command writes a compressed, restorable archive of the wiki outside the tree |
| `setup` command | Interactive review and editing of `fiona-settings.json`, with validation |
| Smarter graph | Show only important nodes until you expand a parent; hide gitignored pages |
| Code blocks in markdown | Lint Python and shell snippets inside fenced code blocks |
| Shellcheck | Lint shell scripts as part of wiki sanity |
| HTML and JavaScript lint | Validate HTML and JS files in the wiki |
| `python-ruff fix` | Auto-fix Python lint findings |
| More converters | Ingest more source formats beyond HTML, PDF, text, and markdown |
| Version tags for scripts | Track versions of Python and shell files like markdown pages |
---
## Development
### Set up
Clone the repository and load the environment with the bootstrap script.
Linux and macOS:
```bash
git clone <repository-url>
cd fiona-assistant
```
- **Create and activate the virtual environment:**
Linux / macOS:
```bash
source bootstrap --env fiona_env -c
```
@@ -95,296 +366,71 @@ python -m pip install fiona-assistant
. .\bootstrap.ps1 --env fiona_env -c
```
> Make sure `fiona_env` is activated before proceeding. On Windows the
> environment lives in `.venvs\fiona_env`.
The default install is editable (`pip install -e ".[dev]"`). On Windows
the environment lives in `.venvs\fiona_env`.
### Local install (not editable)
### Other install modes
Install this checkout as a normal package. The default bootstrap install
is editable (`pip install -e ".[dev]"`).
| Goal | Bash | PowerShell |
| --- | --- | --- |
| Install this checkout as a normal package | `source bootstrap --local` | `. .\bootstrap.ps1 --local` |
| Same as `pip install fiona-assistant`, no venv | `source bootstrap --local --no-env` | `powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1 --local --no-env` |
`--local --no-env` runs `python -m pip install --user .`. If
`fiona-assistant` is not found afterwards, add the user scripts
directory printed by bootstrap to `PATH`.
### Test and check
```bash
source bootstrap --local
# Unit tests with coverage
python scripts/run_tests.py
# Full sanity: tests, coverage gate, markdown, Ruff, frontmatter, JSON
python scripts/run_sanity.py --non-interactive
```
```powershell
. .\bootstrap.ps1 --local
```
Contributions follow the spec-first, test-first lifecycle in
[AGENTS](./AGENTS.md).
### Same as `pip install fiona-assistant`
`--local --no-env` installs this repository the same way
`python -m pip install fiona-assistant` does. Pip builds a wheel from
this directory and installs it into your user site-packages. The
`fiona-assistant` command then runs with no virtual environment. The
flag name is `--no-env`.
```bash
source bootstrap --local --no-env
```
```powershell
powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1 --local --no-env
```
That command is `python -m pip install --user .` from the repository
root. The package files are the ones in this checkout. If the command
is not found, add the user scripts directory printed by bootstrap to
`PATH`.
---
## Usage
### Main CLI
Fiona-Assistant provides a unified CLI with multiple subcommands:
```bash
# Show all available commands
fiona-assistant --help
# Run via Python module
python -m fiona --help
```
#### Available Commands
```bash
# Run tests
fiona-assistant test
# Manage wiki content with Librarian
fiona-assistant librarian [directory]
# Generate an in-file table of contents below the H1
fiona-assistant librarian toc file <path_to_file>
# Force section numbering on for the run
fiona-assistant librarian toc file <path_to_file> --sectionized
# Generate in-file TOCs for every md file in the current directory / wiki root
fiona-assistant librarian toc file '*'
# Diagnose markdown files with MDoctor
fiona-assistant mdoctor [chklint] [directory]
# Lint Python code with Ruff
fiona-assistant python-ruff [chklint] [directory]
```
### Direct Tool Access
Each tool can also be called directly:
```bash
# Librarian - List all files in a directory
librarian [directory]
# MDoctor - Check markdown lint violations
mdoctor chklint [directory]
# MDoctor - List all files
# Python-Ruff - Check Python code quality
python-ruff chklint [directory]
# Generate table of contents for markdown files
generate-toc [directory] [options]
```
---
## Workflow Examples
### Wiki Ingestion Workflow
```bash
# 1. Drop raw files into ingest directory
# (Manual or automated process)
# 2. List files ready for processing
librarian llm-wiki/ingest
# 3. Validate markdown quality before processing
mdoctor chklint llm-wiki/ingest
# 4. Move processed files to raw archive
# (Agent/orchestration task)
```
### Content Maintenance Workflow
```bash
# Check all markdown files in wiki for lint violations
mdoctor chklint llm-wiki/wiki
# Generate table of contents for concept notes
generate-toc llm-wiki/wiki/concepts --recursive-toc
# Validate Python code in the project
python-ruff chklint src/
# List all markdown files for inventory
librarian llm-wiki/
```
### Standalone Document Organization
```bash
# Organize any directory of markdown files
librarian /path/to/docs/
# Validate markdown formatting
mdoctor chklint /path/to/docs/
# Create nested table of contents
generate-toc /path/to/docs/ --recursive-toc
```
---
## Output Format
All tools produce **AI-friendly output** with consistent formatting:
### MDoctor Output Format
```text
PyMarkdownLint Violations
TARGET: /path/to/directory
- DEFINITIONS:
- md001: Heading levels should only increment by one, Heading levels should only increment by one level at a time
- md013: Line length, Line length
- FILE: file1.md
- 10:5 md013
- 20:3 md001
- SUMMARY:
- Total files with violations: 1
- Total violations: 2
```
### Python-Ruff Output Format
```text
Ruff Violations
TARGET: /path/to/directory
Definitions:
- F401: `*` import used, but not imported
- E501: Line too long
- FILE: script.py
- 15:10 F401
- 25:80 E501
- SUMMARY:
- Total files with violations: 1
- Total violations: 2
```
---
## Project Structure
### Project structure
```text
fiona-assistant/
├── src/fiona/ # Installable package
│ ├── __main__.py # Unified command dispatcher
│ ├── librarian/ # Wiki content management
│ ├── mdoctor/ # Markdown diagnosis
│ ├── python_ruff/ # Python code linting
│ ├── customlinter/ # Custom linters
├── src/fiona/ # The installable package
│ ├── __main__.py # fiona-assistant CLI
│ ├── librarian/ # File listing and TOC generation
│ ├── mdoctor/ # Markdown lint and fix
│ ├── customlinter/ # Frontmatter, markdown link, Python, JSON linters
│ ├── python_ruff/ # Ruff wrapper
│ ├── gittool/ # Git operations
│ ├── sanity_runner/ # Shared sanity engine
│ ├── wiki/ # Wiki lifecycle
│ ├── wiki/ # init, update, sanity, graph, ingest, housekeeping
│ └── data/llm_wiki/ # Packaged wiki template
│ ├── AGENTS.md # Agent rules and directory permissions
│ ├── ingest/ # Input zone for new content
│ ├── raw/ # Archived source materials
│ ├── wiki/ # Processed concept notes
│ └── utils/ # Utility scripts
├── tests/ # Unit tests (not installed)
├── scripts/ # Repo tooling (not installed)
│ ├── run_tests.py
│ ├── run_sanity.py
│ └── settings_dev.json
├── pyproject.toml # Project configuration
├── bootstrap # Environment setup script (bash)
├── bootstrap.ps1 # Environment setup script (PowerShell)
├── LICENSE # GPL-3.0-only
└── README.md # This file
├── scripts/ # Test and sanity runners, dev settings
├── bootstrap # Environment setup (bash)
├── bootstrap.ps1 # Environment setup (PowerShell)
├── SPEC.md # Requirements and acceptance criteria
└── pyproject.toml
```
---
## Testing
## Documentation
### Run Tests
```bash
# Run all tests
python scripts/run_tests.py
# Or use pytest directly
python -m pytest
# Run with coverage
python -m pytest --cov=src/fiona
```
- [Project Specification](./SPEC.md): every command, setting, and rule,
with acceptance criteria
- [LLM Wiki Agent Rules](./src/fiona/data/llm_wiki/AGENTS.md): what a
deployed wiki tells its agent
- [Fiona skill](./src/fiona/data/llm_wiki/utils/skills/fiona/SKILL.md):
the workflow the agent follows inside a wiki
- [Development Agent Rules](./AGENTS.md): how to contribute to this
repository
- [Roadmap](./todo.md): planned and in-progress work
---
## License
GPL-3.0-only
---
## Key Concepts
### For LLM Agents
- **Deterministic Operations**: Use Fiona-Assistant for file listing, linting, and organization
- **Token Efficiency**: Reserve LLM context for synthesis, analysis, and creative tasks
- **Structured Output**: All tool outputs are formatted for easy parsing by LLMs
### For Human Users
- **CLI-First**: All functionality available through command-line interface
- **Composable Tools**: Combine tools in scripts for automated workflows
- **Clear Structure**: Maintains consistent wiki organization standards
---
## Related Documentation
- [LLM Wiki Agent Rules](./src/fiona/data/llm_wiki/AGENTS.md) - Directory permissions and workflow rules
- [Development Setup](./src/README.md) - Detailed development information
- [Project Specification](./SPEC.md) - Feature spec sheet with requirements and acceptance criteria
- [Project TODO](./todo.md) - Roadmap and planned features
---
## Quick Reference Card
| Task | Command |
| ---- | ------- |
| Show help | `fiona-assistant --help` |
| List files | `fiona-assistant librarian /path/to/dir` |
| Check MD lint | `fiona-assistant mdoctor chklint /path/to/dir` |
| Check Python lint | `fiona-assistant python-ruff chklint /path/to/dir` |
| Generate TOC | `generate-toc /path/to/dir --recursive-toc` |
| Generate file TOC | `fiona-assistant librarian toc file /path/to/file.md --sectionized` |
| Run tests | `python scripts/run_tests.py` |
| Install | `pip install fiona-assistant` |
| Dev install | `pip install -e .` |
| Local install | `bootstrap --local` |
| Install like `pip install fiona-assistant` | `bootstrap --local --no-env` |
---
> **Note**: All paths are relative to the current working directory unless specified as absolute paths.
+106 -14
View File
@@ -1,6 +1,6 @@
---
name: Fiona-Assistant Specification
version: 1.1.0
version: 1.2.0
title: Project Spec Sheet
created: 2026-09-23
updated: 2026-10-01
@@ -39,7 +39,7 @@ type: summary
- [5. Settings Schema](#5-settings-schema)
- [5.1. fiona-settings.json](#51-fiona-settingsjson)
- [5.2. settings_dev.json](#52-settings_devjson)
- [5.3. constellation-settings.json](#53-constellation-settingsjson)
- [5.3. constellation themes](#53-constellation-themes)
- [6. Violation Rule Catalog](#6-violation-rule-catalog)
- [6.1. Shared Report](#61-shared-report)
- [6.2. Frontmatter Fields and FML Codes](#62-frontmatter-fields-and-fml-codes)
@@ -109,7 +109,10 @@ leaves that requirement unbuilt. Revision 0.99.0 builds `wiki ingest`
module and moves Non-Goals, Priority Order, and Open Questions
to Appendices A, B, and C. Revision 1.1.0 treats a differing
`fiona-settings.json` as a conflict and writes
`fiona-settings-update.json` (*7.1.2.3.*).
`fiona-settings-update.json` (*7.1.2.3.*). Revision 1.2.0 folds
text line endings before the SHA-256 compare (*7.1.2.13.*) and
writes `corefiles-update.json` so a later update does not list a
core file whose version and hashes are unchanged (*7.1.2.14.*).
Each feature section starts with a `Status` line. Requirements use
`- *N.M.K.*`. Each `*acceptance*` sits under the requirement it tests.
@@ -273,6 +276,11 @@ the text `fiona.llm-wiki.ignore_files must be a list of strings`.
AGENTS.md
README.md
fiona-settings.json
constellation/colorful.json
constellation/dark.json
constellation/grayscale.json
constellation/night-sky.json
constellation/professional.json
table_of_contents.md
ingest/README.md
personal/README.md
@@ -320,6 +328,7 @@ Core directories (every file under them is core):
- `personal/`
- `raw/`
- `utils/`
- `constellation/`
Read-only zones, including the zone directory itself:
@@ -337,7 +346,10 @@ newer version, it writes `<stem>-update.md` beside the file and
leaves the owner's file as it is. A differing
`fiona-settings.json` is the same kind of conflict: the owner's
file stays, and the template is written as
`fiona-settings-update.json` (*7.1.2.3.*). It never deletes user files. It
`fiona-settings-update.json` (*7.1.2.3.*). A confirmed update
that changes or reports anything also writes `corefiles-update.json`
at the wiki root (*7.1.2.14.*). That file is not part of the
template. It never deletes user files. It
never writes inside a read-only zone, so a missing file under
`personal/` or `raw/` is not added back. It
never writes a path matched by the repository `.gitignore` or by
@@ -670,6 +682,11 @@ Merge each <stem>-update<suffix> into its file: run fiona-assistant housekeeping
}
```
A confirmed update that had something to report writes
`corefiles-update.json` at the wiki root (*7.1.2.14.*).
`check-update` and `--dry-run` do not. A pristine wiki still
writes nothing (*7.1.2.5.*).
Comparison and merge rules are section 7.1.2.
#### 4.7.4. wiki sanity
@@ -1149,12 +1166,18 @@ newline, then delete the update file.
- *acceptance*: Raising the number in this file flips a green run
to failed with no code change.
### 5.3. constellation-settings.json
### 5.3. constellation themes
Themes for the wiki graph. The file has a `themes` object. `colorful`
is complete. Any other theme may omit keys. A missing key is taken
from `colorful`. A `dark` object on a theme is the same kind of
partial theme, used when the page is in dark mode.
Themes for the wiki graph live in `constellation/`. Each theme is
one JSON file. The file name without `.json` is the theme name.
`colorful` is complete and listed first. The other names follow
in alphabetical order. Any other theme may omit keys. A missing
key is taken from `colorful`. A `dark` object on a theme is the
same kind of partial theme, used when the page is in dark mode.
Each file has a `version` string (semver). Bump it when that
theme changes. `version` is not a color key. A theme that omits
it does not take `colorful`'s version.
`colorful` is a warm paper field. Nodes run from warm gray
through amber to crimson. Edges use that same warm ramp, darker
@@ -1199,6 +1222,7 @@ buttons, and a quiet radius.
| `shapes.page` | `circle`, `cloud`, or `star` |
| `shapes.external` | Shape for an external-link node |
| `subtitle_color` | Label under a large node |
| `version` | Semver of this theme file. Not a color key |
`subtitle.padding` is 12 when absent. `subtitle.size` is 11 when
absent or below 1. `subtitle.on_top` and `subtitle.outline` are
@@ -1217,6 +1241,29 @@ A theme that sets only some of these keeps the rest from
- *acceptance*: The resolved grayscale subtitle padding, size,
`on_top`, and outline match `colorful`. The graph HTML reads
those keys from the theme.
- *5.3.3.* Each theme is one JSON file in `constellation/`. The
name is the file stem. `colorful` is first in the catalog. The
other names follow in alphabetical order. Each file has a
`version` string. Filling a theme does not copy `version` from
`colorful`, in the loader or in the page script.
- *acceptance*: The template has `constellation/colorful.json`,
`constellation/night-sky.json`, `constellation/grayscale.json`,
`constellation/dark.json`, and `constellation/professional.json`,
and no `constellation-settings.json`. Each resolved packaged
theme `version` equals the `version` in its file. A theme
object that omits `version` has no `version` after it is
filled from `colorful`.
- *5.3.4.* A `constellation/` directory at the wiki, or in a
parent, overlays the packaged themes. Each JSON file there
overlays the theme of the same name. `constellation-settings.json`
in that same directory overlays those files. The nearest
directory that has either source wins. A theme file that is
not a JSON object is skipped.
- *acceptance*: `constellation/night-sky.json` setting
`background` changes that key and keeps the packaged page
shape. A `constellation-settings.json` beside it replaces
`background` with its own value. A file of `{` does not
remove `colorful`.
---
@@ -1561,7 +1608,8 @@ Implements sections 4.7.2 and 4.7.3.
`fiona-settings-update.json`. Relative links in the template still
resolve from that directory.
- *acceptance*: A conflict on `wiki/schema.md` writes
`wiki/schema-update.md` and no other file.
`wiki/schema-update.md` and `corefiles-update.json`, and no
other file.
- *7.1.2.11.2.* The update file holds the template text with
`DATE_PLACEHOLDER` expanded, as `wiki init` would write it. An
existing update file is replaced with the current template
@@ -1580,10 +1628,10 @@ Implements sections 4.7.2 and 4.7.3.
with the owner's body, check-update lists no conflict for it.
- *7.1.2.12.* A file without version control, meaning a markdown file
with no `version` on either side or any non-markdown file, is
compared by SHA-256. The wiki side hashes the file's bytes. The
template side hashes the text `wiki init` would write: UTF-8 with
`DATE_PLACEHOLDER` expanded and line endings kept, or the raw
bytes for a binary file.
compared by SHA-256. The wiki side and the template side both use
the text hash in *7.1.2.13.*. The template side expands
`DATE_PLACEHOLDER` before that hash. A binary file hashes its raw
bytes.
- *7.1.2.12.1.* Equal hashes: the file is up to date and is not
listed.
- *acceptance*: A freshly initialized wiki reports
@@ -1598,6 +1646,50 @@ Implements sections 4.7.2 and 4.7.3.
`utils/scripts/example.py (sha256 <8 hex> -> <8 hex>)`, and a
markdown file with no `version` that differs is a conflict with
the same parenthesis.
- *7.1.2.13.* The SHA-256 of a UTF-8 text file is the digest of that
text after every `\r\n` and every lone `\r` is folded to `\n`,
then encoded as UTF-8. Two text files that differ only in line
endings are equal. A file that is not valid UTF-8 hashes its raw
bytes, with no folding.
- *acceptance*: `fiona-settings.json` saved with CRLF against a
template saved with LF, with the same characters, is not a
conflict and is absent from the check-update report.
- *7.1.2.14.* A confirmed `wiki update` that had a file to update,
add, or conflict writes `corefiles-update.json` at the wiki root.
`check-update` and `--dry-run` do not write it. A pristine wiki
writes nothing (*7.1.2.5.*). The file is not part of the template
and is never itself an update, a conflict, or an addition. It is
one JSON object:
```json
{
"files": {
"<relative posix path>": {
"version": "<owner version or null>",
"template_version": "<template version or null>",
"sha256": "<64 hex>",
"template_sha256": "<64 hex>",
"date": "YYYY-MM-DD"
}
}
}
```
Each entry is a core file the update compared, using that file's
bytes after the update. `date` is the UTC day the entry was
written. A later check does not list a core file while its owner
version, template version, owner hash, and template hash still
match that entry, including a second update on the same day. The
date does not expire the entry. A missing record, or a record that
is not this object, acknowledges nothing. When the owner file or
the template changes, the file is listed again.
- *acceptance*: After `wiki update --yes` on a drifted
`fiona-settings.json`, `corefiles-update.json` names
`fiona-settings.json` with `version` null, both 64-digit hashes,
and the UTC date. A second check-update does not list that file.
Editing the owner file lists it again.
- *acceptance*: `wiki update --dry-run` does not create
`corefiles-update.json`.
#### 7.1.3. wiki sanity
@@ -1,329 +0,0 @@
{
"themes": {
"colorful": {
"background": "#f4efe6",
"graph_background": "#fffdf8",
"font_family": "Arial, sans-serif",
"text_color": "#2c2416",
"node_colors": {
"low": "#8f8272",
"mid": "#e0943a",
"high": "#c23b4a"
},
"node_stroke": "none",
"node_radius": {
"min": 5,
"max": 40
},
"edge_colors": {
"low": "#a89884",
"mid": "#b86a1a",
"high": "#8e2436"
},
"edge_width": 1,
"highlight": {
"node_color": "#2aa7a1",
"edge_color": "#0d6e74",
"size_multiplier": 1.3
},
"clicked": {
"node_color": "#0e6b66"
},
"buttons": {
"background": "#0f6e78",
"text": "#fffdf8",
"hover": "#0b555c",
"disabled": "#b7aea3"
},
"card": {
"background": "#fffdf8",
"border": "#e0d3c2"
},
"shapes": {
"page": "circle",
"external": "cloud"
},
"subtitle_color": "#2c2416",
"subtitle": {
"min_radius": 0.8,
"padding": 2,
"size": 6,
"on_top": true,
"outline": false,
"outline_color": "#fffdf8",
"outline_width": 3
}
},
"night-sky": {
"background": "#070b14",
"graph_background": "#0b1020",
"font_family": "Segoe UI, sans-serif",
"text_color": "#d6def5",
"node_colors": {
"low": "#8ea2c8",
"mid": "#ffe9a0",
"high": "#ffffff"
},
"node_stroke": "none",
"node_radius": {
"min": 3,
"max": 20
},
"edge_colors": {
"low": "#243056",
"mid": "#7f8cbf",
"high": "#e7ecff"
},
"edge_width": 1,
"highlight": {
"node_color": "#fff6c2",
"edge_color": "#9ecbff",
"size_multiplier": 1.6
},
"clicked": {
"node_color": "#ffd56a"
},
"buttons": {
"background": "#1e2a4a",
"text": "#e8eeff",
"hover": "#314572",
"disabled": "#3a4258"
},
"card": {
"background": "#12182b",
"border": "#2a3558"
},
"shapes": {
"page": "circle",
"external": "star"
},
"subtitle_color": "#d5def8",
"subtitle": {
"min_radius": 0.8,
"padding": 2,
"size": 6,
"on_top": true,
"outline": false,
"outline_color": "#0b1020",
"outline_width": 3
}
},
"grayscale": {
"background": "#e6e6e6",
"graph_background": "#f4f4f4",
"font_family": "Arial, sans-serif",
"text_color": "#141414",
"node_colors": {
"low": "#5a5a5a",
"mid": "#2e2e2e",
"high": "#0d0d0d"
},
"node_stroke": "#141414",
"node_radius": {
"min": 5,
"max": 36
},
"edge_colors": {
"low": "#8f8f8f",
"mid": "#3d3d3d",
"high": "#141414"
},
"edge_width": 1,
"highlight": {
"node_color": "#000000",
"edge_color": "#1a1a1a",
"size_multiplier": 1.4
},
"clicked": {
"node_color": "#000000"
},
"buttons": {
"background": "#2a2a2a",
"text": "#ffffff",
"hover": "#111111",
"disabled": "#b0b0b0"
},
"card": {
"background": "#ffffff",
"border": "#8a8a8a"
},
"shapes": {
"page": "circle",
"external": "cloud"
},
"subtitle_color": "#141414",
"subtitle": {
"min_radius": 0.8,
"padding": 2,
"size": 6,
"on_top": true,
"outline": false,
"outline_color": "#f4f4f4",
"outline_width": 3
},
"dark": {
"background": "#2c2c2c",
"graph_background": "#3a3a3a",
"font_family": "Arial, sans-serif",
"text_color": "#f5f5f5",
"node_colors": {
"low": "#8d8d8d",
"mid": "#fff4c4",
"high": "#f5b44a"
},
"node_stroke": "none",
"node_radius": {
"min": 5,
"max": 36
},
"edge_colors": {
"low": "#6e6e6e",
"mid": "#c4c4c4",
"high": "#ffffff"
},
"edge_width": 1,
"highlight": {
"node_color": "#ffffff",
"edge_color": "#ffffff",
"size_multiplier": 1.4
},
"clicked": {
"node_color": "#ffffff"
},
"buttons": {
"background": "#e8e8e8",
"text": "#1a1a1a",
"hover": "#ffffff",
"disabled": "#5a5a5a"
},
"card": {
"background": "#454545",
"border": "#9a9a9a"
},
"shapes": {
"page": "circle",
"external": "cloud"
},
"subtitle_color": "#f5f5f5",
"subtitle": {
"min_radius": 0.5,
"padding": 2,
"size": 8,
"on_top": true,
"outline": true,
"outline_color": "#2c2c2c",
"outline_width": 3
}
}
},
"dark": {
"background": "#1e2836",
"graph_background": "#283448",
"font_family": "Segoe UI, sans-serif",
"text_color": "#e7eef8",
"node_colors": {
"low": "#7d8da3",
"mid": "#fff4c4",
"high": "#f7d67c"
},
"node_stroke": "none",
"node_radius": {
"min": 4,
"max": 24
},
"edge_colors": {
"low": "#51627a",
"mid": "#8fa3bd",
"high": "#d5e2f2"
},
"edge_width": 1,
"highlight": {
"node_color": "#f3d48a",
"edge_color": "#9ec5ea",
"size_multiplier": 1.45
},
"clicked": {
"node_color": "#ffe3a3"
},
"buttons": {
"background": "#3e5674",
"text": "#f4f8fc",
"hover": "#527094",
"disabled": "#2a3648"
},
"card": {
"background": "#31445c",
"border": "#5c7390"
},
"shapes": {
"page": "circle",
"external": "cloud"
},
"subtitle_color": "#e7eef8",
"subtitle": {
"min_radius": 0.8,
"padding": 2,
"size": 6,
"on_top": true,
"outline": false,
"outline_color": "#283448",
"outline_width": 3
}
},
"professional": {
"background": "#f7fafc",
"graph_background": "#fcfdfe",
"font_family": "Segoe UI, Calibri, Helvetica Neue, Arial, sans-serif",
"text_color": "#4a5d70",
"node_colors": {
"low": "#e4eef4",
"mid": "#a9c6d8",
"high": "#7eabc4"
},
"node_stroke": "#9bb8cb",
"node_radius": {
"min": 4,
"max": 26
},
"edge_colors": {
"low": "#e7f0f5",
"mid": "#b7d0de",
"high": "#8eb4c9"
},
"edge_width": 1,
"highlight": {
"node_color": "#6aa3c0",
"edge_color": "#7eabc4",
"size_multiplier": 1.15
},
"clicked": {
"node_color": "#5b93b0"
},
"buttons": {
"background": "#8eb4c9",
"text": "#ffffff",
"hover": "#7aa6bd",
"disabled": "#dce7ee"
},
"card": {
"background": "#ffffff",
"border": "#e6eef3"
},
"shapes": {
"page": "circle",
"external": "cloud"
},
"subtitle_color": "#4a5d70",
"subtitle": {
"min_radius": 0.8,
"padding": 2,
"size": 6,
"on_top": true,
"outline": false,
"outline_color": "#fcfdfe",
"outline_width": 3
}
}
}
}
@@ -0,0 +1,55 @@
{
"version": "1.0.0",
"background": "#f4efe6",
"graph_background": "#fffdf8",
"font_family": "Arial, sans-serif",
"text_color": "#2c2416",
"node_colors": {
"low": "#8f8272",
"mid": "#e0943a",
"high": "#c23b4a"
},
"node_stroke": "none",
"node_radius": {
"min": 5,
"max": 40
},
"edge_colors": {
"low": "#a89884",
"mid": "#b86a1a",
"high": "#8e2436"
},
"edge_width": 1,
"highlight": {
"node_color": "#2aa7a1",
"edge_color": "#0d6e74",
"size_multiplier": 1.3
},
"clicked": {
"node_color": "#0e6b66"
},
"buttons": {
"background": "#0f6e78",
"text": "#fffdf8",
"hover": "#0b555c",
"disabled": "#b7aea3"
},
"card": {
"background": "#fffdf8",
"border": "#e0d3c2"
},
"shapes": {
"page": "circle",
"external": "cloud"
},
"subtitle_color": "#2c2416",
"subtitle": {
"min_radius": 0.8,
"padding": 2,
"size": 6,
"on_top": true,
"outline": false,
"outline_color": "#fffdf8",
"outline_width": 3
}
}
@@ -0,0 +1,55 @@
{
"version": "1.0.0",
"background": "#1e2836",
"graph_background": "#283448",
"font_family": "Segoe UI, sans-serif",
"text_color": "#e7eef8",
"node_colors": {
"low": "#7d8da3",
"mid": "#fff4c4",
"high": "#f7d67c"
},
"node_stroke": "none",
"node_radius": {
"min": 4,
"max": 24
},
"edge_colors": {
"low": "#51627a",
"mid": "#8fa3bd",
"high": "#d5e2f2"
},
"edge_width": 1,
"highlight": {
"node_color": "#f3d48a",
"edge_color": "#9ec5ea",
"size_multiplier": 1.45
},
"clicked": {
"node_color": "#ffe3a3"
},
"buttons": {
"background": "#3e5674",
"text": "#f4f8fc",
"hover": "#527094",
"disabled": "#2a3648"
},
"card": {
"background": "#31445c",
"border": "#5c7390"
},
"shapes": {
"page": "circle",
"external": "cloud"
},
"subtitle_color": "#e7eef8",
"subtitle": {
"min_radius": 0.8,
"padding": 2,
"size": 6,
"on_top": true,
"outline": false,
"outline_color": "#283448",
"outline_width": 3
}
}
@@ -0,0 +1,109 @@
{
"version": "1.0.0",
"background": "#e6e6e6",
"graph_background": "#f4f4f4",
"font_family": "Arial, sans-serif",
"text_color": "#141414",
"node_colors": {
"low": "#5a5a5a",
"mid": "#2e2e2e",
"high": "#0d0d0d"
},
"node_stroke": "#141414",
"node_radius": {
"min": 5,
"max": 36
},
"edge_colors": {
"low": "#8f8f8f",
"mid": "#3d3d3d",
"high": "#141414"
},
"edge_width": 1,
"highlight": {
"node_color": "#000000",
"edge_color": "#1a1a1a",
"size_multiplier": 1.4
},
"clicked": {
"node_color": "#000000"
},
"buttons": {
"background": "#2a2a2a",
"text": "#ffffff",
"hover": "#111111",
"disabled": "#b0b0b0"
},
"card": {
"background": "#ffffff",
"border": "#8a8a8a"
},
"shapes": {
"page": "circle",
"external": "cloud"
},
"subtitle_color": "#141414",
"subtitle": {
"min_radius": 0.8,
"padding": 2,
"size": 6,
"on_top": true,
"outline": false,
"outline_color": "#f4f4f4",
"outline_width": 3
},
"dark": {
"background": "#2c2c2c",
"graph_background": "#3a3a3a",
"font_family": "Arial, sans-serif",
"text_color": "#f5f5f5",
"node_colors": {
"low": "#8d8d8d",
"mid": "#fff4c4",
"high": "#f5b44a"
},
"node_stroke": "none",
"node_radius": {
"min": 5,
"max": 36
},
"edge_colors": {
"low": "#6e6e6e",
"mid": "#c4c4c4",
"high": "#ffffff"
},
"edge_width": 1,
"highlight": {
"node_color": "#ffffff",
"edge_color": "#ffffff",
"size_multiplier": 1.4
},
"clicked": {
"node_color": "#ffffff"
},
"buttons": {
"background": "#e8e8e8",
"text": "#1a1a1a",
"hover": "#ffffff",
"disabled": "#5a5a5a"
},
"card": {
"background": "#454545",
"border": "#9a9a9a"
},
"shapes": {
"page": "circle",
"external": "cloud"
},
"subtitle_color": "#f5f5f5",
"subtitle": {
"min_radius": 0.5,
"padding": 2,
"size": 8,
"on_top": true,
"outline": true,
"outline_color": "#2c2c2c",
"outline_width": 3
}
}
}
@@ -0,0 +1,55 @@
{
"version": "1.0.0",
"background": "#070b14",
"graph_background": "#0b1020",
"font_family": "Segoe UI, sans-serif",
"text_color": "#d6def5",
"node_colors": {
"low": "#8ea2c8",
"mid": "#ffe9a0",
"high": "#ffffff"
},
"node_stroke": "none",
"node_radius": {
"min": 3,
"max": 20
},
"edge_colors": {
"low": "#243056",
"mid": "#7f8cbf",
"high": "#e7ecff"
},
"edge_width": 1,
"highlight": {
"node_color": "#fff6c2",
"edge_color": "#9ecbff",
"size_multiplier": 1.6
},
"clicked": {
"node_color": "#ffd56a"
},
"buttons": {
"background": "#1e2a4a",
"text": "#e8eeff",
"hover": "#314572",
"disabled": "#3a4258"
},
"card": {
"background": "#12182b",
"border": "#2a3558"
},
"shapes": {
"page": "circle",
"external": "star"
},
"subtitle_color": "#d5def8",
"subtitle": {
"min_radius": 0.8,
"padding": 2,
"size": 6,
"on_top": true,
"outline": false,
"outline_color": "#0b1020",
"outline_width": 3
}
}
@@ -0,0 +1,55 @@
{
"version": "1.0.0",
"background": "#f7fafc",
"graph_background": "#fcfdfe",
"font_family": "Segoe UI, Calibri, Helvetica Neue, Arial, sans-serif",
"text_color": "#4a5d70",
"node_colors": {
"low": "#e4eef4",
"mid": "#a9c6d8",
"high": "#7eabc4"
},
"node_stroke": "#9bb8cb",
"node_radius": {
"min": 4,
"max": 26
},
"edge_colors": {
"low": "#e7f0f5",
"mid": "#b7d0de",
"high": "#8eb4c9"
},
"edge_width": 1,
"highlight": {
"node_color": "#6aa3c0",
"edge_color": "#7eabc4",
"size_multiplier": 1.15
},
"clicked": {
"node_color": "#5b93b0"
},
"buttons": {
"background": "#8eb4c9",
"text": "#ffffff",
"hover": "#7aa6bd",
"disabled": "#dce7ee"
},
"card": {
"background": "#ffffff",
"border": "#e6eef3"
},
"shapes": {
"page": "circle",
"external": "cloud"
},
"subtitle_color": "#4a5d70",
"subtitle": {
"min_radius": 0.8,
"padding": 2,
"size": 6,
"on_top": true,
"outline": false,
"outline_color": "#fcfdfe",
"outline_width": 3
}
}
@@ -4,7 +4,7 @@ category: productivity
description: Operate an llm-wiki with the fiona-assistant CLI.
author: nvaldez
license: MIT
version: 1.12.1
version: 1.13.0
updated: 2026-10-01
---
@@ -249,7 +249,9 @@ Total: <N> file(s) need attention
Files skipped (locally modified): <N>
```
A file that lacks a version on either side is compared by SHA-256. Equal
A file that lacks a version on either side is compared by SHA-256.
Text hashes fold `\r\n` and lone `\r` to `\n` first, so a file that
differs from the template only in line endings is up to date. Equal
hashes mean up to date. Different hashes print the first 8 hex
digits of each side instead of versions:
@@ -280,6 +282,14 @@ 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`.
A confirmed update that had something to report writes
`corefiles-update.json` at the wiki root. It lists each compared
core file's version, template version, owner hash, template hash,
and the UTC date. A later check does not list a file while those
four values still match, so a second update the same day stays
quiet about a file you already updated. `check-update` and
`--dry-run` do not write that file.
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
@@ -966,9 +976,11 @@ from the template object. For each user key, if both sides are
objects, merge recursively; otherwise the user value replaces the
template value. Keep new template keys the user does not set. Write
the result as JSON with indent 2 and a trailing newline, then delete
`fiona-settings-update.json`. Settings have no `version` field. A
later `wiki update` conflicts again only when the owner bytes still
differ from the template. Log the merge the same way as step 7.
`fiona-settings-update.json`. Settings have no `version` field.
Line endings alone are not a difference. A later `wiki update`
lists the file again only when the text still differs and
`corefiles-update.json` does not already record that same version
and hash pair. Log the merge the same way as step 7.
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
+102 -20
View File
@@ -34,6 +34,8 @@ logger = logging.getLogger(__name__)
# AI/LLM: 2026-09-29 - colorful is the complete theme; the page opens on night-sky.
FALLBACK_THEME = "colorful"
OPENING_THEME = "night-sky"
# CURSOR: 2026-10-01 - version is metadata; dark is a nested palette.
_THEME_META_KEYS = ("dark", "version")
def _posix_path(path: str) -> str:
@@ -356,22 +358,51 @@ def resolve_theme(theme: dict, default: dict) -> dict:
Generated by AI/LLM: 2026-09-29 - a missing key comes from colorful.
A ``dark`` object is resolved on top of the filled theme for dark mode.
Modified by CURSOR: 2026-10-01 - ``version`` stays on the theme that sets it.
Args:
theme: The theme to fill. ``dark`` is not copied as a color key.
theme: The theme to fill. ``dark`` and ``version`` are not color keys.
default: The complete colorful theme.
Returns:
The theme with every missing key taken from colorful.
The theme with every missing color key taken from colorful.
"""
partial = {key: value for key, value in theme.items() if key != "dark"}
merged = deep_merge(default, partial)
base = {key: value for key, value in default.items() if key not in _THEME_META_KEYS}
partial = {key: value for key, value in theme.items() if key not in _THEME_META_KEYS}
merged = deep_merge(base, partial)
dark = theme.get("dark")
if isinstance(dark, dict):
merged["dark"] = deep_merge(merged, dark)
dark_partial = {key: value for key, value in dark.items() if key != "version"}
merged["dark"] = deep_merge(merged, dark_partial)
version = theme.get("version")
if isinstance(version, str) and version:
merged["version"] = version
return merged
def _read_json_object(path: pathlib.Path) -> dict:
"""Return a JSON object, or an empty dict when the file cannot be read.
Generated by CURSOR: 2026-10-01 - one warning per unreadable theme file.
Args:
path: Path of a JSON file.
Returns:
The object, or an empty dict when the file is missing, invalid,
or not a JSON object.
"""
try:
with open(path, encoding="utf-8") as handle:
payload = json.load(handle)
except (json.JSONDecodeError, OSError) as exc:
logger.warning("Constellation settings skipped for %s: %s", path, exc)
return {}
if not isinstance(payload, dict):
return {}
return payload
def _read_constellation(path: pathlib.Path) -> dict:
"""Return the themes object from a constellation settings file.
@@ -383,34 +414,83 @@ def _read_constellation(path: pathlib.Path) -> dict:
Returns:
The ``themes`` object, or an empty dict when the file cannot be read.
"""
try:
with open(path, encoding="utf-8") as handle:
payload = json.load(handle)
except (json.JSONDecodeError, OSError) as exc:
logger.warning("Constellation settings skipped for %s: %s", path, exc)
return {}
themes = payload.get("themes", payload) if isinstance(payload, dict) else {}
payload = _read_json_object(path)
themes = payload.get("themes", payload)
if not isinstance(themes, dict):
return {}
return {key: value for key, value in themes.items() if isinstance(value, dict)}
def _read_constellation_dir(path: pathlib.Path) -> dict:
"""Return themes from one JSON file per theme.
Generated by CURSOR: 2026-10-01 - the file stem is the theme name.
``colorful`` is first. The other names follow alphabetically.
Args:
path: Directory of theme JSON files.
Returns:
Theme name to theme object. Unreadable files are omitted.
"""
if not path.is_dir():
return {}
themes: dict = {}
files = sorted(
path.glob("*.json"),
key=lambda item: (item.stem != FALLBACK_THEME, item.stem),
)
for theme_file in files:
if not theme_file.is_file() or theme_file.name.startswith("."):
continue
theme = _read_json_object(theme_file)
if theme:
themes[theme_file.stem] = theme
return themes
def _local_constellation(search_dir: pathlib.Path) -> dict | None:
"""Return theme overlays from one directory, if it has any.
Generated by CURSOR: 2026-10-01 - a theme directory, then the legacy file.
Args:
search_dir: Directory that may hold ``constellation/`` or
``constellation-settings.json``.
Returns:
Theme overlays, or None when this directory has neither source.
The legacy file overlays the directory.
"""
directory = search_dir / "constellation"
legacy = search_dir / "constellation-settings.json"
has_dir = directory.is_dir() and any(directory.glob("*.json"))
has_legacy = legacy.is_file()
if not has_dir and not has_legacy:
return None
themes = _read_constellation_dir(directory) if has_dir else {}
if has_legacy:
themes = deep_merge(themes, _read_constellation(legacy))
return themes
def _find_constellation(directory: str) -> dict:
"""Find a constellation-settings.json by walking parents of directory.
"""Find constellation themes by walking parents of directory.
Generated by AI/LLM: 2026-09-29 - a wiki can personalize themes locally.
Modified by CURSOR: 2026-10-01 - a constellation directory or the legacy file.
Args:
directory: Directory to start the search from.
Returns:
Themes from the nearest file, or an empty dict when none exist.
Themes from the nearest source, or an empty dict when none exist.
"""
search_dir = pathlib.Path(directory)
while True:
candidate = search_dir / "constellation-settings.json"
if candidate.exists():
return _read_constellation(candidate)
found = _local_constellation(search_dir)
if found is not None:
return found
parent = search_dir.parent
if parent == search_dir:
return {}
@@ -457,16 +537,18 @@ def load_constellation_themes(
"""Load constellation themes and fill missing keys from colorful.
Generated by AI/LLM: 2026-09-29 - packaged themes, then a local file.
Modified by CURSOR: 2026-10-01 - packaged themes are one JSON file each.
Args:
directory: Wiki directory. A constellation-settings.json here or in
a parent overrides the packaged themes.
directory: Wiki directory. A ``constellation/`` directory or a
``constellation-settings.json`` here or in a parent overlays
the packaged themes.
graph_settings: Optional ``fiona.wiki.graph`` overrides for colorful.
Returns:
Theme name to a complete theme. ``colorful`` is always present.
"""
packaged = _read_constellation(llm_wiki_template() / "constellation-settings.json")
packaged = _read_constellation_dir(llm_wiki_template() / "constellation")
local = _find_constellation(directory) if directory else {}
raw = deep_merge(packaged, local)
colorful = _apply_graph_overrides(raw.get(FALLBACK_THEME, {}), graph_settings or {})
@@ -26,6 +26,11 @@
if (source.dark) merged.dark = source.dark;
return;
}
// CURSOR: 2026-10-01 - version is not a color key.
if (key === 'version') {
if (source.version !== undefined) merged.version = source.version;
return;
}
const fromTheme = source[key];
const fromDefault = base[key];
if (fromTheme && typeof fromTheme === 'object' && !Array.isArray(fromTheme)
+181 -11
View File
@@ -15,8 +15,10 @@ The module handles:
from __future__ import annotations
import datetime
import hashlib
import json
import logging
import sys
from dataclasses import dataclass, field
from pathlib import Path
@@ -37,23 +39,29 @@ from fiona.wiki.wiki import _copy_file, get_ignore_patterns, replace_date_placeh
CORE_FILES = [
"AGENTS.md",
"fiona-settings.json",
"constellation-settings.json",
"README.md",
"table_of_contents.md",
]
# Directories that are part of the core package
# CURSOR: 2026-10-01 - constellation/ is one JSON file per theme.
CORE_DIRECTORIES = [
"wiki",
"ingest",
"personal",
"raw",
"utils",
"constellation",
]
# Files that require special update handling
SETTINGS_FILE = "fiona-settings.json"
# Generated by CURSOR: 2026-10-01 - local record of core-file versions and hashes
COREFILES_UPDATE_NAME = "corefiles-update.json"
logger = logging.getLogger(__name__)
# Read-only zones that should never be modified
READ_ONLY_ZONES = ["personal/", "raw/"]
@@ -64,6 +72,7 @@ UPDATE_SUFFIX = "-update"
SHORT_HASH_LENGTH = 8
__all__ = [
"COREFILES_UPDATE_NAME",
"CORE_DIRECTORIES",
"CORE_FILES",
"READ_ONLY_ZONES",
@@ -278,10 +287,46 @@ def is_version_newer(candidate: str, baseline: str) -> bool:
return candidate > baseline
def utc_day() -> str:
"""Return today's UTC date as YYYY-MM-DD.
Generated by CURSOR: 2026-10-01 - date stored in corefiles-update.json.
"""
return datetime.datetime.now(datetime.UTC).strftime("%Y-%m-%d")
def _fold_newlines(text: str) -> str:
"""Fold CRLF and lone CR to LF.
Generated by CURSOR: 2026-10-01 - line endings are not a content change.
"""
return text.replace("\r\n", "\n").replace("\r", "\n")
def text_file_sha256(file_path: Path) -> str:
"""Hash a text file after folding newlines to LF (SPEC 7.1.2.13).
Generated by CURSOR: 2026-10-01 - CRLF and LF of the same text match.
Args:
file_path: Path to the file.
Returns:
str: SHA-256 hex digest. A file that is not UTF-8 hashes its raw bytes.
"""
try:
with open(file_path, encoding="utf-8", newline="") as handle:
text = handle.read()
except UnicodeDecodeError:
return calculate_sha256(file_path)
folded = _fold_newlines(text)
return hashlib.sha256(folded.encode("utf-8")).hexdigest()
def template_sha256(template_path: Path) -> str:
"""Hash the text wiki init would write for a template file (SPEC 7.1.2.12).
Generated by AI/LLM: 2026-09-30 - DATE_PLACEHOLDER expanded, endings kept.
Modified by CURSOR: 2026-10-01 - fold newlines after DATE_PLACEHOLDER.
Args:
template_path: Path to the template file.
@@ -295,7 +340,8 @@ def template_sha256(template_path: Path) -> str:
text = replace_date_placeholders(handle.read())
except UnicodeDecodeError:
return calculate_sha256(template_path)
return hashlib.sha256(text.encode("utf-8")).hexdigest()
folded = _fold_newlines(text)
return hashlib.sha256(folded.encode("utf-8")).hexdigest()
def _content_differs(wiki_file: Path, template_file: Path) -> bool:
@@ -356,7 +402,7 @@ def compare_md_file(file_path: Path, template_path: Path) -> FileComparisonResul
)
if current_version is None or template_version is None:
result.current_hash = calculate_sha256(file_path)
result.current_hash = text_file_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):
@@ -388,7 +434,7 @@ def compare_non_md_file(file_path: Path, template_path: Path) -> FileComparisonR
file_path=file_path,
is_core_file=True,
has_template_version=False,
current_hash=calculate_sha256(file_path),
current_hash=text_file_sha256(file_path),
template_hash=template_sha256(template_path),
)
result.needs_update = result.current_hash != result.template_hash
@@ -537,6 +583,129 @@ def find_missing_directories(wiki_root: Path, template_dir: Path) -> list[Path]:
return sorted(missing)
# =============================================================================
# Core-file update record (SPEC 7.1.2.14)
# =============================================================================
def _compare_core_file(
wiki_file: Path, template_file: Path, relative: Path
) -> FileComparisonResult:
"""Compare one core file with the rule for its type.
Generated by CURSOR: 2026-10-01 - shared by the check and the update record.
"""
if relative.name == SETTINGS_FILE:
return compare_settings_file(wiki_file, template_file)
if relative.suffix == ".md":
return compare_md_file(wiki_file, template_file)
return compare_non_md_file(wiki_file, template_file)
def _file_identity(
result: FileComparisonResult, template_file: Path
) -> dict[str, str | None]:
"""Return the version and hash fields stored for one core file.
Generated by CURSOR: 2026-10-01 - versions plus newline-folded hashes.
"""
current_hash = result.current_hash
if current_hash is None:
current_hash = text_file_sha256(result.file_path)
template_hash = result.template_hash
if template_hash is None:
template_hash = template_sha256(template_file)
return {
"version": result.current_version,
"template_version": result.template_version,
"sha256": current_hash,
"template_sha256": template_hash,
}
def load_corefiles_update(wiki_root: Path) -> dict:
"""Load corefiles-update.json, or an empty record.
Generated by CURSOR: 2026-10-01 - a missing or invalid record acknowledges nothing.
Args:
wiki_root: Root path of the wiki.
Returns:
dict: The record object. ``files`` is a dict, empty when nothing is known.
"""
path = wiki_root / COREFILES_UPDATE_NAME
if not path.is_file():
return {"files": {}}
try:
payload = json.loads(path.read_text(encoding="utf-8"))
except (OSError, UnicodeError, json.JSONDecodeError) as exc:
logger.warning("Ignoring unreadable %s: %s", path, exc)
return {"files": {}}
if not isinstance(payload, dict) or not isinstance(payload.get("files"), dict):
logger.warning("Ignoring %s without a files object", path)
return {"files": {}}
return payload
def _acknowledged(record: dict, relative: str, identity: dict[str, str | None]) -> bool:
"""Return whether the record already has this core file's identity.
Generated by CURSOR: 2026-10-01 - same version and hashes means already updated.
"""
files = record.get("files")
if not isinstance(files, dict):
return False
entry = files.get(relative)
if not isinstance(entry, dict):
return False
return all(entry.get(key) == identity[key] for key in identity)
def _considered_core_file(relative: Path, wiki_root: Path, patterns: list[str]) -> bool:
"""Return whether update compares this template-relative path.
Generated by CURSOR: 2026-10-01 - same filter as the update check.
"""
wiki_file = wiki_root / relative
if _is_protected(relative, wiki_root, patterns):
return False
wiki_page = _is_wiki_page_path(relative)
skipped_page = relative.suffix != ".md" or not wiki_file.is_file()
return not (wiki_page and skipped_page)
def write_corefiles_update(wiki_root: Path) -> None:
"""Write corefiles-update.json for every compared core file.
Generated by CURSOR: 2026-10-01 - versions, hashes, and the UTC date.
Args:
wiki_root: Root path of the wiki.
"""
template_dir = get_llm_wiki_source_path()
patterns = _patterns_for_update(wiki_root)
day = utc_day()
files: dict[str, dict[str, str | None]] = {}
for relative in get_all_template_files(template_dir):
if not _considered_core_file(relative, wiki_root, patterns):
continue
wiki_file = wiki_root / relative
if not wiki_file.is_file():
continue
template_file = template_dir / relative
result = _compare_core_file(wiki_file, template_file, relative)
identity = _file_identity(result, template_file)
identity["date"] = day
files[relative.as_posix()] = identity
path = wiki_root / COREFILES_UPDATE_NAME
path.write_text(
json.dumps({"files": files}, indent=2) + "\n",
encoding="utf-8",
newline="\n",
)
logger.info("Wrote core file update record to %s", path)
# =============================================================================
# Check Update Functions
# =============================================================================
@@ -582,6 +751,7 @@ def check_wiki_updates(directory: str | Path = ".") -> UpdateSummary:
summary = UpdateSummary()
patterns = _patterns_for_update(wiki_root)
record = load_corefiles_update(wiki_root)
for relative in get_all_template_files(template_dir):
wiki_file = wiki_root / relative
@@ -598,12 +768,10 @@ def check_wiki_updates(directory: str | Path = ".") -> UpdateSummary:
summary.files_to_add.append(relative)
continue
if relative.name == SETTINGS_FILE:
result = compare_settings_file(wiki_file, template_file)
elif relative.suffix == ".md":
result = compare_md_file(wiki_file, template_file)
else:
result = compare_non_md_file(wiki_file, template_file)
result = _compare_core_file(wiki_file, template_file, relative)
identity = _file_identity(result, template_file)
if _acknowledged(record, relative.as_posix(), identity):
continue
if result.is_conflict:
summary.conflicts.append(result)
@@ -757,6 +925,8 @@ def update_core_files(directory: str | Path = ".", force: bool = False, yes: boo
relative = result.file_path.relative_to(wiki_root)
_copy_file(template_dir / relative, result.update_path)
write_corefiles_update(wiki_root)
# Report locally-modified files that were skipped
if verbose and summary.files_skipped:
print("Skipped locally-modified files:")
+118 -1
View File
@@ -7,6 +7,7 @@ import json
import os
import fiona.wiki.graph_generator as wiki_graph
from fiona.paths import llm_wiki_template
from fiona.wiki.graph_generator import (
HTMLGraphRenderer,
MarkdownLinkParser,
@@ -101,7 +102,7 @@ class TestLoadGraphSettings:
class TestConstellationThemes:
"""Themes in constellation-settings.json."""
"""Themes in constellation/*.json."""
def test_missing_theme_key_comes_from_default(self):
"""A partial theme keeps unspecified keys from the default theme.
@@ -115,6 +116,74 @@ class TestConstellationThemes:
assert filled["text_color"] == "#ffffff"
assert filled["font_family"] == "Arial, sans-serif"
def test_version_is_not_copied_from_colorful(self):
"""A theme that omits version does not inherit colorful's version.
Generated by CURSOR: 2026-10-01 - version stays on the theme that sets it.
"""
filled = resolve_theme(
{"text_color": "#ffffff"},
{
"text_color": "#000000",
"font_family": "Arial, sans-serif",
"version": "9.9.9",
},
)
assert "version" not in filled
assert filled["font_family"] == "Arial, sans-serif"
def test_theme_keeps_its_own_version(self):
"""A theme version replaces the default theme version.
Generated by CURSOR: 2026-10-01 - each theme file tracks its own version.
"""
filled = resolve_theme(
{"version": "1.2.0", "text_color": "#ffffff"},
{
"version": "9.9.9",
"text_color": "#000000",
"font_family": "Arial, sans-serif",
},
)
assert filled["version"] == "1.2.0"
assert filled["font_family"] == "Arial, sans-serif"
def test_each_packaged_theme_is_its_own_file(self):
"""Packaged themes are separate JSON files with a version.
Generated by CURSOR: 2026-10-01 - one file per theme (SPEC 5.3.3).
"""
root = llm_wiki_template()
assert not (root / "constellation-settings.json").exists()
theme_dir = root / "constellation"
expected = [
"colorful",
"dark",
"grayscale",
"night-sky",
"professional",
]
names = sorted(path.stem for path in theme_dir.glob("*.json"))
assert names == expected
themes = load_constellation_themes()
assert list(themes) == ["colorful", *expected[1:]]
for name in expected:
payload = json.loads(
(theme_dir / f"{name}.json").read_text(encoding="utf-8")
)
assert isinstance(payload["version"], str) and payload["version"]
assert themes[name]["version"] == payload["version"]
def test_page_script_does_not_copy_theme_version(self):
"""The page script does not fill version from colorful.
Generated by CURSOR: 2026-10-01 - version is not a color key.
"""
graph = WikiGraph()
graph.add_node("wiki/file1.md")
html = HTMLGraphRenderer(graph).generate_html()
assert "key === 'version'" in html
def test_packaged_themes_cover_colorful_night_sky_and_grayscale(self):
"""The packaged catalog has a complete colorful theme and the others.
@@ -230,6 +299,54 @@ class TestConstellationThemes:
assert themes["night-sky"]["shapes"]["page"] == "circle"
assert themes["night-sky"]["shapes"]["external"] == "star"
def test_local_constellation_directory_overrides_a_theme(self, tmp_path):
"""A constellation directory personalizes one theme key.
Generated by CURSOR: 2026-10-01 - one JSON file overlays that theme.
"""
theme_dir = tmp_path / "constellation"
theme_dir.mkdir()
(theme_dir / "night-sky.json").write_text(
json.dumps({"version": "2.0.0", "background": "#111111"}),
encoding="utf-8",
)
themes = load_constellation_themes(str(tmp_path))
assert themes["night-sky"]["background"] == "#111111"
assert themes["night-sky"]["shapes"]["page"] == "circle"
assert themes["night-sky"]["version"] == "2.0.0"
assert themes["colorful"]["background"] != "#111111"
def test_legacy_file_overlays_a_local_directory(self, tmp_path):
"""constellation-settings.json wins over a theme file beside it.
Generated by CURSOR: 2026-10-01 - older wikis keep their overrides.
"""
theme_dir = tmp_path / "constellation"
theme_dir.mkdir()
(theme_dir / "night-sky.json").write_text(
json.dumps({"background": "#111111"}),
encoding="utf-8",
)
(tmp_path / "constellation-settings.json").write_text(
json.dumps({"themes": {"night-sky": {"background": "#222222"}}}),
encoding="utf-8",
)
themes = load_constellation_themes(str(tmp_path))
assert themes["night-sky"]["background"] == "#222222"
assert themes["night-sky"]["shapes"]["external"] == "star"
def test_unreadable_theme_file_is_skipped(self, tmp_path):
"""A broken theme file does not drop the other themes.
Generated by CURSOR: 2026-10-01 - skip a file that is not a JSON object.
"""
theme_dir = tmp_path / "constellation"
theme_dir.mkdir()
(theme_dir / "broken.json").write_text("{", encoding="utf-8")
themes = load_constellation_themes(str(tmp_path))
assert "broken" not in themes
assert "colorful" in themes
def test_node_radius_keeps_a_fraction(self, tmp_path):
"""A fractional min and max stay fractional and drive the drawing.
+111 -1
View File
@@ -673,12 +673,14 @@ class TestConstants:
assert isinstance(CORE_FILES, list)
assert "AGENTS.md" in CORE_FILES
assert "fiona-settings.json" in CORE_FILES
assert "constellation-settings.json" not in CORE_FILES
def test_core_directories_constant(self):
"""Test that CORE_DIRECTORIES is a list."""
assert isinstance(CORE_DIRECTORIES, list)
assert "wiki" in CORE_DIRECTORIES
assert "ingest" in CORE_DIRECTORIES
assert "constellation" in CORE_DIRECTORIES
def test_read_only_zones_constant(self):
"""Test that READ_ONLY_ZONES is a list."""
@@ -1239,7 +1241,10 @@ class TestUpdateCoreFilesImplemented:
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 after - before == {
wiki / "wiki" / "schema-update.md",
wiki / "corefiles-update.json",
}
assert (wiki / "wiki" / "schema.md").read_text(encoding="utf-8") == owner
def test_yes_adds_missing_file_and_directory(self, template_wiki_pair):
@@ -1633,3 +1638,108 @@ class TestSha256Report:
conflict = output["conflicts"][0]
assert conflict["current_sha256"] is None
assert conflict["template_sha256"] is None
# =============================================================================
# Line endings and corefiles-update.json (SPEC 7.1.2.13, 7.1.2.14)
# Generated by CURSOR: 2026-10-01 - CRLF settings stay quiet after update.
# =============================================================================
class TestNewlineFoldedHash:
"""Text that differs only in line endings is up to date."""
def test_crlf_settings_match_lf_template(self, tmp_path):
"""SPEC 7.1.2.13: CRLF owner vs LF template is not a conflict."""
content = '{\n "a": 1\n}\n'
wiki_file = tmp_path / "fiona-settings.json"
template_file = tmp_path / "template_settings.json"
wiki_file.write_text(content, encoding="utf-8", newline="\r\n")
template_file.write_text(content, encoding="utf-8", newline="\n")
result = compare_settings_file(wiki_file, template_file)
assert result.is_conflict is False
assert result.current_hash == result.template_hash
def test_crlf_settings_absent_from_check(self, template_wiki_pair):
"""SPEC 7.1.2.13: check-update does not list a CRLF settings file."""
template, wiki = template_wiki_pair
content = '{\n "a": 1\n}\n'
(template / "fiona-settings.json").write_text(
content, encoding="utf-8", newline="\n"
)
(wiki / "fiona-settings.json").write_text(
content, encoding="utf-8", newline="\r\n"
)
summary = check_wiki_updates(str(wiki))
assert summary.conflicts == []
assert summary.has_updates is False
class TestCorefilesUpdateRecord:
"""corefiles-update.json remembers a file already updated."""
def test_second_check_omits_recorded_settings(self, template_wiki_pair, monkeypatch):
"""SPEC 7.1.2.14: a second check does not list the recorded file."""
_template, wiki = template_wiki_pair
monkeypatch.setattr(
"fiona.wiki.update_manager.utc_day", lambda: "2026-10-01"
)
(wiki / "fiona-settings.json").write_text(
json.dumps({"a": 1, "user_key": "custom"}), encoding="utf-8"
)
update_core_files(str(wiki), yes=True)
record = json.loads((wiki / "corefiles-update.json").read_text(encoding="utf-8"))
entry = record["files"]["fiona-settings.json"]
assert entry["version"] is None
assert entry["template_version"] is None
assert entry["date"] == "2026-10-01"
assert re.fullmatch(HEX64, entry["sha256"])
assert re.fullmatch(HEX64, entry["template_sha256"])
assert entry["sha256"] != entry["template_sha256"]
again = check_wiki_updates(str(wiki))
assert again.conflicts == []
assert "fiona-settings.json" not in format_check_update_output(again)
(wiki / "fiona-settings.json").write_text(
json.dumps({"a": 1, "user_key": "other"}), encoding="utf-8"
)
third = check_wiki_updates(str(wiki))
assert any(result.is_settings_file for result in third.conflicts)
def test_invalid_record_acknowledges_nothing(self, template_wiki_pair):
"""SPEC 7.1.2.14: a record that is not the object still reports drift."""
_template, wiki = template_wiki_pair
(wiki / "fiona-settings.json").write_text(
json.dumps({"a": 1, "user_key": "custom"}), encoding="utf-8"
)
(wiki / "corefiles-update.json").write_text("[]\n", encoding="utf-8")
summary = check_wiki_updates(str(wiki))
assert any(result.is_settings_file for result in summary.conflicts)
def test_dry_run_does_not_write_record(self, template_wiki_pair):
"""SPEC 7.1.2.14: dry-run leaves corefiles-update.json uncreated."""
_template, wiki = template_wiki_pair
(wiki / "fiona-settings.json").write_text(
json.dumps({"a": 2}), encoding="utf-8"
)
assert update_main(directory=str(wiki), dry_run=True) == 0
assert not (wiki / "corefiles-update.json").exists()
def test_pristine_update_writes_no_record(self, template_wiki_pair):
"""SPEC 7.1.2.5: an up-to-date wiki update writes nothing."""
_template, wiki = template_wiki_pair
update_core_files(str(wiki), yes=True)
assert not (wiki / "corefiles-update.json").exists()
+7 -1
View File
@@ -9,6 +9,11 @@ from pathlib import Path
import git
import pytest
from fiona.wiki.ignore import (
gitignore_patterns_from_text,
path_is_ignored,
repository_gitignore_text,
)
from fiona.wiki.wiki import (
copy_directory_tree,
get_ignore_patterns,
@@ -35,9 +40,10 @@ def test_wiki_init_is_1_to_1_copy_with_source():
copied_files = _relative_files(Path(tmpdir))
# Gitignored template artifacts are not part of the copy.
patterns = gitignore_patterns_from_text(repository_gitignore_text())
gitignored = {
path for path in template_files
if "__pycache__" in path.parts or path.suffix in {".pyc", ".pyo", ".pyd"}
if path_is_ignored(path.as_posix(), patterns)
}
assert (template_files - gitignored).issubset(copied_files)
assert gitignored.isdisjoint(copied_files)