publinker-cli 0.6.2__py3-none-any.whl

publinker_cli/commands/skill.py

@@ -0,0 +1,46 @@
+"""`publinker skill` — install the agent skill that teaches AI assistants the CLI.
+
+The skill is a plain SKILL.md packaged with the CLI, so it always matches the
+installed version. `install` copies it to the user-level skill folders that
+Claude Code and Codex read; `path` prints it for any other assistant.
+"""
+
+from __future__ import annotations
+
+from importlib import resources
+from pathlib import Path
+
+import typer
+
+app = typer.Typer(
+    name="skill",
+    help="Install the Publinker skill for Claude Code and Codex.",
+    no_args_is_help=True,
+)
+
+SKILL_NAME = "publinker"
+# User-level skill folders: Claude Code reads ~/.claude/skills, Codex reads
+# ~/.agents/skills. Both take <name>/SKILL.md.
+TARGETS = (Path(".claude/skills"), Path(".agents/skills"))
+
+
+def packaged_skill() -> Path:
+    return Path(str(resources.files("publinker_cli") / "skill" / "SKILL.md"))
+
+
+@app.command(
+    "install", help="Copy the skill into ~/.claude/skills and ~/.agents/skills."
+)
+def install_cmd() -> None:
+    text = packaged_skill().read_text(encoding="utf-8")
+    for target in TARGETS:
+        dest = Path.home() / target / SKILL_NAME / "SKILL.md"
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text(text, encoding="utf-8")
+        typer.echo(f"installed {dest}")
+    typer.echo("Restart Claude Code / Codex to pick it up.")
+
+
+@app.command("path", help="Print the packaged SKILL.md path (for other assistants).")
+def path_cmd() -> None:
+    typer.echo(packaged_skill())

publinker_cli/commands/token_cmd.py

@@ -0,0 +1,97 @@
+"""`publinker token` — print the live access/id token for scripting and debugging.
+
+Exists so nobody has to dig a session token out of DevTools → Application →
+Local Storage to authenticate a curl or a preview host (the workflow this
+replaces; see DEV-1361's per-PR preview environments).
+
+Contract, deliberately Unix-ish:
+- **stdout carries the token and nothing else** — no banner, no color, no
+  spinner — so `$(publinker token)` is safe to embed in a command.
+- **All human messaging goes to stderr**, so it stays visible in a terminal but
+  never contaminates a pipe.
+- The token is never written to a file, a log, or the shell history by this
+  command; printing it to stdout is the caller's decision to make.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+
+import typer
+from rich.console import Console
+
+from publinker_cli import keyring_store
+from publinker_cli.client import NotAuthenticatedError, PublinkerClient
+from publinker_cli.config import AUTH0_AUDIENCE, AUTH0_SCOPES
+
+# stderr so it can never pollute `$(publinker token)`.
+err_console = Console(stderr=True)
+
+
+def token_command(
+    id_token: bool = typer.Option(
+        False,
+        "--id",
+        help="Print the id_token (identity claims) instead of the access token.",
+    ),
+    as_json: bool = typer.Option(
+        False,
+        "--json",
+        help=(
+            "Print the full bundle as JSON: access_token, id_token, token_type, "
+            "scope, audience, expires_at, expires_in."
+        ),
+    ),
+) -> None:
+    """Print a live Auth0 token for the logged-in user.
+
+    Refreshes transparently when the cached token has expired, so the value
+    printed is always usable right now.
+    """
+    if id_token and as_json:
+        err_console.print("[red]--id and --json are mutually exclusive.[/red]")
+        raise typer.Exit(code=2)
+
+    try:
+        # Reuse the client's refresh-and-persist path rather than duplicating it:
+        # current_bundle() returns a non-expired bundle, refreshing (and
+        # re-saving) when needed, and raises when the session is truly gone.
+        bundle = PublinkerClient().current_bundle()
+    except NotAuthenticatedError as exc:
+        err_console.print(f"[red]{exc}[/red]")
+        raise typer.Exit(code=1)
+
+    if as_json:
+        typer.echo(json.dumps(_bundle_as_dict(bundle), indent=2))
+        return
+
+    value = bundle.id_token if id_token else bundle.access_token
+    if not value:
+        which = "id_token" if id_token else "access_token"
+        err_console.print(
+            f"[red]No {which} in the stored session — run `publinker login`.[/red]"
+        )
+        raise typer.Exit(code=1)
+
+    typer.echo(value)
+
+
+def _bundle_as_dict(bundle: keyring_store.TokenBundle) -> dict:
+    """Shape the bundle like Auth0's own /oauth/token response.
+
+    Mirroring that shape means the JSON can be dropped straight into tooling
+    that already understands an Auth0 token response. `expires_in` is recomputed
+    from the stored absolute expiry so it is accurate at print time, not at
+    login time.
+    """
+    now = int(time.time())
+    return {
+        "access_token": bundle.access_token,
+        "id_token": bundle.id_token,
+        "token_type": "Bearer",
+        "scope": AUTH0_SCOPES,
+        "audience": AUTH0_AUDIENCE,
+        "expires_at": bundle.expires_at,
+        "expires_in": max(0, bundle.expires_at - now),
+    }

publinker_cli/commands/update.py

@@ -0,0 +1,207 @@
+"""`publinker update` — check for and install a newer publinker-cli (DEV-1973).
+
+The release source is the git spec pipx recorded when this installation was
+made (`install-cli.sh` records a `git+https://...@<ref>#subdirectory=cli` spec).
+The latest version is the `__version__` in `publinker_cli/__init__.py` at that
+ref, read with the same git credentials pipx installs with — no Publinker
+login, no AWS credentials, no write gate.
+
+Only the running pipx installation is ever modified, and only from the source
+it was installed from. Editable/local-path/wheel installs and customer builds
+get instructions instead: a customer wheel must never be replaced by the
+internal build that lives in the repository.
+
+Exit codes:
+- 0  up to date, or updated and verified
+- 10 `--check` only: a newer version is available
+- 1  anything else (unsupported install, metadata/network/access/installer
+     failure); nothing was installed or the install could not be verified
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from publinker_cli import __version__, audience
+from publinker_cli.version import is_newer, parse_version
+
+PACKAGE = "publinker-cli"
+EXIT_UPDATE_AVAILABLE = 10
+INSTALLER_HINT = (
+    "Install with ./cli/scripts/install-cli.sh from a publinker-api checkout "
+    "(a pipx install from git), then `publinker update` can manage it."
+)
+_GIT_SPEC_RE = re.compile(
+    r"^git\+(?P<url>[^@#]+?)(?:@(?P<ref>[^#]+))?#subdirectory=cli$"
+)
+_INIT_VERSION_RE = re.compile(r'^__version__ = "([^"]+)"', re.M)
+
+
+class UpdateError(Exception):
+    """A failure the user must act on. The message says how."""
+
+
+@dataclass(frozen=True)
+class Installation:
+    pipx: str
+    spec: str
+    url: str
+    ref: Optional[str]
+
+
+def _run(cmd: list[str], **kwargs) -> subprocess.CompletedProcess:
+    # GIT_TERMINAL_PROMPT=0: a missing credential fails instead of hanging.
+    env = {**os.environ, "GIT_TERMINAL_PROMPT": "0"}
+    return subprocess.run(cmd, text=True, env=env, **kwargs)
+
+
+def find_installation() -> Installation:
+    """The pipx install that is running this process, or UpdateError."""
+    if audience.is_customer_build():
+        raise UpdateError(
+            "This is a customer build of publinker-cli; update it with "
+            "`pipx upgrade publinker-cli`."
+        )
+    pipx = shutil.which("pipx")
+    if not pipx:
+        raise UpdateError(f"pipx not found on PATH. {INSTALLER_HINT}")
+    venvs = _run(
+        [pipx, "environment", "--value", "PIPX_LOCAL_VENVS"], capture_output=True
+    )
+    if (
+        venvs.returncode != 0
+        or Path(sys.prefix).resolve()
+        != (Path(venvs.stdout.strip()) / PACKAGE).resolve()
+    ):
+        raise UpdateError(
+            f"This publinker ({sys.prefix}) is not a pipx installation; "
+            f"update it where it was installed (e.g. `git pull` for an editable "
+            f"install). {INSTALLER_HINT}"
+        )
+    listing = _run([pipx, "list", "--json"], capture_output=True)
+    try:
+        spec = json.loads(listing.stdout)["venvs"][PACKAGE]["metadata"]["main_package"][
+            "package_or_url"
+        ]
+    except (ValueError, KeyError, TypeError) as exc:
+        raise UpdateError(f"could not read the pipx install record: {exc}") from exc
+    match = _GIT_SPEC_RE.match(spec)
+    if not match:
+        raise UpdateError(
+            f"publinker-cli was installed from {spec}, which has no release "
+            f"source to check. {INSTALLER_HINT}"
+        )
+    return Installation(pipx, spec, match["url"], match["ref"])
+
+
+def latest_version(inst: Installation) -> str:
+    """`__version__` of cli/ at the installation's git ref."""
+    with tempfile.TemporaryDirectory() as tmp:
+        clone = [
+            "git",
+            "clone",
+            "--quiet",
+            "--depth",
+            "1",
+            "--filter=blob:none",
+            "--no-checkout",
+        ]
+        if inst.ref:
+            clone += ["--branch", inst.ref]
+        cloned = _run(clone + [inst.url, tmp], capture_output=True)
+        if cloned.returncode != 0:
+            raise UpdateError(
+                f"could not read {inst.url}@{inst.ref or 'HEAD'}: "
+                f"{cloned.stderr.strip() or 'git clone failed'}"
+            )
+        shown = _run(
+            ["git", "-C", tmp, "show", "HEAD:cli/publinker_cli/__init__.py"],
+            capture_output=True,
+        )
+    found = _INIT_VERSION_RE.search(shown.stdout) if shown.returncode == 0 else None
+    if not found:
+        raise UpdateError(
+            f"no publinker-cli version found at {inst.url}@{inst.ref or 'HEAD'}"
+        )
+    try:
+        parse_version(found[1])
+    except ValueError as exc:
+        raise UpdateError(f"release source has a malformed version: {exc}") from exc
+    return found[1]
+
+
+def installed_version() -> str:
+    """Version reported by this installation's own binary, after a reinstall."""
+    binary = Path(sys.prefix) / "bin" / "publinker"
+    out = _run([str(binary), "--version"], capture_output=True)
+    if out.returncode != 0:
+        raise UpdateError(f"{binary} --version failed: {out.stderr.strip()}")
+    reported = out.stdout.strip().rsplit(" ", 1)[-1]
+    try:
+        parse_version(reported)
+    except ValueError as exc:
+        raise UpdateError(f"could not verify the installed version: {exc}") from exc
+    return reported
+
+
+def update_command(
+    check: bool = typer.Option(
+        False,
+        "--check",
+        help="Only report installed/latest versions as JSON; never install.",
+    ),
+) -> None:
+    """Check for a newer publinker-cli and install it into this pipx install.
+
+    Needs no Publinker login. Exit codes: 0 current/updated, 10 update
+    available (--check), 1 failure.
+    """
+    try:
+        inst = find_installation()
+        latest = latest_version(inst)
+        available = is_newer(latest)
+        if check:
+            typer.echo(
+                json.dumps(
+                    {
+                        "installed": __version__,
+                        "latest": latest,
+                        "update_available": available,
+                        "source": inst.spec,
+                    }
+                )
+            )
+            raise typer.Exit(EXIT_UPDATE_AVAILABLE if available else 0)
+        if not available:
+            typer.echo(f"publinker-cli {__version__} is up to date ({inst.spec}).")
+            return
+        typer.echo(f"Updating publinker-cli {__version__} -> {latest} ...", err=True)
+        # Installer logs go to stderr; stdout stays the one-line result.
+        reinstall = _run(
+            [inst.pipx, "reinstall", PACKAGE], stdout=sys.stderr, stderr=sys.stderr
+        )
+        if reinstall.returncode != 0:
+            raise UpdateError(
+                f"pipx reinstall failed (exit {reinstall.returncode}); "
+                f"publinker-cli may need `pipx install --force '{inst.spec}'`."
+            )
+        now = installed_version()
+        if parse_version(now) < parse_version(latest):
+            raise UpdateError(
+                f"installed version is {now}, expected {latest}; update not verified."
+            )
+        typer.echo(f"publinker-cli updated {__version__} -> {now}.")
+    except UpdateError as exc:
+        typer.echo(f"publinker update: {exc}", err=True)
+        raise typer.Exit(1)

publinker_cli/commands/use.py

@@ -0,0 +1,100 @@
+"""`publinker use <site>` — set the active site for subsequent commands.
+
+Persists to ~/.config/publinker/state.json. Validates the site is in the
+user's permission set against `GET /site` so typos surface immediately.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+from rich.console import Console
+
+from publinker_cli import state
+from publinker_cli.config import available_stages
+from publinker_cli.client import APIError, NotAuthenticatedError, PublinkerClient
+
+console = Console()
+
+
+def use_command(
+    site: Optional[str] = typer.Argument(
+        None,
+        help=(
+            "Site domain to make active. Subsequent site-scoped commands "
+            "default to this site. Use --clear to unset."
+        ),
+    ),
+    clear: bool = typer.Option(
+        False,
+        "--clear",
+        "-c",
+        help="Clear the active site instead of setting one.",
+    ),
+    no_verify: bool = typer.Option(
+        False,
+        "--no-verify",
+        help=(
+            "Skip the API permission check. Useful when your permissions "
+            "just changed and the cached token hasn't refreshed."
+        ),
+    ),
+    stage: str = typer.Option(
+        "prod",
+        "--stage",
+        "-s",
+        help=f"API stage to verify against: {' | '.join(available_stages())}",
+    ),
+) -> None:
+    """Set or clear the active publinker site (persisted across sessions)."""
+    if clear:
+        if site:
+            console.print(
+                "[red]error:[/red] --clear takes no argument. Use either "
+                "`publinker use <site>` OR `publinker use --clear`."
+            )
+            raise typer.Exit(code=2)
+        state.clear()
+        console.print("[green]✓[/green] Active site cleared.")
+        return
+
+    if not site:
+        current = state.active_site()
+        if current:
+            console.print(f"Active site: [cyan]{current}[/cyan]")
+        else:
+            console.print(
+                "[yellow]No active site set.[/yellow] "
+                "Run `publinker use <domain>` to set one."
+            )
+        return
+
+    if not no_verify:
+        try:
+            sites = PublinkerClient(stage=stage).list_sites()
+        except NotAuthenticatedError as exc:
+            console.print(f"[red]{exc}[/red]")
+            raise typer.Exit(code=1)
+        except (APIError, ValueError) as exc:
+            console.print(f"[red]{exc}[/red]")
+            raise typer.Exit(code=1)
+        if site not in sites:
+            console.print(
+                f"[red]error:[/red] [cyan]{site}[/cyan] is not in your permission "
+                f"set on stage [cyan]{stage}[/cyan]."
+            )
+            if sites:
+                console.print(
+                    "\nYou have access to "
+                    f"[cyan]{len(sites)}[/cyan] site(s). "
+                    "Run [bold]publinker site list[/bold] to see them."
+                )
+            console.print(
+                "\nIf your permissions just changed and the cached token hasn't "
+                "refreshed, pass [bold]--no-verify[/bold] to skip the check."
+            )
+            raise typer.Exit(code=1)
+
+    state.set_active_site(site)
+    console.print(f"[green]✓[/green] Active site set to [cyan]{site}[/cyan].")

publinker_cli/commands/write.py

@@ -0,0 +1,72 @@
+"""`publinker write` diagnostics for the process-scoped mutation gate.
+
+File-backed allow windows are retired. A reviewed mutation carries
+``PUBLINKER_ALLOW_WRITES=1`` on that one command; nothing stays armed afterward.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+from rich.console import Console
+
+from publinker_cli import write_gate
+from publinker_cli.config import available_stages
+
+app = typer.Typer(
+    name="write",
+    help="Inspect the process-scoped mutation gate and clear retired state.",
+    no_args_is_help=True,
+)
+console = Console()
+
+
+@app.command("status", help="Show whether this process is authorized to mutate.")
+def status_cmd() -> None:
+    gate = write_gate.status()
+    if gate.allowed:
+        console.print(
+            f"[green]Writes ALLOWED[/green] — {gate.reason}; this process only"
+        )
+        return
+
+    console.print(f"[red]Writes BLOCKED[/red] — {gate.reason}.")
+    console.print("Authorize one reviewed command inline:")
+    stage = " --stage <stage>" if len(available_stages()) > 1 else ""
+    console.print(
+        f"  [cyan]{write_gate.ENV_VAR}=1 publinker <mutation>{stage} ...[/cyan]"
+    )
+
+
+@app.command("allow", help="Explain the one-process write authorization pattern.")
+def allow_cmd(
+    minutes: Optional[int] = typer.Option(
+        None,
+        "--minutes",
+        "-m",
+        help="Retired compatibility option; persistent windows are disabled.",
+    ),
+    persistent: bool = typer.Option(
+        False,
+        "--persistent",
+        help="Retired compatibility option; persistent authorization is disabled.",
+    ),
+) -> None:
+    del minutes, persistent
+    console.print(
+        "[red]Persistent write windows are disabled.[/red] Prefix one reviewed "
+        f"mutation with [cyan]{write_gate.ENV_VAR}=1[/cyan] instead."
+    )
+    raise typer.Exit(code=2)
+
+
+@app.command("block", help="Clear retired file-backed write authorization.")
+def block_cmd() -> None:
+    write_gate.clear_legacy_state()
+    console.print("[yellow]Retired file-backed write state cleared.[/yellow]")
+    if write_gate.status().allowed:
+        console.print(
+            f"[yellow]{write_gate.ENV_VAR} is enabled in this process; "
+            "don't export it in a shared shell.[/yellow]"
+        )

publinker_cli/config.py

@@ -0,0 +1,64 @@
+"""Static Auth0 + API config for publinker-cli.
+
+These values are non-secret per OAuth spec (the audience and client_id of a public
+Native client are public), so they live in source.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+AUTH0_DOMAIN = "dev-hqiwr-re.us.auth0.com"
+# Internal by default; the customer wheel replaces this and the vault namespace.
+AUTH0_CLIENT_ID = "t1NcBeA9ULAC34DYz3Ms5rwIlrFkjW7Z"
+AUTH0_AUDIENCE = "https://backend.publinker.com"
+AUTH0_SCOPES = "openid profile email offline_access"
+
+# Per-stage API base URLs.
+STAGE_URLS: dict[str, str] = {
+    "prod": "https://hlkl4tw3vd.execute-api.us-east-1.amazonaws.com/prod",
+}
+
+DEFAULT_STAGE = "prod"
+
+# Keyring service name — namespaces our tokens away from other apps.
+KEYRING_SERVICE = "publinker-cli-customer"
+KEYRING_ACCOUNT = "default"
+
+
+@dataclass(frozen=True)
+class Auth0Config:
+    domain: str
+    client_id: str
+    audience: str
+    scopes: str
+
+    @property
+    def device_code_url(self) -> str:
+        return f"https://{self.domain}/oauth/device/code"
+
+    @property
+    def token_url(self) -> str:
+        return f"https://{self.domain}/oauth/token"
+
+
+def auth0_config() -> Auth0Config:
+    return Auth0Config(
+        domain=AUTH0_DOMAIN,
+        client_id=AUTH0_CLIENT_ID,
+        audience=AUTH0_AUDIENCE,
+        scopes=AUTH0_SCOPES,
+    )
+
+
+def available_stages() -> list[str]:
+    """Stages this build may call. Customer builds get prod only (DEV-1566)."""
+    from publinker_cli.audience import is_customer_build
+
+    return [DEFAULT_STAGE] if is_customer_build() else sorted(STAGE_URLS)
+
+
+def api_base_url(stage: str) -> str:
+    if stage not in available_stages():
+        raise ValueError(f"unknown stage {stage!r}; valid: {available_stages()}")
+    return STAGE_URLS[stage]