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 675 additions and 89 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 "tags" --value "project,urgent"
onyx frontmatter "note-name" --edit --key "status" --value "in-progress" 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 # Clear frontmatter values
onyx frontmatter "note-name" --clear --key "tags" onyx frontmatter "note-name" --clear --key "tags"
onyx frontmatter "note-name" --clear --key "date,status,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 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 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 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 (`"[[Haro]]"`). `tags`, and any key that is already a list in the note, take a comma-separated
empty (`status:`), cleared tags `tags: []`. 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 ### Version
@@ -262,6 +316,8 @@ onyx --version
- **Periodic Notes**: Support for daily, weekly, monthly, quarterly, and yearly notes - **Periodic Notes**: Support for daily, weekly, monthly, quarterly, and yearly notes
- **Frontmatter Management**: Edit, view, clear, and delete YAML frontmatter - **Frontmatter Management**: Edit, view, clear, and delete YAML frontmatter
- **Link Updates**: Automatically update internal links when moving notes - **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 - **Cross-Platform**: Works on macOS, Windows, and Linux
## Requirements ## Requirements
+401 -10
View File
@@ -9,6 +9,7 @@ import datetime
import builtins import builtins
from pathlib import Path from pathlib import Path
import re import re
import unicodedata
from collections import Counter from collections import Counter
from typing import List, Union, Optional, Dict, Any from typing import List, Union, Optional, Dict, Any
from urllib.parse import quote from urllib.parse import quote
@@ -90,6 +91,144 @@ def _iter_notes(vault_path: Path):
yield 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: class OnyxCLI:
_PERIODIC_DEFAULTS: Dict[str, Dict[str, str]] = { _PERIODIC_DEFAULTS: Dict[str, Dict[str, str]] = {
'daily': {'format': 'YYYY-MM-DD', 'folder': '', 'template': ''}, '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.""" """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) 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): def print_note(self, note_name: str, vault: str = None):
vault_name, vault_path = self._get_vault_and_path(vault) vault_name, vault_path = self._get_vault_and_path(vault)
note_path = vault_path / note_name note_path = vault_path / note_name
@@ -678,9 +918,21 @@ class OnyxCLI:
_write_text(note_path, new_content) _write_text(note_path, new_content)
return True 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): 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) vault_name, vault_path = self._get_vault_and_path(vault)
note_path = self._find_note(vault_path, note_name) note_path = self._find_note(vault_path, note_name)
existing, _, _ = self._parse_frontmatter(note_path.read_text(encoding='utf-8-sig'))
updates = {} updates = {}
@@ -691,14 +943,50 @@ class OnyxCLI:
for i, key in enumerate(keys): for i, key in enumerate(keys):
value = values[i] if values and i < len(values) else None value = values[i] if values and i < len(values) else None
for k in self._split_keys((key,)): for k in self._split_keys((key,)):
if k == 'tags': if k == 'tags' or isinstance(existing.get(k), list):
updates[k] = [t.strip() for t in value.split(',') if t.strip()] if value else [] updates[k] = self._split_list(value)
else: else:
updates[k] = value if value is not None else "" updates[k] = value if value is not None else ""
self._rewrite_frontmatter(note_path, updates) self._rewrite_frontmatter(note_path, updates)
click.echo(f"Updated frontmatter for {note_name}") 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): 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) vault_name, vault_path = self._get_vault_and_path(vault)
note_path = self._find_note(vault_path, note_name) 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 " help="Don't open Obsidian; a newly created note keeps raw Templater syntax "
"until Obsidian processes it")(command) "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') @click.group(name='onyx')
def cli(): def cli():
"""Onyx - Interact with Obsidian vaults from the command line """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') content = content.replace('\\n', '\n')
OnyxCLI().create_note(note_name, content, vault, overwrite, append, open_after, template) 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() @cli.command()
@click.argument('note_name') @click.argument('note_name')
@click.option('--vault', help="Vault name (if not using default)") @click.option('--vault', help="Vault name (if not using default)")
@@ -1132,24 +1509,33 @@ def delete(note_path, vault):
@click.option('--view', is_flag=True, help="View frontmatter") @click.option('--view', is_flag=True, help="View frontmatter")
@click.option('--clear', is_flag=True, help="Clear frontmatter values") @click.option('--clear', is_flag=True, help="Clear frontmatter values")
@click.option('--delete', is_flag=True, help="Delete frontmatter keys") @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('--key', required=True, multiple=True, help="Frontmatter key to manage")
@click.option('--value', multiple=True, help="Value to set or check for") @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('--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('--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).") @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 """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: USAGE:
onyx frontmatter "my-note" --view --key "tags" onyx frontmatter "my-note" --view --key "tags"
onyx frontmatter "my-note" --edit --key "tags" --value "project,work" 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" onyx frontmatter "my-note" --delete --key "date"
""" """
cli = OnyxCLI() cli = OnyxCLI()
if sum([edit, view, clear, delete]) != 1: if sum([edit, view, clear, delete, add, remove]) != 1:
raise click.UsageError("Exactly one of --edit, --view, --clear, or --delete must be specified") raise click.UsageError("Exactly one of --edit, --view, --clear, --delete, --add or --remove must be specified")
if edit: if edit:
if value and len(value) > 1 and len(key) != len(value): if value and len(value) > 1 and len(key) != len(value):
@@ -1167,11 +1553,16 @@ def frontmatter_command(note_name, edit, view, clear, delete, key, value, open_f
cli.frontmatter_clear(note_name, key, vault) cli.frontmatter_clear(note_name, key, vault)
elif delete: elif delete:
cli.frontmatter_delete(note_name, key, vault) 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__': if __name__ == '__main__':
# Scripts read onyx's output (e.g. `--print-path`): emit UTF-8 with LF on every OS. # Scripts talk to onyx through pipes (`--content -`, `--print-path`): UTF-8 with LF on
# Without this, Windows pipes get the ANSI code page (é -> 0xE9; PyInstaller ignores # every OS. Without this, Windows pipes use the ANSI code page (é -> 0xE9 out, UTF-8 in
# PYTHONUTF8) and CRLF, whose trailing \r survives bash's $(...). # 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): for stream in (sys.stdout, sys.stderr):
stream.reconfigure(encoding='utf-8', newline='\n') stream.reconfigure(encoding='utf-8', newline='\n')
cli() cli()
+216 -77
View File
@@ -1,4 +1,7 @@
import json
import os import os
import subprocess
import sys
import unittest import unittest
import yaml import yaml
import shutil import shutil
@@ -9,6 +12,8 @@ import click
from click.testing import CliRunner from click.testing import CliRunner
from datetime import datetime from datetime import datetime
SRC = Path(__file__).resolve().parent.parent / 'src' / 'onyx.py'
class TestOnyxCLI(unittest.TestCase): class TestOnyxCLI(unittest.TestCase):
def setUp(self): def setUp(self):
# Create temporary test directory and files # 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.test_dir, ignore_errors=True)
shutil.rmtree(self.temp_config_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): def test_create_note(self):
"""Test note creation""" """Test note creation"""
# Test basic note creation # Test basic note creation
self.cli.create_note('test.md', 'Test content') self.cli.create_note('test.md', 'Test content')
note_path = self.test_dir / 'test.md' note_path = self.test_dir / 'test.md'
self.assertTrue(note_path.exists()) 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') self.assertEqual(note_path.read_text(encoding='utf-8-sig'), 'Test content')
# Test note creation with auto-extension # Test note creation with auto-extension
@@ -137,6 +65,21 @@ Note content"""
'New content\nAdditional content' '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): def test_frontmatter_operations(self):
"""Test frontmatter operations""" """Test frontmatter operations"""
# Create a test note with frontmatter # Create a test note with frontmatter
@@ -256,6 +199,187 @@ Test content"""
self.assertEqual(note.read_text(encoding='utf-8'), self.assertEqual(note.read_text(encoding='utf-8'),
'---\ntags:\n - a\n - b\n---\nCorps\n---\nPas un frontmatter\n') '---\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): def test_move_rewrites_every_link_form(self):
"""Aliases, headings, embeds, path links, frontmatter links, regex characters""" """Aliases, headings, embeds, path links, frontmatter links, regex characters"""
(self.test_dir / 'films').mkdir() (self.test_dir / 'films').mkdir()
@@ -474,5 +598,20 @@ Test content"""
self.assertIn(str(self.test_dir.resolve()), printed) self.assertIn(str(self.test_dir.resolve()), printed)
self.assertNotIn('path_prefix', 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__': if __name__ == '__main__':
unittest.main() unittest.main()