4 Commits
Author SHA1 Message Date
olivier 34d28c03fa fix: v0.4.1 — read stdin as UTF-8 (section --content - got mojibake from the frozen exe) 2026-10-19 12:01:54 -04:00
olivier d063551a1e feat: v0.4.0 — section, resolve, list, tasks
- section: append to / replace one section, list-aware spacing, fences ignored
- resolve: filename or alias, case/accent-insensitive, --link wikilinks
- list: frontmatter filters (key=value, key!=value, key, !key), --json
- tasks: checkbox tasks by folder, date range, status, --ignore-from template, --json
- libyaml loader for whole-vault scans
2026-10-19 11:59:16 -04:00
olivier 3d3873b699 chore: v0.3.0; tests: drop dead export_to_csv and shadowed set_default tests, restore create checks 2026-10-19 11:51:58 -04:00
olivier 0f763f98ed feat(frontmatter): --add/--remove list items; --edit keeps existing list type
- --edit splits on commas for tags and for keys already holding a list
- --add/--remove change single items, matched by wikilink target, no duplicates
- refuse lists with unquoted [[links]] (parsed as nested lists)
2026-10-19 11:48:39 -04:00
3 changed files with 679 additions and 93 deletions

No files matched your search

+58 -2
View File
@@ -231,6 +231,10 @@ onyx frontmatter "note-name" --edit --key "tags" --value "project"
onyx frontmatter "note-name" --edit --key "tags" --value "project,urgent"
onyx frontmatter "note-name" --edit --key "status" --value "in-progress"
# Add / remove single items of a list property (repeat --value for several items)
onyx frontmatter "note-name" --add --key "participants" --value "[[Haro]]" --value "[[Jeffrey]]"
onyx frontmatter "note-name" --remove --key "participants" --value "[[Haro]]"
# Clear frontmatter values
onyx frontmatter "note-name" --clear --key "tags"
onyx frontmatter "note-name" --clear --key "date,status,tags"
@@ -243,8 +247,58 @@ onyx frontmatter "note-name" --delete --key "date,status,tags"
Edits only touch the targeted keys: key order, quoting, accents and long values elsewhere in the
frontmatter stay byte-for-byte identical. Values are written the way Obsidian stores them: plain
when YAML reads them back unchanged (`done`, `2026-10-19`, `3`), double-quoted otherwise
(`"[[Haro]]"`). `tags` takes a comma-separated list, written as a block list. Cleared keys become
empty (`status:`), cleared tags `tags: []`.
(`"[[Haro]]"`). `tags`, and any key that is already a list in the note, take a comma-separated
list with `--edit`, written as a block list. Cleared keys become empty (`status:`), cleared tags
`tags: []`.
`--add` and `--remove` change one list without rewriting it: items are taken whole (no comma
splitting) and matched by wikilink target, so `[[Name|Alias]]` and `[[name]]` are the same item.
`--add` skips duplicates, creates the list if the key is missing, and turns a text value into the
first item. A list holding unquoted `[[links]]` (which YAML reads as nested lists) is refused.
### Editing One Section
```bash
# Append at the end of a section (before the next heading of the same or a higher level)
onyx section "periodic/daily/2026-10-19" --heading "## Journal" --content "### 10:00 - Titre\n- note"
onyx section "periodic/daily/2026-10-19" --heading "### Matin" --content "- [ ] Appeler Haro"
# Replace a section's body; --content - reads stdin; --create adds a missing section at the end
onyx section "periodic/weekly/2026-W43" --heading "## Weekly review" --replace --create --content - < review.md
```
`--heading "## Journal"` matches that level only; `--heading Journal` matches any level (case-insensitive).
Appended text gets a blank line before it, except between two list items, so a list stays one list.
Headings in the frontmatter or in code blocks are ignored, and everything outside the section is left
byte-for-byte. A missing heading is an error (listing the note's headings) unless `--create`.
### Finding Notes
```bash
# By filename or alias: exact, ignoring case and accents; exit code 1 when nothing matches
onyx resolve "Stéphane" --folder entities --link # [[Stéphane Charbonneau|Stéphane]], one line per match
onyx resolve "METC" # entities/businesses/Mousquetons et Cie
# By frontmatter (repeatable --where = AND): key=value, key!=value, key, !key
onyx list --folder projects --where type=project --where status=active
onyx list --where client=Symbolitech --where "status!=done" --json
```
`--where` values compare without case or accents, a `[[link]]` compares by its target, and a list matches
when any item does. `resolve --link` uses a path link when the filename is shared by several notes.
### Tasks
```bash
# Open and in-progress tasks of a week's daily notes, minus the template's recurring ones
onyx tasks --folder periodic/daily --from 2026-10-12 --to 2026-10-18 --status open,doing \
--ignore-from resources/template/daily-note
onyx tasks --folder projects --status open --json # path, line, date, status, heading, text
```
Statuses: `- [ ]` open, `- [/]` doing, `- [x]` done, `- [-]` cancelled. With `--from`/`--to`, a note's
date is the `YYYY-MM-DD` at the start of its filename, else its `date` property; undated notes are
skipped. Output is `path:line: - [ ] text`, like grep.
### Version
@@ -262,6 +316,8 @@ onyx --version
- **Periodic Notes**: Support for daily, weekly, monthly, quarterly, and yearly notes
- **Frontmatter Management**: Edit, view, clear, and delete YAML frontmatter
- **Link Updates**: Automatically update internal links when moving notes
- **Sections**: Append to or replace one section of a note
- **Queries**: Resolve notes by name/alias, list notes by frontmatter, list tasks by date and status
- **Cross-Platform**: Works on macOS, Windows, and Linux
## Requirements
+405 -14
View File
@@ -9,6 +9,7 @@ import datetime
import builtins
from pathlib import Path
import re
import unicodedata
from collections import Counter
from typing import List, Union, Optional, Dict, Any
from urllib.parse import quote
@@ -90,6 +91,144 @@ def _iter_notes(vault_path: Path):
yield path
_HEADING = re.compile(r'^(#{1,6})[ \t]+(.*?)[ \t]*$')
_FENCE = re.compile(r'^[ \t]*(`{3,}|~{3,})')
_LIST_ITEM = re.compile(r'^[ \t]*([-*+]|\d+[.)])[ \t]')
def _section_bounds(lines: List[str], first: int, heading: str) -> Optional[tuple]:
"""(heading line, end line) of the first section titled `heading`, skipping fenced code.
`heading` is "## Title" (that level only) or "Title" (any level); case-insensitive.
The section ends at the next heading of the same or a higher level, or at EOF."""
wanted = _HEADING.match(heading.strip())
level_wanted, title_wanted = (len(wanted.group(1)), wanted.group(2)) if wanted else (None, heading.strip())
fence, start, level = None, None, None
for i in range(first, len(lines)):
line = lines[i].rstrip('\n')
fence_match = _FENCE.match(line)
if fence_match:
marker = fence_match.group(1)[0]
fence = None if fence == marker else (fence or marker)
continue
match = None if fence else _HEADING.match(line)
if not match:
continue
if start is None:
if (match.group(2).casefold() == title_wanted.casefold()
and level_wanted in (None, len(match.group(1)))):
start, level = i, len(match.group(1))
elif len(match.group(1)) <= level:
return start, i
return (start, len(lines)) if start is not None else None
def _write_section(text: str, heading: str, content: str, replace: bool = False, create: bool = False) -> str:
"""Append `content` at the end of a section (or replace the section's body).
Appending adds a blank line before the new content, except between two list items so
a list stays one list. Blank lines before the next heading are preserved. A missing
section raises KeyError unless `create`, which adds it at the end of the note."""
match = _FRONTMATTER.match(text)
lines = text.splitlines(keepends=True)
if lines and not lines[-1].endswith('\n'):
lines[-1] += '\n'
new = [line + '\n' for line in content.strip('\n').split('\n')] if content.strip() else []
bounds = _section_bounds(lines, text[:match.end()].count('\n') if match else 0, heading)
if bounds is None:
if not create:
raise KeyError(heading)
title = heading.strip() if heading.strip().startswith('#') else f"## {heading.strip()}"
while lines and not lines[-1].strip():
lines.pop()
return ''.join(lines + (['\n'] if lines else []) + [title + '\n'] + new)
start, end = bounds
body = lines[start + 1:end]
keep = len(body)
while keep and not body[keep - 1].strip():
keep -= 1
kept, trailing = body[:keep], body[keep:]
if replace:
kept = new
elif new:
lists_touch = kept and _LIST_ITEM.match(kept[-1]) and _LIST_ITEM.match(new[0])
kept = kept + ([] if not kept or lists_touch else ['\n']) + new
return ''.join(lines[:start + 1] + kept + trailing + lines[end:])
_TASK = re.compile(r'^[ \t]*[-*+][ \t]+\[(.)\][ \t]+(.*?)[ \t]*$')
_TASK_STATUS = {' ': 'open', 'x': 'done', 'X': 'done', '/': 'doing', '-': 'cancelled'}
_DATE_PREFIX = re.compile(r'^(\d{4}-\d{2}-\d{2})')
_YAML_LOADER = getattr(yaml, 'CSafeLoader', yaml.SafeLoader) # libyaml: ~7x faster on whole-vault scans
def _read_frontmatter(text: str, needed: Optional[str] = None) -> dict:
"""Frontmatter as a dict; {} when missing or invalid YAML. With `needed`, skip the
YAML parse when that key name doesn't even appear in the frontmatter."""
match = _FRONTMATTER.match(text)
if not match or (needed and needed not in match.group(1)):
return {}
try:
data = yaml.load(match.group(1), Loader=_YAML_LOADER)
except yaml.YAMLError:
return {}
return data if isinstance(data, dict) else {}
def _fold(value: Any) -> str:
"""Comparison form: wikilink target if the value is one link, accents and case removed."""
text = str(value).strip()
link = _WIKILINK.fullmatch(text)
if link:
text = link.group(1).strip()
decomposed = unicodedata.normalize('NFKD', text)
return ''.join(c for c in decomposed if not unicodedata.combining(c)).casefold()
def _where_matches(frontmatter: dict, expression: str) -> bool:
"""key=value, key!=value, key (present and non-empty), !key (missing or empty).
A list matches `=` when any item matches."""
match = re.fullmatch(r'\s*(!?)([^=!]+?)\s*(?:(!?=)\s*(.*?))?\s*', expression)
if not match:
raise click.UsageError(f"Invalid --where '{expression}': use key=value, key!=value, key or !key")
negate_key, key, operator, wanted = match.groups()
value = frontmatter.get(key)
items = value if isinstance(value, list) else ([] if value in (None, '') else [value])
if operator is None:
return not items if negate_key else bool(items)
found = any(_fold(item) == _fold(wanted) for item in items)
return found if operator == '=' else not found
def _iter_tasks(text: str):
"""(line number, status char, text, nearest heading) for each checkbox outside
frontmatter and fenced code."""
match = _FRONTMATTER.match(text)
lines = text.splitlines()
fence, heading = None, ''
for number in range(text[:match.end()].count('\n') if match else 0, len(lines)):
line = lines[number]
fence_match = _FENCE.match(line)
if fence_match:
marker = fence_match.group(1)[0]
fence = None if fence == marker else (fence or marker)
continue
if fence:
continue
heading_match = _HEADING.match(line)
if heading_match:
heading = heading_match.group(2)
continue
task = _TASK.match(line)
if task:
yield number + 1, task.group(1), task.group(2), heading
class OnyxCLI:
_PERIODIC_DEFAULTS: Dict[str, Dict[str, str]] = {
'daily': {'format': 'YYYY-MM-DD', 'folder': '', 'template': ''},
@@ -540,6 +679,107 @@ class OnyxCLI:
"""Create or open a yearly note for a specific date, next, or previous year."""
self._create_or_open_periodic_note('yearly', vault, date, next_, previous, open_after, print_path)
def write_section(self, note_name: str, heading: str, content: str, replace: bool = False,
create: bool = False, vault: str = None):
"""Append to (or replace) one section of a note; the rest of the note is untouched."""
vault_name, vault_path = self._get_vault_and_path(vault)
note_path = self._find_note(vault_path, note_name)
text = note_path.read_text(encoding='utf-8-sig')
try:
new_text = _write_section(text, heading, content, replace, create)
except KeyError:
lines = text.splitlines()
headings = [line for line in lines if _HEADING.match(line)]
raise click.UsageError(f"Heading '{heading}' not found in {note_name} (use --create to add it). "
f"Headings: {', '.join(headings) or 'none'}")
if new_text != text:
_write_text(note_path, new_text)
click.echo(f"{'Replaced' if replace else 'Updated'} section '{heading}' in {note_name}")
def resolve_note(self, name: str, folder: str = None, link: bool = False, vault: str = None) -> int:
"""Print notes whose filename or one of whose aliases equals `name` (case and accents
ignored, no fuzzy matching). Returns the number of matches."""
vault_name, vault_path = self._get_vault_and_path(vault)
notes = list(_iter_notes(vault_path))
stems = Counter(p.stem.casefold() for p in notes)
wanted = _fold(name)
matches = 0
for note in sorted(notes):
if folder and not note.relative_to(vault_path).as_posix().startswith(folder.strip('/') + '/'):
continue
if _fold(note.stem) == wanted:
display = None
else:
text = note.read_text(encoding='utf-8-sig')
aliases = _read_frontmatter(text, needed='aliases').get('aliases') or []
aliases = aliases if isinstance(aliases, list) else [aliases]
display = next((str(a) for a in aliases if a is not None and _fold(a) == wanted), None)
if display is None:
continue
matches += 1
rel = note.relative_to(vault_path).with_suffix('').as_posix()
if link:
target = note.stem if stems[note.stem.casefold()] == 1 else rel
click.echo(f"[[{target}|{display}]]" if display else f"[[{target}]]")
else:
click.echo(rel)
return matches
def _notes_in(self, vault_path: Path, folder: Optional[str]) -> List[Path]:
base = vault_path / folder if folder else vault_path
if not base.is_dir():
raise click.UsageError(f"Folder {folder} does not exist")
return sorted(p for p in _iter_notes(vault_path) if base in p.parents)
def list_notes(self, folder: str = None, where: tuple = (), as_json: bool = False, vault: str = None):
"""Notes whose frontmatter matches every --where expression."""
vault_name, vault_path = self._get_vault_and_path(vault)
results = []
for note in self._notes_in(vault_path, folder):
frontmatter = _read_frontmatter(note.read_text(encoding='utf-8-sig'))
if all(_where_matches(frontmatter, expression) for expression in where):
results.append((note.relative_to(vault_path).with_suffix('').as_posix(), frontmatter))
if as_json:
click.echo(json.dumps([{'path': rel, 'frontmatter': fm} for rel, fm in results],
ensure_ascii=False, indent=2, default=str))
else:
for rel, _ in results:
click.echo(rel)
def list_tasks(self, folder: str = None, date_from: str = None, date_to: str = None,
statuses: Optional[set] = None, ignore_from: str = None, as_json: bool = False,
vault: str = None):
"""Checkbox tasks across notes. With --from/--to, a note's date is its filename's
YYYY-MM-DD prefix, else its `date` property; undated notes are skipped."""
vault_name, vault_path = self._get_vault_and_path(vault)
ignored = set()
if ignore_from:
text = self._find_note(vault_path, ignore_from).read_text(encoding='utf-8-sig')
ignored = {_fold(task_text) for _, _, task_text, _ in _iter_tasks(text)}
results = []
for note in self._notes_in(vault_path, folder):
text = note.read_text(encoding='utf-8-sig')
prefix = _DATE_PREFIX.match(note.stem)
note_date = prefix.group(1) if prefix else str(_read_frontmatter(text).get('date') or '')[:10]
if (date_from or date_to) and not _DATE_PREFIX.match(note_date):
continue
if (date_from and note_date < date_from) or (date_to and note_date > date_to):
continue
rel = note.relative_to(vault_path).as_posix()
for line, char, task_text, heading in _iter_tasks(text):
status = _TASK_STATUS.get(char, char)
if (statuses and status not in statuses) or _fold(task_text) in ignored:
continue
results.append({'path': rel, 'line': line, 'date': note_date or None, 'status': status,
'heading': heading, 'text': task_text, 'char': char})
if as_json:
click.echo(json.dumps([{k: v for k, v in r.items() if k != 'char'} for r in results],
ensure_ascii=False, indent=2))
else:
for r in results:
click.echo(f"{r['path']}:{r['line']}: - [{r['char']}] {r['text']}")
def print_note(self, note_name: str, vault: str = None):
vault_name, vault_path = self._get_vault_and_path(vault)
note_path = vault_path / note_name
@@ -678,9 +918,21 @@ class OnyxCLI:
_write_text(note_path, new_content)
return True
@staticmethod
def _split_list(value: Optional[str]) -> List[str]:
return [item.strip() for item in value.split(',') if item.strip()] if value else []
@staticmethod
def _list_item_id(item: str) -> str:
"""Identity of a list item: a wikilink's target (alias and heading ignored), else its text."""
match = _WIKILINK.fullmatch(item.strip())
return (match.group(1).strip() if match else item.strip()).casefold()
def frontmatter_edit(self, note_name: str, keys: tuple, values: tuple = None, vault: str = None):
"""Set keys. `tags` and keys that are already lists in the note take a comma-separated list."""
vault_name, vault_path = self._get_vault_and_path(vault)
note_path = self._find_note(vault_path, note_name)
existing, _, _ = self._parse_frontmatter(note_path.read_text(encoding='utf-8-sig'))
updates = {}
@@ -691,14 +943,50 @@ class OnyxCLI:
for i, key in enumerate(keys):
value = values[i] if values and i < len(values) else None
for k in self._split_keys((key,)):
if k == 'tags':
updates[k] = [t.strip() for t in value.split(',') if t.strip()] if value else []
if k == 'tags' or isinstance(existing.get(k), list):
updates[k] = self._split_list(value)
else:
updates[k] = value if value is not None else ""
self._rewrite_frontmatter(note_path, updates)
click.echo(f"Updated frontmatter for {note_name}")
def frontmatter_list_items(self, note_name: str, key: str, items: tuple, remove: bool = False,
vault: str = None):
"""Add items to, or remove them from, a list property; other items and keys stay as they are.
Items are matched by wikilink target, so "[[Name|Alias]]" and "[[name]]" are the same
item. Adding skips duplicates; a missing key becomes a list, a text value becomes its
first item. Each item is taken whole (no comma splitting)."""
vault_name, vault_path = self._get_vault_and_path(vault)
note_path = self._find_note(vault_path, note_name)
existing, _, _ = self._parse_frontmatter(note_path.read_text(encoding='utf-8-sig'))
value = existing.get(key)
current = value if isinstance(value, list) else ([] if value in (None, '') else [value])
if any(isinstance(item, (list, dict)) for item in current):
raise click.UsageError(f"'{key}' in {note_name} has nested values (unquoted [[link]]?); "
"fix it by hand: Obsidian needs \"[[link]]\" quoted")
current = [item if isinstance(item, str) else str(item) for item in current if item is not None]
if remove:
dropped = {self._list_item_id(item) for item in items}
new = [item for item in current if self._list_item_id(item) not in dropped]
else:
new, seen = list(current), {self._list_item_id(item) for item in current}
for item in (i.strip() for i in items):
if item and self._list_item_id(item) not in seen:
new.append(item)
seen.add(self._list_item_id(item))
changed = len(new) - len(current)
if not changed:
click.echo(f"No change to '{key}' in {note_name}")
return
self._rewrite_frontmatter(note_path, {key: new})
click.echo(f"{'Removed' if remove else 'Added'} {abs(changed)} item(s) "
f"{'from' if remove else 'to'} '{key}' in {note_name}")
def frontmatter_view(self, note_name: str, keys: tuple, value: str = None, vault: str = None, open_file: bool = False, output_path: Union[bool, str, None] = None):
vault_name, vault_path = self._get_vault_and_path(vault)
note_path = self._find_note(vault_path, note_name)
@@ -926,7 +1214,7 @@ def _periodic_output_options(command):
help="Don't open Obsidian; a newly created note keeps raw Templater syntax "
"until Obsidian processes it")(command)
@click.version_option(version='0.2.0', prog_name='onyx')
@click.version_option(version='0.4.1', prog_name='onyx')
@click.group(name='onyx')
def cli():
"""Onyx - Interact with Obsidian vaults from the command line
@@ -1094,6 +1382,95 @@ def create(note_name, content, vault, overwrite, append, open_after, template):
content = content.replace('\\n', '\n')
OnyxCLI().create_note(note_name, content, vault, overwrite, append, open_after, template)
@cli.command()
@click.argument('note_name')
@click.option('--heading', required=True,
help="Section title: '## Journal' (that level) or 'Journal' (any level); case-insensitive")
@click.option('--content', required=True, help="Text to insert; '-' reads stdin; literal \\n becomes a newline")
@click.option('--replace', is_flag=True, help="Replace the section's body instead of appending to it")
@click.option('--create', is_flag=True, help="Add the section at the end of the note if it is missing")
@click.option('--vault', help="Vault name (if not using default)")
def section(note_name, heading, content, replace, create, vault):
"""Append to, or replace, one section of a note
Appends at the end of the section (before the next heading of the same or a
higher level), after a blank line, except between two list items. Headings in
code blocks are ignored. Everything outside the section stays byte-for-byte.
USAGE:
onyx section "periodic/daily/2026-10-19" --heading "## Journal" --content "### 10:00 - Titre\\n- note"
onyx section "periodic/daily/2026-10-19" --heading "### Matin" --content "- [ ] Appeler Haro"
onyx section "periodic/weekly/2026-W43" --heading "## Weekly review" --replace --content - < review.md
"""
content = sys.stdin.read() if content == '-' else content.replace('\\n', '\n')
OnyxCLI().write_section(note_name, heading, content, replace, create, vault)
@cli.command()
@click.argument('name')
@click.option('--folder', help="Only notes under this vault-relative folder (e.g. entities)")
@click.option('--link', is_flag=True, help="Print a ready-to-paste wikilink instead of the path")
@click.option('--vault', help="Vault name (if not using default)")
def resolve(name, folder, link, vault):
"""Find notes by filename or alias
Exact match on the filename or any `aliases` entry, ignoring case and accents
(no fuzzy matching). Prints one vault-relative path per match; exits 1 when
nothing matches. --link prints [[Note]] or [[Note|Alias]] (a path link when the
filename is shared by several notes).
USAGE:
onyx resolve "Stéphane" --folder entities --link
onyx resolve "METC"
"""
if not OnyxCLI().resolve_note(name, folder, link, vault):
click.echo(f"No note named or aliased '{name}'", err=True)
sys.exit(1)
@cli.command(name='list')
@click.option('--folder', help="Only notes under this vault-relative folder")
@click.option('--where', multiple=True,
help="Frontmatter filter, repeatable (AND): key=value, key!=value, key, !key")
@click.option('--json', 'as_json', is_flag=True, help="Print paths and frontmatter as JSON")
@click.option('--vault', help="Vault name (if not using default)")
def list_command(folder, where, as_json, vault):
"""List notes, filtered by frontmatter
Values compare without case or accents; a [[link]] compares by its target, and a
list matches when any item does. Prints vault-relative paths, or JSON with --json.
USAGE:
onyx list --folder projects --where type=project --where status=active
onyx list --where client=Symbolitech --where "status!=done" --json
"""
OnyxCLI().list_notes(folder, where, as_json, vault)
@cli.command()
@click.option('--folder', help="Only notes under this vault-relative folder (e.g. periodic/daily)")
@click.option('--from', 'date_from', help="First note date (YYYY-MM-DD), inclusive")
@click.option('--to', 'date_to', help="Last note date (YYYY-MM-DD), inclusive")
@click.option('--status', help="Comma-separated: open, doing, done, cancelled (default: all)")
@click.option('--ignore-from', help="Skip tasks whose text also appears in this note (e.g. the daily template)")
@click.option('--json', 'as_json', is_flag=True, help="JSON with path, line, date, status, heading, text")
@click.option('--vault', help="Vault name (if not using default)")
def tasks(folder, date_from, date_to, status, ignore_from, as_json, vault):
"""List checkbox tasks: - [ ] open, - [/] doing, - [x] done, - [-] cancelled
With --from/--to, a note's date is the YYYY-MM-DD at the start of its filename,
else its `date` property; undated notes are skipped. Tasks in code blocks are ignored.
USAGE:
onyx tasks --folder periodic/daily --from 2026-10-12 --to 2026-10-18 --status open \\
--ignore-from resources/template/daily-note
"""
for value in (date_from, date_to):
if value and not re.fullmatch(r'\d{4}-\d{2}-\d{2}', value):
raise click.UsageError(f"Invalid date '{value}': use YYYY-MM-DD")
statuses = {s.strip() for s in status.split(',')} if status else None
unknown = (statuses or set()) - set(_TASK_STATUS.values())
if unknown:
raise click.UsageError(f"Unknown status {', '.join(sorted(unknown))}: use open, doing, done, cancelled")
OnyxCLI().list_tasks(folder, date_from, date_to, statuses, ignore_from, as_json, vault)
@cli.command()
@click.argument('note_name')
@click.option('--vault', help="Vault name (if not using default)")
@@ -1132,31 +1509,40 @@ def delete(note_path, vault):
@click.option('--view', is_flag=True, help="View frontmatter")
@click.option('--clear', is_flag=True, help="Clear frontmatter values")
@click.option('--delete', is_flag=True, help="Delete frontmatter keys")
@click.option('--add', is_flag=True, help="Add each --value as an item of the list --key (no duplicates)")
@click.option('--remove', is_flag=True, help="Remove each --value from the list --key")
@click.option('--key', required=True, multiple=True, help="Frontmatter key to manage")
@click.option('--value', multiple=True, help="Value to set or check for")
@click.option('--open', 'open_file', is_flag=True, help="Open the file referenced in the value")
@click.option('--vault', help="Vault name (if not using default)")
@click.option('--output-path', is_flag=False, flag_value=True, default=None, help="Resolve relative paths. Can be a flag (uses config prefix) or a string (custom prefix).")
def frontmatter_command(note_name, edit, view, clear, delete, key, value, open_file, vault, output_path):
def frontmatter_command(note_name, edit, view, clear, delete, add, remove, key, value, open_file, vault, output_path):
"""Manage YAML frontmatter in notes
Must specify exactly one action: --edit, --view, --clear, or --delete
Must specify exactly one action: --edit, --view, --clear, --delete, --add or --remove
--edit replaces a value; `tags` and keys already holding a list take a
comma-separated list. --add/--remove change single items of a list property;
repeat --value for several items. Items match by wikilink target, so
"[[Name|Alias]]" and "[[name]]" are the same item.
USAGE:
onyx frontmatter "my-note" --view --key "tags"
onyx frontmatter "my-note" --edit --key "tags" --value "project,work"
onyx frontmatter "my-note" --add --key participants --value "[[Haro]]" --value "[[Jeffrey]]"
onyx frontmatter "my-note" --remove --key participants --value "[[Haro]]"
onyx frontmatter "my-note" --delete --key "date"
"""
cli = OnyxCLI()
if sum([edit, view, clear, delete]) != 1:
raise click.UsageError("Exactly one of --edit, --view, --clear, or --delete must be specified")
if sum([edit, view, clear, delete, add, remove]) != 1:
raise click.UsageError("Exactly one of --edit, --view, --clear, --delete, --add or --remove must be specified")
if edit:
if value and len(value) > 1 and len(key) != len(value):
# If we have multiple values, they must match keys count
# Unless we have 1 value, which we apply to all keys (handled in frontmatter_edit)
raise click.UsageError(f"Number of values ({len(value)}) must match number of keys ({len(key)})")
cli.frontmatter_edit(note_name, key, value, vault)
elif view:
# For view, we ignore value unless it's for checking existence, which is complex with multiple keys
@@ -1167,11 +1553,16 @@ def frontmatter_command(note_name, edit, view, clear, delete, key, value, open_f
cli.frontmatter_clear(note_name, key, vault)
elif delete:
cli.frontmatter_delete(note_name, key, vault)
else:
if len(key) != 1 or not value:
raise click.UsageError("--add/--remove need exactly one --key and at least one --value")
cli.frontmatter_list_items(note_name, key[0], value, remove=remove, vault=vault)
if __name__ == '__main__':
# Scripts read onyx's output (e.g. `--print-path`): emit UTF-8 with LF on every OS.
# Without this, Windows pipes get the ANSI code page (é -> 0xE9; PyInstaller ignores
# PYTHONUTF8) and CRLF, whose trailing \r survives bash's $(...).
# Scripts talk to onyx through pipes (`--content -`, `--print-path`): UTF-8 with LF on
# every OS. Without this, Windows pipes use the ANSI code page (é -> 0xE9 out, UTF-8 in
# read as "é"; PyInstaller ignores PYTHONUTF8) and CRLF, whose \r survives bash's $(...).
sys.stdin.reconfigure(encoding='utf-8')
for stream in (sys.stdout, sys.stderr):
stream.reconfigure(encoding='utf-8', newline='\n')
cli()
+216 -77
View File
@@ -1,4 +1,7 @@
import json
import os
import subprocess
import sys
import unittest
import yaml
import shutil
@@ -9,6 +12,8 @@ import click
from click.testing import CliRunner
from datetime import datetime
SRC = Path(__file__).resolve().parent.parent / 'src' / 'onyx.py'
class TestOnyxCLI(unittest.TestCase):
def setUp(self):
# Create temporary test directory and files
@@ -35,89 +40,12 @@ class TestOnyxCLI(unittest.TestCase):
shutil.rmtree(self.test_dir, ignore_errors=True)
shutil.rmtree(self.temp_config_dir, ignore_errors=True)
def test_set_default_vault(self):
"""Test setting default vault"""
self.cli.set_default_vault('new_vault', str(self.test_dir))
self.assertEqual(self.cli.default_vault, 'new_vault')
config = yaml.safe_load(self.cli.config_file.read_text(encoding='utf-8-sig'))
self.assertEqual(config['default_vault'], 'new_vault')
self.assertEqual(Path(config['vaults']['new_vault']), self.test_dir.resolve())
def test_create_note(self):
"""Test note creation"""
# Test basic note creation
self.cli.create_note('test.md', 'Test content')
note_path = self.test_dir / 'test.md'
self.assertTrue(note_path.exists())
def test_writes_keep_lf_without_bom(self):
"""Append and frontmatter edits write LF, no BOM, even on Windows"""
note_path = self.test_dir / 'lf.md'
note_path.write_bytes(b'---\nstatus: draft\n---\n# Journal\n')
self.cli.create_note('lf.md', '### 10:00 - Entry\nline', append=True)
self.cli.frontmatter_edit('lf', ('status',), ('done',))
data = note_path.read_bytes()
self.assertNotIn(b'\r', data)
self.assertFalse(data.startswith(b'\xef\xbb\xbf'))
self.assertIn(b'status: done', data)
self.assertTrue(data.endswith(b'# Journal\n\n### 10:00 - Entry\nline'))
@unittest.skip("Method export_to_csv not implemented")
def test_export_to_csv(self):
"""Test exporting note frontmatter to CSV"""
# Create a test note with frontmatter
note_content = """---
title: Test Note
tags: [tag1, tag2]
status: in-progress
date: 2025-10-28
custom: value
---
Note content"""
self.cli.create_note('test_note.md', note_content)
# Test export with specific columns included
output_file = self.test_dir / 'output1.csv'
self.cli.export_to_csv('test_note', str(output_file), include_columns=['title', 'status', 'date'])
with open(output_file, 'r', encoding='utf-8') as f:
content = f.read().strip()
self.assertEqual(content, 'title,status,date\nTest Note,in-progress,2025-10-28')
# Test export excluding specific columns
output_file = self.test_dir / 'output2.csv'
self.cli.export_to_csv('test_note', str(output_file), exclude_columns=['tags', 'custom'])
with open(output_file, 'r', encoding='utf-8') as f:
content = f.read().strip()
self.assertEqual(content, 'title,status,date\nTest Note,in-progress,2025-10-28')
# Test export with both include and exclude (exclude takes precedence)
output_file = self.test_dir / 'output3.csv'
self.cli.export_to_csv('test_note', str(output_file),
include_columns=['title', 'status', 'date', 'custom'],
exclude_columns=['status'])
with open(output_file, 'r', encoding='utf-8') as f:
content = f.read().strip()
self.assertEqual(content, 'title,date,custom\nTest Note,2025-10-28,value')
# Test with non-existent note
with self.assertRaises(click.UsageError) as context:
self.cli.export_to_csv('non_existent', 'output.csv')
self.assertTrue("not found in vault" in str(context.exception))
# Test with note without frontmatter
self.cli.create_note('no_frontmatter.md', 'Just content')
with self.assertRaises(click.UsageError) as context:
self.cli.export_to_csv('no_frontmatter', 'output.csv')
self.assertTrue("No frontmatter found" in str(context.exception))
# Test with empty frontmatter
self.cli.create_note('empty_frontmatter.md', '---\n---\nContent')
with self.assertRaises(click.UsageError) as context:
self.cli.export_to_csv('empty_frontmatter', 'output.csv')
self.assertTrue("Empty frontmatter" in str(context.exception))
self.assertEqual(note_path.read_text(encoding='utf-8-sig'), 'Test content')
# Test note creation with auto-extension
@@ -136,6 +64,21 @@ Note content"""
(self.test_dir / 'test.md').read_text(encoding='utf-8-sig'),
'New content\nAdditional content'
)
def test_writes_keep_lf_without_bom(self):
"""Append and frontmatter edits write LF, no BOM, even on Windows"""
note_path = self.test_dir / 'lf.md'
note_path.write_bytes(b'---\nstatus: draft\n---\n# Journal\n')
self.cli.create_note('lf.md', '### 10:00 - Entry\nline', append=True)
self.cli.frontmatter_edit('lf', ('status',), ('done',))
data = note_path.read_bytes()
self.assertNotIn(b'\r', data)
self.assertFalse(data.startswith(b'\xef\xbb\xbf'))
self.assertIn(b'status: done', data)
self.assertTrue(data.endswith(b'# Journal\n\n### 10:00 - Entry\nline'))
def test_frontmatter_operations(self):
"""Test frontmatter operations"""
@@ -256,6 +199,187 @@ Test content"""
self.assertEqual(note.read_text(encoding='utf-8'),
'---\ntags:\n - a\n - b\n---\nCorps\n---\nPas un frontmatter\n')
MEETING = (
'---\n'
'type: meeting\n'
'participants:\n'
' - "[[Stéphane Charbonneau|Stéphane]]"\n'
' - "[[Haro]]"\n'
'summary: "Résumé : décisions."\n'
'---\n'
'Corps\n')
def test_frontmatter_edit_keeps_existing_list_type(self):
"""--edit on a key that is already a list writes a list, not one quoted string"""
note = self.test_dir / 'm.md'
note.write_text(self.MEETING, encoding='utf-8')
self.cli.frontmatter_edit('m', ('participants', 'type'), ('[[Jeffrey]], [[Haro]]', 'réunion, interne'))
self.assertEqual(note.read_text(encoding='utf-8'), self.MEETING
.replace(' - "[[Stéphane Charbonneau|Stéphane]]"\n - "[[Haro]]"\n',
' - "[[Jeffrey]]"\n - "[[Haro]]"\n')
.replace('type: meeting', 'type: réunion, interne'))
def test_frontmatter_add_and_remove_list_items(self):
"""Items match by link target (alias/case ignored); other items and keys untouched"""
note = self.test_dir / 'm.md'
note.write_text(self.MEETING, encoding='utf-8')
self.cli.frontmatter_list_items('m', 'participants', ('[[stéphane charbonneau]]', '[[Jeffrey]]', '[[Jeffrey|Jeff]]'))
self.cli.frontmatter_list_items('m', 'participants', ('[[Haro|H]]',), remove=True)
self.cli.frontmatter_list_items('m', 'mentioned', ('[[Livre, tome 2]]',))
self.cli.frontmatter_list_items('m', 'type', ('log',))
self.assertEqual(note.read_text(encoding='utf-8'),
'---\n'
'type:\n'
' - meeting\n'
' - log\n'
'participants:\n'
' - "[[Stéphane Charbonneau|Stéphane]]"\n'
' - "[[Jeffrey]]"\n'
'summary: "Résumé : décisions."\n'
'mentioned:\n'
' - "[[Livre, tome 2]]"\n'
'---\n'
'Corps\n')
with patch('click.echo') as echo:
self.cli.frontmatter_list_items('m', 'participants', ('[[Jeffrey|J]]',))
self.cli.frontmatter_list_items('m', 'absent', ('x',), remove=True)
self.assertEqual([c.args[0] for c in echo.call_args_list],
["No change to 'participants' in m", "No change to 'absent' in m"])
def test_frontmatter_add_refuses_unquoted_links(self):
note = self.test_dir / 'bad.md'
content = '---\nrelated:\n - [[Haro]]\n---\n'
note.write_text(content, encoding='utf-8')
with self.assertRaises(click.UsageError):
self.cli.frontmatter_list_items('bad', 'related', ('[[Plane]]',))
self.assertEqual(note.read_text(encoding='utf-8'), content)
DAILY = (
'---\n'
'type: daily-note\n'
'# Journal: not a heading inside frontmatter\n'
'---\n'
'\n'
'# 2026-10-29\n'
'\n'
'## To do\n'
'### Matin\n'
'- [ ] Regarder ma Weekly note\n'
'\n'
'### Après-midi\n'
'\n'
'### Soir\n'
'- [ ] Prendre calcium\n'
'\n'
'```markdown\n'
'## Journal\n'
'```\n'
'\n'
'## Journal\n'
'Aujourd’hui, Mark présente Align.')
def _daily(self):
note = self.test_dir / 'd.md'
note.write_text(self.DAILY, encoding='utf-8')
return note
def test_section_append(self):
"""Blank line before new blocks, none between list items or after an empty heading;
headings in frontmatter or code fences are ignored; nothing else moves"""
note = self._daily()
self.cli.write_section('d', '## Journal', '### 10:00 - Ménage\n- fait')
self.cli.write_section('d', 'matin', '- [ ] Appeler Haro')
self.cli.write_section('d', '### Après-midi', '- [ ] Courses\n')
self.cli.write_section('d', '## Journal', '### 11:00')
self.assertEqual(note.read_text(encoding='utf-8'), self.DAILY
.replace('- [ ] Regarder ma Weekly note\n', '- [ ] Regarder ma Weekly note\n- [ ] Appeler Haro\n')
.replace('### Après-midi\n', '### Après-midi\n- [ ] Courses\n')
.replace('Align.', 'Align.\n\n### 10:00 - Ménage\n- fait\n\n### 11:00\n'))
def test_section_replace_keeps_neighbours(self):
"""Replacing '## To do' drops its subsections and the code block inside it, but stops
at '## Journal' (the fake one in the fence doesn't end the section)"""
note = self._daily()
self.cli.write_section('d', '## To do', '- [ ] Une seule tâche', replace=True)
self.cli.write_section('d', '## Journal', '', replace=True)
self.assertEqual(note.read_text(encoding='utf-8'),
'---\ntype: daily-note\n# Journal: not a heading inside frontmatter\n---\n\n# 2026-10-29\n\n'
'## To do\n- [ ] Une seule tâche\n\n## Journal\n')
def test_section_missing_heading(self):
note = self._daily()
with self.assertRaises(click.UsageError):
self.cli.write_section('d', '## Review', 'x')
self.assertEqual(note.read_text(encoding='utf-8'), self.DAILY)
self.cli.write_section('d', 'Review', 'Bilan', create=True)
self.assertEqual(note.read_text(encoding='utf-8'), self.DAILY + '\n\n## Review\nBilan\n')
def _write_notes(self, notes: dict):
for rel, text in notes.items():
path = self.test_dir / rel
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(text, encoding='utf-8')
def _echoed(self, call, *args, **kwargs):
with patch('click.echo') as echo:
result = call(*args, **kwargs)
return [c.args[0] for c in echo.call_args_list], result
def test_resolve_by_name_or_alias(self):
"""Case/accent-insensitive exact match; alias gives [[Note|Alias]]; shared filename
gives a path link; no fuzzy match"""
self._write_notes({
'entities/people/Stéphane Charbonneau.md': '---\naliases:\n - Stéphane\n---\n',
'entities/people/Stéphane Bigham.md': '---\naliases: [stephane]\n---\n',
'entities/businesses/Securitech.md': '---\naliases:\n - Sécuritech\n---\n',
'entities/businesses/Haro.md': '',
'archives/Haro.md': '',
'.trash/Securitech.md': '',
})
self.assertEqual(self._echoed(self.cli.resolve_note, 'STEPHANE', link=True),
(['[[Stéphane Bigham|stephane]]', '[[Stéphane Charbonneau|Stéphane]]'], 2))
self.assertEqual(self._echoed(self.cli.resolve_note, 'sécuritech'),
(['entities/businesses/Securitech'], 1))
self.assertEqual(self._echoed(self.cli.resolve_note, 'haro', folder='entities', link=True),
(['[[entities/businesses/Haro]]'], 1))
self.assertEqual(self._echoed(self.cli.resolve_note, 'Charbonneau'), ([], 0))
def test_list_where(self):
self._write_notes({
'projects/A.md': '---\ntype: project\nstatus: active\nclient: "[[Symbolitech]]"\n---\n',
'projects/B.md': '---\ntype: project\nstatus: done\nclient: "[[Diakonos]]"\n---\n',
'projects/C.md': '---\ntype: project\ntags:\n - Écriture\n---\n',
'notes/D.md': '---\ntype: project\nstatus: active\n---\n',
})
list_notes = self.cli.list_notes
self.assertEqual(self._echoed(list_notes, 'projects', ('status=ACTIVE', 'client=symbolitech'))[0],
['projects/A'])
self.assertEqual(self._echoed(list_notes, 'projects', ('status!=done', 'type'))[0],
['projects/A', 'projects/C'])
self.assertEqual(self._echoed(list_notes, None, ('!status',))[0], ['projects/C'])
self.assertEqual(self._echoed(list_notes, 'projects', ('tags=ecriture',))[0], ['projects/C'])
def test_tasks_dates_statuses_and_template(self):
self._write_notes({
'template.md': '- [ ] Prendre calcium\n',
'daily/2026-10-12.md': '## To do\n### Matin\n- [ ] Appeler Haro\n- [x] Fait\n- [/] En cours\n'
'```\n- [ ] dans du code\n```\n## Soir\n - [ ] prendre CALCIUM\n- [-] Annulé\n',
'daily/2026-10-20.md': '- [ ] Trop tard\n',
'daily/Sans date.md': '---\ndate: 2026-10-13\n---\n- [ ] Daté par la propriété\n',
})
lines, _ = self._echoed(self.cli.list_tasks, 'daily', '2026-10-12', '2026-10-18',
{'open', 'doing'}, 'template')
self.assertEqual(lines, ['daily/2026-10-12.md:3: - [ ] Appeler Haro',
'daily/2026-10-12.md:5: - [/] En cours',
'daily/Sans date.md:4: - [ ] Daté par la propriété'])
output, _ = self._echoed(self.cli.list_tasks, 'daily', statuses={'cancelled'}, as_json=True)
self.assertEqual(json.loads(output[0]), [{'path': 'daily/2026-10-12.md', 'line': 11, 'date': '2026-10-12',
'status': 'cancelled', 'heading': 'Soir', 'text': 'Annulé'}])
def test_move_rewrites_every_link_form(self):
"""Aliases, headings, embeds, path links, frontmatter links, regex characters"""
(self.test_dir / 'films').mkdir()
@@ -474,5 +598,20 @@ Test content"""
self.assertIn(str(self.test_dir.resolve()), printed)
self.assertNotIn('path_prefix', printed)
def test_pipes_are_utf8_without_utf8_mode(self):
"""stdin/stdout are UTF-8 even when Python isn't in UTF-8 mode (frozen exe on Windows)"""
note = self.test_dir / 'd.md'
note.write_text('## Journal\n', encoding='utf-8')
env = {k: v for k, v in os.environ.items() if k not in ('PYTHONUTF8', 'PYTHONIOENCODING')}
home = str(self.temp_config_dir.resolve())
env.update(PYTHONUTF8='0', USERPROFILE=home, HOME=home)
result = subprocess.run([sys.executable, str(SRC), 'section', 'd', '--heading', 'Journal',
'--content', '-'], input='Réunion « test »'.encode('utf-8'),
capture_output=True, env=env)
self.assertEqual(result.returncode, 0, result.stderr)
self.assertEqual(note.read_text(encoding='utf-8'), '## Journal\nRéunion « test »\n')
printed = subprocess.run([sys.executable, str(SRC), 'print-note', 'd'], capture_output=True, env=env)
self.assertEqual(printed.stdout, '## Journal\nRéunion « test »\n\n'.encode('utf-8'))
if __name__ == '__main__':
unittest.main()