@brickhouse-tech/sync-agents - npm Package Compare versions

Comparing version 1.3.2 to 1.4.0

package.json

 {
   "name": "@brickhouse-tech/sync-agents",
-  "version": "1.3.2",
+  "version": "1.4.0",
   "description": "Simple scripts to DRY up common agent interactions across multiple LLM providers.",
@@ -29,7 +29,7 @@ "keywords": [
   "optionalDependencies": {
-    "@brickhouse-tech/sync-agents-darwin-arm64": "1.3.2",
-    "@brickhouse-tech/sync-agents-darwin-x64": "1.3.2",
-    "@brickhouse-tech/sync-agents-linux-arm64": "1.3.2",
-    "@brickhouse-tech/sync-agents-linux-x64": "1.3.2",
-    "@brickhouse-tech/sync-agents-win32-x64": "1.3.2"
+    "@brickhouse-tech/sync-agents-darwin-arm64": "1.4.0",
+    "@brickhouse-tech/sync-agents-darwin-x64": "1.4.0",
+    "@brickhouse-tech/sync-agents-linux-arm64": "1.4.0",
+    "@brickhouse-tech/sync-agents-linux-x64": "1.4.0",
+    "@brickhouse-tech/sync-agents-win32-x64": "1.4.0"
   },
@@ -36,0 +36,0 @@ "overrides": {

README.md

@@ -112,6 +112,7 @@ # sync-agents
 | `source add <entry>` | Append an entry to `sources.yaml` and pull it |
+| `source add --link[=<path>] [<entry>]` | Declare a **linked (editable)** source — symlink a live local checkout instead of a fetched snapshot (SPEC-007) |
 | `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 list [--json]` | Show each entry's local state: `ok` / `outdated` / `modified` / `missing` / `linked` |
 | `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 |
+| `source detach <name>` | Un-manage an artifact: flip its origin to manual and drop the manifest entry (for a **linked** source, freeze the live copy into a vendored snapshot) |
 | `quarantine` | List remotely-fetched artifacts awaiting review, with their scan findings |
@@ -244,2 +245,28 @@ | `approve <name>\|--all [--force]` | Promote a quarantined artifact into `.agents/` (`--force` accepts critical findings, recorded in the lock) |
 
+## Linked (editable) sources
+
+When you're **actively developing** a skill that lives in another repo (or the upstream repo itself), a SHA-pinned snapshot forces a slow `edit → commit → push → update` loop. A **linked** source is the `npm link` / `go mod replace` for `.agents/` — it symlinks the artifact at a live local checkout, so edits flow both ways and `git pull` in the checkout reaps updates with no re-fetch (SPEC-007).
+
+```bash
+# Link a checkout you already have (path relative to cwd or absolute):
+sync-agents source add --link=../foo-skill skill:me/foo-skill
+
+# Derive the entry from the checkout's github remote + layout:
+sync-agents source add --link=../foo-skill
+
+# Managed clone: sync-agents clones the repo under .agents/.sources/ and links out of it
+# (the initial clone is scanned once through the quarantine scanner; --trust to skip):
+sync-agents source add --link skill:me/foo-skill
+```
+
+The link is recorded declaratively as a `link:` override in `sources.yaml` and echoed in `sources.lock`, so the intent is committed and reviewable:
+
+```yaml
+overrides:
+  - match: skill:me/foo-skill
+    link: file:../foo-skill      # relative to .agents/; mutually exclusive with pin_sha
+```
+
+All persisted paths are **relative** (`file:` scheme) and the on-disk symlink is created relative too — an absolute path would break the instant another machine cloned the repo, so absolute `file:` paths are rejected at parse time. `pull` verifies (and self-heals) the symlink and never re-fetches a snapshot over it; a missing checkout surfaces as a warning, not a silent revert. `update` advances a **managed clone** with `git pull --ff-only` (a checkout you own is yours to drive). `source list` shows linked entries as `[linked] … link → file:../foo-skill`, and `source detach` **freezes** the live copy into an ordinary vendored snapshot (materialize the files, drop the `link` override, keep the upstream identity). Because a linked source is a local working tree you own, it is trusted by default — only the first fetch of a managed clone is scanned.
+
 ## ADRs (Architecture Decision Records)
@@ -246,0 +273,0 @@

No alert changes

Improved metrics

Total package byte prevSize

26481

9.6%

Number of lines in readme file

480

5.96%

No dependency changes