@brickhouse-tech/sync-agents 1.0.1 → 1.2.0

package/README.md

@@ -106,6 +106,16 @@ AGENTS.md is also symlinked to CLAUDE.md so that Claude reads the index natively
 | `sync` | Create symlinks from `.agents/` into all target directories, and symlink `AGENTS.md` to `CLAUDE.md` |
 | `watch` | Watch `.agents/` for changes and auto-regenerate `AGENTS.md` |
 | `import <url>` | Import a rule/skill/workflow from a URL |
+| `pull [--dry-run\|--offline\|--force\|--only NAME\|--global]` | Fetch every `sources.yaml` entry, verify integrity, install into the matching buckets |
+| `update [NAME]` | Re-resolve refs and re-pull entries whose upstream moved; SHA-pinned entries are skipped |
+| `source add <entry>` | Append an entry to `sources.yaml` and pull it |
+| `source remove <name> [--keep]` | Remove the manifest entry and delete the artifact (`--keep` converts it to manual) |
+| `source list [--json]` | Show each entry's local state: `ok` / `outdated` / `modified` / `missing` |
+| `source bundle` | Rebuild `sources.yaml` from installed artifacts' origin metadata |
+| `source detach <name>` | Un-manage an artifact: flip its origin to manual and drop the manifest entry |
+| `quarantine` | List remotely-fetched artifacts awaiting review, with their scan findings |
+| `approve <name>\|--all [--force]` | Promote a quarantined artifact into `.agents/` (`--force` accepts critical findings, recorded in the lock) |
+| `reject <name>\|--all` | Delete a quarantined artifact without installing it |
 | `git-hook` | Install a pre-commit git hook for auto-sync (`hook` remains as a deprecated alias) |
 | `inherit <label> <path>` | Add an inheritance link to AGENTS.md |
 | `inherit --list` | List current inheritance links |
@@ -136,6 +146,7 @@ AGENTS.md is also symlinked to CLAUDE.md so that Claude reads the index natively
 | `--no-clobber` | (fix only) Skip items that already exist in `.agents/` instead of merging |
 | `--fix` | (lint only) Amend fixable frontmatter findings in place |
 | `--no-fix` | (index only) Skip the skill frontmatter backfill |
+| `--trust` | (pull/update only) Bypass the quarantine gate; the scan still runs and prints findings |
 
 ## Configuration
 
@@ -193,6 +204,42 @@ sync-agents lint
 sync-agents lint --fix
 ```
 
+## Source manifest (pull, lockfile & provenance)
+
+Declare upstream rules, skills, workflows — or whole `.agents/` trees — in `.agents/sources.yaml` and install them reproducibly:
+
+```yaml
+version: 1
+sources:
+  - skill:anthropic/skill-pack@v1.2.0/skills/code-review
+  - rule:my-org/agent-norms@main/rules/security.md
+  - tree:my-org/team-agents@v2.0.0   # fans out to every bucket in the upstream .agents/
+```
+
+`sync-agents pull` resolves each ref to a commit SHA via the GitHub API, fetches the repo tarball (cached by SHA under `$XDG_CACHE_HOME/sync-agents/`, no `git` binary needed), verifies a deterministic sha256 content hash against `.agents/sources.lock`, and only then installs — a tampered tarball or corrupted cache aborts before anything is written. Every installed artifact carries provenance (`_origin.json` inside skill dirs, `<name>.origin.json` beside flat files) recording owner/repo/ref/SHA/hash; commit these so clones keep their provenance.
+
+Safety rules: locally-edited artifacts are never overwritten without `--force`; a destination without origin metadata is treated as a manual conflict. Private repos use your token (`SYNC_AGENTS_GITHUB_TOKEN` > `GITHUB_TOKEN` > `GH_TOKEN` > `gh auth token`). All commands accept `--global` to operate on `~/.agents/` instead of the project.
+
+```bash
+sync-agents source add skill:anthropic/skill-pack@v1.2.0/skills/code-review
+sync-agents source list          # ok / outdated / modified / missing per entry
+sync-agents update               # bump tag-tracked entries when upstream moves
+sync-agents pull --offline       # cache-only, for CI or airplanes
+```
+
+## Quarantine (remote content review)
+
+Remote installs are treated like a hostile supply chain. By default, everything `pull`/`update` fetches lands in `.agents/.quarantine/` — invisible to `sync` and the index — after a static scan for network-then-execute patterns (`curl | bash`), credential access combined with network calls, obfuscation (long base64, zero-width Unicode), and prompt-injection phrasing aimed at your agent.
+
+```bash
+sync-agents pull                  # → 1 quarantined (run `sync-agents quarantine`)
+sync-agents quarantine            # review findings per artifact
+sync-agents approve code-review   # promote into .agents/ (blocked on CRITICAL unless --force)
+sync-agents reject sketchy-rule   # delete without installing
+```
+
+Critical findings block `approve`; overriding with `--force` is recorded in `sources.lock` as `approved_with_findings` so the decision is auditable. `--trust` on `pull`/`update` skips the gate for one invocation (findings still print), and `quarantine = off` in `.agents/config` disables it for teams that review via pinned SHAs in PRs instead.
+
 ## ADRs (Architecture Decision Records)
 
 ADRs live in `.agents/adrs/` with **status encoded by subdirectory**: `proposed/`, `accepted/`, `denied/`. `add adr <name>` scaffolds into `proposed/`; `sync-agents adr accept|deny|propose <name>` moves a record between statuses (nested grouping subdirs are preserved) and regenerates the index.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brickhouse-tech/sync-agents",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "Simple scripts to DRY up common agent interactions across multiple LLM providers.",
   "keywords": [
     "agents",
@@ -26,11 +26,11 @@
     "bin/sync-agents.js"
   ],
   "optionalDependencies": {
-    "@brickhouse-tech/sync-agents-darwin-arm64": "1.0.1",
-    "@brickhouse-tech/sync-agents-darwin-x64": "1.0.1",
-    "@brickhouse-tech/sync-agents-linux-arm64": "1.0.1",
-    "@brickhouse-tech/sync-agents-linux-x64": "1.0.1",
-    "@brickhouse-tech/sync-agents-win32-x64": "1.0.1"
+    "@brickhouse-tech/sync-agents-darwin-arm64": "1.2.0",
+    "@brickhouse-tech/sync-agents-darwin-x64": "1.2.0",
+    "@brickhouse-tech/sync-agents-linux-arm64": "1.2.0",
+    "@brickhouse-tech/sync-agents-linux-x64": "1.2.0",
+    "@brickhouse-tech/sync-agents-win32-x64": "1.2.0"
   },
   "overrides": {
     "file-type": ">=22",