peaks-loop-mut 0.1.30 → 0.1.31

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/dist/index.d.ts CHANGED
@@ -11,5 +11,5 @@
11
11
  * import { cleanupStaleCache } from 'peaks-loop-mut/services/agent/ecc-cache-service';
12
12
  */
13
13
  export * from './services/mut/index.js';
14
- export { setCacheDirPermissions, downloadToCache, readCacheManifest, listCachedAgents, readAgentSkill, cleanupStaleCache, ECC_REPO_OWNER, ECC_REPO_NAME, type CacheManifest, type DownloadResult, } from './services/agent/ecc-cache-service.js';
14
+ export { setCacheDirPermissions, downloadToCache, readCacheManifest, listCachedAgents, readAgentSkill, cleanupStaleCache, resolveEccMaterializedDir, resolveEccMaterializedManifestPath, materializeEccAgents, readEccMaterializeManifest, listMaterializedAgents, hasMaterializedEccAgents, resolveMaterializedAgentName, readMaterializedAgent, ECC_REPO_OWNER, ECC_REPO_NAME, type CacheManifest, type DownloadResult, type EccMaterializeManifest, } from './services/agent/ecc-cache-service.js';
15
15
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,cAAc,yBAAyB,CAAC;AAExC,OAAO,EACL,sBAAsB,EACtB,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,EACd,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,KAAK,aAAa,EAClB,KAAK,cAAc,GACpB,MAAM,uCAAuC,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,cAAc,yBAAyB,CAAC;AAExC,OAAO,EACL,sBAAsB,EACtB,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,EACd,iBAAiB,EACjB,yBAAyB,EACzB,kCAAkC,EAClC,oBAAoB,EACpB,0BAA0B,EAC1B,sBAAsB,EACtB,wBAAwB,EACxB,4BAA4B,EAC5B,qBAAqB,EACrB,cAAc,EACd,aAAa,EACb,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,sBAAsB,GAC5B,MAAM,uCAAuC,CAAC"}
package/dist/index.js CHANGED
@@ -11,4 +11,4 @@
11
11
  * import { cleanupStaleCache } from 'peaks-loop-mut/services/agent/ecc-cache-service';
12
12
  */
13
13
  export * from './services/mut/index.js';
14
- export { setCacheDirPermissions, downloadToCache, readCacheManifest, listCachedAgents, readAgentSkill, cleanupStaleCache, ECC_REPO_OWNER, ECC_REPO_NAME, } from './services/agent/ecc-cache-service.js';
14
+ export { setCacheDirPermissions, downloadToCache, readCacheManifest, listCachedAgents, readAgentSkill, cleanupStaleCache, resolveEccMaterializedDir, resolveEccMaterializedManifestPath, materializeEccAgents, readEccMaterializeManifest, listMaterializedAgents, hasMaterializedEccAgents, resolveMaterializedAgentName, readMaterializedAgent, ECC_REPO_OWNER, ECC_REPO_NAME, } from './services/agent/ecc-cache-service.js';
@@ -9,7 +9,7 @@
9
9
  * + cache only; the LLM consumes cached `agents/*.md` directly
10
10
  * through `peaks ecc show <name>`.
11
11
  *
12
- * Six exports per RD §2:
12
+ * Six cache exports per RD §2:
13
13
  * - setCacheDirPermissions
14
14
  * - downloadToCache
15
15
  * - readCacheManifest
@@ -17,6 +17,11 @@
17
17
  * - readAgentSkill
18
18
  * - cleanupStaleCache
19
19
  *
20
+ * Slice A of 2026-09-09-ecc-dynamic adds the plugin-free materialize
21
+ * layer (`materializeEccAgents` + readers) that copies the active sha's
22
+ * `agents/*.md` into `~/.peaks/agents/ecc/` so the RD fan-out works on a
23
+ * machine with no ECC Claude Code plugin.
24
+ *
20
25
  * The cache layout is `~/.peaks/cache/ecc-installed.json` (manifest)
21
26
  * + `~/.peaks/cache/ecc-<sha>/agents/<name>.md`. The manifest is
22
27
  * the active-cache pointer; cleanupStaleCache iterates the on-disk
@@ -31,12 +36,18 @@
31
36
  * - D-009 fallback: parseFrontmatter throws on malformed input —
32
37
  * wrap it in try/catch and synthesize `{name, description}`
33
38
  * from the file name + first non-empty body line.
34
- * - D-010 fallback: PRD's `ecc.tar.gz` asset URL does NOT exist
35
- * upstream; try PRD first, fall back to GitHub's `tarball_url`
36
- * on the release JSON.
39
+ * - D-010 fallback order (2026-09-09, leads with what actually works):
40
+ * 1. `tarball_url` from `releases/tags/<ref>` — the only path that
41
+ * serves a tarball on upstream v2.2.0. Must be fetched with
42
+ * `accept: application/vnd.github+json`; GitHub's API tarball
43
+ * endpoint answers 415 to `application/octet-stream`.
44
+ * 2. release asset named `ecc.tar.gz` or any `.tgz` / `.tar.gz`.
45
+ * 3. PRD's `ecc.tar.gz` asset URL — dead today (v2.2.0 ships only
46
+ * `.png` assets) but kept as last resort in case a future
47
+ * release ships the asset again.
37
48
  */
38
49
  export declare const ECC_REPO_OWNER = "affaan-m";
39
- export declare const ECC_REPO_NAME = "everything-claude-code";
50
+ export declare const ECC_REPO_NAME = "ECC";
40
51
  export type CacheManifest = {
41
52
  version: string;
42
53
  sha: string;
@@ -47,6 +58,19 @@ export type DownloadResult = {
47
58
  sha: string;
48
59
  agents: number;
49
60
  };
61
+ /**
62
+ * Peaks-owned materialize manifest. Written next to the normalized
63
+ * agent copies under `~/.peaks/agents/ecc/`. Unlike the cache manifest
64
+ * (which points at a sha dir), this one records the *stable* copy the
65
+ * plugin-free dispatch path reads when no ECC Claude Code plugin is
66
+ * installed.
67
+ */
68
+ export type EccMaterializeManifest = {
69
+ version: string;
70
+ sha: string;
71
+ materializedAt: string;
72
+ agents: string[];
73
+ };
50
74
  /**
51
75
  * Cache dir resolution — single source of truth. Tests inject
52
76
  * via `dirOverride` on the functions that take one.
@@ -55,6 +79,16 @@ export declare function resolveEccCacheDir(): string;
55
79
  export declare function resolveManifestPath(dirOverride?: string): string;
56
80
  export declare function resolveShaDir(sha: string, dirOverride?: string): string;
57
81
  export declare function resolveAgentsDir(sha: string, dirOverride?: string): string;
82
+ /**
83
+ * Plugin-free materialize target: `~/.peaks/agents/ecc/`.
84
+ *
85
+ * Deliberately NOT under `~/.claude/` — peaks-loop must never write into
86
+ * the user's Claude Code tree (user direction 2026-09-09). The LLM reads
87
+ * `<target>/<agent-name>.md` directly when the ECC Claude Code plugin is
88
+ * absent, then dispatches a generic sub-agent with that body.
89
+ */
90
+ export declare function resolveEccMaterializedDir(): string;
91
+ export declare function resolveEccMaterializedManifestPath(dirOverride?: string): string;
58
92
  /**
59
93
  * Best-effort chmod 0o700 on POSIX; no-op on Windows (NTFS uses
60
94
  * ACLs, not POSIX mode bits). Swallows errors with WARN so a
@@ -77,6 +111,46 @@ export declare function listCachedAgents(): {
77
111
  description: string;
78
112
  }[];
79
113
  export declare function readAgentSkill(name: string): string | null;
114
+ export declare function readEccMaterializeManifest(dirOverride?: string): EccMaterializeManifest | null;
115
+ export declare function listMaterializedAgents(dirOverride?: string): string[];
116
+ export declare function hasMaterializedEccAgents(dirOverride?: string): boolean;
117
+ /**
118
+ * Resolve the materialized ECC agent name for a logical role.
119
+ *
120
+ * Upstream ECC names its agents `<lang>-reviewer` (`code-reviewer.md`),
121
+ * NOT `code-review.md` — so no caller may hardcode a single filename.
122
+ * Resolution order (deterministic; `listMaterializedAgents` is sorted):
123
+ * 1. the caller's explicit candidates, in declared priority order
124
+ * (e.g. `['code-reviewer', 'code-review']` — real upstream name
125
+ * first, legacy/forward-compat second);
126
+ * 2. a fallback over the materialized list: the exact
127
+ * `<stem>-reviewer`, else the first `<stem>-*` whose name contains
128
+ * `reviewer`, where `stem` is the candidate minus a `-reviewer`
129
+ * suffix (`code-reviewer` -> `code`).
130
+ *
131
+ * Returns `null` when nothing matches — the caller degrades to inline
132
+ * review instead of dispatching a non-existent agent.
133
+ */
134
+ export declare function resolveMaterializedAgentName(candidates: readonly string[], dirOverride?: string): string | null;
135
+ export declare function readMaterializedAgent(name: string, dirOverride?: string): string | null;
136
+ /**
137
+ * Copy the active cache's `agents/*.md` into a stable, peaks-owned
138
+ * directory (`~/.peaks/agents/ecc/` by default) and write a small
139
+ * manifest. Fail-soft: an empty/missing cache yields
140
+ * `{ sha: null, materialized: [] }` and never throws — `peaks ecc install`
141
+ * must not fail because materialization did.
142
+ *
143
+ * `targetDir` is the ONLY write root (plus `mkdirSync` on it). Nothing in
144
+ * this function can reach `~/.claude/`.
145
+ */
146
+ export declare function materializeEccAgents({ cacheDir, targetDir }?: {
147
+ cacheDir?: string;
148
+ targetDir?: string;
149
+ }): {
150
+ targetDir: string;
151
+ sha: string | null;
152
+ materialized: string[];
153
+ };
80
154
  /**
81
155
  * 7-day TTL sweep over `ecc-<sha>/` directories.
82
156
  *
@@ -1 +1 @@
1
- {"version":3,"file":"ecc-cache-service.d.ts","sourceRoot":"","sources":["../../../src/services/agent/ecc-cache-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAgBH,eAAO,MAAM,cAAc,aAAa,CAAC;AACzC,eAAO,MAAM,aAAa,2BAA2B,CAAC;AAItD,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED,wBAAgB,mBAAmB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAEvE;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAE1E;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAO7D;AAyMD;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,EAAE,GAAG,EAAE,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GAC7B,OAAO,CAAC,cAAc,CAAC,CAuCzB;AAOD,wBAAgB,iBAAiB,IAAI,aAAa,GAAG,IAAI,CAkBxD;AAkDD,wBAAgB,gBAAgB,IAAI;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,EAAE,CAqB1E;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAW1D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,aAAa,EACb,KAAK,EACL,WAAW,GACZ,EAAE;IACD,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG;IAAE,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAyDxB"}
1
+ {"version":3,"file":"ecc-cache-service.d.ts","sourceRoot":"","sources":["../../../src/services/agent/ecc-cache-service.ts"],"names":[],"mappings":"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"}
@@ -9,7 +9,7 @@
9
9
  * + cache only; the LLM consumes cached `agents/*.md` directly
10
10
  * through `peaks ecc show <name>`.
11
11
  *
12
- * Six exports per RD §2:
12
+ * Six cache exports per RD §2:
13
13
  * - setCacheDirPermissions
14
14
  * - downloadToCache
15
15
  * - readCacheManifest
@@ -17,6 +17,11 @@
17
17
  * - readAgentSkill
18
18
  * - cleanupStaleCache
19
19
  *
20
+ * Slice A of 2026-09-09-ecc-dynamic adds the plugin-free materialize
21
+ * layer (`materializeEccAgents` + readers) that copies the active sha's
22
+ * `agents/*.md` into `~/.peaks/agents/ecc/` so the RD fan-out works on a
23
+ * machine with no ECC Claude Code plugin.
24
+ *
20
25
  * The cache layout is `~/.peaks/cache/ecc-installed.json` (manifest)
21
26
  * + `~/.peaks/cache/ecc-<sha>/agents/<name>.md`. The manifest is
22
27
  * the active-cache pointer; cleanupStaleCache iterates the on-disk
@@ -31,18 +36,29 @@
31
36
  * - D-009 fallback: parseFrontmatter throws on malformed input —
32
37
  * wrap it in try/catch and synthesize `{name, description}`
33
38
  * from the file name + first non-empty body line.
34
- * - D-010 fallback: PRD's `ecc.tar.gz` asset URL does NOT exist
35
- * upstream; try PRD first, fall back to GitHub's `tarball_url`
36
- * on the release JSON.
39
+ * - D-010 fallback order (2026-09-09, leads with what actually works):
40
+ * 1. `tarball_url` from `releases/tags/<ref>` — the only path that
41
+ * serves a tarball on upstream v2.2.0. Must be fetched with
42
+ * `accept: application/vnd.github+json`; GitHub's API tarball
43
+ * endpoint answers 415 to `application/octet-stream`.
44
+ * 2. release asset named `ecc.tar.gz` or any `.tgz` / `.tar.gz`.
45
+ * 3. PRD's `ecc.tar.gz` asset URL — dead today (v2.2.0 ships only
46
+ * `.png` assets) but kept as last resort in case a future
47
+ * release ships the asset again.
37
48
  */
38
49
  import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from 'node:fs';
39
50
  import { join } from 'node:path';
40
51
  import { homedir } from 'node:os';
41
52
  import { parseFrontmatter } from '../../shared/frontmatter.js';
42
53
  export const ECC_REPO_OWNER = 'affaan-m';
43
- export const ECC_REPO_NAME = 'everything-claude-code';
54
+ // Upstream renamed `everything-claude-code` -> `ECC` on 2026-09; GitHub
55
+ // 301-redirects the old name but we keep the current one to avoid the hop.
56
+ export const ECC_REPO_NAME = 'ECC';
44
57
  const ECC_CACHE_VERSION = '1';
58
+ const ECC_MATERIALIZE_VERSION = '1';
45
59
  const ECC_TARBALL_BASENAME = 'ecc.tar.gz';
60
+ // GitHub's API tarball endpoint 415s on `application/octet-stream`.
61
+ const GITHUB_API_ACCEPT = 'application/vnd.github+json';
46
62
  /**
47
63
  * Cache dir resolution — single source of truth. Tests inject
48
64
  * via `dirOverride` on the functions that take one.
@@ -59,6 +75,20 @@ export function resolveShaDir(sha, dirOverride) {
59
75
  export function resolveAgentsDir(sha, dirOverride) {
60
76
  return join(resolveShaDir(sha, dirOverride), 'agents');
61
77
  }
78
+ /**
79
+ * Plugin-free materialize target: `~/.peaks/agents/ecc/`.
80
+ *
81
+ * Deliberately NOT under `~/.claude/` — peaks-loop must never write into
82
+ * the user's Claude Code tree (user direction 2026-09-09). The LLM reads
83
+ * `<target>/<agent-name>.md` directly when the ECC Claude Code plugin is
84
+ * absent, then dispatches a generic sub-agent with that body.
85
+ */
86
+ export function resolveEccMaterializedDir() {
87
+ return join(homedir(), '.peaks', 'agents', 'ecc');
88
+ }
89
+ export function resolveEccMaterializedManifestPath(dirOverride) {
90
+ return join(dirOverride ?? resolveEccMaterializedDir(), 'ecc-agents.json');
91
+ }
62
92
  /**
63
93
  * Best-effort chmod 0o700 on POSIX; no-op on Windows (NTFS uses
64
94
  * ACLs, not POSIX mode bits). Swallows errors with WARN so a
@@ -77,6 +107,18 @@ export function setCacheDirPermissions(cacheDir) {
77
107
  function isSafeAgentName(name) {
78
108
  return /^[a-z][a-z0-9-]*$/.test(name);
79
109
  }
110
+ /**
111
+ * GitHub prefixes every tarball entry with a synthetic root dir —
112
+ * `<repo>-<sha>` on codeload, `<owner>-<repo>-<sha>` on the API tarball
113
+ * endpoint. Match on shape, not on the repo name, so a rename (or either
114
+ * endpoint) cannot silently zero out the extraction.
115
+ */
116
+ function stripTarballRootSegments(entryName) {
117
+ const segments = entryName.split('/');
118
+ if (segments.length >= 3 && segments[0] !== 'agents')
119
+ segments.shift();
120
+ return segments;
121
+ }
80
122
  function isSafeArchiveEntry(entryName) {
81
123
  if (entryName.length === 0)
82
124
  return false;
@@ -84,23 +126,15 @@ function isSafeArchiveEntry(entryName) {
84
126
  return false;
85
127
  if (entryName.includes('..'))
86
128
  return false;
87
- // Strip the leading "<repo-root>/" segment (github tarballs prefix
88
- // every entry with "<repo>-<sha>/..."); everything after must
89
- // start with "agents/" and end with ".md" at a single level.
90
- const segments = entryName.split('/');
91
- // Drop the first "<repo>-<sha>" segment if present.
92
- if (segments.length >= 3 && segments[0]?.startsWith(`${ECC_REPO_NAME}-`)) {
93
- segments.shift();
94
- }
129
+ // After dropping the synthetic root, everything must be exactly
130
+ // "agents/<name>.md" at a single level.
131
+ const segments = stripTarballRootSegments(entryName);
95
132
  if (segments.length !== 2)
96
133
  return false;
97
134
  return segments[0] === 'agents' && segments[1]?.endsWith('.md') === true;
98
135
  }
99
136
  function safeAgentNameFromEntry(entryName) {
100
- const segments = entryName.split('/');
101
- if (segments.length >= 3 && segments[0]?.startsWith(`${ECC_REPO_NAME}-`)) {
102
- segments.shift();
103
- }
137
+ const segments = stripTarballRootSegments(entryName);
104
138
  const file = segments[segments.length - 1] ?? '';
105
139
  const base = file.replace(/\.md$/i, '');
106
140
  return isSafeAgentName(base) ? base : null;
@@ -222,11 +256,20 @@ function parseOctal(value) {
222
256
  const n = Number.parseInt(trimmed, 8);
223
257
  return Number.isFinite(n) && n >= 0 ? n : null;
224
258
  }
225
- async function fetchBuffer(url) {
259
+ /**
260
+ * Binary fetch with an explicit, overridable `accept`.
261
+ *
262
+ * Do NOT default to `application/octet-stream`: GitHub's
263
+ * `api.github.com/.../tarball/<ref>` endpoint rejects it with 415.
264
+ * Omitting `accept` entirely is fine for release-asset / codeload
265
+ * URLs, which always serve the bytes.
266
+ */
267
+ async function fetchBuffer(url, accept) {
226
268
  try {
227
- const res = await fetch(url, {
228
- headers: { accept: 'application/octet-stream', 'user-agent': 'peaks-loop' },
229
- });
269
+ const headers = { 'user-agent': 'peaks-loop' };
270
+ if (accept !== undefined)
271
+ headers.accept = accept;
272
+ const res = await fetch(url, { headers });
230
273
  if (!res.ok)
231
274
  return null;
232
275
  const ab = await res.arrayBuffer();
@@ -237,22 +280,27 @@ async function fetchBuffer(url) {
237
280
  }
238
281
  }
239
282
  async function downloadTarball(ref, sha, outDir) {
240
- // D-010: PRD URL first, GitHub fallback second.
241
- const prdUrl = `https://github.com/${ECC_REPO_OWNER}/${ECC_REPO_NAME}/releases/download/${encodeURIComponent(ref)}/${ECC_TARBALL_BASENAME}`;
242
- let buffer = await fetchBuffer(prdUrl);
283
+ // D-010 order (2026-09-09): tarball_url -> release asset -> PRD URL.
284
+ // See the module header for why each step exists and which one works.
285
+ let buffer = null;
286
+ const release = await fetchReleaseJson(`https://api.github.com/repos/${ECC_REPO_OWNER}/${ECC_REPO_NAME}/releases/tags/${encodeURIComponent(ref)}`);
287
+ // 1. API tarball. Requires the GitHub JSON accept header (octet-stream 415s).
288
+ const tarballUrl = release?.tarball_url;
289
+ if (typeof tarballUrl === 'string' && tarballUrl.length > 0) {
290
+ buffer = await fetchBuffer(tarballUrl, GITHUB_API_ACCEPT);
291
+ }
292
+ // 2. Release asset, if this release happens to ship one.
293
+ if (buffer === null && Array.isArray(release?.assets)) {
294
+ const asset = release.assets.find((a) => a.name === ECC_TARBALL_BASENAME) ??
295
+ release.assets.find((a) => a.name === `${ECC_REPO_NAME}-universal-${ref}.tgz`) ??
296
+ release.assets.find((a) => a.name.endsWith('.tgz') || a.name.endsWith('.tar.gz'));
297
+ if (asset)
298
+ buffer = await fetchBuffer(asset.browser_download_url);
299
+ }
300
+ // 3. PRD asset URL — last resort, dead upstream today.
243
301
  if (buffer === null) {
244
- const release = await fetchReleaseJson(`https://api.github.com/repos/${ECC_REPO_OWNER}/${ECC_REPO_NAME}/releases/tags/${encodeURIComponent(ref)}`);
245
- const tarballUrl = release?.tarball_url;
246
- if (typeof tarballUrl === 'string' && tarballUrl.length > 0) {
247
- buffer = await fetchBuffer(tarballUrl);
248
- }
249
- if (buffer === null && Array.isArray(release?.assets)) {
250
- const asset = release.assets.find((a) => a.name === ECC_TARBALL_BASENAME) ??
251
- release.assets.find((a) => a.name === `${ECC_REPO_NAME}-universal-${ref}.tgz`) ??
252
- release.assets.find((a) => a.name.endsWith('.tgz') || a.name.endsWith('.tar.gz'));
253
- if (asset)
254
- buffer = await fetchBuffer(asset.browser_download_url);
255
- }
302
+ const prdUrl = `https://github.com/${ECC_REPO_OWNER}/${ECC_REPO_NAME}/releases/download/${encodeURIComponent(ref)}/${ECC_TARBALL_BASENAME}`;
303
+ buffer = await fetchBuffer(prdUrl);
256
304
  }
257
305
  if (buffer === null) {
258
306
  throw new Error('fetch-failed');
@@ -291,6 +339,7 @@ export async function downloadToCache({ ref } = {}) {
291
339
  .filter((f) => f.endsWith('.md'))
292
340
  .map((f) => f.replace(/\.md$/i, ''));
293
341
  writeManifest({ version: ECC_CACHE_VERSION, sha: resolvedSha, fetchedAt: new Date().toISOString(), agents });
342
+ materializeBestEffort(cacheDir);
294
343
  return { sha: resolvedSha, agents: agents.length };
295
344
  }
296
345
  const extracted = await downloadTarball(requestedRef === 'latest' ? resolvedSha : requestedRef, resolvedSha, agentsDir);
@@ -301,14 +350,32 @@ export async function downloadToCache({ ref } = {}) {
301
350
  agents: extracted,
302
351
  };
303
352
  writeManifest(manifest);
353
+ materializeBestEffort(cacheDir);
304
354
  return { sha: resolvedSha, agents: extracted.length };
305
355
  }
356
+ /**
357
+ * Refresh the plugin-free copy after a successful download. Swallows every
358
+ * error: `peaks ecc install` succeeds even when the materialize step cannot
359
+ * write (read-only home, disk full, ...) — the caller falls back to inline
360
+ * review in that case.
361
+ */
362
+ function materializeBestEffort(cacheDir) {
363
+ try {
364
+ materializeEccAgents({ cacheDir });
365
+ }
366
+ catch {
367
+ /* best-effort */
368
+ }
369
+ }
306
370
  function writeManifest(manifest) {
307
371
  const path = resolveManifestPath();
308
372
  writeFileSync(path, JSON.stringify(manifest, null, 2));
309
373
  }
310
374
  export function readCacheManifest() {
311
- const path = resolveManifestPath();
375
+ return readManifestAt();
376
+ }
377
+ function readManifestAt(dirOverride) {
378
+ const path = resolveManifestPath(dirOverride);
312
379
  if (!existsSync(path))
313
380
  return null;
314
381
  try {
@@ -418,6 +485,183 @@ export function readAgentSkill(name) {
418
485
  return null;
419
486
  }
420
487
  }
488
+ // ---------------------------------------------------------------------
489
+ // Plugin-free materialize layer (Slice A of 2026-09-09-ecc-dynamic)
490
+ //
491
+ // `peaks ecc install` downloads ECC `agents/*.md` into the sha cache, but
492
+ // that path is plugin-independent only in storage — the RD fan-out still
493
+ // needed `Agent({subagent_type: 'everything-claude-code:code-review'})` (old retired id),
494
+ // which requires the ECC Claude Code plugin. Materializing a normalized
495
+ // copy under `~/.peaks/agents/ecc/` gives the RD loop a plugin-free read
496
+ // target so a fresh machine without the ECC plugin can still run the
497
+ // review via a generic sub-agent.
498
+ // ---------------------------------------------------------------------
499
+ export function readEccMaterializeManifest(dirOverride) {
500
+ const path = resolveEccMaterializedManifestPath(dirOverride);
501
+ if (!existsSync(path))
502
+ return null;
503
+ try {
504
+ const parsed = JSON.parse(readFileSync(path, 'utf8'));
505
+ if (typeof parsed.version === 'string' &&
506
+ typeof parsed.sha === 'string' &&
507
+ typeof parsed.materializedAt === 'string' &&
508
+ Array.isArray(parsed.agents)) {
509
+ return parsed;
510
+ }
511
+ return null;
512
+ }
513
+ catch {
514
+ return null;
515
+ }
516
+ }
517
+ export function listMaterializedAgents(dirOverride) {
518
+ const dir = dirOverride ?? resolveEccMaterializedDir();
519
+ if (!existsSync(dir))
520
+ return [];
521
+ try {
522
+ return readdirSync(dir)
523
+ .filter((f) => f.endsWith('.md'))
524
+ .map((f) => f.replace(/\.md$/i, ''))
525
+ .filter((name) => isSafeAgentName(name))
526
+ .sort();
527
+ }
528
+ catch {
529
+ return [];
530
+ }
531
+ }
532
+ export function hasMaterializedEccAgents(dirOverride) {
533
+ return listMaterializedAgents(dirOverride).length > 0;
534
+ }
535
+ /**
536
+ * Resolve the materialized ECC agent name for a logical role.
537
+ *
538
+ * Upstream ECC names its agents `<lang>-reviewer` (`code-reviewer.md`),
539
+ * NOT `code-review.md` — so no caller may hardcode a single filename.
540
+ * Resolution order (deterministic; `listMaterializedAgents` is sorted):
541
+ * 1. the caller's explicit candidates, in declared priority order
542
+ * (e.g. `['code-reviewer', 'code-review']` — real upstream name
543
+ * first, legacy/forward-compat second);
544
+ * 2. a fallback over the materialized list: the exact
545
+ * `<stem>-reviewer`, else the first `<stem>-*` whose name contains
546
+ * `reviewer`, where `stem` is the candidate minus a `-reviewer`
547
+ * suffix (`code-reviewer` -> `code`).
548
+ *
549
+ * Returns `null` when nothing matches — the caller degrades to inline
550
+ * review instead of dispatching a non-existent agent.
551
+ */
552
+ export function resolveMaterializedAgentName(candidates, dirOverride) {
553
+ const available = listMaterializedAgents(dirOverride);
554
+ if (available.length === 0)
555
+ return null;
556
+ for (const candidate of candidates) {
557
+ if (available.includes(candidate))
558
+ return candidate;
559
+ }
560
+ for (const candidate of candidates) {
561
+ const stem = candidate.replace(/-reviewer$/, '');
562
+ const exact = available.find((name) => name === `${stem}-reviewer`);
563
+ if (exact !== undefined)
564
+ return exact;
565
+ const reviewerish = available.find((name) => name.startsWith(`${stem}-`) && name.includes('reviewer'));
566
+ if (reviewerish !== undefined)
567
+ return reviewerish;
568
+ }
569
+ return null;
570
+ }
571
+ export function readMaterializedAgent(name, dirOverride) {
572
+ if (!isSafeAgentName(name))
573
+ return null;
574
+ const file = join(dirOverride ?? resolveEccMaterializedDir(), `${name}.md`);
575
+ if (!existsSync(file))
576
+ return null;
577
+ try {
578
+ return readFileSync(file, 'utf8');
579
+ }
580
+ catch {
581
+ return null;
582
+ }
583
+ }
584
+ /**
585
+ * Copy the active cache's `agents/*.md` into a stable, peaks-owned
586
+ * directory (`~/.peaks/agents/ecc/` by default) and write a small
587
+ * manifest. Fail-soft: an empty/missing cache yields
588
+ * `{ sha: null, materialized: [] }` and never throws — `peaks ecc install`
589
+ * must not fail because materialization did.
590
+ *
591
+ * `targetDir` is the ONLY write root (plus `mkdirSync` on it). Nothing in
592
+ * this function can reach `~/.claude/`.
593
+ */
594
+ export function materializeEccAgents({ cacheDir, targetDir } = {}) {
595
+ const resolvedTarget = targetDir ?? resolveEccMaterializedDir();
596
+ const manifest = readManifestAt(cacheDir);
597
+ if (manifest === null) {
598
+ return { targetDir: resolvedTarget, sha: null, materialized: [] };
599
+ }
600
+ const agentsDir = resolveAgentsDir(manifest.sha, cacheDir);
601
+ if (!existsSync(agentsDir)) {
602
+ return { targetDir: resolvedTarget, sha: null, materialized: [] };
603
+ }
604
+ let entries;
605
+ try {
606
+ entries = readdirSync(agentsDir);
607
+ }
608
+ catch {
609
+ return { targetDir: resolvedTarget, sha: null, materialized: [] };
610
+ }
611
+ try {
612
+ if (!existsSync(resolvedTarget))
613
+ mkdirSync(resolvedTarget, { recursive: true });
614
+ setCacheDirPermissions(resolvedTarget);
615
+ }
616
+ catch {
617
+ return { targetDir: resolvedTarget, sha: null, materialized: [] };
618
+ }
619
+ const materialized = [];
620
+ for (const file of entries) {
621
+ if (!file.endsWith('.md'))
622
+ continue;
623
+ const name = file.replace(/\.md$/i, '');
624
+ if (!isSafeAgentName(name))
625
+ continue;
626
+ try {
627
+ const body = readFileSync(join(agentsDir, file), 'utf8');
628
+ writeFileSync(join(resolvedTarget, `${name}.md`), body);
629
+ materialized.push(name);
630
+ }
631
+ catch {
632
+ /* fail-soft per agent */
633
+ }
634
+ }
635
+ materialized.sort();
636
+ // Prune stale copies so `readMaterializedAgent` cannot serve an agent
637
+ // the active cache no longer ships.
638
+ try {
639
+ for (const existing of readdirSync(resolvedTarget)) {
640
+ if (!existing.endsWith('.md'))
641
+ continue;
642
+ const name = existing.replace(/\.md$/i, '');
643
+ if (!materialized.includes(name)) {
644
+ rmSync(join(resolvedTarget, existing), { force: true });
645
+ }
646
+ }
647
+ }
648
+ catch {
649
+ /* fail-soft */
650
+ }
651
+ const nextManifest = {
652
+ version: ECC_MATERIALIZE_VERSION,
653
+ sha: manifest.sha,
654
+ materializedAt: new Date().toISOString(),
655
+ agents: materialized,
656
+ };
657
+ try {
658
+ writeFileSync(resolveEccMaterializedManifestPath(resolvedTarget), JSON.stringify(nextManifest, null, 2));
659
+ }
660
+ catch {
661
+ /* fail-soft */
662
+ }
663
+ return { targetDir: resolvedTarget, sha: manifest.sha, materialized };
664
+ }
421
665
  /**
422
666
  * 7-day TTL sweep over `ecc-<sha>/` directories.
423
667
  *
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "peaks-loop-mut",
3
- "version": "0.1.30",
3
+ "version": "0.1.31",
4
4
  "description": "Mutation testing + assertion scanning + ECC cache for peaks-loop (workspace-internal)",
5
5
  "keywords": [
6
6
  "peaks-loop",