nostos 1.0.0__py3-none-any.whl

core/__init__.py

@@ -0,0 +1,4 @@
+# nostos - Batch-update multiple git repositories in parallel
+# Copyright (c) 2026 prodrom3 / radamic
+# License: MIT
+# https://github.com/prodrom3/nostos

core/auth.py

@@ -0,0 +1,165 @@
+"""Auth config for nostos upstream probes.
+
+Reads $XDG_CONFIG_HOME/nostos/auth.toml and exposes a per-host view:
+
+    [hosts."github.com"]
+    token_env = "GITHUB_TOKEN"       # preferred
+    # token   = "ghp_..."            # inline (discouraged; use env var)
+    # provider = "github"            # optional override; default derived from host
+
+    [hosts."gitlab.internal.corp"]
+    provider  = "gitlab"             # required for non-standard hosts
+    token_env = "CORP_GITLAB_TOKEN"
+
+    [defaults]
+    allow_unknown = false            # fail-closed for hosts not listed above
+
+Security
+- The file must be owned by the current user and not world-readable
+  on Unix. Failure of either check causes the loader to refuse to
+  read it and return an empty / fail-closed config with a warning.
+- A missing file is NOT an error; upstream probes will simply fail
+  closed for every host.
+- Inline tokens are supported but discouraged; token_env is always
+  preferred and is the only form that is redacted from audit output.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import stat
+import sys
+from typing import Any
+
+from .paths import auth_config_path
+
+# Python 3.11+ ships tomllib in the stdlib. On 3.10 we fall back to
+# tomli if it happens to be installed; otherwise the TOML loader is
+# disabled entirely and load_auth() returns a fail-closed config with
+# a clear warning. This keeps nostos importable with zero runtime
+# dependencies on every supported Python, and keeps the opsec posture
+# correct: no TOML parser means no auth.toml is read, which means
+# every upstream probe is skipped fail-closed.
+_toml: Any = None
+try:
+    import tomllib as _toml  # type: ignore[import-not-found,no-redef,unused-ignore]
+except ModuleNotFoundError:  # pragma: no cover - Python 3.10
+    try:
+        import tomli as _toml  # type: ignore[import-not-found,no-redef]
+    except ModuleNotFoundError:
+        pass
+
+
+_DEFAULT_PROVIDERS: dict[str, str] = {
+    "github.com": "github",
+    "gitlab.com": "gitlab",
+}
+
+
+class AuthConfig:
+    """In-memory view of the auth.toml file.
+
+    Hosts not present in the config produce (None, False) from
+    resolve_host_token() unless defaults.allow_unknown is True.
+    """
+
+    def __init__(
+        self,
+        hosts: dict[str, dict[str, Any]] | None = None,
+        allow_unknown: bool = False,
+    ) -> None:
+        self.hosts = hosts or {}
+        self.allow_unknown = allow_unknown
+
+    def provider_for(self, host: str) -> str | None:
+        """Return the provider name for a host, or None if unknown."""
+        cfg = self.hosts.get(host)
+        if cfg and cfg.get("provider"):
+            return str(cfg["provider"]).lower()
+        return _DEFAULT_PROVIDERS.get(host)
+
+    def resolve_token(self, host: str) -> str | None:
+        """Return the token for a host, or None.
+
+        token_env takes precedence over inline token. Unknown hosts
+        always return None.
+        """
+        cfg = self.hosts.get(host)
+        if not cfg:
+            return None
+        env_name = cfg.get("token_env")
+        if env_name:
+            return os.environ.get(str(env_name)) or None
+        inline = cfg.get("token")
+        return str(inline) if inline else None
+
+    def is_allowed(self, host: str) -> bool:
+        """Should a probe against this host be permitted?
+
+        True when the host is explicitly configured OR when
+        defaults.allow_unknown is True.
+        """
+        if host in self.hosts:
+            return True
+        return self.allow_unknown
+
+
+def _is_auth_file_safe(path: str) -> bool:
+    """Reject if not owned by current user or world-readable/writable (Unix)."""
+    try:
+        st = os.stat(path)
+    except OSError:
+        return False
+    if sys.platform == "win32":
+        return True
+    if st.st_uid != os.getuid():
+        logging.warning(
+            f"Ignoring {path}: owned by uid {st.st_uid}, not current user"
+        )
+        return False
+    if st.st_mode & (stat.S_IWOTH | stat.S_IROTH | stat.S_IWGRP | stat.S_IRGRP):
+        logging.warning(
+            f"Ignoring {path}: permissions too loose "
+            f"(fix with: chmod 600 {path})"
+        )
+        return False
+    return True
+
+
+def load_auth(path: str | None = None) -> AuthConfig:
+    """Load the auth config. Returns an empty fail-closed config if
+    the file is missing, unsafe, or malformed."""
+    cfg_path = path or auth_config_path()
+    if not os.path.isfile(cfg_path):
+        return AuthConfig()
+    if not _is_auth_file_safe(cfg_path):
+        return AuthConfig()
+    if _toml is None:
+        logging.warning(
+            f"Ignoring {cfg_path}: no TOML parser available on this Python. "
+            f"Upgrade to Python 3.11+ (preferred) or install 'tomli' "
+            f"for 3.10. Upstream probes will fail closed until then."
+        )
+        return AuthConfig()
+
+    try:
+        with open(cfg_path, "rb") as f:
+            data = _toml.load(f)
+    except (OSError, _toml.TOMLDecodeError) as e:
+        logging.warning(f"Ignoring {cfg_path}: parse error ({e})")
+        return AuthConfig()
+
+    hosts_raw = data.get("hosts", {})
+    hosts: dict[str, dict[str, Any]] = {}
+    if isinstance(hosts_raw, dict):
+        for name, cfg in hosts_raw.items():
+            if isinstance(cfg, dict):
+                hosts[str(name)] = {k: v for k, v in cfg.items()}
+
+    defaults = data.get("defaults", {})
+    allow_unknown = False
+    if isinstance(defaults, dict):
+        allow_unknown = bool(defaults.get("allow_unknown", False))
+
+    return AuthConfig(hosts=hosts, allow_unknown=allow_unknown)

core/cli.py

@@ -0,0 +1,226 @@
+"""Argparse / subcommand dispatch for nostos.
+
+The top-level command is a verb-first subparser tree: `nostos pull`,
+`nostos add`, `nostos list`, etc. Invocations without a verb are
+treated as an implicit `pull` for backward compatibility. The legacy
+top-level flags (--add, --remove, --list) are rewritten to their
+subcommand equivalents and emit a deprecation notice.
+"""
+
+# PYTHON_ARGCOMPLETE_OK
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+from .commands import add as _cmd_add
+from .commands import attack as _cmd_attack
+from .commands import dashboard as _cmd_dashboard
+from .commands import digest as _cmd_digest
+from .commands import doctor as _cmd_doctor
+from .commands import export_cmd as _cmd_export
+from .commands import import_cmd as _cmd_import
+from .commands import list_cmd as _cmd_list
+from .commands import note as _cmd_note
+from .commands import pull as _cmd_pull
+from .commands import refresh as _cmd_refresh
+from .commands import rm as _cmd_rm
+from .commands import show as _cmd_show
+from .commands import tag as _cmd_tag
+from .commands import triage as _cmd_triage
+from .commands import update as _cmd_update
+from .commands import vault as _cmd_vault
+
+_KNOWN_VERBS: frozenset[str] = frozenset(
+    {
+        "pull", "add", "list", "show", "tag", "note", "triage",
+        "rm", "refresh", "digest", "vault", "export", "import",
+        "update", "doctor", "attack", "dashboard",
+    }
+)
+
+
+def get_version() -> str:
+    """Return the nostos version.
+
+    Reads the VERSION file at the repo root first so source-tree edits
+    are reflected immediately. Falls back to installed package metadata
+    for pip-installed runs.
+    """
+    version_file = os.path.join(os.path.dirname(os.path.dirname(__file__)), "VERSION")
+    try:
+        with open(version_file) as f:
+            value = f.read().strip()
+            if value:
+                return value
+    except OSError:
+        pass
+    try:
+        return _pkg_version("nostos")
+    except PackageNotFoundError:
+        return "unknown"
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="nostos",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        description=(
+            "nostos - manage a fleet of git repositories.\n"
+            "\n"
+            "Pull updates in parallel, maintain a curated index with tags, "
+            "status, and notes, probe upstream metadata (stars, archived, "
+            "last push), generate weekly digests and HTML dashboards, "
+            "bridge to an Obsidian vault, and export portable bundles "
+            "that move cleanly between machines."
+        ),
+        epilog=(
+            "Examples:\n"
+            "  nostos pull ~/code               Pull every repo under ~/code\n"
+            "  nostos pull --from-index --tags  Pull indexed repos + all their git tags\n"
+            "  nostos add URL --tag python      Clone a remote repo and register it\n"
+            "  nostos list --tag security       Show indexed repos carrying a tag\n"
+            "  nostos refresh                   Fetch upstream metadata for the index\n"
+            "  nostos export --out fleet.json   Export the full index for portability\n"
+            "\n"
+            "Run `nostos <command> --help` for flags on a specific command.\n"
+            "Docs: https://github.com/prodrom3/nostos"
+        ),
+    )
+    parser.add_argument(
+        "-v",
+        "--version",
+        action="version",
+        version=f"%(prog)s {get_version()}",
+    )
+    subparsers = parser.add_subparsers(
+        title="commands",
+        dest="command",
+        metavar="COMMAND",
+    )
+    # Group the verbs in a logical order so `--help` reads top to bottom.
+    # Core pull / index intake:
+    _cmd_pull.add_parser(subparsers)
+    _cmd_add.add_parser(subparsers)
+    # Index inspection & editing:
+    _cmd_list.add_parser(subparsers)
+    _cmd_show.add_parser(subparsers)
+    _cmd_tag.add_parser(subparsers)
+    _cmd_note.add_parser(subparsers)
+    _cmd_triage.add_parser(subparsers)
+    _cmd_rm.add_parser(subparsers)
+    # Upstream intelligence & reporting:
+    _cmd_refresh.add_parser(subparsers)
+    _cmd_digest.add_parser(subparsers)
+    _cmd_dashboard.add_parser(subparsers)
+    _cmd_attack.add_parser(subparsers)
+    # External bridges & portability:
+    _cmd_vault.add_parser(subparsers)
+    _cmd_export.add_parser(subparsers)
+    _cmd_import.add_parser(subparsers)
+    # Operational / housekeeping:
+    _cmd_update.add_parser(subparsers)
+    _cmd_doctor.add_parser(subparsers)
+    return parser
+
+
+def _rewrite_legacy_argv(argv: list[str]) -> list[str]:
+    """Translate legacy top-level flags to subcommand form.
+
+    Keeps `nostos --add X`, `nostos --remove X`, `nostos --list`,
+    and `nostos --watchlist` working for one release. Users get a
+    one-line deprecation notice to stderr when a legacy flag fires.
+    """
+    if not argv:
+        return argv
+
+    # --list with no other verb -> `list`
+    if argv and argv[0] == "--list":
+        _deprecate("--list", "list")
+        return ["list"] + argv[1:]
+
+    # --add PATH ... -> `add PATH ...`
+    if "--add" in argv:
+        idx = argv.index("--add")
+        if idx + 1 < len(argv):
+            target = argv[idx + 1]
+            _deprecate("--add", "add")
+            rest = argv[:idx] + argv[idx + 2 :]
+            return ["add", target] + rest
+
+    # --remove PATH ... -> `rm PATH ...`
+    if "--remove" in argv:
+        idx = argv.index("--remove")
+        if idx + 1 < len(argv):
+            target = argv[idx + 1]
+            _deprecate("--remove", "rm")
+            rest = argv[:idx] + argv[idx + 2 :]
+            return ["rm", target] + rest
+
+    return argv
+
+
+def _deprecate(old: str, new_verb: str) -> None:
+    print(
+        f"nostos: warning: {old} is deprecated; use `nostos {new_verb}` instead",
+        file=sys.stderr,
+        flush=True,
+    )
+
+
+def _inject_default_verb(argv: list[str]) -> list[str]:
+    """If the first positional arg is not a known verb, prepend `pull`."""
+    for a in argv:
+        if a in {"-h", "--help", "-v", "--version"}:
+            return argv
+        if not a.startswith("-"):
+            if a in _KNOWN_VERBS:
+                return argv
+            return ["pull"] + argv
+    # All flags, no positional -> implicit pull
+    return ["pull"] + argv
+
+
+def run(argv: list[str] | None = None) -> int:
+    if argv is None:
+        argv = sys.argv[1:]
+    argv = _rewrite_legacy_argv(list(argv))
+    argv = _inject_default_verb(argv)
+
+    parser = build_parser()
+
+    # Optional shell tab-completion. Only active if argcomplete is installed
+    # and the shell invoked us in completion mode. Silently no-ops otherwise,
+    # so we don't make argcomplete a hard dependency.
+    try:
+        import argcomplete  # type: ignore[import-not-found]
+
+        argcomplete.autocomplete(parser)
+    except ImportError:
+        pass
+
+    args = parser.parse_args(argv)
+
+    func = getattr(args, "func", None)
+    if func is None:
+        parser.print_help()
+        return 2
+    return int(func(args))
+
+
+# Back-compat: keep the old parse_args() symbol for anyone importing it.
+def parse_args() -> argparse.Namespace:
+    """Legacy entry used by older tests. Returns a Namespace for the
+    rewritten argv, without executing the command."""
+    argv = _rewrite_legacy_argv(list(sys.argv[1:]))
+    argv = _inject_default_verb(argv)
+    return build_parser().parse_args(argv)
+
+
+def main_entry() -> None:
+    """Entry point for the pip-installed `nostos` console script."""
+    sys.exit(run(sys.argv[1:]))

core/commands/__init__.py

@@ -0,0 +1,6 @@
+"""Subcommand modules for nostos.
+
+Each module in this package defines two callables:
+- add_parser(subparsers): register the subparser for the command
+- run(args) -> int: execute the command and return a process exit code
+"""

core/commands/_common.py

@@ -0,0 +1,51 @@
+"""Shared helpers for subcommand modules."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+
+def fail(msg: str, *, code: int = 1) -> int:
+    """Print an error to stderr and return an exit code."""
+    print(f"nostos: error: {msg}", file=sys.stderr, flush=True)
+    return code
+
+
+def maybe_migrate_watchlist() -> None:
+    """One-shot migration from ~/.nostos_repos into the index.
+
+    If the legacy watchlist file still exists (and has not already been
+    renamed to .migrated), its entries are imported into the index with
+    source='legacy-watchlist' and status='reviewed'. The file is then
+    renamed to ~/.nostos_repos.migrated and a one-line notice is
+    printed to stderr.
+    """
+    legacy = os.path.join(os.path.expanduser("~"), ".nostos_repos")
+    if not os.path.isfile(legacy):
+        return
+    from .. import index as _index
+
+    try:
+        with _index.connect() as conn:
+            n = _index.migrate_watchlist(conn, legacy)
+    except OSError:
+        return
+
+    try:
+        os.rename(legacy, legacy + ".migrated")
+    except OSError:
+        # Rename failed - leave the file but don't re-migrate next run
+        # by rewriting it with a header comment. Best-effort.
+        try:
+            with open(legacy, "w", encoding="utf-8") as f:
+                f.write("# migrated into nostos index; safe to delete\n")
+        except OSError:
+            pass
+
+    print(
+        f"nostos: migrated {n} watchlist entries into the metadata index "
+        f"({legacy} -> {legacy}.migrated)",
+        file=sys.stderr,
+        flush=True,
+    )

core/commands/add.py

@@ -0,0 +1,118 @@
+"""`nostos add` - ingest a repo into the metadata index.
+
+Accepts either a local path to an existing git repository or a remote
+URL. When given a URL, the repo is cloned first (via the hardened
+clone routine, with hooks disabled) and then the resulting local path
+is registered.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from typing import Any
+
+from .. import index as _index
+from ..config import load_config
+from ..watchlist import clone_repo, is_remote_url
+from ._common import fail, maybe_migrate_watchlist
+
+
+def add_parser(subparsers: Any) -> None:
+    p = subparsers.add_parser(
+        "add",
+        help="Register a repository in the metadata index",
+        description="Register a local git repository, or clone a remote URL and register it.",
+    )
+    p.add_argument(
+        "target",
+        metavar="PATH_OR_URL",
+        help="Local path to a git repository, or a remote URL to clone",
+    )
+    p.add_argument(
+        "--tag",
+        action="append",
+        default=[],
+        metavar="TAG",
+        help="Tag to attach (repeatable, or comma-separated)",
+    )
+    p.add_argument(
+        "--source",
+        default=None,
+        help="Free-text provenance (e.g. 'blog:orange.tw, 2026-04-12')",
+    )
+    p.add_argument(
+        "--note",
+        default=None,
+        help="Initial free-text note",
+    )
+    p.add_argument(
+        "--status",
+        default="new",
+        choices=sorted(_index.VALID_STATUSES),
+        help="Initial triage status (default: new)",
+    )
+    p.add_argument(
+        "--quiet-upstream",
+        action="store_true",
+        help="Opsec flag: never query upstream metadata for this repo",
+    )
+    p.add_argument(
+        "--clone-dir",
+        default=None,
+        metavar="DIR",
+        help="Directory to clone into when target is a URL (default: cwd or config)",
+    )
+    p.set_defaults(func=run)
+
+
+def _flatten_tags(raw: list[str]) -> list[str]:
+    tags: list[str] = []
+    for item in raw:
+        for piece in item.split(","):
+            piece = piece.strip()
+            if piece:
+                tags.append(piece)
+    return tags
+
+
+def run(args: argparse.Namespace) -> int:
+    maybe_migrate_watchlist()
+
+    target = args.target
+    tags = _flatten_tags(args.tag)
+
+    if is_remote_url(target):
+        clone_dir = args.clone_dir
+        if clone_dir is None:
+            clone_dir = load_config()["clone_dir"] or os.getcwd()
+        local_path = clone_repo(target, clone_dir)
+        if local_path is None:
+            return fail(f"clone failed: {target}")
+        repo_path = local_path
+        remote_url = target
+    else:
+        repo_path = target
+        if not os.path.isdir(os.path.join(os.path.expanduser(repo_path), ".git")):
+            return fail(f"not a git repository: {repo_path}")
+        remote_url = None
+
+    try:
+        with _index.connect() as conn:
+            repo_id = _index.add_repo(
+                conn,
+                repo_path,
+                remote_url=remote_url,
+                source=args.source,
+                status=args.status,
+                quiet=args.quiet_upstream,
+                tags=tags,
+                note=args.note,
+            )
+    except (OSError, ValueError) as e:
+        return fail(str(e))
+
+    print(f"Added to index (id={repo_id}): {os.path.realpath(os.path.expanduser(repo_path))}",
+          file=sys.stderr, flush=True)
+    return 0

core/commands/attack.py

@@ -0,0 +1,83 @@
+"""`nostos attack` - ATT&CK technique helpers.
+
+Sub-verbs:
+- `attack list`       print the built-in technique lookup table.
+- `attack tag <repo> T1059 [T1071 ...]`  shorthand for
+  `nostos tag <repo> +attack:t1059 +attack:t1071`.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Any
+
+from .. import index as _index
+from .. import taxonomy as _tax
+from ._common import fail, maybe_migrate_watchlist
+
+
+def add_parser(subparsers: Any) -> None:
+    p = subparsers.add_parser(
+        "attack",
+        help="ATT&CK technique helpers (list taxonomy, tag repos)",
+        description="Work with MITRE ATT&CK technique tags.",
+    )
+    sub = p.add_subparsers(dest="attack_command", metavar="SUBCOMMAND", required=True)
+
+    # attack list
+    lst = sub.add_parser(
+        "list",
+        help="Print the built-in ATT&CK technique lookup table",
+    )
+    lst.set_defaults(func=run_list)
+
+    # attack tag <repo> T1059 [T1071 ...]
+    tg = sub.add_parser(
+        "tag",
+        help="Tag a repo with one or more ATT&CK technique IDs",
+        description=(
+            "Shorthand for `nostos tag <repo> +attack:TNNNN`. "
+            "Each ID is validated against the built-in lookup table."
+        ),
+    )
+    tg.add_argument("target", metavar="PATH_OR_ID")
+    tg.add_argument("techniques", nargs="+", metavar="TNNNN")
+    tg.set_defaults(func=run_tag)
+
+
+def run_list(args: argparse.Namespace) -> int:
+    print(f"MITRE ATT&CK techniques ({len(_tax.TECHNIQUES)} in the built-in table):\n")
+    sys.stdout.write(_tax.render_table())
+    return 0
+
+
+def run_tag(args: argparse.Namespace) -> int:
+    maybe_migrate_watchlist()
+
+    tags_to_add: list[str] = []
+    for raw in args.techniques:
+        tag = _tax.normalize_attack_tag(raw)
+        info = _tax.lookup(tag)
+        if info is None:
+            print(
+                f"warning: {raw} is not in the built-in lookup table; "
+                f"adding as {tag} anyway",
+                file=sys.stderr,
+            )
+        tags_to_add.append(tag)
+
+    try:
+        with _index.connect() as conn:
+            if not _index.add_tags(conn, args.target, tags_to_add):
+                return fail(f"not in index: {args.target}")
+            final = _index.get_tags(conn, args.target)
+    except OSError as e:
+        return fail(str(e))
+
+    attack_tags = [t for t in final if t.startswith("attack:")]
+    other_tags = [t for t in final if not t.startswith("attack:")]
+    print(f"attack tags: {', '.join(attack_tags) or '(none)'}", file=sys.stderr)
+    if other_tags:
+        print(f"other tags:  {', '.join(other_tags)}", file=sys.stderr)
+    return 0