pi-sync-cli 0.4.0__tar.gz → 0.5.1__tar.gz

pi_sync_cli-0.5.1/AGENTS.md

@@ -0,0 +1,125 @@
+# AGENTS.md
+
+Working notes for AI agents (and humans) changing this repo. User-facing
+documentation lives in [README.md](README.md); layout, tooling and the release
+process live in [DEVELOPMENT.md](DEVELOPMENT.md).
+
+## What this is
+
+pi-sync: a single click module that rsyncs pi agent config between hosts.
+`src/pi_sync/cli.py` is the whole program and `tests/test_cli.py` the whole
+suite, so a change is one file plus its tests.
+
+## Commands
+
+```bash
+uv sync                 # create/refresh .venv and uv.lock
+uv run pytest           # the suite (fast, offline)
+uv run pi-sync --help
+```
+
+## Invariants — please don't "fix" these
+
+- **Entry point is `pi_sync.cli:app`**, a click group with a default-command
+  fallback: `DefaultGroup.parse_args` prepends `sync` when the first token is not
+  a subcommand, and `SyncCommand.format_usage` keeps help reading
+  `pi-sync [OPTIONS] ...`. The sync function stays named `main` because the tests
+  invoke `cli.main` directly.
+- **No `__version__`.** The version comes from distribution metadata; adding one
+  back reintroduces the drift that removal fixed.
+- **Tests never spawn anything.** `FakeRun` records argv and replays output;
+  extend it instead of calling `subprocess`. That guarantee is deliberate.
+- **Host probes are POSIX sh piped to `ssh host sh -s`**, because some hosts run
+  fish and `for …; do … done` is a syntax error there.
+- **Never trust pi's installer exit status.** Its "do nothing" menu choice exits
+  0, so `install_pi` re-probes the host. Keep new install/uninstall paths
+  verification-based.
+- **`update` resolves the distribution from its own environment**; do not
+  hardcode `pi-sync-cli`, since an older install can coexist under `pi-sync` and
+  a hardcoded name would upgrade the wrong virtualenv.
+- **`--dry-run` must not mutate anything**, including installing or uninstalling
+  pi on a host.
+
+## Conventions
+
+- Commit messages: all lowercase, conventional prefix (`fix:`, `feat:`, `chore:`,
+  `ci:`, `docs:`).
+- Run `uv run pytest` and `lens_diagnostics mode=all` before declaring work done;
+  fix blockers rather than reporting around them.
+- pi-lens reformats files on write and sometimes *after* a commit. Check
+  `git status` before finishing and commit formatter churn separately.
+- `.pi/tasks/` is gitignored local task output — never commit it.
+- Never commit secrets. `auth.json` is host-local and only travels with an
+  explicit `--auth`.
+
+## Working against real hosts
+
+- This Mac drives everything; `tinfoil` and the Raspberry Pi (`pi`) are real
+  hosts and can be offline.
+- Prefer `--dry-run` when demonstrating. A real push overwrites host config — a
+  `.backup` is kept, but don't be cavalier about it.
+- `~/.ssh/config` is protected: read it through code that extracts host aliases,
+  and don't dump its contents into output or a commit.
+
+Kept out of the README: these describe *using* pi-sync rather than changing
+it, and are collected here so the README stays a short front page.
+
+## Hosts without pi
+
+Each host is checked before syncing. If pi is missing, pi-sync offers to install
+it — interactively, pi's installer takes over your terminal, and the sync
+continues when it exits. `--install` does that unattended.
+
+A host that still has no pi afterwards is skipped, and the run exits non-zero.
+
+## Updating
+
+- `pi-sync update` upgrades pi-sync itself, through whichever installer owns it
+  (`--check` reports without changing anything).
+- `pi-sync --update-pi <hosts>` updates pi on the hosts before syncing.
+
+## Uninstalling pi from a host
+
+`pi-sync --uninstall <hosts>` removes pi and leaves your config in place. If it
+fails, run `curl -fsSL https://pi.dev/install.sh | sh` on the host and choose
+`u` instead.
+
+## Shell completions
+
+Host arguments complete from `~/.ssh/config`. zsh and fish also show where each
+alias points:
+
+```console
+$ pi-sync t<TAB>
+tinfoil          tinfoil@tinfoil.sayan.page
+tinfoil-proxy    notdebian@100.98.241.11
+```
+
+```bash
+# bash
+_PI_SYNC_COMPLETE=bash_source pi-sync > ~/.pi-sync-complete.bash
+echo 'source ~/.pi-sync-complete.bash' >> ~/.bashrc
+
+# zsh
+_PI_SYNC_COMPLETE=zsh_source pi-sync > ~/.pi-sync-complete.zsh
+echo 'source ~/.pi-sync-complete.zsh' >> ~/.zshrc
+
+# fish (config.fish)
+_PI_SYNC_COMPLETE=fish_source pi-sync | source
+```
+
+PowerShell uses `powershell_source` the same way.
+
+## Caveats
+
+- `settings.json` is written by pi itself (`lastChangelogVersion` bumps, UI
+  toggles), so pushing it overwrites the host's local preferences — the previous
+  copy is kept as `settings.json.backup`. Sync it when you change `packages`.
+- Extensions that keep runtime files in their own directory (logs, checkpoints)
+  get those files synced too, and whichever side pushes last wins. Exclude them
+  with `-x '*/logs/*'`.
+- Extension versions are whatever each host has installed; pin them in
+  `settings.json` (`npm:pi-lens@1.2.3`) if you need hosts identical.
+- `--auth` copies API keys in the clear. Prefer `OPENCODE_API_KEY` (and friends)
+  in the environment where you can.
+- `--delete` disables backups for the mirrored directory.

pi_sync_cli-0.5.1/DEVELOPMENT.md

@@ -0,0 +1,166 @@
+# Developing pi-sync
+
+## Layout
+
+```text
+src/pi_sync/cli.py    the whole CLI: probing, rsync, completions, self-update
+tests/test_cli.py     unit tests (no ssh or rsync process is ever executed)
+pyproject.toml        click dependency, console script, uv dev group
+pyrightconfig.json    points pyright at .venv (see "Tooling" below)
+```
+
+Three design anchors worth understanding before editing:
+
+- **The console script points at `pi_sync.cli:app`**, a click *group*.
+  `DefaultGroup.parse_args` prepends `sync` when the first argument is not a
+  subcommand, which is what lets `pi-sync tinfoil`, `pi-sync --config tinfoil`
+  and `pi-sync update` all work. `SyncCommand.format_usage` exists so help reads
+  `pi-sync [OPTIONS] [USER@]HOST...` instead of `pi-sync sync [OPTIONS] ...`.
+  `main` is the sync subcommand and keeps that name because the tests drive it
+  directly.
+- **The version comes from distribution metadata** (`@click.version_option`), so
+  there is no `__version__` to fall out of step with the release.
+- **`update` resolves the distribution from its own environment**
+  (`importlib.metadata.packages_distributions()`) rather than hardcoding a name.
+  An older install can coexist under the pre-rename name `pi-sync`, and a
+  hardcoded name would upgrade the wrong virtualenv — or nothing.
+
+## How it works
+
+**One probe per host.** `probe_host` pipes a POSIX sh script through
+`ssh host sh -s`, so reachability and pi's location cost a single round trip. It
+checks `command -v pi` and then the usual install locations (`~/.local/bin`,
+`~/.pi/bin`, `~/.pi/agent/bin`, linuxbrew, homebrew, `/usr/local/bin`) because a
+non-interactive ssh session does not source the host's shell init — on a
+linuxbrew host `command -v pi` alone finds nothing.
+
+**Installing pi.** Interactively the terminal is handed to pi's own installer and
+the sync resumes when it exits. Unattended (`--install` with no tty) the output is
+captured and stdin is closed, so a prompt fails fast instead of hanging. The
+installer's exit status is not trusted — its "do nothing" menu choice exits 0 —
+so `install_pi` re-probes and reports honestly. A host that still lacks pi is
+skipped, which makes the run exit non-zero. After a successful install,
+`mkdir -p` creates the agent directory, because rsync will not create
+intermediate directories itself.
+
+**Uninstalling.** The official installer can only uninstall through its
+interactive menu (its unattended mode always installs or reinstalls), so pi-sync
+issues the npm command that menu would have: `npm uninstall -g --prefix <prefix>
+@earendil-works/pi-coding-agent`, with the prefix derived from where pi actually
+lives. It re-probes afterwards, since npm can exit 0 having removed nothing. Only
+the CLI goes; the agent directory is never touched.
+
+**Self-update.** `update` classifies the running environment and delegates:
+
+| Detected | Action |
+| --- | --- |
+| pipx | `pipx upgrade <dist>` |
+| uv tool | `uv tool upgrade <dist>` |
+| editable checkout | prints `git -C <path> pull` |
+| uvx ephemeral | nothing to do; suggests a durable install |
+| otherwise | `python -m pip install --upgrade <dist>` |
+
+It resolves the distribution from its own environment instead of hardcoding a
+name, and refuses to downgrade when the local version is ahead of PyPI.
+
+**Completions.** Read from `~/.ssh/config` at completion time, following
+`Include` and skipping wildcard entries; `CompletionItem.help` carries
+`user@hostname` for the shells that render it (bash cannot).
+
+**rsync invocation.** `-az -i`, plus `--backup --suffix=.backup` and
+`--exclude=*.backup` so replaced files are kept but backups never travel, and
+`--delete-during` only for `extensions/` when `--delete` is given — which also
+suppresses backups for that directory.
+
+## Commands
+
+```bash
+uv sync                 # create/refresh .venv and uv.lock
+uv run pytest           # the suite
+uv run pi-sync --help
+uv build                # wheel + sdist into dist/
+```
+
+## Tests
+
+`FakeRun` records every command and replays canned output, so the suite needs no
+network, no hosts, and no real transfers. When you add a command, extend
+`FakeRun` rather than reaching for `subprocess` — the guarantee that nothing is
+executed is what keeps the suite fast and safe.
+
+The one path that cannot be unit-tested is the interactive installer handover,
+because it depends on a real terminal. It was verified out-of-band with a PTY
+harness that attaches a pseudo-terminal, feeds a keystroke, and asserts the
+installer's `/dev/tty` menu reached the terminal and that the keypress reached
+the remote host.
+
+## Tooling
+
+`pi-lens` runs ruff format/lint as files are written, and sometimes reformats
+*after* a commit — check `git status` before finishing, and commit formatter
+churn on its own.
+
+`pyrightconfig.json` sets `venvPath`/`venv` because pyright does not pick up a
+uv-created venv on its own here. Measured: without it, `Import "pytest" could
+not be resolved`; with it, zero errors. A long-lived pyright language server
+that started before the venv existed will keep reporting the stale result until
+it is restarted.
+
+## Releasing
+
+```bash
+uv version --bump minor            # or patch; also updates uv.lock
+git commit -am "chore: release X.Y.Z"
+git push origin main
+git tag -a vX.Y.Z -m vX.Y.Z
+git push origin vX.Y.Z             # publishing happens on the tag
+```
+
+`.github/workflows/publish.yml` then builds, smoke-tests both artifacts *through
+the console script*, and publishes with OIDC trusted publishing — no token is
+stored anywhere. It refuses to publish when the tag does not match the version in
+`pyproject.toml`.
+
+Verify a release:
+
+```bash
+gh run view <run-id> --log | grep "Uploading pi_"
+curl -s https://pypi.org/pypi/pi-sync-cli/X.Y.Z/json   # per-version: immediate
+```
+
+Expect **CDN lag** on the aggregate endpoints. Measured on 0.4.0: the
+per-version endpoint answered immediately, `/pypi/pi-sync-cli/json` took ~45s,
+and the simple index took ~40s. Until the simple index flips,
+`uvx --from pi-sync-cli==X.Y.Z` fails with "no version … requirements are
+unsatisfiable", which looks like a broken release but is not. Re-tagging never
+helps (PyPI rejects duplicate versions); `workflow_dispatch` re-runs the job
+without a new tag.
+
+## PyPI notes
+
+The distribution is `pi-sync-cli`; the command is `pi-sync`. Plain `pi-sync` is
+permanently unavailable: PyPI compares names with punctuation stripped, and
+`pisync` already exists (an unrelated rsync backup script).
+
+Trusted publisher fields: project `pi-sync-cli`, owner `say4n`, repository
+`pi-sync`, workflow `publish.yml`, environment `pypi`. A pending publisher
+reserves nothing until first use — it is invalidated if someone else registers
+the name in the meantime.
+
+## Platform gotchas found the hard way
+
+- macOS ships **openrsync**, which rejects rsync 3 flags. Only flags verified
+  against it are used; `--ignore-missing-args`, `--human-readable` and
+  `--mkpath` are not available.
+- `--backup` with `--delete` fails on openrsync acting as *receiver*
+  (`fchownat: Operation not permitted`, exit 23) but works fine with rsync 3.x,
+  so backups are suppressed whenever `--delete` is in play.
+- rsync's default check compares size and mtime at 1-second granularity: two
+  files created in the same second with equal sizes look "already in sync". Use
+  distinct mtimes when testing backups, or the test proves nothing.
+- Remote shells are **fish** on some hosts, so probes are POSIX sh piped over
+  stdin (`ssh host sh -s`), never a shell loop in the command string
+  (`for …; do … done` is a syntax error there).
+- pi's installer reads `/dev/tty`, not stdin, so capturing its output makes its
+  prompts invisible while it waits for a keypress. Interactive installs must
+  stream; unattended ones must close stdin so a prompt fails fast.

pi_sync_cli-0.5.1/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.5
+Name: pi-sync-cli
+Version: 0.5.1
+Summary: Sync pi agent config and extensions between hosts over rsync
+Project-URL: Repository, https://github.com/say4n/pi-sync
+Project-URL: Issues, https://github.com/say4n/pi-sync/issues
+Author: Sayan Goswami
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-config,dotfiles,pi,rsync,sync
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Archiving :: Mirroring
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Description-Content-Type: text/markdown
+
+# pi-sync
+
+pi-sync keeps your pi agent config the same across hosts. It copies the
+declarative parts of `~/.pi/agent` to another machine over rsync, and it reads
+your ssh config, so the aliases in `~/.ssh/config` work as host names.
+
+```bash
+pi-sync tinfoil                  # copy config and extensions to tinfoil
+pi-sync --config laptop          # copy only models.json and settings.json
+pi-sync --pull --all tinfoil     # copy tinfoil's config back to this machine
+pi-sync --dry-run --all a b      # report what would change, without copying
+pi-sync update                   # update pi-sync itself
+```
+
+## install
+
+```bash
+pipx install pi-sync-cli
+```
+
+The PyPI package is `pi-sync-cli`, and it installs the `pi-sync` command.
+`uv tool install pi-sync-cli` works the same way.
+
+To install from source, run:
+
+```bash
+pipx install git+ssh://git@github.com/say4n/pi-sync
+```
+
+pi-sync requires Python 3.10 or later.
+
+## what syncs
+
+pi-sync copies the declarative parts of the agent directory, and nothing else.
+
+| group | what it copies |
+| --- | --- |
+| `--config` | `models.json` and `settings.json` |
+| `--extensions` | the `extensions/` directory |
+| `--auth` | `auth.json`, which holds API keys. This group is opt-in, and pi-sync warns you before it copies secrets. |
+
+`--all` copies `--config` and `--extensions`. It is the default when you pass no
+group flag.
+
+pi-sync leaves host-local state alone: `sessions/`, `npm/`, `models-store.json`,
+`ayu/`, `bin/`, and `trust.json` stay where they are.
+
+## flags
+
+| flag | effect |
+| --- | --- |
+| `--all`, `--config`, `--extensions`, `--auth` | set what pi-sync copies |
+| `--pull` | copy from the host to this machine instead of the other way |
+| `--delete` | make `extensions/` match the source exactly, including deletions |
+| `--dry-run` | report changes without copying anything |
+| `-x, --exclude PATTERN` | skip files that match the pattern. Repeat the flag to add more patterns. |
+| `--install` | install pi on hosts that do not have it, without prompting |
+| `--uninstall` | remove pi from the host instead of copying config. Your config stays. |
+| `--update-pi` | update pi on each host before copying config |
+| `--local-dir` | set the local agent directory. The default is `$PI_CODING_AGENT_DIR`, or `~/.pi/agent`. |
+| `--remote-dir` | set the agent directory on the host. The default is `~/.pi/agent`. |
+| `-v, --verbose` | print each rsync command and its output |
+
+To copy to more than one host, pass more than one name: `pi-sync a b c`. The
+command exits with a non-zero status when it cannot copy to a host. Each file
+pi-sync overwrites on the destination is kept beside the new one as
+`<name>.backup`.
+
+## developing
+
+For the layout, the tests, and the release process, see
+[DEVELOPMENT.md](DEVELOPMENT.md).

pi_sync_cli-0.5.1/README.md

@@ -0,0 +1,72 @@
+# pi-sync
+
+pi-sync keeps your pi agent config the same across hosts. It copies the
+declarative parts of `~/.pi/agent` to another machine over rsync, and it reads
+your ssh config, so the aliases in `~/.ssh/config` work as host names.
+
+```bash
+pi-sync tinfoil                  # copy config and extensions to tinfoil
+pi-sync --config laptop          # copy only models.json and settings.json
+pi-sync --pull --all tinfoil     # copy tinfoil's config back to this machine
+pi-sync --dry-run --all a b      # report what would change, without copying
+pi-sync update                   # update pi-sync itself
+```
+
+## install
+
+```bash
+pipx install pi-sync-cli
+```
+
+The PyPI package is `pi-sync-cli`, and it installs the `pi-sync` command.
+`uv tool install pi-sync-cli` works the same way.
+
+To install from source, run:
+
+```bash
+pipx install git+ssh://git@github.com/say4n/pi-sync
+```
+
+pi-sync requires Python 3.10 or later.
+
+## what syncs
+
+pi-sync copies the declarative parts of the agent directory, and nothing else.
+
+| group | what it copies |
+| --- | --- |
+| `--config` | `models.json` and `settings.json` |
+| `--extensions` | the `extensions/` directory |
+| `--auth` | `auth.json`, which holds API keys. This group is opt-in, and pi-sync warns you before it copies secrets. |
+
+`--all` copies `--config` and `--extensions`. It is the default when you pass no
+group flag.
+
+pi-sync leaves host-local state alone: `sessions/`, `npm/`, `models-store.json`,
+`ayu/`, `bin/`, and `trust.json` stay where they are.
+
+## flags
+
+| flag | effect |
+| --- | --- |
+| `--all`, `--config`, `--extensions`, `--auth` | set what pi-sync copies |
+| `--pull` | copy from the host to this machine instead of the other way |
+| `--delete` | make `extensions/` match the source exactly, including deletions |
+| `--dry-run` | report changes without copying anything |
+| `-x, --exclude PATTERN` | skip files that match the pattern. Repeat the flag to add more patterns. |
+| `--install` | install pi on hosts that do not have it, without prompting |
+| `--uninstall` | remove pi from the host instead of copying config. Your config stays. |
+| `--update-pi` | update pi on each host before copying config |
+| `--local-dir` | set the local agent directory. The default is `$PI_CODING_AGENT_DIR`, or `~/.pi/agent`. |
+| `--remote-dir` | set the agent directory on the host. The default is `~/.pi/agent`. |
+| `-v, --verbose` | print each rsync command and its output |
+
+To copy to more than one host, pass more than one name: `pi-sync a b c`. The
+command exits with a non-zero status when it cannot copy to a host. Each file
+pi-sync overwrites on the destination is kept beside the new one as
+`<name>.backup`.
+
+## developing
+
+For the layout, the tests, and the release process, see
+[DEVELOPMENT.md](DEVELOPMENT.md).

{pi_sync_cli-0.4.0 → pi_sync_cli-0.5.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pi-sync-cli"
-version = "0.4.0"
+version = "0.5.1"
 description = "Sync pi agent config and extensions between hosts over rsync"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -20,7 +20,7 @@ Repository = "https://github.com/say4n/pi-sync"
 Issues = "https://github.com/say4n/pi-sync/issues"
 
 [project.scripts]
-pi-sync = "pi_sync.cli:main"
+pi-sync = "pi_sync.cli:app"
 
 [dependency-groups]
 dev = ["pytest>=8"]

pi_sync_cli-0.5.1/src/pi_sync/__init__.py

@@ -0,0 +1,5 @@
+"""Sync pi agent config between hosts over rsync.
+
+The version lives in the distribution metadata (see `pi-sync --version`), so
+there is deliberately no `__version__` here to fall out of step with it.
+"""