sediment-cli 0.3.0__tar.gz → 0.5.0__tar.gz

{sediment_cli-0.3.0 → sediment_cli-0.5.0}/.gitignore

@@ -13,8 +13,7 @@ exports/
 !docs/exports/
 .env
 .DS_Store
-.claude/settings.local.*
-.claude/worktrees/
+.claude/
 
 # Deployment-local compose overrides (mirror credentials etc.) — never in PRs
 compose.override.yml
@@ -29,4 +28,3 @@ litellm/config.local.yaml
 !.env.example
 .agents/
 skills-lock.json
-.claude/skills/asd-ste100

{sediment_cli-0.3.0 → sediment_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sediment-cli
-Version: 0.3.0
+Version: 0.5.0
 Summary: The sediment command: login, install, server, facts, exports
 Project-URL: Source, https://github.com/sediment-ai/sediment
 Project-URL: Documentation, https://github.com/sediment-ai/sediment/tree/main/docs
@@ -10,7 +10,7 @@ License-Expression: AGPL-3.0-or-later
 License-File: LICENSE
 Requires-Python: >=3.12
 Requires-Dist: httpx>=0.27
-Requires-Dist: sediment-api==0.3.0
-Requires-Dist: sediment-core==0.3.0
-Requires-Dist: sediment-derive==0.3.0
-Requires-Dist: sediment-export==0.3.0
+Requires-Dist: sediment-api==0.5.0
+Requires-Dist: sediment-core==0.5.0
+Requires-Dist: sediment-derive==0.5.0
+Requires-Dist: sediment-export==0.5.0

{sediment_cli-0.3.0 → sediment_cli-0.5.0}/pyproject.toml

@@ -5,7 +5,7 @@
 # Depends on sediment-api deliberately: the operator verbs are DB-local by
 # design (ADR 0001) and `server`/reports/mirror-gc forward into it.
 name = "sediment-cli"
-version = "0.3.0"
+version = "0.5.0"
 description = "The sediment command: login, install, server, facts, exports"
 requires-python = ">=3.12"
 license = "AGPL-3.0-or-later"
@@ -14,10 +14,10 @@ license-files = ["LICENSE"]
 # so an install never mixes member versions (the release workflow asserts
 # the versions agree before publishing).
 dependencies = [
-    "sediment-core==0.3.0",
-    "sediment-derive==0.3.0",
-    "sediment-export==0.3.0",
-    "sediment-api==0.3.0",
+    "sediment-core==0.5.0",
+    "sediment-derive==0.5.0",
+    "sediment-export==0.5.0",
+    "sediment-api==0.5.0",
     "httpx>=0.27",
 ]
 

sediment_cli-0.5.0/sediment_cli/__init__.py

@@ -0,0 +1,72 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""The sediment CLI — the top-level `cli/` workspace member.
+
+Remote verbs speak HTTP through `.client`; operator verbs run where the
+facts live (ADR 0001); `.attribution` is the stdlib-only stamper. The
+version is single-sourced from ``sediment_api`` (the string ``/v1/me``
+and ``/health`` report)."""
+
+import re
+
+from sediment_api import __version__ as __version__
+
+# The release policy's two shapes, X.Y.Z and X.Y.ZrcN, in ASCII digits.
+_RELEASE_VERSION = re.compile(r"[0-9]+\.[0-9]+\.[0-9]+(?:rc[0-9]+)?")
+# A release candidate pins these at the same pre-release; uv admits a
+# pre-release only when a direct requirement names it.
+_FIRST_PARTY_DEPENDENCIES = (
+    "sediment-api",
+    "sediment-capture",
+    "sediment-core",
+    "sediment-derive",
+    "sediment-export",
+)
+
+
+def install_command(version: str) -> str:
+    """The installer's uv command pinned to *version*.
+
+    A pinned install replaces the tool in either direction. `uv tool upgrade`
+    keeps an earlier pin and otherwise moves only to the newest release.
+    """
+    command = f"uv tool install --python 3.12 --upgrade 'sediment-cli=={version}'"
+    if re.fullmatch(r"[0-9.]+rc[0-9]+", version):
+        command += "".join(
+            f" --with '{name}=={version}'" for name in _FIRST_PARTY_DEPENDENCIES
+        )
+    return command
+
+
+def version_skew_advice(server_version: object, client_version: str) -> str | None:
+    """How to match the server's version, or None when it matches or is absent.
+
+    The server controls *server_version*; only a release version reaches the
+    copyable command, so a server can't put shell syntax or terminal control
+    characters into it.
+    """
+    if server_version is None or server_version == client_version:
+        return None
+    if not isinstance(server_version, str) or not _RELEASE_VERSION.fullmatch(
+        server_version
+    ):
+        return (
+            f"server reported an unrecognized version; client is {client_version}. "
+            f"Install your deployment's release: {install_command('<version>')}"
+        )
+    return (
+        f"server version {server_version} differs from client {client_version}; "
+        f"install the server's version: {install_command(server_version)}"
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Refuse unsupported capture installation before importing POSIX operators."""
+    import os
+    import sys
+
+    args = sys.argv[1:] if argv is None else argv
+    if os.name == "nt" and args[:1] == ["install"]:
+        from .attribution import main as run
+    else:
+        from .cli import main as run
+    return run(args)

{sediment_cli-0.3.0 → sediment_cli-0.5.0}/sediment_cli/_pi/README.md

@@ -195,7 +195,7 @@ delivery changes also trigger this workflow. To exercise the same tests locally,
 set `SEDIMENT_PI_TEST_PYTHON` to the installed environment's Python executable
 and `SEDIMENT_PI_TEST_INSTALLED_BIN` to its `bin` directory before `npm test`.
 
-The lockfile pins pi 0.86.1 (`@earendil-works/pi-coding-agent`) as a development
+The lockfile pins pi 0.87.1 (`@earendil-works/pi-coding-agent`) as a development
 dependency. The native retrieval test exercises its extension registration,
 argument validation, agent loop, and model-visible tool result with a scripted
 model stream. It makes no paid inference request and downloads no package during

{sediment_cli-0.3.0 → sediment_cli-0.5.0}/sediment_cli/_pi/package.json

@@ -13,8 +13,8 @@
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "0.86.1",
-    "@types/node": "^24.13.6",
+    "@earendil-works/pi-coding-agent": "0.87.1",
+    "@types/node": "^24.19.0",
     "typescript": "^7.0.2"
   }
 }

sediment_cli-0.5.0/sediment_cli/agent_guide.txt

@@ -0,0 +1,142 @@
+# Help operators and developers use Sediment
+
+Use this guide when you help an operator run Sediment or help a developer
+capture work from repositories and coding agents. Both roles install the
+Sediment CLI. Developers connecting to a shared server use the installer's
+`--capture-only` option; they don't need to run a local server.
+
+`sediment guide` prints this bundled guide without reading configuration,
+contacting a server, or changing the machine. It converts procedure links to
+raw GitHub URLs pinned to the release it ships in, or to `main` from a source
+checkout. Reading those pages requires network access. `sediment --help` lists
+public commands; hooks invoke others.
+
+## Read the state before changing it
+
+- Run `sediment --version`. For a shared deployment, compare it with the
+  server's `/health` version. Use the guide from the version you operate.
+- Establish the task, server URL, deployment method, server account, and
+  repository. A developer's machine might only send capture to a remote server.
+- Use `/health` to check server readiness and `sediment doctor <repo>` to
+  inspect capture. Neither proves that the server received agent evidence.
+- Stay within the requested task. Don't start another server, reinstall hooks,
+  upgrade, rotate credentials, quarantine Facts, or remove data as a repair
+  unless that change is authorized. Follow the linked procedure for changes.
+
+## Help an operator
+
+Run server commands as the account that owns the deployment. For database
+commands, first set up the operator shell from the deployment procedure.
+An API login doesn't configure database access. Keep operator credentials on
+the operator machine; give developers capture credentials only.
+
+| Task | First command | Procedure |
+| --- | --- | --- |
+| Try a local server | `sediment server` | [Quickstart](../quickstart.md) |
+| Deploy on your own host | `sediment --version` | [Deploy Sediment on your own host](deploy.md) |
+| Deploy on Amazon Elastic Compute Cloud (EC2) | `sediment --version` | [Deploy Sediment on EC2](deploy-ec2.md) |
+| Enroll a team and connect repository webhooks | `sediment facts` | [Enroll your team](run-pilot.md) |
+| Check schema and Fact counts | `sediment db status` | [Monitor the deployment](maintain.md#monitor-the-deployment) |
+| Upgrade | `sediment --version` | [Upgrade Sediment](maintain.md#upgrade-sediment) |
+| Back up or restore | `sediment db status` | [Back up and restore](maintain.md#back-up-and-restore) |
+| Rotate credentials | `sediment --version` | [Rotate credentials](maintain.md#rotate-credentials) |
+| Build a Derivation bundle | `sediment derive --help` | [Run derivations](run-derivations.md) |
+| Export training data | `sediment export --help` | [Choose a training export](../exports/training-exports.md) |
+| Quarantine captured data | `sediment quarantine-log` | [Quarantine captured data](maintain.md#quarantine-captured-data) |
+| Tear down a deployment | `sediment --version` | [Tear down the deployment](maintain.md#tear-down-the-deployment) |
+
+`sediment server` runs in the foreground. Without an external PostgreSQL
+connection, it downloads PostgreSQL on first use and owns the local database.
+It stores data, credentials, and mirrors under `~/.sediment/server` or `--root`.
+Starting it provisions database roles and applies migrations. Preserve that
+directory across restarts and upgrades. Plan backups before migrations or
+teardown. Use the deployment's supervisor to manage a shared server.
+
+## Help a developer
+
+Use the server URL and capture credential that the operator supplies.
+Login saves credentials; installation changes Git hooks, agent configuration,
+and shell configuration. Run these steps when the developer requests capture.
+
+| Task | First command | Procedure |
+| --- | --- | --- |
+| Enroll with a shared server | `sediment login <url> --capture` | [Configure local capture](../capture/local-capture.md) |
+| Install repository and agent capture | `sediment install <repo>` | [Install capture](../capture/local-capture.md#install-capture) |
+| Select agent setup and verify delivery | `sediment doctor <repo>` | [Choose an agent integration](../capture/agent-integrations.md) |
+| Check buffered delivery | `sediment delivery status` | [Preserve prepared payloads through outages](../capture/local-capture.md#preserve-prepared-payloads-through-outages) |
+| Inspect evidence for a pushed commit | `sediment commit <full commit SHA>` | [Measure agent work](measure-agent-work.md) |
+| Remove capture | `sediment uninstall <repo>` | [Uninstall capture](../capture/local-capture.md#uninstall-capture) |
+
+Default `doctor` checks configuration and contacts the server and `origin`.
+It changes nothing unless you pass `--fetch`, which updates a notes tracking
+ref. Only `FAIL` lines make it exit 1. A sandbox network restriction or an
+unloaded capture environment can explain a failure. Use the agent procedure's
+Session checks to verify delivery. `commit` requires an operator credential;
+`no attributions` before the push and notes reach the server isn't a failure.
+
+## Preserve capture while doing repository work
+
+- Leave the marked `sediment-attribution` Git hook blocks, `notes.rewriteRef`,
+  and `refs/notes/sediment` in place. Don't bypass hooks or change
+  `core.hooksPath`. If hook files are tracked, leave Sediment's uncommitted
+  blocks for the developer; don't commit, stash, or revert them incidentally.
+- Keep the `sediment` executable at its installed path. Hooks use that absolute
+  path; source installs also depend on their checkout and virtual environment.
+- Preserve the `sediment env` blocks in shell profiles and Sediment's entries
+  in Claude Code settings, Codex hooks and profiles, Cursor hooks, and pi
+  settings. User-level agent hooks apply across repositories.
+- Read hook output. Sediment commands end in `|| true`; an appended block can
+  also mask a repository check that relies on its last command's exit status.
+  A zero status alone doesn't prove that the repository's checks passed.
+
+[What the installer changes](../capture/local-capture.md#what-the-installer-changes)
+describes the hooks. [Roll out managed capture](../capture/managed-capture.md)
+covers system settings, gateways, and fleet installation.
+
+## Remove capture within its installation scope
+
+- `uninstall <repo>` removes that repository's hook blocks and Sediment's
+  `notes.rewriteRef` value. Require `removed git hooks from` in its output;
+  a silent exit can mean that the path isn't a Git repository.
+- `uninstall <repo> --agents` also removes user-level agent hooks, including
+  pi, environment files, shell blocks, and verified Codex telemetry blocks.
+  These user-level removals affect capture across repositories. The command
+  doesn't remove Claude Code managed settings, fleet Git templates, or
+  externally distributed environment settings. Follow
+  [Remove managed capture](../capture/managed-capture.md#remove-managed-capture)
+  for those installations. Report skipped files; don't claim complete removal.
+- `logout` removes stored CLI credentials, but environment files retain their
+  ingest token and hooks keep running. It doesn't stop capture.
+- Neither uninstall form removes existing notes, remote notes, or
+  `~/.sediment/`. An `auto_install_remotes` allowlist can reinstall hooks at
+  the next Session. Remove that entry as part of an authorized teardown.
+  Restart running agents so they stop using the earlier environment.
+
+## Keep credentials and captured content private
+
+Don't print credentials, paste them into chat, or commit them. Credential
+locations include `~/.sediment/config.json`, `~/.sediment/env.sh`, the Fish
+`sediment.fish` file, Codex telemetry profiles, and server environment files.
+Custom server roots, shell profiles, and service settings can hold them too.
+Don't dump the process environment: it can contain `SEDIMENT_INGEST_TOKEN`,
+`OTEL_EXPORTER_OTLP_HEADERS`, database passwords, and gateway credentials.
+Follow [Secure a deployment](security.md) when handling secrets.
+
+Capture can leave the developer machine in these forms:
+
+- The pre-push hook sends the whole notes ref to each push remote, including
+  forks, even during `git push --dry-run`. Notes contain commit SHAs, agent
+  names, Session identifiers, and timestamps, including other branches' notes.
+  They don't contain prompts, diffs, file paths, model names, or hostnames.
+- Agent telemetry goes to the Sediment server. Claude Code tool details can
+  include paths, shell commands, edit text, and the Claude account email.
+  Codex decisions can include patch code and tool arguments; Sediment removes
+  the Codex account email and account identifier before storage. Cursor sends
+  accept decisions for applied writes and a configured user identifier.
+- Opt-in transcript capture sends edit text and edited-file contents. Claude
+  Code transcripts also include refused edit text and non-agent change counts.
+- If the operator routes model calls through a gateway, it captures full
+  prompts and responses.
+
+[Privacy boundaries and ceilings](../explanation/how-capture-works.md#privacy-boundaries-and-ceilings)
+describes these payloads and their limits.

{sediment_cli-0.3.0 → sediment_cli-0.5.0}/sediment_cli/attribution.py

@@ -55,8 +55,7 @@ Stdlib only, no daemon. Nine subcommands:
                      + ``notes.rewriteRef`` (local config) + the agent
                      telemetry env files generated from the ``sediment
                      login`` config (``--no-env`` skips; ``--user-id``
-                     stamps per-developer attribution; ``--gateway-url``/
-                     ``--gateway-key`` add the completions routing);
+                     stamps per-developer attribution);
                      ``--transcripts`` opts in to the SessionEnd transcript
                      extractor and its PreToolUse snapshot hook
                      (sediment_transcript.py — ships edit text pairs, a
@@ -106,9 +105,12 @@ try:
 except ImportError:  # pragma: no cover — run by path, not as a package
     # The checkout shim (scripts/sediment_attribution.py) and the fleet
     # bundle execute this file standalone, where no sibling ui module
-    # exists. Those are hook/MDM piped contexts: plain text is the correct
-    # output there, so a passthrough stand-in keeps the bytes identical.
+    # exists. Keep styling plain and match ui's server-text display filter.
     class ui:  # type: ignore[no-redef]  # ponytail: plain-text stand-in
+        @staticmethod
+        def printable_text(value: object) -> str:
+            return "".join(char for char in str(value) if char.isprintable())
+
         @staticmethod
         def style(text: str, *names: str, stream=None) -> str:
             return text
@@ -2852,8 +2854,6 @@ def _env_pairs(
     url: str,
     token: str,
     user_id: str | None,
-    gateway_url: str | None,
-    gateway_key: str | None,
 ) -> list[tuple[str, str]]:
     """The §5.1 block, generated. The exporter appends /v1/logs itself, so
     the endpoint is the bare server URL."""
@@ -2875,22 +2875,27 @@ def _env_pairs(
         _warn("capture helper unavailable; dedicated hook delivery is disabled")
     if user_id:
         pairs.append(("OTEL_RESOURCE_ATTRIBUTES", f"user.id={user_id}"))
-    if gateway_url:
-        pairs.append(("ANTHROPIC_BASE_URL", gateway_url))
-    if gateway_key:
-        pairs.append(("ANTHROPIC_AUTH_TOKEN", gateway_key))
-        pairs.append(("SEDIMENT_GATEWAY_KEY", gateway_key))
     return pairs
 
 
 def _write_0600(path: Path, content: str) -> None:
-    """0600 on create AND on rewrite — O_CREAT's mode applies only at
-    creation, and these files carry the bearer token."""
+    """Publish a complete private file without truncating the previous version."""
+    if path.is_symlink():
+        raise ValueError(
+            "refusing to replace a symbolic link with private configuration"
+        )
     path.parent.mkdir(parents=True, exist_ok=True)
-    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
-    os.fchmod(fd, 0o600)
-    with os.fdopen(fd, "w", encoding="utf-8") as fh:
-        fh.write(content)
+    temporary = path.with_name(f".{path.name}.{uuid4().hex}.tmp")
+    fd = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            os.fchmod(fh.fileno(), 0o600)
+            fh.write(content)
+            fh.flush()
+            os.fsync(fh.fileno())
+        os.replace(temporary, path)
+    finally:
+        temporary.unlink(missing_ok=True)
 
 
 def _write_env_files(pairs: list[tuple[str, str]]) -> None:
@@ -2956,19 +2961,14 @@ def _unwire_env() -> list[str]:
     return removed
 
 
-def cmd_install_env(
-    user_id: str | None,
-    gateway_url: str | None,
-    gateway_key: str | None,
-    transcripts: bool = False,
-) -> str:
+def cmd_install_env(user_id: str | None, transcripts: bool = False) -> str:
     """Wire the agent telemetry env from the login config; the install
     summary string says what happened."""
     cfg = _cli_config(capture=True)
     if cfg is None:
         return f"skipped (capture credential is absent; {_CAPTURE_LOGIN})"
     url, token = cfg
-    pairs = _env_pairs(url, token, user_id, gateway_url, gateway_key)
+    pairs = _env_pairs(url, token, user_id)
     try:
         previous = _sh_env_file().read_text(encoding="utf-8").splitlines()
     except FileNotFoundError:
@@ -3222,11 +3222,13 @@ def _uninstall_codex_profiles() -> bool:
     complete = True
     for path in profiles:
         try:
-            if path.is_symlink() or not path.is_file():
+            if not path.is_file():
                 raise ValueError
             original = path.read_text(encoding="utf-8")
             if _CODEX_OTEL_BEGIN not in original and _CODEX_OTEL_END not in original:
                 continue
+            if path.is_symlink():
+                raise ValueError
             remaining = _without_codex_telemetry(original)
             if remaining.strip():
                 _write_0600(path, remaining)
@@ -3436,21 +3438,17 @@ def _doctor_server(findings: list[Finding]) -> None:
             )
         )
         return
-    detail = f"reachable, {authority} token valid (org {body.get('org_id')})"
+    org_id = ui.printable_text(body.get("org_id"))
+    detail = f"reachable, {authority} token valid (org {org_id})"
     try:
-        from sediment_api import __version__ as client_version
+        from sediment_cli import __version__ as client_version
+        from sediment_cli import version_skew_advice
     except ImportError:  # standalone copied-file run — skew unknowable
-        client_version = None
-    server_version = body.get("version")
-    if server_version and client_version and server_version != client_version:
-        findings.append(
-            (
-                DOCTOR_INFO,
-                check,
-                f"{detail}; version skew: server {server_version}, client "
-                f"{client_version} — uv tool upgrade sediment-cli",
-            )
-        )
+        advice = None
+    else:
+        advice = version_skew_advice(body.get("version"), client_version)
+    if advice:
+        findings.append((DOCTOR_INFO, check, f"{detail}; {advice}"))
     else:
         findings.append((DOCTOR_OK, check, detail))
 
@@ -3461,8 +3459,6 @@ def cmd_install(
     transcripts: bool = False,
     env: bool = True,
     user_id: str | None = None,
-    gateway_url: str | None = None,
-    gateway_key: str | None = None,
     codex_profile: str | None = None,
 ) -> int:
     repo_path = Path(repo).resolve()
@@ -3511,7 +3507,7 @@ def cmd_install(
         # same flag pair: --no-agents implies no env wiring.
         if env:
             try:
-                detail = cmd_install_env(user_id, gateway_url, gateway_key, transcripts)
+                detail = cmd_install_env(user_id, transcripts)
             except ValueError as exc:
                 _error(str(exc))
                 return 1
@@ -3854,17 +3850,6 @@ def build_parser() -> argparse.ArgumentParser:
         metavar="NAME",
         help="write a Codex telemetry profile with resolved login credentials (0600); preserve its model and unrelated settings",
     )
-    p_install.add_argument(
-        "--gateway-url",
-        default=None,
-        help="also wire ANTHROPIC_BASE_URL to this LLM gateway",
-    )
-    p_install.add_argument(
-        "--gateway-key",
-        default=None,
-        help="also wire ANTHROPIC_AUTH_TOKEN and SEDIMENT_GATEWAY_KEY "
-        "(the key agents present to the gateway)",
-    )
     p_install.add_argument(
         "--fleet",
         action="store_true",
@@ -3954,15 +3939,13 @@ def main(argv: list[str] | None = None) -> int:
             or args.transcripts
             or args.no_env
             or args.user_id is not None
-            or args.gateway_url is not None
-            or args.gateway_key is not None
             or args.codex_profile is not None
         )
         if args.fleet:
             if per_user_flags:
                 _error(
                     "REPO, --no-agents, --transcripts, --codex-profile, and the env "
-                    "flags (--no-env/--user-id/--gateway-*) do not apply "
+                    "flags (--no-env/--user-id) do not apply "
                     "to --fleet"
                 )
                 return 2
@@ -3983,8 +3966,6 @@ def main(argv: list[str] | None = None) -> int:
             transcripts=args.transcripts,
             env=not args.no_env,
             user_id=args.user_id,
-            gateway_url=args.gateway_url,
-            gateway_key=args.gateway_key,
             codex_profile=args.codex_profile,
         )
     if args.command == "uninstall":