pi-config-sync 0.1.2 → 0.1.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +49 -4
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,7 +1,10 @@
|
|
|
1
1
|
# pi-config-sync
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/pi-config-sync)
|
|
4
|
+
[](https://github.com/diogovdias/pi-config-sync/actions/workflows/ci.yml)
|
|
5
|
+
|
|
6
|
+
Securely sync your `~/.pi/agent` configuration across machines through a git remote — automatically, with hard guards that keep secrets out.
|
|
7
|
+
It is a [pi package](https://pi.dev/packages) and keeps the repository **in place** (`~/.pi/agent` *is* the repo) so its history stays transparent.
|
|
5
8
|
|
|
6
9
|
## Install
|
|
7
10
|
|
|
@@ -21,6 +24,20 @@ Without `gh`, first create a private remote yourself, then run:
|
|
|
21
24
|
|
|
22
25
|
On each additional machine, run `/gitsync link` (with `gh`) or `/gitsync link <remote-url>`. It fetches the remote configuration. A differing local allowed file is moved to `<file>.local-backup`; it is never deleted, and linking refuses to touch a directory that already has its own git history. Run `/reload` afterwards; local-only allowed files are committed and pushed by the next sync.
|
|
23
26
|
|
|
27
|
+
That is the whole setup — from here on, syncing is automatic.
|
|
28
|
+
|
|
29
|
+
## How it works
|
|
30
|
+
|
|
31
|
+
```text
|
|
32
|
+
session start → auto-sync (rate-limited, default every 5 min across sessions)
|
|
33
|
+
ensure ignore rules → commit allowlisted changes → fetch
|
|
34
|
+
→ fast-forward or rebase → push
|
|
35
|
+
→ notifies you to /reload when remote changes were pulled
|
|
36
|
+
session shutdown → best-effort commit + push (next start reconciles the rest)
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Commits look like `pi config: auto-sync from <hostname>`. Concurrent pi sessions coordinate through a pid-liveness lock, subagent child processes never sync, and a diverged repo aborts the rebase and asks you to resolve manually — nothing is ever forced.
|
|
40
|
+
|
|
24
41
|
## Commands
|
|
25
42
|
|
|
26
43
|
| Command | Description |
|
|
@@ -34,9 +51,30 @@ On each additional machine, run `/gitsync link` (with `gh`) or `/gitsync link <r
|
|
|
34
51
|
|
|
35
52
|
## Security model
|
|
36
53
|
|
|
37
|
-
This package uses an **allowlist**, not a broad config-directory upload.
|
|
54
|
+
This package uses an **allowlist**, not a broad config-directory upload.
|
|
38
55
|
|
|
39
|
-
|
|
56
|
+
### What syncs
|
|
57
|
+
|
|
58
|
+
| Path | Contents |
|
|
59
|
+
| --- | --- |
|
|
60
|
+
| `settings.json` | Model defaults, theme, installed package list |
|
|
61
|
+
| `AGENTS.md` | Your global agent instructions |
|
|
62
|
+
| `extensions/`, `chains/`, `prompts/`, `themes/`, `skills/` | Your custom resources |
|
|
63
|
+
| `.gitignore`, `git-sync.jsonc` | The sync policy itself |
|
|
64
|
+
| `extraPaths` entries | Anything safe you add explicitly |
|
|
65
|
+
|
|
66
|
+
Nothing outside the allowlist ever syncs — new files are ignored by default.
|
|
67
|
+
|
|
68
|
+
### What never syncs
|
|
69
|
+
|
|
70
|
+
| Path / pattern | Why |
|
|
71
|
+
| --- | --- |
|
|
72
|
+
| `auth*` (`auth.json`) | API keys and OAuth tokens |
|
|
73
|
+
| `*token*`, `*secret*`, `*credential*`, `*.env*`, `*.local.json` | Anything named like a secret |
|
|
74
|
+
| `sessions/`, `state/`, `.git-sync/` | Local history and machine state |
|
|
75
|
+
| `npm/`, `git/`, `bin/`, `node_modules` | Installed packages — pi reinstalls them from `settings.json` |
|
|
76
|
+
|
|
77
|
+
The policy is enforced four ways — a managed allowlist `.gitignore`, `.git/info/exclude`, a post-stage hard guard that resets and aborts any commit staging a denied path, and a tracked-file scan warning — so it holds even against `git add -f`. It never force-pushes.
|
|
40
78
|
|
|
41
79
|
Git commands operate only on the agent directory's own repository — `GIT_CEILING_DIRECTORIES` stops git from ever discovering a parent repository (such as dotfiles in `$HOME`), and sync refuses to run until `~/.pi/agent/.git` itself exists. GitHub CLI calls are account-level (`gh api user`, `gh repo view/create`) and never modify repository contents. Use a private repository. When `gh` can identify a public GitHub remote, the package warns; it does not block because no credentials are synced.
|
|
42
80
|
|
|
@@ -71,6 +109,13 @@ If migrating from a hand-rolled `extensions/git-sync.ts`, delete that file first
|
|
|
71
109
|
|
|
72
110
|
Onboarding flow inspired by [opencode-synced](https://github.com/iHildy/opencode-synced).
|
|
73
111
|
|
|
112
|
+
## Alternatives
|
|
113
|
+
|
|
114
|
+
- [`pi-git-sync`](https://www.npmjs.com/package/pi-git-sync) — manual-first `/sync` with interactive conflict handling, including agent-assisted merges and force-push / hard-reset options.
|
|
115
|
+
- [`pi-sync-config`](https://www.npmjs.com/package/pi-sync-config) — background sync through a separate staging clone, with `settings.json` machine-key stripping, SSH-only remotes, and fast-forward-only pulls.
|
|
116
|
+
|
|
117
|
+
pi-config-sync differs from both: your agent directory itself is the repository (transparent history, no copy step), sync is fully automatic, onboarding can create the private repo through `gh`, and no destructive git operation exists in any code path. All three register different commands and can coexist.
|
|
118
|
+
|
|
74
119
|
## Releases
|
|
75
120
|
|
|
76
121
|
Tags matching `v*` publish automatically through the included GitHub Action using [npm trusted publishing](https://docs.npmjs.com/trusted-publishers) (OIDC) — no registry tokens exist anywhere in the pipeline. Every release carries a provenance attestation linking the tarball to its exact source commit, verifiable on the npm package page.
|