atlas-vault 0.1.0__tar.gz

atlas_vault-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan Mattson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

atlas_vault-0.1.0/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: atlas-vault
+Version: 0.1.0
+Summary: A command-line tool for managing and validating Markdown-based worldbuilding vaults.
+Author-email: Ryan Mattson <ramattson5@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/you/atlas
+Project-URL: Issues, https://github.com/you/atlas/issues
+Keywords: worldbuilding,markdown,cli,vault
+Classifier: Programming Language :: Python :: 3
+Classifier: Environment :: Console
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Dynamic: license-file
+
+# Atlas
+
+A command-line tool for managing Markdown worldbuilding vaults, built with Obsidian in mind.
+
+Atlas creates, moves, deletes, lists, and searches notes in a vault of plain Markdown files. It keeps note ids and `[[wiki links]]` consistent when you reorganize, so renaming a note never leaves broken links behind.
+
+## Features
+
+- Create notes from templates, with frontmatter written for you
+- Move or rename notes and automatically update every wiki link that points at them
+- Safe deletes: notes go to a trash folder instead of being erased
+- Tree view of your vault and title search
+- Works on plain `.md` files, so your vault stays usable in Obsidian or any other editor
+
+## Requirements
+
+- Python 3.11 or newer
+
+## Installation
+
+
+
+## Quick start
+
+```bash
+cd ~/Documents/MyWorld
+atlas init
+atlas create "Nations/Republic of Valora" --type Nation
+atlas list
+```
+
+`atlas init` marks a folder as an Atlas vault by creating a `.atlas` directory inside it. Every other command needs that directory to exist.
+
+## Finding your vault
+
+Atlas looks for a vault in this order:
+
+1. The path given with `-v` / `--vault`
+2. The current directory, then up to five parent directories, stopping at the first one that contains `.atlas`
+
+So you can run commands from any subfolder of your vault without passing a path. Global options go before the command:
+
+```bash
+atlas --vault ~/Documents/MyWorld list
+atlas --quiet create "Characters/Aria"
+```
+
+| Option | Description |
+| --- | --- |
+| `-v`, `--vault PATH` | Path to the vault. |
+| `--quiet` | Silence messages from Atlas. |
+| `--version` | Show the Atlas version. |
+
+## Commands
+
+Note names are paths relative to the vault root. The `.md` extension is optional.
+
+### `atlas init`
+
+Initializes the current directory (or `--vault`) as an Atlas vault. This creates `.atlas/` directory.
+
+### `atlas create NAME [NAME ...]`
+
+Creates one or more notes. Missing folders are created for you. Each new note gets an `id` in its frontmatter, generated from its path, and a heading with its title.
+
+```bash
+atlas create "Nations/Republic of Valora"
+atlas create "Characters/Aria" "Characters/Bram" --type character
+atlas create "Places/Old Harbor" --template location --open
+```
+
+| Option | Description |
+| --- | --- |
+| `--type TYPE` | Sets `type` in the note's frontmatter, lowercased. |
+| `-t`, `--template NAME` | Starts the note from a template in `.atlas/templates`. |
+| `--open` | Opens the last created note in `$EDITOR`. |
+
+### `atlas list`
+
+Prints a tree of every Markdown file in the vault. Hidden files and folders are skipped unless you pass `-a` / `--all`.
+
+### `atlas search QUERY`
+
+Prints the vault-relative path of every note whose title contains the query. The match is case-insensitive and only looks at titles, not folders or note contents. Use `-a` / `--all` to include hidden directories such as the trash.
+
+```bash
+atlas search valora
+```
+
+### `atlas move SOURCE [SOURCE ...] DESTINATION`
+
+Moves or renames notes.
+
+- With one source, the destination is the new path of the note.
+- With several sources, the destination must be an existing folder.
+
+```bash
+atlas move "Nations/Valora" "Nations/Republic of Valora"
+atlas move "Characters/Aria" "Characters/Bram" Archive
+```
+
+When a note moves, Atlas:
+
+- Rewrites the note's frontmatter `id` to match its new path
+- Updates wiki links in every note in the vault, including aliases (`[[Note|alias]]`), headings (`[[Note#Heading]]`), and embeds (`![[Note]]`)
+- Leaves links inside code blocks and inline code untouched
+- Leaves a bare-title link alone when several notes share that title, since it is unclear which one was meant
+
+All moves are checked before anything changes, so a bad argument never leaves the vault half moved. Pass `--no-links` to skip the link updates.
+
+### `atlas delete NAME [NAME ...]`
+
+Moves notes to the vault's `.trash` folder instead of erasing them. A timestamp is added to the file name, so deleting a note with the same name twice never overwrites the earlier copy.
+
+## Templates
+
+Templates are Markdown files in `.atlas/templates`. Pass the name without the `.md` suffix:
+
+```bash
+atlas create "Places/Old Harbor" --template location
+```
+
+Templates can have frontmatter and a body, and `{{placeholders}}` are filled in when the note is created:
+
+| Placeholder | Value |
+| --- | --- |
+| `{{title}}` | The note title (its file name without `.md`). |
+| `{{id}}` | The generated note id. |
+| `{{date}}` | Today's date as `YYYY-MM-DD`. |
+
+Unknown placeholders are left as they are. Example `.atlas/templates/location.md`:
+
+```markdown
+---
+type: location
+created: "{{date}}"
+tags: []
+---
+
+# {{title}}
+
+## Description
+
+## Notable people
+```
+
+The note `id` is always generated by Atlas, and a `--type` given on the command line overrides a `type` set in the template.
+
+## Vault layout
+
+```text
+MyWorld/
+├── .atlas/
+│   ├── config.toml
+│   └── templates/
+├── .trash/
+├── Nations/
+│   └── Republic of Valora.md
+└── Characters/
+    └── Aria.md
+```
+
+## License
+
+MIT

atlas_vault-0.1.0/README.md

@@ -0,0 +1,165 @@
+# Atlas
+
+A command-line tool for managing Markdown worldbuilding vaults, built with Obsidian in mind.
+
+Atlas creates, moves, deletes, lists, and searches notes in a vault of plain Markdown files. It keeps note ids and `[[wiki links]]` consistent when you reorganize, so renaming a note never leaves broken links behind.
+
+## Features
+
+- Create notes from templates, with frontmatter written for you
+- Move or rename notes and automatically update every wiki link that points at them
+- Safe deletes: notes go to a trash folder instead of being erased
+- Tree view of your vault and title search
+- Works on plain `.md` files, so your vault stays usable in Obsidian or any other editor
+
+## Requirements
+
+- Python 3.11 or newer
+
+## Installation
+
+
+
+## Quick start
+
+```bash
+cd ~/Documents/MyWorld
+atlas init
+atlas create "Nations/Republic of Valora" --type Nation
+atlas list
+```
+
+`atlas init` marks a folder as an Atlas vault by creating a `.atlas` directory inside it. Every other command needs that directory to exist.
+
+## Finding your vault
+
+Atlas looks for a vault in this order:
+
+1. The path given with `-v` / `--vault`
+2. The current directory, then up to five parent directories, stopping at the first one that contains `.atlas`
+
+So you can run commands from any subfolder of your vault without passing a path. Global options go before the command:
+
+```bash
+atlas --vault ~/Documents/MyWorld list
+atlas --quiet create "Characters/Aria"
+```
+
+| Option | Description |
+| --- | --- |
+| `-v`, `--vault PATH` | Path to the vault. |
+| `--quiet` | Silence messages from Atlas. |
+| `--version` | Show the Atlas version. |
+
+## Commands
+
+Note names are paths relative to the vault root. The `.md` extension is optional.
+
+### `atlas init`
+
+Initializes the current directory (or `--vault`) as an Atlas vault. This creates `.atlas/` directory.
+
+### `atlas create NAME [NAME ...]`
+
+Creates one or more notes. Missing folders are created for you. Each new note gets an `id` in its frontmatter, generated from its path, and a heading with its title.
+
+```bash
+atlas create "Nations/Republic of Valora"
+atlas create "Characters/Aria" "Characters/Bram" --type character
+atlas create "Places/Old Harbor" --template location --open
+```
+
+| Option | Description |
+| --- | --- |
+| `--type TYPE` | Sets `type` in the note's frontmatter, lowercased. |
+| `-t`, `--template NAME` | Starts the note from a template in `.atlas/templates`. |
+| `--open` | Opens the last created note in `$EDITOR`. |
+
+### `atlas list`
+
+Prints a tree of every Markdown file in the vault. Hidden files and folders are skipped unless you pass `-a` / `--all`.
+
+### `atlas search QUERY`
+
+Prints the vault-relative path of every note whose title contains the query. The match is case-insensitive and only looks at titles, not folders or note contents. Use `-a` / `--all` to include hidden directories such as the trash.
+
+```bash
+atlas search valora
+```
+
+### `atlas move SOURCE [SOURCE ...] DESTINATION`
+
+Moves or renames notes.
+
+- With one source, the destination is the new path of the note.
+- With several sources, the destination must be an existing folder.
+
+```bash
+atlas move "Nations/Valora" "Nations/Republic of Valora"
+atlas move "Characters/Aria" "Characters/Bram" Archive
+```
+
+When a note moves, Atlas:
+
+- Rewrites the note's frontmatter `id` to match its new path
+- Updates wiki links in every note in the vault, including aliases (`[[Note|alias]]`), headings (`[[Note#Heading]]`), and embeds (`![[Note]]`)
+- Leaves links inside code blocks and inline code untouched
+- Leaves a bare-title link alone when several notes share that title, since it is unclear which one was meant
+
+All moves are checked before anything changes, so a bad argument never leaves the vault half moved. Pass `--no-links` to skip the link updates.
+
+### `atlas delete NAME [NAME ...]`
+
+Moves notes to the vault's `.trash` folder instead of erasing them. A timestamp is added to the file name, so deleting a note with the same name twice never overwrites the earlier copy.
+
+## Templates
+
+Templates are Markdown files in `.atlas/templates`. Pass the name without the `.md` suffix:
+
+```bash
+atlas create "Places/Old Harbor" --template location
+```
+
+Templates can have frontmatter and a body, and `{{placeholders}}` are filled in when the note is created:
+
+| Placeholder | Value |
+| --- | --- |
+| `{{title}}` | The note title (its file name without `.md`). |
+| `{{id}}` | The generated note id. |
+| `{{date}}` | Today's date as `YYYY-MM-DD`. |
+
+Unknown placeholders are left as they are. Example `.atlas/templates/location.md`:
+
+```markdown
+---
+type: location
+created: "{{date}}"
+tags: []
+---
+
+# {{title}}
+
+## Description
+
+## Notable people
+```
+
+The note `id` is always generated by Atlas, and a `--type` given on the command line overrides a `type` set in the template.
+
+## Vault layout
+
+```text
+MyWorld/
+├── .atlas/
+│   ├── config.toml
+│   └── templates/
+├── .trash/
+├── Nations/
+│   └── Republic of Valora.md
+└── Characters/
+    └── Aria.md
+```
+
+## License
+
+MIT

atlas_vault-0.1.0/atlas/__init__.py

@@ -0,0 +1,18 @@
+# atlas/__init__.py
+
+"""
+Atlas: a command-line tool for managing and validating worldbuilding vaults.
+
+Attributes:
+    __version__: The installed version of Atlas, read from package metadata.
+        Falls back to a development version when Atlas is not installed.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__: str = version("atlas-vault")
+except PackageNotFoundError:
+    __version__: str = "0.1.0-dev"
+
+__all__ = ["__version__"]

atlas_vault-0.1.0/atlas/__main__.py

@@ -0,0 +1,10 @@
+# atlas/__main__.py
+
+"""Enables running Atlas with ``python -m atlas``."""
+
+import sys
+
+from atlas.main import main
+
+if __name__ == "__main__":
+    sys.exit(main())

atlas_vault-0.1.0/atlas/commands/__init__.py

@@ -0,0 +1,21 @@
+# atlas/commands/__init__.py
+
+"""Atlas subcommands."""
+
+from atlas.commands import create_cmd, delete_cmd, init_cmd, list_cmd, move_cmd, search_cmd
+from atlas.commands._types import SubParsers
+
+
+def register_all(subparsers: SubParsers) -> None:
+    """
+    Registers every Atlas subcommand.
+
+    Args:
+        subparsers: The subparsers action to add the commands to.
+    """
+    init_cmd.register(subparsers)
+    create_cmd.register(subparsers)
+    list_cmd.register(subparsers)
+    delete_cmd.register(subparsers)
+    move_cmd.register(subparsers)
+    search_cmd.register(subparsers)

atlas_vault-0.1.0/atlas/commands/_types.py

@@ -0,0 +1,82 @@
+# atlas/commands/_types.py
+
+"""Shared typing helpers for Atlas subcommands."""
+
+import argparse
+from typing import Any, Protocol
+
+import yaml
+
+
+class SubParsers(Protocol):
+    """
+    The part of an argparse subparsers action that commands rely on.
+
+    This mirrors ``argparse._SubParsersAction`` without importing the private
+    class. Anything with a compatible ``add_parser`` method satisfies it.
+    """
+
+    def add_parser(
+        self,
+        name: str,
+        *,
+        help: str | None = None,  # noqa: A002
+    ) -> argparse.ArgumentParser:
+        """Adds a named subparser and returns it."""
+        ...
+
+
+def non_empty(value: str) -> str:
+    """
+    Strips a command-line value and rejects it if nothing is left.
+
+    Args:
+        value: The raw value from the command line.
+
+    Returns:
+        The stripped value.
+
+    Raises:
+        argparse.ArgumentTypeError: If the value is empty or only whitespace.
+    """
+    stripped: str = value.strip()
+    if not stripped:
+        raise argparse.ArgumentTypeError("must not be empty")
+    return stripped
+
+
+def key_value(value: str) -> tuple[str, Any]:
+    """
+    Parses a ``KEY=VALUE`` command-line argument.
+
+    The text is split at the first ``=``. The key is stripped of surrounding
+    whitespace. The value is parsed as YAML, so ``2000000`` becomes an int,
+    ``true`` a bool, ``[a, b]`` a list, and ``draft`` stays a string. Quote
+    the value inside the argument to force a string, as in ``name="'123'"``.
+    An empty value becomes ``None``.
+
+    Args:
+        value: The raw ``KEY=VALUE`` argument.
+
+    Returns:
+        The key and the parsed value.
+
+    Raises:
+        argparse.ArgumentTypeError: If there is no ``=``, the key is empty
+            or is ``id``, or the value is not valid YAML.
+    """
+    key, separator, raw_value = value.partition("=")
+    key = key.strip()
+    if not separator or not key:
+        raise argparse.ArgumentTypeError(f"expected KEY=VALUE, got {value!r}")
+    if key == "id":
+        raise argparse.ArgumentTypeError("'id' is set from the note path and cannot be changed")
+
+    try:
+        parsed: Any = yaml.safe_load(raw_value)
+    except yaml.YAMLError as error:
+        problem: str = getattr(error, "problem", None) or "invalid YAML"
+        raise argparse.ArgumentTypeError(
+            f"value for {key!r} is not valid YAML ({problem}); quote it to use it as text"
+        ) from error
+    return key, parsed

atlas_vault-0.1.0/atlas/commands/create_cmd.py

@@ -0,0 +1,187 @@
+# atlas/commands/create_cmd.py
+
+"""The ``atlas create`` command."""
+
+import argparse
+import os
+import shlex
+import subprocess
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from atlas import frontmatter
+from atlas.commands._types import SubParsers, non_empty
+from atlas.errors import FileReadError, InvalidNoteIdError
+from atlas.vault import Vault
+
+if TYPE_CHECKING:
+    from atlas.note import Note
+
+
+def register(subparsers: SubParsers) -> None:
+    """
+    Registers the ``create`` subcommand.
+
+    Args:
+        subparsers: The subparsers action to add the command to.
+    """
+    parser: argparse.ArgumentParser = subparsers.add_parser(
+        "create", help="Create a new Atlas Object."
+    )
+
+    parser.add_argument(
+        "names",
+        nargs="+",
+        type=str,
+        help=(
+            "Path(s) of the new item(s) relative to the vault root, e.g. "
+            "'Nations/Republic of Valora'. The '.md' extension is optional."
+        ),
+    )
+
+    parser.add_argument(
+        "--type",
+        type=non_empty,
+        metavar="TYPE",
+        help=(
+            "Set the type of the new note, e.g. 'Nation'. Written to its frontmatter. "
+            "Shorthand for --set type=<lowercased TYPE>."
+        ),
+    )
+
+    parser.add_argument(
+        "--set",
+        dest="properties",
+        action="append",
+        metavar="KEY=VALUE",
+        help=(
+            "Set a frontmatter property, e.g. --set status=draft. The value is parsed "
+            "as YAML, so numbers, booleans and lists work: --set population=2000000 "
+            "--set 'tags=[nation, active]'. Repeatable. Overrides --type and the template."
+        ),
+    )
+
+    parser.add_argument(
+        "--id",
+        type=non_empty,
+        metavar="ID",
+        dest="note_id",
+        help=(
+            "Use this ID instead of the one derived from the note's path. "
+            "Only valid when creating a single note."
+        ),
+    )
+
+    parser.add_argument(
+        "-b",
+        "--body",
+        metavar="TEXT",
+        help=(
+            "Seed the note body with this text instead of the default heading or the "
+            "template body. Use '-' to read the body from standard input. When creating "
+            "several notes, every note gets the same body."
+        ),
+    )
+
+    parser.add_argument(
+        "-t",
+        "--template",
+        type=non_empty,
+        metavar="NAME",
+        help="Name of a template in .atlas/templates to start the note from.",
+    )
+
+    parser.add_argument(
+        "--open",
+        action="store_true",
+        help="Open the note (or last note) in the users $EDITOR. Does not open if no $EDITOR.",
+    )
+
+    parser.set_defaults(handler=run)
+
+
+def _read_stdin() -> str:
+    """
+    Reads all of standard input as text.
+
+    Returns:
+        The text that was piped in.
+
+    Raises:
+        FileReadError: If standard input cannot be read or is not valid text.
+    """
+    try:
+        return sys.stdin.read()
+    except (OSError, UnicodeDecodeError) as error:
+        reason: str = getattr(error, "strerror", None) or str(error)
+        raise FileReadError(Path("<stdin>"), reason) from error
+
+
+def run(args: argparse.Namespace) -> int:
+    """
+    Runs the ``create`` command.
+
+    Args:
+        args: The parsed command-line arguments.
+
+    Returns:
+        The process exit code. Zero indicates success.
+
+    Raises:
+        VaultNotFoundError: If the vault path does not exist.
+        VaultNotInitializedError: If the vault has no ``.atlas`` directory.
+        InvalidPropertyError: If a ``--set`` property is not valid.
+        InvalidNoteNameError: If the note name is not valid.
+        InvalidTemplateNameError: If the template name is not valid.
+        TemplateNotFoundError: If the template does not exist.
+        FileReadError: If the template cannot be read.
+        InvalidFrontmatterError: If the template's frontmatter is not valid.
+        NoteExistsError: If the note already exists.
+        FileCreationError: If the note or its parent folders cannot be created.
+    """
+    vault: Vault = Vault.open(args.vault)
+
+    if args.note_id is not None and len(args.names) > 1:
+        raise InvalidNoteIdError(args.note_id, "--id can only be used when creating one note")
+
+    properties: dict[str, Any] = {}
+    if args.type is not None:
+        properties["type"] = args.type.lower()
+
+    raw_properties: list[str] = args.properties or []
+    for assignment in raw_properties:
+        key, value = frontmatter.parse_property(assignment)
+        properties[key] = value
+
+    body: str | None = args.body
+    if body == "-":
+        body = _read_stdin()
+
+    last_note: Note | None = None
+
+    for name in args.names:
+        new_note: Note = vault.resolve_note(name)
+        vault.create(
+            new_note,
+            properties=properties,
+            template=args.template,
+            note_id=args.note_id,
+            body=body,
+        )
+        last_note = new_note
+
+        if not args.quiet:
+            print("Created Note:", new_note.path)
+
+    if args.open and last_note is not None:
+        editor: str | None = os.environ.get("EDITOR", None)
+        if editor:
+            try:
+                cmd: list[str] = [*shlex.split(editor), str(last_note.path)]
+                subprocess.call(cmd)  # noqa: S603
+            except FileNotFoundError:
+                print(f"Editor '{editor}' not found.")
+                return 0
+
+    return 0