arcsecond 4.0.0__tar.gz → 4.2.1__tar.gz

{arcsecond-4.0.0 → arcsecond-4.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: arcsecond
-Version: 4.0.0
+Version: 4.2.1
 Summary: CLI for arcsecond.io
 Project-URL: Homepage, https://github.com/arcsecond-io/cli
 Project-URL: Issues, https://github.com/arcsecond-io/cli/issues
@@ -56,7 +56,7 @@ The Command-line interface (CLI) for Arcsecond. It can be used as Python
 module too. The CLI makes it easy to login/register and access Arcsecond resources,
 public and private ones.
 
-[Read the docs](https://docs.arcsecond.io/cli)
+[Read the docs](https://docs.arcsecond.io/reference/cli)
 
 ## Running Arcsecond.local
 
@@ -65,6 +65,7 @@ The CLI owns the whole lifecycle of a self-hosted installation; there is no
 
 ```bash
 $ arcsecond setup --lan-host 192.168.1.42   # writes .env and docker-compose.yml
+$ arcsecond token set                       # the access token Arcsecond gave you, once per machine (setup asks too)
 $ arcsecond start                           # first run downloads the images
 $ arcsecond status
 $ arcsecond logs backend -f

{arcsecond-4.0.0 → arcsecond-4.2.1}/README.md

@@ -7,7 +7,7 @@ The Command-line interface (CLI) for Arcsecond. It can be used as Python
 module too. The CLI makes it easy to login/register and access Arcsecond resources,
 public and private ones.
 
-[Read the docs](https://docs.arcsecond.io/cli)
+[Read the docs](https://docs.arcsecond.io/reference/cli)
 
 ## Running Arcsecond.local
 
@@ -16,6 +16,7 @@ The CLI owns the whole lifecycle of a self-hosted installation; there is no
 
 ```bash
 $ arcsecond setup --lan-host 192.168.1.42   # writes .env and docker-compose.yml
+$ arcsecond token set                       # the access token Arcsecond gave you, once per machine (setup asks too)
 $ arcsecond start                           # first run downloads the images
 $ arcsecond status
 $ arcsecond logs backend -f

{arcsecond-4.0.0 → arcsecond-4.2.1}/arcsecond/cli.py

@@ -12,6 +12,7 @@ from arcsecond.cloud import (
 from arcsecond.docgen import docs
 from arcsecond.hosting import (
     backups,
+    check_cmd,
     db,
     logs,
     restart,
@@ -19,6 +20,7 @@ from arcsecond.hosting import (
     start,
     status,
     stop,
+    token_group,
     update,
 )
 from arcsecond.imagesources import commands as imagesources
@@ -72,6 +74,12 @@ main.add_command(status)
 main.add_command(logs)
 main.add_command(update)
 
+# Is it reachable from the rest of the observatory, and if not, why not.
+main.add_command(check_cmd)
+
+# The access token Arcsecond gave the observatory, once per machine.
+main.add_command(token_group)
+
 # Browse and restore Arcsecond.local DB backups.
 main.add_command(backups)
 

{arcsecond-4.0.0 → arcsecond-4.2.1}/arcsecond/docgen.py

@@ -1,6 +1,6 @@
 """The command reference, generated from the command tree itself.
 
-`arcsecond docs commands --out DIR` writes one Markdown page per top-level
+`arcsecond docs commands --out docs/reference/commands` writes one Markdown page per top-level
 command — usage, help, arguments, options, subcommands — plus an index and a
 machine-readable `commands.json`, every page carrying the documentation
 site's frontmatter with `source: generated`.
@@ -22,6 +22,7 @@ committed copy honest.
 """
 
 import html
+import inspect
 import json
 import textwrap
 from pathlib import Path
@@ -54,8 +55,13 @@ def _render_help(text: Optional[str]) -> List[str]:
     Click marks a paragraph it must not rewrap with a backspace character —
     that is how command examples are written in a docstring — and such a
     paragraph is exactly what belongs in a code fence here."""
+    # Dedented the way click dedents it for --help. Python 3.13 strips a
+    # docstring's indentation at compile time and 3.12 does not, so without
+    # this the same source generated two different pages depending on the
+    # interpreter that ran it.
+    text = inspect.cleandoc(text or "")
     lines: List[str] = []
-    for paragraph in (text or "").strip().split("\n\n"):
+    for paragraph in text.split("\n\n"):
         if not paragraph.strip():
             continue
         if paragraph.lstrip().startswith("\b"):
@@ -293,3 +299,43 @@ def docs_commands(ctx, out, check):
         )
     written = write(files, Path(out))
     click.echo(f"Wrote {len(written)} files to {out}")
+
+
+@docs.command(
+    name="compose",
+    help="Write the services and environment reference from the packaged compose template.",
+)
+@click.option(
+    "--out",
+    "out",
+    type=click.Path(file_okay=False),
+    default=None,
+    help="Folder to write into.",
+)
+@click.option(
+    "--check",
+    "check",
+    type=click.Path(file_okay=False, exists=True),
+    default=None,
+    help="Compare against this folder instead of writing; exit 1 if it is out of date.",
+)
+def docs_compose(out, check):
+    from arcsecond.hosting import composedoc
+
+    files = composedoc.generate(__version__.__version__)
+    if check:
+        changed = differences(files, Path(check))
+        if changed:
+            click.echo("The services/environment reference is out of date:")
+            for name in changed:
+                click.echo(f"  {name}")
+            click.echo("\nRegenerate it:  arcsecond docs compose --out " + check)
+            raise SystemExit(1)
+        click.echo(f"The services/environment reference in {check} is up to date.")
+        return
+    if not out:
+        raise click.UsageError(
+            "Give --out FOLDER to write, or --check FOLDER to verify."
+        )
+    written = write(files, Path(out))
+    click.echo(f"Wrote {len(written)} files to {out}")

{arcsecond-4.0.0 → arcsecond-4.2.1}/arcsecond/hosting/__init__.py

@@ -1,13 +1,20 @@
 from .backups import backups
+
+# check_cmd, not check: `check` is also this package's module of that name,
+# and re-exporting the command under it would shadow the module for tests.
+from .check import check_cmd
 from .database import db
 from .lifecycle import logs, restart, start, status, stop, update
 from .local import setup
+from .token import token_group
 
 # Re-exported: the command groups `arcsecond.cli` mounts.
 __all__ = [
     "backups",
+    "check_cmd",
     "db",
     "setup",
+    "token_group",
     "start",
     "stop",
     "restart",

{arcsecond-4.0.0 → arcsecond-4.2.1}/arcsecond/hosting/backups.py

@@ -10,9 +10,13 @@ from pathlib import Path
 
 import click
 
+from arcsecond.errors import ArcsecondError
 from arcsecond.options import basic_options
 
-from .utils import _container_running, _read_env_value
+from . import stack
+from .lifecycle import dir_option
+from .utils import _container_running
+from .utils import _read_env_value as _read_env_value_from
 
 DB_CONTAINER = "arcsecond-db"
 API_CONTAINER = "arcsecond-api"
@@ -44,8 +48,16 @@ STATUS_BROKEN = "broken"
 GZIP_MAGIC = b"\x1f\x8b"
 
 
-def _cwd_env_path():
-    return Path.cwd() / ".env"
+# The installation the current command works on, resolved once by
+# _ensure_install_dir: --dir, else the current folder, else the folder
+# `arcsecond setup` last ran in (see stack.resolve_install_dir).
+_install = None
+
+
+def _read_env_value(key):
+    """A value from the installation's .env — the resolved one, not whatever
+    happens to be in the current folder."""
+    return _read_env_value_from(key, _install.env_path if _install else None)
 
 
 def _backups_dir():
@@ -55,18 +67,13 @@ def _backups_dir():
     return Path(shared) / "db_backups"
 
 
-def _print_wrong_dir_hint():
-    click.echo(
-        "Could not find an Arcsecond.local installation in the current directory.\n"
-        "Run `arcsecond backups ...` from the directory that contains your "
-        "docker-compose.yml and .env files (the one you used for `arcsecond setup`)."
-    )
-
-
-def _ensure_install_dir():
+def _ensure_install_dir(directory=None):
     """Return the backups dir, or None after printing a clear error."""
-    if not _cwd_env_path().exists():
-        _print_wrong_dir_hint()
+    global _install
+    try:
+        _install = stack.resolve_install_dir(directory)
+    except ArcsecondError as e:
+        click.echo(str(e))
         return None
     backups_dir = _backups_dir()
     if backups_dir is None:
@@ -78,9 +85,8 @@ def _ensure_install_dir():
     if not backups_dir.exists():
         click.echo(
             f"No backups directory found at: {backups_dir.resolve()}\n"
-            "Make sure you run this command from the Arcsecond.local working directory "
-            "(the one with docker-compose.yml and .env), and that the backend has been "
-            "started at least once — the boot-time backup is the first to appear."
+            "Make sure the backend has been started at least once — the boot-time "
+            "backup is the first to appear."
         )
         return None
     return backups_dir
@@ -569,9 +575,10 @@ def _print_destination_section(items):
 @backups.command(
     name="list", help="List available DB backups with compatibility status."
 )
+@dir_option
 @basic_options
-def list_cmd():
-    backups_dir = _ensure_install_dir()
+def list_cmd(directory):
+    backups_dir = _ensure_install_dir(directory)
     if backups_dir is None:
         sys.exit(1)
 
@@ -624,9 +631,10 @@ def list_cmd():
 
 @backups.command(name="inspect", help="Show detailed info about a backup.")
 @click.argument("ref", required=True)
+@dir_option
 @basic_options
-def inspect_cmd(ref):
-    backups_dir = _ensure_install_dir()
+def inspect_cmd(directory, ref):
+    backups_dir = _ensure_install_dir(directory)
     if backups_dir is None:
         sys.exit(1)
 
@@ -1085,9 +1093,8 @@ def _stop_services(dry_run):
 
 def _start_services(dry_run):
     """Bring the stack back. Compose restarts dependents; by name if it is absent."""
-    compose_file = Path.cwd() / "docker-compose.yml"
-    if compose_file.exists():
-        _run(["docker", "compose", "up", "-d"], dry_run)
+    if _install is not None and _install.compose_path.exists():
+        _run(stack.compose_command(_install, "up", "-d", "--remove-orphans"), dry_run)
     else:
         for name in reversed(SERVICES_TO_STOP):
             _run(["docker", "start", name], dry_run, capture_output=True, text=True)
@@ -1149,9 +1156,10 @@ def _perform_restore(path, backups_dir, dry_run, no_safety_backup):
 @click.option(
     "--no-safety-backup", is_flag=True, help="Skip the pre-restore safety snapshot."
 )
+@dir_option
 @basic_options
-def restore_cmd(ref, force, dry_run, no_safety_backup):
-    backups_dir = _ensure_install_dir()
+def restore_cmd(directory, ref, force, dry_run, no_safety_backup):
+    backups_dir = _ensure_install_dir(directory)
     if backups_dir is None:
         sys.exit(1)