armarium 0.1.0__py3-none-any.whl

armarium/__init__.py

@@ -0,0 +1 @@
+"""Read-only tools for human-maintained Armarium vaults."""

armarium/add.py

@@ -0,0 +1,304 @@
+"""Campaign creation and shared operations for adding records.
+
+Command modules prepare type-specific contents. These helpers resolve the local
+vault conventions and validate each new record; the CLI validates the whole vault.
+"""
+
+import re
+import shutil
+import unicodedata
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from armarium.lib import CAMPAIGN_NAME, find_files, find_vault, parse_directories
+from armarium.logging import logger
+from armarium.parse import Record
+from armarium.validate import CAMPAIGN_DIRECTORIES, validate
+
+
+def select_vault(vault: Path | None) -> Path:
+    """Resolve an explicit vault root or discover it from the working directory.
+
+    Reject explicit paths inside a vault rather than silently changing their scope.
+    """
+    selected = vault.expanduser().resolve() if vault is not None else Path.cwd()
+    root = find_vault(selected)
+    if vault is not None and selected != root:
+        raise ValueError("--vault must name the vault root")
+    return root
+
+
+def infer_campaign(root: Path, campaign: int | None) -> int | None:
+    """Prefer an explicit campaign; otherwise infer one only inside this vault."""
+    working_directory = Path.cwd().resolve()
+    if campaign is None and working_directory.is_relative_to(root):
+        parts = working_directory.relative_to(root).parts
+        if (
+            len(parts) >= 2
+            and parts[0] == "campaigns"
+            and CAMPAIGN_NAME.fullmatch(parts[1])
+        ):
+            campaign = int(parts[1].removeprefix("campaign_"))
+    return campaign
+
+
+def require_campaign(root: Path, campaign: int | None) -> int:
+    """Select a positive campaign number, raising when none can be inferred."""
+    campaign = infer_campaign(root, campaign)
+    if campaign is None:
+        raise ValueError("specify --campaign or run inside a campaign directory")
+    if campaign < 1:
+        raise ValueError("campaign number must be positive")
+    return campaign
+
+
+def check_name(name: str) -> None:
+    """Reject names that are empty, non-plain, path-like or include .md."""
+    if (
+        not name
+        or name != " ".join(name.split())
+        or name.startswith(".")
+        or name.endswith(".")
+        or name.lower().endswith(".md")
+        or any(c in name for c in '/\\\x00[]#|:*?"<>')
+        or any(ord(c) < 32 for c in name)
+    ):
+        raise ValueError(
+            "name must be a plain record name without .md, path separators, or reserved characters"
+        )
+
+
+def record_directory(root: Path, kind: str, campaign: int | str | None) -> Path:
+    """Read a Type's scoped directory and require a real, existing write path.
+
+    None selects shared scope. An integer selects campaign_N; a folder name
+    preserves a campaign already identified by an existing record.
+    """
+    definition, failures = Record.parse(root / f"reference/types/{kind}.md", root)
+    if definition is None:
+        raise ValueError(f"cannot read {kind} Type: {failures[0].message}")
+    declarations = parse_directories(definition.frontmatter.get("directories"))
+    scope = "shared" if campaign is None else "campaign"
+    if scope not in declarations:
+        raise ValueError(f"{kind} Type declares no {scope} directory")
+    if isinstance(campaign, int):
+        campaign = f"campaign_{campaign}"
+    base = root if campaign is None else root / "campaigns" / campaign
+    directory = base / declarations[scope]
+    for path in (directory, *directory.parents):
+        if path == root:
+            break
+        if not path.is_dir() or path.is_symlink():
+            raise ValueError(f"{path} must be an existing real directory")
+    return directory
+
+
+def check_destination(destination: Path, *, normalize: bool = False) -> None:
+    """Refuse case-equivalent entries, optionally normalizing Unicode names.
+
+    Plain user-supplied record names use NFC normalization. Numbered filenames
+    use their existing case-insensitive comparison. Exclusive writing also
+    protects against a destination created after this check.
+    """
+    names = [destination.name, *(p.name for p in destination.parent.iterdir())]
+    if normalize:
+        names = [unicodedata.normalize("NFC", name) for name in names]
+    if names[0].casefold() in {name.casefold() for name in names[1:]}:
+        raise FileExistsError(f"record already exists: {destination}")
+
+
+def read_template(root: Path, kind: str, *, check_reference: bool = False) -> Record:
+    """Parse a local template of the expected type, rejecting symlinked inputs.
+
+    check_reference also rejects a symlink at the reference directory, for
+    callers that require that component to be a real directory.
+    """
+    path = root / f"reference/templates/{kind}.md"
+    paths = (
+        (path, path.parent, path.parent.parent)
+        if check_reference
+        else (path, path.parent)
+    )
+    if any(p.is_symlink() for p in paths):
+        raise ValueError(f"{kind} template must be a regular file in the vault")
+    template, failures = Record.parse(path, root)
+    if template is None:
+        raise ValueError(f"cannot read {kind} template: {failures[0].message}")
+    if template.frontmatter.type != kind:
+        raise ValueError(f"{kind} template must declare the {kind} type")
+    return template
+
+
+def record_text(metadata: Mapping[str, Any], body: str) -> str:
+    """Serialize frontmatter without reordering fields and append the given body."""
+    return (
+        "---\n"
+        + yaml.safe_dump(dict(metadata), sort_keys=False, allow_unicode=True)
+        + "---\n"
+        + body
+    )
+
+
+def write_record(destination: Path, text: str, root: Path, kind: str) -> Path:
+    """Exclusively create and validate a record, removing it on any failure.
+
+    Log the destination and validation diagnostics. A failed exclusive open
+    leaves an existing entry untouched. After a successful open, write errors,
+    failed validation and interruptions remove only the newly created record.
+    Whole-vault validation is the caller's responsibility.
+    """
+    logger.info("Adding new %s record at %s", kind, destination)
+    stream = destination.open("x", encoding="utf-8")
+    try:
+        with stream:
+            stream.write(text)
+        result = validate(destination, root)
+        if result.failed:
+            for diagnostic in result.diagnostics:
+                diagnostic.report()
+            raise ValueError(
+                f"generated {kind} record failed validation; no record created"
+            )
+    except BaseException:
+        destination.unlink()
+        raise
+    return destination
+
+
+def record_number(
+    directory: Path,
+    campaign: int,
+    number: int | None,
+    *,
+    kind: str,
+    prefix: str,
+    digits: int,
+) -> int:
+    """Choose an unused bounded number, including records in archive directories.
+
+    When omitted, use the largest existing number plus one. Explicit numbers
+    must be unused and in the range representable by the filename's digits.
+    """
+    pattern = re.compile(rf"{prefix}-{campaign}-([0-9]{{{digits}}})\.md", re.IGNORECASE)
+    existing = {
+        int(match[1])
+        for path in find_files(directory)
+        if (match := pattern.fullmatch(path.name))
+    }
+    if number is None:
+        number = max(existing, default=0) + 1
+    maximum = 10**digits - 1
+    if not 1 <= number <= maximum:
+        raise ValueError(f"{kind} number must be between 1 and {maximum}")
+    if number in existing:
+        raise ValueError(
+            f"{kind} number {number} already exists in campaign {campaign}"
+        )
+    return number
+
+
+def _campaign_directories(root: Path) -> set[str]:
+    """Collect required campaign directories and locally declared additions.
+
+    Args:
+        root: Resolved vault directory.
+
+    Returns:
+        set[str]: Paths relative to each campaign directory.
+
+    Raises:
+        ValueError: A Type record cannot be parsed or its directories are invalid.
+        OSError: Type records cannot be read.
+    """
+    directories = set(CAMPAIGN_DIRECTORIES)
+    for path in find_files(root / "reference/types"):
+        if path.suffix.lower() != ".md":
+            continue
+        record, diagnostics = Record.parse(path, root)
+        if record is None:
+            raise ValueError(f"{path}: {diagnostics[0].message}")
+        declarations = parse_directories(record.frontmatter.get("directories"))
+        if "campaign" in declarations:
+            directories.add(declarations["campaign"])
+    return directories
+
+
+def _render_campaign(text: str, number: int) -> str:
+    """Adapt the campaign-1 examples in a local campaign template.
+
+    Args:
+        text: Template contents; campaign_1 denotes the new campaign.
+        number: Campaign number to put in directory names and clue ID examples.
+
+    Returns:
+        str: Text with campaign_1 and C-1-NNNN/C-1-XXXX tokens updated. Other
+            campaign references and surrounding formatting are preserved.
+    """
+    text = re.sub(r"\bcampaign_1\b", f"campaign_{number}", text)
+    return re.sub(r"\bC-1-(?=\d{4}\b|XXXX\b)", f"C-{number}-", text)
+
+
+def add_campaign(vault: Path | None = None, *, number: int | None = None) -> Path:
+    """Create an empty campaign from the selected vault's local scaffolding.
+
+    Args:
+        vault: Vault root, or None to discover it from the working directory.
+        number: Positive campaign number; defaults to the largest existing
+            campaign number plus one, or 1 when there are no campaigns.
+
+    Returns:
+        Path: Resolved absolute path of the new campaign. Existing files and
+            shared templates are unchanged; callers can validate the whole vault.
+
+    Raises:
+        ValueError: The vault cannot be identified, the number is invalid or
+            already used, or the local scaffolding is invalid.
+        OSError: A required template is missing, the destination exists, or
+            creation fails. A partial campaign is removed on write failure.
+        KeyboardInterrupt: Interrupted creation is cleaned up before propagating.
+    """
+    root = select_vault(vault)
+    for directory in ("campaigns", "reference/types", "reference/templates"):
+        path = root / directory
+        if not path.is_dir() or path.is_symlink():
+            raise ValueError(f"{path} must be a real directory")
+    existing = {
+        int(path.name.removeprefix("campaign_"))
+        for path in (root / "campaigns").iterdir()
+        if CAMPAIGN_NAME.fullmatch(path.name) and path.is_dir()
+    }
+    if number is None:
+        number = max(existing, default=0) + 1
+    if number < 1:
+        raise ValueError("campaign number must be positive")
+    if number in existing:
+        raise ValueError(f"campaign number {number} already exists")
+    destination = root / "campaigns" / f"campaign_{number}"
+    directories = _campaign_directories(root)
+    records: dict[str, str] = {}
+    for template, relative in (
+        ("Campaign", "reference/Campaign.md"),
+        ("Clues", "reference/indexes/Clues.md"),
+    ):
+        path = root / f"reference/templates/{template}.md"
+        if path.is_symlink():
+            raise ValueError(f"{path} must be a regular template file")
+        records[relative] = _render_campaign(path.read_text(encoding="utf-8"), number)
+    logger.info("Adding new campaign at %s", destination)
+    destination.mkdir()
+    try:
+        for directory in sorted(directories):
+            (destination / directory).mkdir(parents=True, exist_ok=True)
+        for relative, text in records.items():
+            (destination / relative).write_text(text, encoding="utf-8")
+        for directory in sorted(directories):
+            path = destination / directory
+            if not any(path.iterdir()):
+                (path / ".gitkeep").write_text("", encoding="utf-8")
+    except BaseException:
+        shutil.rmtree(destination)
+        raise
+    return destination

armarium/cli.py

@@ -0,0 +1,232 @@
+"""Command-line adapters for creating and validating vaults and records."""
+
+import argparse
+import json
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from armarium.add import add_campaign, read_template, select_vault
+from armarium.clue import add_clue
+from armarium.content import SUBTYPES, add_content
+from armarium.init import init_vault
+from armarium.lib import find_vault
+from armarium.logging import configure_logging, logger
+from armarium.note import add_note
+from armarium.player import add_player
+from armarium.session import add_session
+from armarium.transcript import add_transcript
+from armarium.validate import validate
+
+
+def _clue_text_help(vault: Path | None) -> str:
+    """Describe the selected vault's template text without making help fail.
+
+    Show usable text as a quoted string with escaped newlines. Missing vaults,
+    unreadable templates and invalid defaults are described explicitly. Escape
+    percent signs because argparse interpolates help strings.
+    """
+    try:
+        root = select_vault(vault)
+        template = read_template(root, "Clue")
+        text = template.frontmatter.get("text")
+        default = (
+            json.dumps(text, ensure_ascii=False)
+            if isinstance(text, str) and text.strip()
+            else "none; --text required"
+        )
+    except OSError, ValueError:
+        default = "unavailable; select a vault with a readable Clue template"
+    return f"nonblank clue text (default: {default})".replace("%", "%%")
+
+
+def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
+    """Parse command arguments separately from command execution.
+
+    Args:
+        argv: Arguments without the executable name, or None to read sys.argv.
+
+    Returns:
+        argparse.Namespace: Selected command and its paths and options.
+
+    Raises:
+        SystemExit: Argparse exits with 0 for help or 2 for invalid arguments.
+    """
+    parser = argparse.ArgumentParser(prog="armarium")
+    commands = parser.add_subparsers(dest="command", required=True)
+    initialize = commands.add_parser(
+        "init",
+        help="create and validate a vault from the starter vault",
+        description=(
+            "Create and validate a single-campaign vault at a new path. Missing "
+            "parent directories are created. Use --force to replace an existing directory."
+        ),
+    )
+    initialize.add_argument("path", type=Path, help="new vault directory")
+    initialize.add_argument(
+        "--force",
+        action="store_true",
+        help="replace an existing directory and all its contents; refuse files and symlinks",
+    )
+    add = commands.add_parser("add", help="add to an existing vault")
+    additions = add.add_subparsers(dest="addition", required=True)
+    campaign = additions.add_parser("campaign", help="create a new campaign")
+    content = additions.add_parser("content", help="create a Content record")
+    player = additions.add_parser("player", help="create a Player record")
+    note = additions.add_parser("note", help="create a Note record")
+    session = additions.add_parser("session", help="create a Session record")
+    clue = additions.add_parser("clue", help="create a Clue record", add_help=False)
+    transcript = additions.add_parser(
+        "transcript", help="create a Transcript for an existing Session"
+    )
+    for addition, create in (
+        (campaign, add_campaign),
+        (content, add_content),
+        (player, add_player),
+        (note, add_note),
+        (session, add_session),
+        (clue, add_clue),
+        (transcript, add_transcript),
+    ):
+        addition.set_defaults(create=create)
+        addition.add_argument(
+            "--vault",
+            type=Path,
+            help="vault root (default: discovered from the current directory)",
+        )
+    for addition in (content, player, note):
+        addition.add_argument("name", help="record name without .md")
+    for addition, shared in (
+        (content, ", or shared content"),
+        (player, ""),
+        (note, ", or shared notes"),
+        (session, ""),
+        (clue, ""),
+    ):
+        addition.add_argument(
+            "--campaign",
+            type=int,
+            help=f"campaign number within vault (default: current campaign directory{shared})",
+        )
+    for addition, description in (
+        (campaign, "positive campaign number"),
+        (session, "session number from 1 to 999"),
+        (clue, "clue number from 1 to 9999"),
+    ):
+        addition.add_argument(
+            "--number",
+            type=int,
+            help=f"{description} (default: largest existing number + 1)",
+        )
+    content.add_argument("--subtype", required=True, choices=SUBTYPES)
+    content.add_argument(
+        "--player", help="existing Player name or vault-relative path (PC only)"
+    )
+    clue.add_argument(
+        "-h",
+        "--help",
+        action="store_true",
+        dest="clue_help",
+        help="show this help message and exit",
+    )
+    clue_text = clue.add_argument("--text", help="nonblank clue text")
+    transcript.add_argument(
+        "session", help="unambiguous Session name or vault-relative path"
+    )
+    transcript.add_argument(
+        "--body-file",
+        type=Path,
+        required=True,
+        help="UTF-8 Markdown file containing transcript body",
+    )
+    command = commands.add_parser(
+        "validate",
+        help="validate a Markdown file or directory",
+        description=(
+            "Validate a Markdown file, or all Markdown files within a directory, "
+            "checking schemas, links and record context. Excludes files outside valid "
+            "Obsidian vaults; single-file mode will fail if outside a vault."
+        ),
+    )
+    command.add_argument(
+        "path", type=Path, help="Markdown file or directory to validate"
+    )
+    command.add_argument("--vault", type=Path, help="explicit vault directory")
+    args = parser.parse_args(argv)
+    if args.command == "add" and args.addition == "clue" and args.clue_help:
+        clue_text.help = _clue_text_help(args.vault)
+        clue.print_help()
+        parser.exit()
+    if args.command == "add":
+        for option in ("number", "campaign"):
+            value = getattr(args, option, None)
+            if value is not None and value < 1:
+                parser.error(f"--{option} must be positive")
+        if args.addition == "session" and args.number is not None and args.number > 999:
+            parser.error("--number must be between 1 and 999")
+        if args.addition == "clue" and args.number is not None and args.number > 9999:
+            parser.error("--number must be between 1 and 9999")
+    return args
+
+
+def main() -> None:
+    """Run the selected command and log its result.
+
+    Raises:
+        SystemExit: Status 1 when creation fails or files fail validation.
+            Creation reports validation warnings and errors; validate also reports
+            informational diagnostics and coverage counts. Argument parsing
+            exits with 0 for help or 2 for usage errors.
+    """
+    args = parse_args()
+    configure_logging()
+    if args.command == "init":
+        try:
+            logger.info(
+                "Initializing new vault at %s", args.path.expanduser().resolve()
+            )
+            destination = init_vault(args.path, force=args.force)
+        except OSError as exc:
+            logger.error("Cannot create vault at %s: %s", args.path, exc)
+            sys.exit(1)
+        logger.info("New vault successfully initialized; validating")
+        result = validate(destination)
+    elif args.command == "add":
+        try:
+            options = {
+                key: value
+                for key, value in vars(args).items()
+                if key not in {"command", "addition", "create", "clue_help"}
+            }
+            destination = args.create(**options)
+        except (OSError, ValueError) as exc:
+            logger.error("Cannot add %s: %s", args.addition, exc)
+            sys.exit(1)
+        logger.info("New %s successfully created; validating", args.addition)
+        result = validate(find_vault(destination))
+    else:
+        result = validate(args.path, args.vault)
+        result.report()
+    if args.command in {"init", "add"}:
+        for diagnostic in result.diagnostics:
+            if diagnostic.severity != "info":
+                diagnostic.report()
+    if result.failed:
+        failed_files = result.failed_files
+        noun = "file" if failed_files == 1 else "files"
+        logger.error("%s %s failed validation", failed_files, noun)
+        if args.command == "init":
+            logger.error("Vault retained at %s for inspection", destination)
+        elif args.command == "add":
+            logger.error(
+                "%s retained at %s for inspection",
+                args.addition.capitalize(),
+                destination,
+            )
+        sys.exit(1)
+    if args.command in {"init", "add"}:
+        logger.info("Validation completed successfully")
+
+
+if __name__ == "__main__":
+    main()

armarium/clue.py

@@ -0,0 +1,97 @@
+"""Create numbered Clue records using a vault's local template."""
+
+from pathlib import Path
+
+from armarium.add import (
+    check_destination,
+    read_template,
+    record_directory,
+    record_number,
+    record_text,
+    require_campaign,
+    select_vault,
+    write_record,
+)
+from armarium.index import VaultIndex
+from armarium.lib import (
+    find_campaign,
+    iter_wikilinks,
+)
+
+
+def _clue_subjects(text: str, destination: Path, index: VaultIndex) -> list[str]:
+    """Return canonical Content links in first-mention order, without duplicates.
+
+    Resolve text with the existing wikilink parser and vault index. Targets must
+    be shared or in the destination campaign. Malformed, missing, ambiguous or
+    ineligible targets raise ValueError before any record is written.
+    """
+    subjects: list[str] = []
+    for link in iter_wikilinks(text):
+        if isinstance(link, ValueError):
+            raise ValueError(f"invalid clue text link: {link}")
+        target, problem = index.resolve(link[0], destination)
+        if problem or target is None:
+            raise ValueError(
+                f"clue text [[{link[0]}]]: {problem}; use a unique Content path"
+            )
+        record = index.parse(target)[0] if target.suffix.lower() == ".md" else None
+        if record is None or record.frontmatter.type != "Content":
+            raise ValueError(f"clue text [[{link[0]}]] must target Content")
+        if find_campaign(target, index.root) not in {
+            None,
+            find_campaign(destination, index.root),
+        }:
+            raise ValueError(f"clue text [[{link[0]}]] targets another campaign")
+        canonical = f"[[{target.relative_to(index.root).with_suffix('').as_posix()}]]"
+        if canonical not in subjects:
+            subjects.append(canonical)
+    return subjects
+
+
+def add_clue(
+    vault: Path | None = None,
+    *,
+    campaign: int | None = None,
+    number: int | None = None,
+    text: str | None = None,
+) -> Path:
+    """Create and validate a Clue stub without modifying existing records.
+
+    Args:
+        vault: Vault root, or None to discover it from the working directory.
+        campaign: Existing campaign number, or None to infer the current campaign.
+        number: Clue number, or None for the largest existing number plus one.
+        text: Nonblank clue text, or None to use the local template text.
+
+    Returns:
+        Path: Resolved path of the new C-N-NNNN.md record after its schema and
+            contextual checks pass. Initial values come from the local template.
+
+    Raises:
+        ValueError: No campaign is selected, numbering or scaffolding is invalid,
+            or the generated record fails validation. Diagnostics are logged.
+        OSError: A destination exists or a filesystem operation fails.
+        KeyboardInterrupt: The partial record is removed before propagating.
+    """
+    root = select_vault(vault)
+    campaign = require_campaign(root, campaign)
+    directory = record_directory(root, "Clue", campaign)
+    number = record_number(
+        directory, campaign, number, kind="clue", prefix="C", digits=4
+    )
+    destination = directory / f"C-{campaign}-{number:04}.md"
+    check_destination(destination)
+    template = read_template(root, "Clue")
+    metadata = dict(template.frontmatter)
+    clue_text = text if text is not None else metadata.get("text")
+    if not isinstance(clue_text, str) or not clue_text.strip():
+        raise ValueError(
+            "provide nonblank --text or set text in the local Clue template"
+        )
+    metadata["text"] = clue_text
+    metadata["subjects"] = _clue_subjects(clue_text, destination, VaultIndex(root))
+    for field in ("first_session", "last_session"):
+        metadata.setdefault(field, None)
+    text = record_text(metadata, template.body.text)
+    return write_record(destination, text, root, "Clue")