wiki update fix, themes versioning, readme refactor, graph ignore
This commit is contained in:
@@ -1,390 +1,436 @@
|
||||
# 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
|
||||
|
||||
- **Clone the repository:**
|
||||
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd fiona-assistant
|
||||
```
|
||||
|
||||
- **Create and activate the virtual environment:**
|
||||
|
||||
Linux / macOS:
|
||||
|
||||
```bash
|
||||
source bootstrap --env fiona_env -c
|
||||
```
|
||||
|
||||
Windows (PowerShell):
|
||||
|
||||
```powershell
|
||||
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
|
||||
. .\bootstrap.ps1 --env fiona_env -c
|
||||
```
|
||||
|
||||
> Make sure `fiona_env` is activated before proceeding. On Windows the
|
||||
> environment lives in `.venvs\fiona_env`.
|
||||
|
||||
### Local install (not editable)
|
||||
|
||||
Install this checkout as a normal package. The default bootstrap install
|
||||
is editable (`pip install -e ".[dev]"`).
|
||||
### 2. Create a wiki
|
||||
|
||||
```bash
|
||||
source bootstrap --local
|
||||
fiona-assistant wiki init my-wiki
|
||||
cd my-wiki
|
||||
```
|
||||
|
||||
```powershell
|
||||
. .\bootstrap.ps1 --local
|
||||
```
|
||||
### 3. Point your agent at it
|
||||
|
||||
### Same as `pip install fiona-assistant`
|
||||
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.
|
||||
|
||||
`--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`.
|
||||
### 4. Feed it sources
|
||||
|
||||
```bash
|
||||
source bootstrap --local --no-env
|
||||
fiona-assistant wiki ingest https://example.com/post.html
|
||||
fiona-assistant wiki ingest ./notes/meeting.pdf
|
||||
```
|
||||
|
||||
```powershell
|
||||
powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1 --local --no-env
|
||||
```
|
||||
Then ask the agent to refine the new pages.
|
||||
|
||||
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:
|
||||
### 5. Keep it healthy
|
||||
|
||||
```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]
|
||||
fiona-assistant housekeeping
|
||||
fiona-assistant git save --description "ingest meeting notes"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Workflow Examples
|
||||
## How It Works
|
||||
|
||||
### 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
|
||||
A wiki created by Fiona has this layout:
|
||||
|
||||
```text
|
||||
PyMarkdownLint Violations
|
||||
TARGET: /path/to/directory
|
||||
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:
|
||||
- md001: Heading levels should only increment by one, Heading levels should only increment by one level at a time
|
||||
- md013: Line length, Line length
|
||||
- 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: file1.md
|
||||
- 10:5 md013
|
||||
- 20:3 md001
|
||||
- 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
|
||||
```
|
||||
|
||||
### 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
|
||||
```
|
||||
`wiki sanity`, `housekeeping`, `wiki ingest`, `wiki check-update`, and
|
||||
`wiki update` also accept `--json` for structured output.
|
||||
|
||||
---
|
||||
|
||||
## Project Structure
|
||||
## 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
|
||||
source bootstrap --env fiona_env -c
|
||||
```
|
||||
|
||||
Windows (PowerShell):
|
||||
|
||||
```powershell
|
||||
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
|
||||
. .\bootstrap.ps1 --env fiona_env -c
|
||||
```
|
||||
|
||||
The default install is editable (`pip install -e ".[dev]"`). On Windows
|
||||
the environment lives in `.venvs\fiona_env`.
|
||||
|
||||
### Other install modes
|
||||
|
||||
| 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
|
||||
# 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
|
||||
```
|
||||
|
||||
Contributions follow the spec-first, test-first lifecycle in
|
||||
[AGENTS](./AGENTS.md).
|
||||
|
||||
### 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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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:")
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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
@@ -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)
|
||||
|
||||
Reference in New Issue
Block a user