nhq 0.1.0__tar.gz

nhq-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+# Build artifacts
+/build/
+/dist/
+/*.egg-info/
+
+# Test / lint caches
+/.coverage
+/.mypy_cache/
+/.pytest_cache/
+/.ruff_cache/
+
+# Environment
+/.venv/

nhq-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kentaro Wada
+
+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.

nhq-0.1.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: nhq
+Version: 0.1.0
+Summary: Private per-repo notes alongside a git repo, kept out of git and backed up via storage you already sync.
+Project-URL: Homepage, https://github.com/wkentaro/nhq
+Project-URL: Issues, https://github.com/wkentaro/nhq/issues
+Project-URL: Repository, https://github.com/wkentaro/nhq
+Author: Kentaro Wada
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,ghq,git,notes,private
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: click>=8
+Requires-Dist: rich>=13
+Requires-Dist: typing-extensions>=4
+Description-Content-Type: text/markdown
+
+# nhq
+
+[![PyPI](https://img.shields.io/pypi/v/nhq.svg)](https://pypi.org/project/nhq/)
+[![Python](https://img.shields.io/pypi/pyversions/nhq.svg)](https://pypi.org/project/nhq/)
+[![Build](https://github.com/wkentaro/nhq/actions/workflows/test.yml/badge.svg)](https://github.com/wkentaro/nhq/actions/workflows/test.yml)
+[![License](https://img.shields.io/pypi/l/nhq.svg)](https://pypi.org/project/nhq/)
+
+ghq for your private per-repo notes: every repo gets a private folder that lives
+in storage you already sync, never in git. A capture tool, not a
+config-distribution tool.
+
+`nhq` ("notes headquarters") manages a deterministic symlink from inside a git
+repo to a notes directory kept outside git. While working in a repo (often with
+an AI agent) you accumulate notes, scratch, and artifacts you want beside the
+code but never committed, not for the team and not on GitHub. `nhq` keeps them
+in a store whose path is derived from the repo's identity, the same way
+[ghq](https://github.com/x-motemen/ghq) derives a checkout path from a remote
+URL.
+
+## How it works
+
+Two planes:
+
+- **The store** is `$NHQ_ROOT/<host>/<user>/<repo>/`: the actual notes. Created
+  once, lives in your synced folder, shared across machines.
+- **The link** is the `./nhq` symlink plus a `.git/info/exclude` entry.
+  Per-checkout and per-machine, never committed.
+
+`nhq init` sets up both on the first machine; `nhq link` connects the link plane
+on every other machine.
+
+`nhq` does not sync. Point the root at a folder something already syncs (Dropbox,
+iCloud, Syncthing, a NAS mount) and backup comes for free.
+
+## Install
+
+```bash
+pip install nhq
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install nhq
+```
+
+Verify it works:
+
+```bash
+nhq --help
+```
+
+Requires POSIX (macOS, Linux); it relies on symlinks.
+
+## Usage
+
+On the first machine, one command sets everything up. `nhq init` creates the
+store and drops a `./nhq` symlink into your working tree, added to
+`.git/info/exclude` so git never sees it:
+
+```console
+$ nhq init
+created store /home/you/nhq/github.com/wkentaro/labelme
+linked /home/you/code/labelme/nhq -> /home/you/nhq/github.com/wkentaro/labelme
+
+$ ls -l nhq
+nhq -> /home/you/nhq/github.com/wkentaro/labelme
+```
+
+Now write notes into `./nhq/`. They live in your synced storage and never touch
+git.
+
+On any other machine or checkout the store already exists (it synced over), so
+just link to it:
+
+```console
+$ nhq link
+linked /home/you/code/labelme/nhq -> /home/you/nhq/github.com/wkentaro/labelme
+```
+
+Your notes from the first machine are already under `./nhq/`, synced over.
+
+Both commands also work from a subdirectory: a subtree gets its own separate
+store, keyed by its path within the repo, so a monorepo subtree keeps its own
+notes.
+
+To undo the link on a checkout, `nhq unlink` removes the `./nhq` symlink and its
+`.git/info/exclude` entry. It is the inverse of `link` and never touches the
+store, so your notes stay safe in the synced root:
+
+```console
+$ nhq unlink
+unlinked /home/you/code/labelme/nhq
+```
+
+### Root resolution
+
+The root is resolved like ghq, in order:
+
+```
+NHQ_ROOT env  ->  git config nhq.root  ->  ~/nhq
+```
+
+`nhq root` prints it, the same way `ghq root` does. It needs no repo, so it
+works anywhere:
+
+```console
+$ nhq root
+/home/you/nhq
+
+$ cd "$(nhq root)"
+```
+
+### Listing stores
+
+`nhq list` prints every store for this repo, the root plus any subtree stores,
+the same wherever in the repo you run it. Each line shows the decoded subpath and
+the store path; the store for the current directory is marked with `*`. It only
+reads, creating and linking nothing:
+
+```console
+$ nhq list
+* .                /home/you/nhq/github.com/wkentaro/labelme
+  tests/           /home/you/nhq/github.com/wkentaro/labelme%2Ftests
+  labelme/widgets/ /home/you/nhq/github.com/wkentaro/labelme%2Flabelme%2Fwidgets
+```
+
+## vs repoverlay
+
+[repoverlay](https://github.com/tylerbutler/repoverlay) uses the same mechanism
+(a symlink plus `.git/info/exclude`) but the opposite data model. It distributes
+one shared bundle of files into many repos; `nhq` captures each repo's own unique
+notes out to a synced store.
+
+- **Capture, not distribute**: notes flow out of the repo, not config in.
+- **Zero config**: the store path is derived from repo identity, not named.
+- **Three verbs**: `init`, `link`, and `unlink` are all that change anything; `root` and `list` only print.
+
+## Scope
+
+v1 manages the link and the derived path; it never syncs, clones, or touches the
+network. Backup is delegated entirely to whatever already syncs your root.
+
+## License
+
+MIT. Modeled on and crediting [ghq](https://github.com/x-motemen/ghq).

nhq-0.1.0/README.md

@@ -0,0 +1,146 @@
+# nhq
+
+[![PyPI](https://img.shields.io/pypi/v/nhq.svg)](https://pypi.org/project/nhq/)
+[![Python](https://img.shields.io/pypi/pyversions/nhq.svg)](https://pypi.org/project/nhq/)
+[![Build](https://github.com/wkentaro/nhq/actions/workflows/test.yml/badge.svg)](https://github.com/wkentaro/nhq/actions/workflows/test.yml)
+[![License](https://img.shields.io/pypi/l/nhq.svg)](https://pypi.org/project/nhq/)
+
+ghq for your private per-repo notes: every repo gets a private folder that lives
+in storage you already sync, never in git. A capture tool, not a
+config-distribution tool.
+
+`nhq` ("notes headquarters") manages a deterministic symlink from inside a git
+repo to a notes directory kept outside git. While working in a repo (often with
+an AI agent) you accumulate notes, scratch, and artifacts you want beside the
+code but never committed, not for the team and not on GitHub. `nhq` keeps them
+in a store whose path is derived from the repo's identity, the same way
+[ghq](https://github.com/x-motemen/ghq) derives a checkout path from a remote
+URL.
+
+## How it works
+
+Two planes:
+
+- **The store** is `$NHQ_ROOT/<host>/<user>/<repo>/`: the actual notes. Created
+  once, lives in your synced folder, shared across machines.
+- **The link** is the `./nhq` symlink plus a `.git/info/exclude` entry.
+  Per-checkout and per-machine, never committed.
+
+`nhq init` sets up both on the first machine; `nhq link` connects the link plane
+on every other machine.
+
+`nhq` does not sync. Point the root at a folder something already syncs (Dropbox,
+iCloud, Syncthing, a NAS mount) and backup comes for free.
+
+## Install
+
+```bash
+pip install nhq
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install nhq
+```
+
+Verify it works:
+
+```bash
+nhq --help
+```
+
+Requires POSIX (macOS, Linux); it relies on symlinks.
+
+## Usage
+
+On the first machine, one command sets everything up. `nhq init` creates the
+store and drops a `./nhq` symlink into your working tree, added to
+`.git/info/exclude` so git never sees it:
+
+```console
+$ nhq init
+created store /home/you/nhq/github.com/wkentaro/labelme
+linked /home/you/code/labelme/nhq -> /home/you/nhq/github.com/wkentaro/labelme
+
+$ ls -l nhq
+nhq -> /home/you/nhq/github.com/wkentaro/labelme
+```
+
+Now write notes into `./nhq/`. They live in your synced storage and never touch
+git.
+
+On any other machine or checkout the store already exists (it synced over), so
+just link to it:
+
+```console
+$ nhq link
+linked /home/you/code/labelme/nhq -> /home/you/nhq/github.com/wkentaro/labelme
+```
+
+Your notes from the first machine are already under `./nhq/`, synced over.
+
+Both commands also work from a subdirectory: a subtree gets its own separate
+store, keyed by its path within the repo, so a monorepo subtree keeps its own
+notes.
+
+To undo the link on a checkout, `nhq unlink` removes the `./nhq` symlink and its
+`.git/info/exclude` entry. It is the inverse of `link` and never touches the
+store, so your notes stay safe in the synced root:
+
+```console
+$ nhq unlink
+unlinked /home/you/code/labelme/nhq
+```
+
+### Root resolution
+
+The root is resolved like ghq, in order:
+
+```
+NHQ_ROOT env  ->  git config nhq.root  ->  ~/nhq
+```
+
+`nhq root` prints it, the same way `ghq root` does. It needs no repo, so it
+works anywhere:
+
+```console
+$ nhq root
+/home/you/nhq
+
+$ cd "$(nhq root)"
+```
+
+### Listing stores
+
+`nhq list` prints every store for this repo, the root plus any subtree stores,
+the same wherever in the repo you run it. Each line shows the decoded subpath and
+the store path; the store for the current directory is marked with `*`. It only
+reads, creating and linking nothing:
+
+```console
+$ nhq list
+* .                /home/you/nhq/github.com/wkentaro/labelme
+  tests/           /home/you/nhq/github.com/wkentaro/labelme%2Ftests
+  labelme/widgets/ /home/you/nhq/github.com/wkentaro/labelme%2Flabelme%2Fwidgets
+```
+
+## vs repoverlay
+
+[repoverlay](https://github.com/tylerbutler/repoverlay) uses the same mechanism
+(a symlink plus `.git/info/exclude`) but the opposite data model. It distributes
+one shared bundle of files into many repos; `nhq` captures each repo's own unique
+notes out to a synced store.
+
+- **Capture, not distribute**: notes flow out of the repo, not config in.
+- **Zero config**: the store path is derived from repo identity, not named.
+- **Three verbs**: `init`, `link`, and `unlink` are all that change anything; `root` and `list` only print.
+
+## Scope
+
+v1 manages the link and the derived path; it never syncs, clones, or touches the
+network. Backup is delegated entirely to whatever already syncs your root.
+
+## License
+
+MIT. Modeled on and crediting [ghq](https://github.com/x-motemen/ghq).

nhq-0.1.0/nhq/__init__.py

@@ -0,0 +1,3 @@
+import importlib.metadata
+
+__version__ = importlib.metadata.version("nhq")

nhq-0.1.0/nhq/__main__.py

@@ -0,0 +1,3 @@
+from nhq._cli import cli
+
+cli()

nhq-0.1.0/nhq/_cli.py

@@ -0,0 +1,386 @@
+import contextlib
+import os
+from pathlib import Path
+from typing import Final
+
+import click
+from rich.console import Console
+from rich.text import Text
+from typing_extensions import override
+
+from . import __version__
+from ._git import GitError
+from ._git import ensure_excluded
+from ._git import get_config
+from ._git import get_origin_url
+from ._git import get_show_prefix
+from ._git import is_git_repo
+from ._git import remove_excluded
+from ._store import list_stores
+from ._store import parse_remote_url
+from ._store import resolve_root
+from ._store import store_path
+
+
+class CliError(Exception):
+    def __init__(
+        self,
+        message: str,
+        *,
+        tip: str | None = None,
+        usage: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.tip = tip
+        self.usage = usage
+
+
+class CliGroup(click.Group):
+    @override
+    def resolve_command(
+        self, ctx: click.Context, args: list[str]
+    ) -> tuple[str | None, click.Command | None, list[str]]:
+        try:
+            return super().resolve_command(ctx, args)
+        except click.UsageError:
+            cmd_name = args[0] if args else ""
+            raise CliError(
+                f"unrecognized subcommand '{cmd_name}'", usage=USAGE
+            ) from None
+
+    @override
+    def invoke(self, ctx: click.Context) -> None:
+        try:
+            super().invoke(ctx)
+        except CliError as exc:
+            print_error(str(exc), tip=exc.tip, usage=exc.usage)
+            ctx.exit(2 if exc.usage else 1)
+        except GitError as exc:
+            print_error(str(exc))
+            ctx.exit(1)
+        except FileNotFoundError:
+            print_error(
+                "git not found",
+                tip="install git and ensure it is on your PATH",
+            )
+            ctx.exit(1)
+        except KeyboardInterrupt:
+            ctx.exit(130)
+
+
+def _resolve_root() -> Path:
+    env_root = os.environ.get("NHQ_ROOT")
+    config_root = None if env_root else get_config("nhq.root")
+    return resolve_root(env_root=env_root, config_root=config_root)
+
+
+def _resolve_identity() -> str:
+    if not is_git_repo():
+        raise CliError("not a git repository")
+
+    origin = get_origin_url()
+    if origin is None:
+        raise CliError(
+            "nhq requires an 'origin' remote",
+            tip="add one with: git remote add origin <url>",
+        )
+    try:
+        return parse_remote_url(origin)
+    except ValueError as exc:
+        raise CliError(str(exc)) from exc
+
+
+def _resolve_store() -> tuple[Path, str]:
+    identity = _resolve_identity()
+    show_prefix = get_show_prefix()
+    store = store_path(root=_resolve_root(), identity=identity, subpath=show_prefix)
+    return store, show_prefix
+
+
+def _exclude_line(show_prefix: str) -> str:
+    return "/" + show_prefix + "nhq"
+
+
+def _link_store(store: Path, show_prefix: str) -> None:
+    link = Path("nhq")
+    try:
+        if link.is_symlink():
+            current = link.readlink()
+            if current != store.absolute():
+                raise CliError(
+                    f"'./nhq' already links to {current}",
+                    tip="remove ./nhq, then re-run",
+                )
+            verb = "already linked"
+        elif link.exists():
+            raise CliError(
+                "'./nhq' exists and is not an nhq symlink",
+                tip="remove ./nhq, then re-run",
+            )
+        else:
+            link.symlink_to(store.absolute())
+            verb = "linked"
+        ensure_excluded(_exclude_line(show_prefix))
+    except OSError as exc:
+        raise CliError(f"cannot link ./nhq: {exc}") from exc
+
+    print_status(verb, link.absolute(), store)
+
+
+def _unlink_store(store: Path, show_prefix: str) -> None:
+    link = Path("nhq")
+    if link.is_symlink():
+        current = link.readlink()
+        if current != store.absolute():
+            raise CliError(
+                f"'./nhq' links to {current}, not this repo's store",
+                tip="remove ./nhq manually if you meant to",
+            )
+        remove_link = True
+    elif link.exists():
+        raise CliError(
+            "'./nhq' exists and is not an nhq symlink",
+            tip="remove ./nhq manually if you meant to",
+        )
+    else:
+        remove_link = False
+
+    # Scrub the exclude entry before removing the symlink: if it fails, the link
+    # is still intact and the user can retry cleanly, rather than being left with
+    # a removed symlink and a lingering exclude entry.
+    exclude_line = _exclude_line(show_prefix)
+    try:
+        scrubbed = remove_excluded(exclude_line)
+    except OSError as exc:
+        raise CliError(f"cannot unlink ./nhq: {exc}") from exc
+
+    if remove_link:
+        try:
+            link.unlink()
+        except OSError as exc:
+            # The symlink survives, so restore the exclude entry we just scrubbed
+            # to keep it ignored and leave a clean state to retry from. Best-effort:
+            # a restore failure must never mask the original error raised below.
+            if scrubbed:
+                with contextlib.suppress(Exception):
+                    ensure_excluded(exclude_line)
+            raise CliError(f"cannot unlink ./nhq: {exc}") from exc
+
+    verb = "unlinked" if remove_link or scrubbed else "nothing to unlink"
+    print_status(verb, link.absolute())
+
+
+@click.group(cls=CliGroup, invoke_without_command=True, add_help_option=False)
+@click.option("-h", "--help", "show_help", is_flag=True)
+@click.option("-V", "--version", "show_version", is_flag=True)
+@click.pass_context
+def cli(ctx: click.Context, show_help: bool, show_version: bool) -> None:
+    if show_version:
+        print_version(__version__)
+        return
+    if show_help or ctx.invoked_subcommand is None:
+        print_help(HELP)
+
+
+@cli.command("init", add_help_option=False)
+@click.option("-h", "--help", "show_help", is_flag=True)
+def cmd_init(show_help: bool) -> None:
+    if show_help:
+        print_help(HELP_INIT)
+        return
+    store, show_prefix = _resolve_store()
+    existed = store.exists()
+    try:
+        store.mkdir(parents=True, exist_ok=True)
+    except OSError as exc:
+        raise CliError(f"cannot create store: {exc}") from exc
+    print_status("store exists" if existed else "created store", store)
+    _link_store(store, show_prefix)
+
+
+@cli.command("link", add_help_option=False)
+@click.option("-h", "--help", "show_help", is_flag=True)
+def cmd_link(show_help: bool) -> None:
+    if show_help:
+        print_help(HELP_LINK)
+        return
+    store, show_prefix = _resolve_store()
+    if not store.exists():
+        raise CliError(
+            "no store for this repo",
+            tip="create it first with: nhq init",
+        )
+    _link_store(store, show_prefix)
+
+
+@cli.command("unlink", add_help_option=False)
+@click.option("-h", "--help", "show_help", is_flag=True)
+def cmd_unlink(show_help: bool) -> None:
+    if show_help:
+        print_help(HELP_UNLINK)
+        return
+    store, show_prefix = _resolve_store()
+    _unlink_store(store, show_prefix)
+
+
+@cli.command("root", add_help_option=False)
+@click.option("-h", "--help", "show_help", is_flag=True)
+def cmd_root(show_help: bool) -> None:
+    if show_help:
+        print_help(HELP_ROOT)
+        return
+    click.echo(str(_resolve_root()))
+
+
+@cli.command("list", add_help_option=False)
+@click.option("-h", "--help", "show_help", is_flag=True)
+def cmd_list(show_help: bool) -> None:
+    if show_help:
+        print_help(HELP_LIST)
+        return
+    identity = _resolve_identity()
+    root = _resolve_root()
+    current = store_path(root=root, identity=identity, subpath=get_show_prefix())
+    stores = list_stores(root=root, identity=identity)
+    if not stores:
+        return
+    rows = [("." if subpath == "" else subpath + "/", path) for subpath, path in stores]
+    width = max(len(label) for label, _ in rows)
+    for label, path in rows:
+        mark = "*" if path == current else " "
+        click.echo(f"{mark} {label:<{width}} {path}")
+
+
+def _out() -> Console:
+    return Console(highlight=False)
+
+
+def _err() -> Console:
+    return Console(stderr=True, highlight=False)
+
+
+def print_help(text: str) -> None:
+    _out().print(text)
+
+
+def print_version(version: str) -> None:
+    _out().print(f"nhq [dim]{version}[/dim]")
+
+
+def print_status(verb: str, path: Path, target: Path | None = None) -> None:
+    line = Text()
+    line.append(f"{verb} ", style="bold green")
+    line.append(str(path), style="cyan")
+    if target is not None:
+        line.append(" -> ", style="dim")
+        line.append(str(target), style="cyan")
+    _err().print(line)
+
+
+def print_error(
+    msg: str,
+    *,
+    tip: str | None = None,
+    usage: str | None = None,
+) -> None:
+    err = _err()
+    err.print(f"[bold red]error[/bold red]: {msg}")
+    if tip:
+        err.print(f"\n  [green]tip[/green]: {tip}")
+    if usage:
+        err.print(f"\n{usage}")
+        err.print("\nFor more information, try '[bold cyan]--help[/bold cyan]'.")
+
+
+USAGE: Final = (
+    "[bold green]Usage:[/bold green] [bold cyan]nhq[/bold cyan] [cyan]<COMMAND>[/cyan]"
+)
+
+HELP: Final = f"""\
+Private per-repo notes alongside a git repo, kept out of git.
+
+{USAGE}
+
+[bold green]Commands:[/bold green]
+  [bold cyan]init[/bold cyan]    Create this repo's store and link it (run once)
+  [bold cyan]link[/bold cyan]    Link ./nhq to an existing store (per checkout)
+  [bold cyan]unlink[/bold cyan]  Remove ./nhq and its exclude entry (inverse of link)
+  [bold cyan]root[/bold cyan]    Print the resolved root directory
+  [bold cyan]list[/bold cyan]    List this repo's stores (root and subtrees)
+
+[bold green]Options:[/bold green]
+  [bold cyan]-h[/bold cyan], [bold cyan]--help[/bold cyan]     Print help
+  [bold cyan]-V[/bold cyan], [bold cyan]--version[/bold cyan]  Print version
+
+[bold green]Examples:[/bold green]
+  [cyan]nhq init[/cyan]    [dim]# Set up the store and link ./nhq (first machine)[/dim]
+  [cyan]nhq link[/cyan]    [dim]# Link ./nhq on another machine or checkout[/dim]
+  [cyan]nhq unlink[/cyan]  [dim]# Remove ./nhq from this checkout[/dim]
+  [cyan]nhq list[/cyan]    [dim]# List this repo's stores[/dim]
+  [cyan]cd packages/foo && nhq init[/cyan]  [dim]# A monorepo subtree's store[/dim]"""
+
+ROOT_RESOLUTION: Final = """\
+[bold green]Root resolution:[/bold green]
+  [cyan]NHQ_ROOT[/cyan] env -> [cyan]git config nhq.root[/cyan] -> [cyan]~/nhq[/cyan]"""
+
+HELP_INIT: Final = f"""\
+Create this repo's store under the resolved root (path derived from the origin
+remote, ghq-style) and link ./nhq to it. Idempotent. Run this once, on the
+machine where you first start; on other machines use nhq link.
+
+[bold green]Usage:[/bold green] [bold cyan]nhq init[/bold cyan]
+
+[bold green]Options:[/bold green]
+  [bold cyan]-h[/bold cyan], [bold cyan]--help[/bold cyan]  Print help
+
+{ROOT_RESOLUTION}"""
+
+HELP_LINK: Final = f"""\
+Link ./nhq in the current directory to this repo's store and add it to
+.git/info/exclude so git ignores it. Per checkout and per machine; the link
+is never committed. Requires the store to exist (run nhq init first).
+
+[bold green]Usage:[/bold green] [bold cyan]nhq link[/bold cyan]
+
+[bold green]Options:[/bold green]
+  [bold cyan]-h[/bold cyan], [bold cyan]--help[/bold cyan]  Print help
+
+{ROOT_RESOLUTION}"""
+
+HELP_UNLINK: Final = f"""\
+Remove ./nhq in the current directory and scrub its .git/info/exclude entry, the
+inverse of nhq link. Idempotent and link-only: it never touches the store, and
+only ever removes a ./nhq that points at this repo's store. Requires a git repo
+with an origin remote.
+
+[bold green]Usage:[/bold green] [bold cyan]nhq unlink[/bold cyan]
+
+[bold green]Options:[/bold green]
+  [bold cyan]-h[/bold cyan], [bold cyan]--help[/bold cyan]  Print help
+
+{ROOT_RESOLUTION}"""
+
+HELP_ROOT: Final = f"""\
+Print the resolved root directory, the base under which every store lives. Use
+it to locate or cd into your stores. Works anywhere; a git repo is not required.
+
+[bold green]Usage:[/bold green] [bold cyan]nhq root[/bold cyan]
+
+[bold green]Options:[/bold green]
+  [bold cyan]-h[/bold cyan], [bold cyan]--help[/bold cyan]  Print help
+
+{ROOT_RESOLUTION}"""
+
+HELP_LIST: Final = f"""\
+List every existing store for this repo, the root store plus any subtree stores,
+one per line, identically wherever in the repo you run it. Each line shows the
+decoded subpath (. for the repo root) and the store path; the store for the
+current directory is marked with *. Read-only: creates and links nothing.
+Requires a git repo with an origin remote.
+
+[bold green]Usage:[/bold green] [bold cyan]nhq list[/bold cyan]
+
+[bold green]Options:[/bold green]
+  [bold cyan]-h[/bold cyan], [bold cyan]--help[/bold cyan]  Print help
+
+{ROOT_RESOLUTION}"""

nhq-0.1.0/nhq/_git.py

@@ -0,0 +1,67 @@
+import subprocess
+from pathlib import Path
+
+
+class GitError(RuntimeError):
+    pass
+
+
+def _run(*args: str) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(["git", *args], capture_output=True, text=True)
+
+
+def _run_checked(*args: str) -> str:
+    result = _run(*args)
+    if result.returncode != 0:
+        detail = result.stderr.strip() or f"exited with {result.returncode}"
+        raise GitError(f"git {' '.join(args)}: {detail}")
+    return result.stdout.strip()
+
+
+def is_git_repo() -> bool:
+    return _run("rev-parse", "--is-inside-work-tree").stdout.strip() == "true"
+
+
+def get_origin_url() -> str | None:
+    result = _run("remote", "get-url", "origin")
+    if result.returncode != 0:
+        return None
+    return result.stdout.strip() or None
+
+
+def get_show_prefix() -> str:
+    return _run_checked("rev-parse", "--show-prefix")
+
+
+def get_config(key: str) -> str | None:
+    result = _run("config", key)
+    if result.returncode != 0:
+        return None
+    return result.stdout.strip() or None
+
+
+def get_exclude_path() -> str:
+    return _run_checked("rev-parse", "--git-path", "info/exclude")
+
+
+def ensure_excluded(line: str) -> None:
+    exclude = Path(get_exclude_path())
+    content = exclude.read_text() if exclude.exists() else ""
+    if line in content.splitlines():
+        return
+    prefix = "" if content == "" or content.endswith("\n") else "\n"
+    exclude.parent.mkdir(parents=True, exist_ok=True)
+    with exclude.open("a") as file:
+        file.write(prefix + line + "\n")
+
+
+def remove_excluded(line: str) -> bool:
+    exclude = Path(get_exclude_path())
+    if not exclude.exists():
+        return False
+    lines = exclude.read_text().splitlines()
+    if line not in lines:
+        return False
+    kept = [existing for existing in lines if existing != line]
+    exclude.write_text("".join(existing + "\n" for existing in kept))
+    return True

nhq-0.1.0/nhq/_store.py

@@ -0,0 +1,72 @@
+import re
+import urllib.parse
+from pathlib import Path
+
+
+def parse_remote_url(url: str) -> str:
+    url = url.strip().rstrip("/")
+
+    scp = (
+        re.match(r"^(?:[^@/]+@)?(?P<host>[^/:]+):(?P<path>.+)$", url)
+        if "://" not in url
+        else None
+    )
+    if scp:
+        host, path = scp.group("host"), scp.group("path")
+    else:
+        parsed = urllib.parse.urlparse(url)
+        host, path = parsed.hostname or "", parsed.path
+
+    host = host.lower()
+    path = re.sub(r"/+", "/", urllib.parse.unquote(path).strip("/"))
+    path = path.removesuffix(".git").strip("/")
+
+    if not host or not path:
+        raise ValueError(f"cannot parse remote url: {url!r}")
+    if any(segment in (".", "..") for segment in path.split("/")):
+        raise ValueError(f"remote url has invalid path: {url!r}")
+    return f"{host}/{path}"
+
+
+def resolve_root(env_root: str | None, config_root: str | None) -> Path:
+    raw = env_root or config_root
+    if raw:
+        return Path(raw).expanduser().absolute()
+    return Path.home() / "nhq"
+
+
+def store_path(root: Path, identity: str, subpath: str) -> Path:
+    base = root / identity
+    subpath = subpath.strip("/")
+    if not subpath:
+        return base
+    # Encode the joining "/" too, so the subtree store is a sibling of the repo
+    # store, not a child of it (ADR-0003).
+    encoded = urllib.parse.quote("/" + subpath, safe="")
+    return base.parent / (base.name + encoded)
+
+
+def decode_subpath(leaf: str, name: str) -> str | None:
+    if name == leaf:
+        return ""
+    prefix = leaf + urllib.parse.quote("/", safe="")
+    if not name.startswith(prefix):
+        return None
+    return urllib.parse.unquote(name[len(leaf) :]).strip("/")
+
+
+def list_stores(root: Path, identity: str) -> list[tuple[str, Path]]:
+    base = root / identity
+    parent = base.parent
+    if not parent.is_dir():
+        return []
+    stores: list[tuple[str, Path]] = []
+    for entry in parent.iterdir():
+        if not entry.is_dir():
+            continue
+        subpath = decode_subpath(leaf=base.name, name=entry.name)
+        if subpath is None:
+            continue
+        stores.append((subpath, entry))
+    stores.sort(key=lambda item: (item[0] != "", item[0]))
+    return stores

nhq-0.1.0/pyproject.toml

@@ -0,0 +1,74 @@
+[build-system]
+build-backend = "hatchling.build"
+requires = ["hatch-vcs", "hatchling"]
+
+[project]
+authors = [{ name = "Kentaro Wada" }]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: POSIX",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Utilities",
+]
+dependencies = ["click>=8", "rich>=13", "typing-extensions>=4"]
+description = "Private per-repo notes alongside a git repo, kept out of git and backed up via storage you already sync."
+dynamic = ["version"]
+keywords = ["cli", "ghq", "git", "notes", "private"]
+license = "MIT"
+name = "nhq"
+readme = "README.md"
+requires-python = ">=3.10"
+
+[project.scripts]
+nhq = "nhq._cli:cli"
+
+[project.urls]
+Homepage = "https://github.com/wkentaro/nhq"
+Issues = "https://github.com/wkentaro/nhq/issues"
+Repository = "https://github.com/wkentaro/nhq"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.targets.sdist]
+include = ["/nhq"]
+
+[tool.ty.rules]
+all = "error"
+
+[tool.ruff.lint]
+select = [
+  "ANN", # flake8-annotations
+  "E",   # pycodestyle
+  "F",   # pyflakes
+  "I",   # isort
+  "UP",  # pyupgrade
+]
+
+[tool.ruff.lint.isort]
+force-single-line = true
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401"]
+
+[dependency-groups]
+dev = [
+  "mdformat-frontmatter>=2.0.10",
+  "mdformat-gfm>=1.0.0",
+  "mdformat>=0.7",
+  "pytest-cov>=4",
+  "pytest-xdist>=3.8.0",
+  "pytest>=7",
+  "ruff>=0.15.9",
+  "taplo>=0.9",
+  "ty>=0.0.28",
+  "typos>=1.44",
+  "yamlfix>=1.17",
+]