@kolisachint/hoocode-agent 0.5.3 → 0.5.4

package/dist/core/extensions/plugins/install.d.ts

@@ -13,10 +13,6 @@
 import type { MarketplacePlatform } from "./formats/types.js";
 import type { NormalizedPlugin } from "./manifest.js";
 import { type MarketplacePluginSource, type MarketplaceRecord } from "./marketplace.js";
-/** `.agents/` is the primary, cross-vendor home for installed plugins and the added-marketplace registry. */
-export declare function installedPluginsDir(cwd: string): string;
-/** Filesystem-safe directory name derived from a plugin name (matches the `/plugin` command). */
-export declare function sanitizeForDir(s: string): string;
 /** The default marketplace record — always present so source-level trust is meaningful out of the box. */
 export declare function defaultMarketplaceRecord(): MarketplaceRecord;
 /**
@@ -24,28 +20,43 @@ export declare function defaultMarketplaceRecord(): MarketplaceRecord;
  * here is a maintainer-level trust decision (the human half of the "adding a
  * marketplace is the human trust boundary" rule) — keep this list short and
  * high-trust. Indices are cloned lazily into the marketplace cache on first
- * search and never auto-updated afterwards (plugin sources inside the official
- * index are sha-pinned).
+ * search and refreshed on a TTL thereafter. Refreshing the *index* only changes
+ * what is discoverable; installed plugins are still never auto-updated, and
+ * plugin sources inside the official index are sha-pinned.
  */
 export declare const WELL_KNOWN_MARKETPLACES: ReadonlyArray<{
     name: string;
     url: string;
 }>;
-/** Local cache directory for a marketplace fetched from `url` (same convention as `/plugin marketplace add`). */
-export declare function marketplaceCacheDir(cwd: string, url: string): string;
+export interface EnsureMarketplacesOptions {
+    /** Refresh regardless of the TTL. */
+    force?: boolean;
+}
+/**
+ * Make sure every well-known marketplace index is cached and reasonably fresh.
+ *
+ * Clones what is missing and pulls what has gone stale. Without the TTL the
+ * indices were fetched exactly once and never again, so a plugin added upstream
+ * stayed permanently invisible — the inherit half of the system quietly stopped
+ * inheriting. Offline is non-fatal: each failure is returned and search degrades
+ * to whatever is already on disk.
+ */
+export declare function ensureWellKnownMarketplaces(agentDir?: string, options?: EnsureMarketplacesOptions): Promise<string[]>;
 /**
- * Clone any well-known marketplace index that is not in the local cache yet.
- * No-op (and no network) when every index is already cached. Returns one error
- * string per marketplace that could not be fetched (offline is non-fatal —
- * search degrades to the marketplaces already available).
+ * Refresh every cached index — well-known and user-added — ignoring the TTL.
+ * The explicit half of the freshness story, for when a user knows the upstream
+ * changed and does not want to wait out the interval.
  */
-export declare function ensureWellKnownMarketplaces(cwd: string): Promise<string[]>;
+export declare function refreshMarketplaces(cwd: string, agentDir?: string): Promise<{
+    refreshed: string[];
+    errors: string[];
+}>;
 /**
  * All marketplace records in effect: the bundled default first (curated,
  * trusted), then user-added ones from `.agents/` (falling back to legacy
  * `.hoocode/`). Deduplicated by directory.
  */
-export declare function readMarketplaceRecords(cwd: string): MarketplaceRecord[];
+export declare function readMarketplaceRecords(cwd: string, agentDir?: string): MarketplaceRecord[];
 /** A plugin offered by some registered marketplace (not necessarily installed). */
 export interface AvailablePlugin {
     name: string;
@@ -60,9 +71,9 @@ export interface AvailablePlugin {
     supportPlatform: MarketplacePlatform[];
 }
 /** Every plugin offered across all registered marketplaces (first marketplace wins on name clash). */
-export declare function listAvailablePlugins(cwd: string): AvailablePlugin[];
+export declare function listAvailablePlugins(cwd: string, agentDir?: string): AvailablePlugin[];
 /** Find a single available plugin by exact name. */
-export declare function findAvailablePlugin(cwd: string, name: string): AvailablePlugin | undefined;
+export declare function findAvailablePlugin(cwd: string, name: string, agentDir?: string): AvailablePlugin | undefined;
 /** All currently installed plugins (project + global plugin dirs). */
 export declare function listInstalledPlugins(cwd: string, agentDir?: string): NormalizedPlugin[];
 /** Whether a plugin with `name` (by id) is already installed. */
@@ -77,17 +88,25 @@ export interface InstallOutcome {
     message: string;
 }
 /**
- * Install an available plugin by name into `.agents/plugins`. Copies local
- * sources; clones git sources. Transparent + reversible by construction — the
- * plugin lands in a named directory and {@link uninstallPlugin} removes it.
- * Callers activate the result (live activation via AgentSession.activatePlugin,
- * or a reload).
+ * Install an available plugin by name into the **consumption home** — the global
+ * `~/.agents/plugins/`, not the working tree. A plugin is portable and reusable
+ * across projects, so installing into the repo would both dirty `git status` and
+ * hide the capability from every other checkout.
+ *
+ * Copies local sources; clones git sources. Transparent + reversible by
+ * construction — the plugin lands in a named directory and
+ * {@link uninstallPlugin} removes it. Callers activate the result (live
+ * activation via AgentSession.activatePlugin, or a reload).
  */
-export declare function installAvailablePlugin(cwd: string, name: string): Promise<InstallOutcome>;
+export declare function installAvailablePlugin(cwd: string, name: string, agentDir?: string): Promise<InstallOutcome>;
 export interface UninstallOutcome {
     removed: boolean;
     message: string;
 }
-/** Remove an installed plugin from `.agents/plugins` (and the legacy `.hoocode/plugins`). */
-export declare function uninstallPlugin(cwd: string, name: string): UninstallOutcome;
+/**
+ * Remove an installed or authored plugin from every location it could occupy:
+ * the consumption home, both production homes, and the legacy project-local
+ * directories that older versions wrote into.
+ */
+export declare function uninstallPlugin(cwd: string, name: string, agentDir?: string): UninstallOutcome;
 //# sourceMappingURL=install.d.ts.map

package/dist/core/extensions/plugins/install.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../../../src/core/extensions/plugins/install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AASH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAE9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD,OAAO,EACN,KAAK,uBAAuB,EAC5B,KAAK,iBAAiB,EAItB,MAAM,kBAAkB,CAAC;AAE1B,6GAA6G;AAC7G,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEvD;AAUD,iGAAiG;AACjG,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEhD;AAOD,4GAA0G;AAC1G,wBAAgB,wBAAwB,IAAI,iBAAiB,CAE5D;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,EAAE,aAAa,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAMhF,CAAC;AAEF,iHAAiH;AACjH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAEpE;AAED;;;;;GAKG;AACH,wBAAsB,2BAA2B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAahF;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAuBvE;AAED,mFAAmF;AACnF,MAAM,WAAW,eAAe;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,MAAM,EAAE,uBAAuB,CAAC;IAChC,oDAAoD;IACpD,UAAU,EAAE,OAAO,GAAG,KAAK,GAAG,YAAY,GAAG,KAAK,CAAC;IACnD,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,6EAA6E;IAC7E,eAAe,EAAE,mBAAmB,EAAE,CAAC;CACvC;AAED,sGAAsG;AACtG,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,EAAE,CAqBnE;AAED,oDAAoD;AACpD,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAE1F;AAED,sEAAsE;AACtE,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAsB,GAAG,gBAAgB,EAAE,CAEtG;AAED,iEAAiE;AACjE,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAsB,GAAG,OAAO,CAEtG;AAqED,MAAM,WAAW,cAAc;IAC9B,SAAS,EAAE,OAAO,CAAC;IACnB,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,eAAe,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACxC,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CA6D/F;AAED,MAAM,WAAW,gBAAgB;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,6FAA6F;AAC7F,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAS3E","sourcesContent":["/**\n * Plugin install/uninstall/discovery — the shared engine behind both the\n * `/plugin` slash command (human-driven) and the model-facing lifecycle tools\n * (`SearchPlugins`, `InstallPlugin`, ...). Keeping it in one place means the two\n * surfaces can never drift on where plugins live or how sources resolve.\n *\n * Trust model (see docs/plugin-system-spec.md): *adding* a marketplace is the\n * human trust boundary; *installing* from an already-trusted marketplace is the\n * model's discretion (package-manager model), and must stay transparent and\n * reversible. This module performs the mechanical install/remove; the gating\n * (announce, injection carve-out) lives with the callers.\n */\n\nimport { spawn } from \"node:child_process\";\nimport { cpSync, existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from \"node:fs\";\nimport * as os from \"node:os\";\nimport * as path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { getAgentDir } from \"../../../config.js\";\nimport { defaultPluginDirs } from \"../loader.js\";\nimport type { MarketplacePlatform } from \"./formats/types.js\";\nimport { discoverPlugins } from \"./index.js\";\nimport type { NormalizedPlugin } from \"./manifest.js\";\nimport { parsePluginDir } from \"./manifest.js\";\nimport {\n\ttype MarketplacePluginSource,\n\ttype MarketplaceRecord,\n\tparseMarketplaceDir,\n\treadMarketplaceStore,\n\tresolvePluginSource,\n} from \"./marketplace.js\";\n\n/** `.agents/` is the primary, cross-vendor home for installed plugins and the added-marketplace registry. */\nexport function installedPluginsDir(cwd: string): string {\n\treturn path.join(cwd, \".agents\", \"plugins\");\n}\n\nfunction marketplaceStorePath(cwd: string): string {\n\treturn path.join(cwd, \".agents\", \"marketplaces.json\");\n}\n\nfunction legacyStorePath(cwd: string): string {\n\treturn path.join(cwd, \".hoocode\", \"marketplaces.json\");\n}\n\n/** Filesystem-safe directory name derived from a plugin name (matches the `/plugin` command). */\nexport function sanitizeForDir(s: string): string {\n\treturn s.replace(/[^a-zA-Z0-9._-]+/g, \"_\").slice(0, 80);\n}\n\n/** Absolute path to the curated default marketplace bundled with hoocode. */\nfunction defaultMarketplaceDir(): string {\n\treturn fileURLToPath(new URL(\"./default-marketplace/\", import.meta.url));\n}\n\n/** The default marketplace record — always present so source-level trust is meaningful out of the box. */\nexport function defaultMarketplaceRecord(): MarketplaceRecord {\n\treturn { location: \"hoocode-default\", dir: defaultMarketplaceDir() };\n}\n\n/**\n * Curated well-known marketplaces, trusted out of the box. Shipping an entry\n * here is a maintainer-level trust decision (the human half of the \"adding a\n * marketplace is the human trust boundary\" rule) — keep this list short and\n * high-trust. Indices are cloned lazily into the marketplace cache on first\n * search and never auto-updated afterwards (plugin sources inside the official\n * index are sha-pinned).\n */\nexport const WELL_KNOWN_MARKETPLACES: ReadonlyArray<{ name: string; url: string }> = [\n\t{ name: \"claude-plugins-official\", url: \"https://github.com/anthropics/claude-plugins-official\" },\n\t// The Copilot plugin directory ships both a `.github/plugin/marketplace.json`\n\t// and a `.claude-plugin/marketplace.json`, so it parses with\n\t// supportPlatform [\"claude\", \"github\"] — the default `github` source.\n\t{ name: \"copilot-plugins\", url: \"https://github.com/github/copilot-plugins\" },\n];\n\n/** Local cache directory for a marketplace fetched from `url` (same convention as `/plugin marketplace add`). */\nexport function marketplaceCacheDir(cwd: string, url: string): string {\n\treturn path.join(cwd, \".agents\", \"marketplace-cache\", sanitizeForDir(url));\n}\n\n/**\n * Clone any well-known marketplace index that is not in the local cache yet.\n * No-op (and no network) when every index is already cached. Returns one error\n * string per marketplace that could not be fetched (offline is non-fatal —\n * search degrades to the marketplaces already available).\n */\nexport async function ensureWellKnownMarketplaces(cwd: string): Promise<string[]> {\n\tconst errors: string[] = [];\n\tfor (const wk of WELL_KNOWN_MARKETPLACES) {\n\t\tconst dir = marketplaceCacheDir(cwd, wk.url);\n\t\tif (existsSync(dir)) continue;\n\t\tmkdirSync(path.dirname(dir), { recursive: true });\n\t\tconst res = await cloneGitRepo(wk.url, dir);\n\t\tif (res.code !== 0) {\n\t\t\trmSync(dir, { recursive: true, force: true });\n\t\t\terrors.push(`${wk.name}: ${(res.stderr || res.stdout).trim()}`);\n\t\t}\n\t}\n\treturn errors;\n}\n\n/**\n * All marketplace records in effect: the bundled default first (curated,\n * trusted), then user-added ones from `.agents/` (falling back to legacy\n * `.hoocode/`). Deduplicated by directory.\n */\nexport function readMarketplaceRecords(cwd: string): MarketplaceRecord[] {\n\tconst records: MarketplaceRecord[] = [];\n\tconst def = defaultMarketplaceRecord();\n\tif (existsSync(def.dir)) records.push(def);\n\n\t// Well-known marketplaces participate once their index is cached locally\n\t// (see ensureWellKnownMarketplaces; SearchPlugins fetches lazily).\n\tfor (const wk of WELL_KNOWN_MARKETPLACES) {\n\t\tconst dir = marketplaceCacheDir(cwd, wk.url);\n\t\tif (existsSync(dir) && !records.some((x) => x.dir === dir)) {\n\t\t\trecords.push({ location: wk.url, dir });\n\t\t}\n\t}\n\n\tconst primary = readMarketplaceStore(marketplaceStorePath(cwd));\n\tconst user =\n\t\tprimary.length > 0 || existsSync(marketplaceStorePath(cwd))\n\t\t\t? primary\n\t\t\t: readMarketplaceStore(legacyStorePath(cwd));\n\tfor (const r of user) {\n\t\tif (!records.some((x) => x.dir === r.dir)) records.push(r);\n\t}\n\treturn records;\n}\n\n/** A plugin offered by some registered marketplace (not necessarily installed). */\nexport interface AvailablePlugin {\n\tname: string;\n\tdescription?: string;\n\t/** Relative path, git URL, `npm:<spec>`, or structured source object. */\n\tsource: MarketplacePluginSource;\n\t/** Resolved source kind, for display and gating. */\n\tsourceKind: \"local\" | \"git\" | \"git-subdir\" | \"npm\";\n\tmarketplaceName: string;\n\tmarketplaceRoot: string;\n\t/** Platforms this entry targets (per-entry hint, else the marketplace's). */\n\tsupportPlatform: MarketplacePlatform[];\n}\n\n/** Every plugin offered across all registered marketplaces (first marketplace wins on name clash). */\nexport function listAvailablePlugins(cwd: string): AvailablePlugin[] {\n\tconst out: AvailablePlugin[] = [];\n\tconst seen = new Set<string>();\n\tfor (const rec of readMarketplaceRecords(cwd)) {\n\t\tconst market = parseMarketplaceDir(rec.dir);\n\t\tif (!market) continue;\n\t\tfor (const entry of market.plugins) {\n\t\t\tif (seen.has(entry.name)) continue;\n\t\t\tseen.add(entry.name);\n\t\t\tout.push({\n\t\t\t\tname: entry.name,\n\t\t\t\tdescription: entry.description,\n\t\t\t\tsource: entry.source,\n\t\t\t\tsourceKind: resolvePluginSource(entry.source, market.root).kind,\n\t\t\t\tmarketplaceName: market.name,\n\t\t\t\tmarketplaceRoot: market.root,\n\t\t\t\tsupportPlatform: entry.supportPlatform ?? market.supportPlatform,\n\t\t\t});\n\t\t}\n\t}\n\treturn out;\n}\n\n/** Find a single available plugin by exact name. */\nexport function findAvailablePlugin(cwd: string, name: string): AvailablePlugin | undefined {\n\treturn listAvailablePlugins(cwd).find((p) => p.name === name);\n}\n\n/** All currently installed plugins (project + global plugin dirs). */\nexport function listInstalledPlugins(cwd: string, agentDir: string = getAgentDir()): NormalizedPlugin[] {\n\treturn discoverPlugins(defaultPluginDirs(cwd, agentDir));\n}\n\n/** Whether a plugin with `name` (by id) is already installed. */\nexport function isPluginInstalled(cwd: string, name: string, agentDir: string = getAgentDir()): boolean {\n\treturn listInstalledPlugins(cwd, agentDir).some((p) => p.id === name);\n}\n\nfunction execGit(args: string[]): Promise<{ code: number; stdout: string; stderr: string }> {\n\treturn new Promise((resolve) => {\n\t\tconst child = spawn(\"git\", args);\n\t\tlet stdout = \"\";\n\t\tlet stderr = \"\";\n\t\tchild.stdout?.on(\"data\", (d) => {\n\t\t\tstdout += d.toString();\n\t\t});\n\t\tchild.stderr?.on(\"data\", (d) => {\n\t\t\tstderr += d.toString();\n\t\t});\n\t\tchild.on(\"error\", (e) => resolve({ code: 1, stdout, stderr: stderr || String(e) }));\n\t\tchild.on(\"close\", (code) => resolve({ code: code ?? 1, stdout, stderr }));\n\t});\n}\n\n/**\n * Clone a git repository into `dest`.\n * If `ref` is provided, does a shallow clone of that branch/tag.\n * If only `sha` is provided, does a full clone and checks out the commit.\n * Returns the clone result; on failure `dest` may be partially created.\n */\nasync function cloneGitRepo(\n\turl: string,\n\tdest: string,\n\tref?: string,\n\tsha?: string,\n): Promise<{ code: number; stdout: string; stderr: string }> {\n\tif (ref) {\n\t\treturn execGit([\"clone\", \"--branch\", ref, \"--depth\", \"1\", \"--\", url, dest]);\n\t}\n\tif (sha) {\n\t\tconst cloneRes = await execGit([\"clone\", \"--\", url, dest]);\n\t\tif (cloneRes.code !== 0) return cloneRes;\n\t\treturn execGit([\"-C\", dest, \"checkout\", \"--quiet\", sha]);\n\t}\n\treturn execGit([\"clone\", \"--depth\", \"1\", \"--\", url, dest]);\n}\n\n/**\n * Resolve a git-subdir source: clone the repo, checkout the requested ref/sha,\n * and copy the subdirectory to `dest`. Cleans up the temporary clone on failure.\n */\nasync function installGitSubdir(\n\turl: string,\n\tsubdir: string,\n\tdest: string,\n\tref?: string,\n\tsha?: string,\n): Promise<{ ok: true } | { ok: false; message: string }> {\n\tconst tmpDir = mkdtempSync(path.join(os.tmpdir(), \"hoo-plugin-clone-\"));\n\ttry {\n\t\tconst cloneRes = await cloneGitRepo(url, tmpDir, ref, sha);\n\t\tif (cloneRes.code !== 0) {\n\t\t\treturn { ok: false, message: `git clone failed: ${cloneRes.stderr || cloneRes.stdout}`.trim() };\n\t\t}\n\t\tconst src = path.resolve(tmpDir, subdir);\n\t\tif (!existsSync(src)) {\n\t\t\treturn { ok: false, message: `Plugin subdirectory not found in cloned repo: ${subdir}` };\n\t\t}\n\t\tcpSync(src, dest, { recursive: true });\n\t\treturn { ok: true };\n\t} finally {\n\t\trmSync(tmpDir, { recursive: true, force: true });\n\t}\n}\n\nexport interface InstallOutcome {\n\tinstalled: boolean;\n\t/** Install destination directory (when installed). */\n\tdest?: string;\n\t/** Platforms the installed plugin supports (read back from disk). */\n\tsupportPlatform?: MarketplacePlatform[];\n\t/** Human-readable summary suitable for a tool result or notification. */\n\tmessage: string;\n}\n\n/**\n * Install an available plugin by name into `.agents/plugins`. Copies local\n * sources; clones git sources. Transparent + reversible by construction — the\n * plugin lands in a named directory and {@link uninstallPlugin} removes it.\n * Callers activate the result (live activation via AgentSession.activatePlugin,\n * or a reload).\n */\nexport async function installAvailablePlugin(cwd: string, name: string): Promise<InstallOutcome> {\n\tconst found = findAvailablePlugin(cwd, name);\n\tif (!found) return { installed: false, message: `Plugin \"${name}\" not found in any registered marketplace.` };\n\n\tconst resolved = resolvePluginSource(found.source, found.marketplaceRoot);\n\tconst dest = path.join(installedPluginsDir(cwd), sanitizeForDir(name));\n\trmSync(dest, { recursive: true, force: true });\n\tmkdirSync(installedPluginsDir(cwd), { recursive: true });\n\n\tif (resolved.kind === \"local\") {\n\t\tif (!existsSync(resolved.path)) {\n\t\t\treturn { installed: false, message: `Plugin source path not found: ${resolved.path}` };\n\t\t}\n\t\tcpSync(resolved.path, dest, { recursive: true });\n\t} else if (resolved.kind === \"git\") {\n\t\tconst res = await cloneGitRepo(resolved.url, dest, resolved.ref, resolved.sha);\n\t\tif (res.code !== 0) {\n\t\t\trmSync(dest, { recursive: true, force: true });\n\t\t\treturn { installed: false, message: `git clone failed: ${res.stderr || res.stdout}`.trim() };\n\t\t}\n\t} else if (resolved.kind === \"git-subdir\") {\n\t\tconst res = await installGitSubdir(resolved.url, resolved.path, dest, resolved.ref, resolved.sha);\n\t\tif (!res.ok) {\n\t\t\trmSync(dest, { recursive: true, force: true });\n\t\t\treturn { installed: false, message: res.message };\n\t\t}\n\t} else {\n\t\treturn { installed: false, message: `npm plugin sources are not supported yet (${resolved.spec}).` };\n\t}\n\n\tlet parsed = parsePluginDir(dest);\n\tif (!parsed) {\n\t\t// Manifest-less plugin dir (some marketplaces index bare capability trees,\n\t\t// e.g. a plugin that is just a `skills/` directory): synthesize a native\n\t\t// manifest from the marketplace entry so the standard loader can carry it.\n\t\tconst manifestDir = path.join(dest, \".agents-plugin\");\n\t\tmkdirSync(manifestDir, { recursive: true });\n\t\twriteFileSync(\n\t\t\tpath.join(manifestDir, \"plugin.json\"),\n\t\t\t`${JSON.stringify(\n\t\t\t\t{ name: found.name, ...(found.description ? { description: found.description } : {}) },\n\t\t\t\tnull,\n\t\t\t\t2,\n\t\t\t)}\\n`,\n\t\t\t\"utf8\",\n\t\t);\n\t\tparsed = parsePluginDir(dest);\n\t}\n\tif (!parsed) {\n\t\trmSync(dest, { recursive: true, force: true });\n\t\treturn { installed: false, message: `Installed source for \"${name}\" has no recognizable plugin manifest.` };\n\t}\n\treturn {\n\t\tinstalled: true,\n\t\tdest,\n\t\tsupportPlatform: parsed.supportPlatform,\n\t\tmessage:\n\t\t\t`Installed \"${name}\" from marketplace \"${found.marketplaceName}\" ` +\n\t\t\t`(${parsed.supportPlatform.join(\", \")}) to ${path.relative(cwd, dest) || dest}. ` +\n\t\t\t`Remove it with UninstallPlugin.`,\n\t};\n}\n\nexport interface UninstallOutcome {\n\tremoved: boolean;\n\tmessage: string;\n}\n\n/** Remove an installed plugin from `.agents/plugins` (and the legacy `.hoocode/plugins`). */\nexport function uninstallPlugin(cwd: string, name: string): UninstallOutcome {\n\tconst candidates = [\n\t\tpath.join(installedPluginsDir(cwd), sanitizeForDir(name)),\n\t\tpath.join(cwd, \".hoocode\", \"plugins\", sanitizeForDir(name)),\n\t];\n\tconst present = candidates.filter((p) => existsSync(p));\n\tif (present.length === 0) return { removed: false, message: `Plugin \"${name}\" is not installed.` };\n\tfor (const p of present) rmSync(p, { recursive: true, force: true });\n\treturn { removed: true, message: `Removed \"${name}\".` };\n}\n"]}
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../../../src/core/extensions/plugins/install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAUH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAW9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD,OAAO,EACN,KAAK,uBAAuB,EAC5B,KAAK,iBAAiB,EAItB,MAAM,kBAAkB,CAAC;AAgB1B,4GAA0G;AAC1G,wBAAgB,wBAAwB,IAAI,iBAAiB,CAE5D;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,EAAE,aAAa,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAMhF,CAAC;AAgFF,MAAM,WAAW,yBAAyB;IACzC,qCAAqC;IACrC,KAAK,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,wBAAsB,2BAA2B,CAChD,QAAQ,GAAE,MAAsB,EAChC,OAAO,GAAE,yBAA8B,GACrC,OAAO,CAAC,MAAM,EAAE,CAAC,CAmBnB;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CACxC,GAAG,EAAE,MAAM,EACX,QAAQ,GAAE,MAAsB,GAC9B,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAmBpD;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAsB,GAAG,iBAAiB,EAAE,CAwBzG;AAED,mFAAmF;AACnF,MAAM,WAAW,eAAe;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,MAAM,EAAE,uBAAuB,CAAC;IAChC,oDAAoD;IACpD,UAAU,EAAE,OAAO,GAAG,KAAK,GAAG,YAAY,GAAG,KAAK,CAAC;IACnD,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,6EAA6E;IAC7E,eAAe,EAAE,mBAAmB,EAAE,CAAC;CACvC;AAED,sGAAsG;AACtG,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAsB,GAAG,eAAe,EAAE,CAqBrG;AAED,oDAAoD;AACpD,wBAAgB,mBAAmB,CAClC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,QAAQ,GAAE,MAAsB,GAC9B,eAAe,GAAG,SAAS,CAE7B;AAED,sEAAsE;AACtE,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAsB,GAAG,gBAAgB,EAAE,CAEtG;AAED,iEAAiE;AACjE,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAsB,GAAG,OAAO,CAEtG;AAqED,MAAM,WAAW,cAAc;IAC9B,SAAS,EAAE,OAAO,CAAC;IACnB,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,eAAe,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACxC,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,sBAAsB,CAC3C,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,QAAQ,GAAE,MAAsB,GAC9B,OAAO,CAAC,cAAc,CAAC,CAiEzB;AAED,MAAM,WAAW,gBAAgB;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAsB,GAAG,gBAAgB,CAS7G","sourcesContent":["/**\n * Plugin install/uninstall/discovery — the shared engine behind both the\n * `/plugin` slash command (human-driven) and the model-facing lifecycle tools\n * (`SearchPlugins`, `InstallPlugin`, ...). Keeping it in one place means the two\n * surfaces can never drift on where plugins live or how sources resolve.\n *\n * Trust model (see docs/plugin-system-spec.md): *adding* a marketplace is the\n * human trust boundary; *installing* from an already-trusted marketplace is the\n * model's discretion (package-manager model), and must stay transparent and\n * reversible. This module performs the mechanical install/remove; the gating\n * (announce, injection carve-out) lives with the callers.\n */\n\nimport { spawn } from \"node:child_process\";\nimport { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from \"node:fs\";\nimport * as os from \"node:os\";\nimport * as path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { getAgentDir } from \"../../../config.js\";\nimport { defaultPluginDirs } from \"../loader.js\";\nimport { hasAnyManifest } from \"./formats/index.js\";\nimport type { MarketplacePlatform } from \"./formats/types.js\";\nimport { discoverPlugins } from \"./index.js\";\nimport {\n\tcandidatePluginDirs,\n\tconsumptionPluginsDir,\n\tmarketplaceCacheDir,\n\tmarketplaceCacheMetaPath,\n\tmarketplaceCacheRoot,\n\tmarketplaceStorePath,\n\tsanitizeForDir,\n} from \"./locations.js\";\nimport type { NormalizedPlugin } from \"./manifest.js\";\nimport { parsePluginDir } from \"./manifest.js\";\nimport {\n\ttype MarketplacePluginSource,\n\ttype MarketplaceRecord,\n\tparseMarketplaceDir,\n\treadMarketplaceStore,\n\tresolvePluginSource,\n} from \"./marketplace.js\";\n\n/**\n * Marketplace registries older versions wrote into the working tree, newest\n * convention first. Still read so a user who added a marketplace before the\n * registry moved to the agent dir does not silently lose it; nothing writes here.\n */\nfunction legacyStorePaths(cwd: string): string[] {\n\treturn [path.join(cwd, \".agents\", \"marketplaces.json\"), path.join(cwd, \".hoocode\", \"marketplaces.json\")];\n}\n\n/** Absolute path to the curated default marketplace bundled with hoocode. */\nfunction defaultMarketplaceDir(): string {\n\treturn fileURLToPath(new URL(\"./default-marketplace/\", import.meta.url));\n}\n\n/** The default marketplace record — always present so source-level trust is meaningful out of the box. */\nexport function defaultMarketplaceRecord(): MarketplaceRecord {\n\treturn { location: \"hoocode-default\", dir: defaultMarketplaceDir() };\n}\n\n/**\n * Curated well-known marketplaces, trusted out of the box. Shipping an entry\n * here is a maintainer-level trust decision (the human half of the \"adding a\n * marketplace is the human trust boundary\" rule) — keep this list short and\n * high-trust. Indices are cloned lazily into the marketplace cache on first\n * search and refreshed on a TTL thereafter. Refreshing the *index* only changes\n * what is discoverable; installed plugins are still never auto-updated, and\n * plugin sources inside the official index are sha-pinned.\n */\nexport const WELL_KNOWN_MARKETPLACES: ReadonlyArray<{ name: string; url: string }> = [\n\t{ name: \"claude-plugins-official\", url: \"https://github.com/anthropics/claude-plugins-official\" },\n\t// The Copilot plugin directory ships both a `.github/plugin/marketplace.json`\n\t// and a `.claude-plugin/marketplace.json`, so it parses with\n\t// supportPlatform [\"claude\", \"github\"] — the default `github` source.\n\t{ name: \"copilot-plugins\", url: \"https://github.com/github/copilot-plugins\" },\n];\n\n/**\n * How long a cached marketplace index is considered fresh.\n *\n * Refreshing an *index* is safe to automate: it changes what is discoverable,\n * not what is installed. The rule that an installed plugin is never auto-updated\n * from a remote is untouched — that is the supply-chain boundary, and this is a\n * catalog listing.\n */\nconst MARKETPLACE_TTL_MS = 24 * 60 * 60 * 1000;\n\nfunction marketplaceTtlMs(): number {\n\tconst raw = Number(process.env.HOOCODE_MARKETPLACE_TTL_MS);\n\treturn Number.isFinite(raw) && raw >= 0 ? raw : MARKETPLACE_TTL_MS;\n}\n\ntype CacheMeta = Record<string, string>;\n\nfunction readCacheMeta(agentDir: string): CacheMeta {\n\tconst parsed = readJsonFile<CacheMeta>(marketplaceCacheMetaPath(agentDir));\n\treturn parsed && typeof parsed === \"object\" ? parsed : {};\n}\n\nfunction recordFetch(agentDir: string, url: string): void {\n\tconst meta = readCacheMeta(agentDir);\n\tmeta[url] = new Date().toISOString();\n\tconst file = marketplaceCacheMetaPath(agentDir);\n\tmkdirSync(path.dirname(file), { recursive: true });\n\twriteFileSync(file, `${JSON.stringify(meta, null, 2)}\\n`, \"utf8\");\n}\n\nfunction isStale(agentDir: string, url: string): boolean {\n\tconst ttl = marketplaceTtlMs();\n\tif (ttl === 0) return true;\n\tconst at = readCacheMeta(agentDir)[url];\n\tif (!at) return true;\n\tconst age = Date.now() - Date.parse(at);\n\treturn !Number.isFinite(age) || age > ttl;\n}\n\nfunction readJsonFile<T>(file: string): T | null {\n\ttry {\n\t\treturn JSON.parse(readFileSync(file, \"utf8\")) as T;\n\t} catch {\n\t\treturn null;\n\t}\n}\n\n/**\n * Bring an existing clone up to date, falling back to a fresh clone when the pull\n * cannot fast-forward (a force-pushed remote, or a corrupt cache).\n *\n * The re-clone goes to a temp directory and is swapped in only on success. An\n * earlier version deleted the cache first, which meant a refresh attempted while\n * offline destroyed a perfectly good index — the opposite of the \"offline is\n * non-fatal\" property the caller depends on.\n */\nasync function refreshClone(url: string, dir: string): Promise<{ code: number; stdout: string; stderr: string }> {\n\tconst pulled = await execGit([\"-C\", dir, \"pull\", \"--ff-only\"]);\n\tif (pulled.code === 0) return pulled;\n\n\tconst staging = mkdtempSync(path.join(os.tmpdir(), \"hoo-market-refresh-\"));\n\tconst target = path.join(staging, \"clone\");\n\tconst cloned = await cloneGitRepo(url, target);\n\tif (cloned.code !== 0) {\n\t\trmSync(staging, { recursive: true, force: true });\n\t\treturn cloned;\n\t}\n\trmSync(dir, { recursive: true, force: true });\n\tmkdirSync(path.dirname(dir), { recursive: true });\n\ttry {\n\t\trenameSync(target, dir);\n\t} catch {\n\t\tcpSync(target, dir, { recursive: true });\n\t}\n\trmSync(staging, { recursive: true, force: true });\n\treturn cloned;\n}\n\nexport interface EnsureMarketplacesOptions {\n\t/** Refresh regardless of the TTL. */\n\tforce?: boolean;\n}\n\n/**\n * Make sure every well-known marketplace index is cached and reasonably fresh.\n *\n * Clones what is missing and pulls what has gone stale. Without the TTL the\n * indices were fetched exactly once and never again, so a plugin added upstream\n * stayed permanently invisible — the inherit half of the system quietly stopped\n * inheriting. Offline is non-fatal: each failure is returned and search degrades\n * to whatever is already on disk.\n */\nexport async function ensureWellKnownMarketplaces(\n\tagentDir: string = getAgentDir(),\n\toptions: EnsureMarketplacesOptions = {},\n): Promise<string[]> {\n\tconst errors: string[] = [];\n\tfor (const wk of WELL_KNOWN_MARKETPLACES) {\n\t\tconst dir = marketplaceCacheDir(wk.url, agentDir);\n\t\tconst present = existsSync(dir);\n\t\tif (present && !options.force && !isStale(agentDir, wk.url)) continue;\n\n\t\tmkdirSync(path.dirname(dir), { recursive: true });\n\t\tconst res = present ? await refreshClone(wk.url, dir) : await cloneGitRepo(wk.url, dir);\n\t\tif (res.code !== 0) {\n\t\t\t// A failed *refresh* keeps the stale copy: an out-of-date index is far\n\t\t\t// more useful than none, and the network may simply be down.\n\t\t\tif (!present) rmSync(dir, { recursive: true, force: true });\n\t\t\terrors.push(`${wk.name}: ${(res.stderr || res.stdout).trim()}`);\n\t\t\tcontinue;\n\t\t}\n\t\trecordFetch(agentDir, wk.url);\n\t}\n\treturn errors;\n}\n\n/**\n * Refresh every cached index — well-known and user-added — ignoring the TTL.\n * The explicit half of the freshness story, for when a user knows the upstream\n * changed and does not want to wait out the interval.\n */\nexport async function refreshMarketplaces(\n\tcwd: string,\n\tagentDir: string = getAgentDir(),\n): Promise<{ refreshed: string[]; errors: string[] }> {\n\tconst errors = await ensureWellKnownMarketplaces(agentDir, { force: true });\n\tconst refreshed = WELL_KNOWN_MARKETPLACES.filter((wk) => existsSync(marketplaceCacheDir(wk.url, agentDir))).map(\n\t\t(wk) => wk.name,\n\t);\n\n\t// User-added marketplaces are cached the same way when they came from git; a\n\t// local-path marketplace is read in place and has nothing to refresh.\n\tfor (const record of readMarketplaceRecords(cwd, agentDir)) {\n\t\tconst isCachedClone = record.dir.startsWith(marketplaceCacheRoot(agentDir));\n\t\tif (!isCachedClone || WELL_KNOWN_MARKETPLACES.some((wk) => wk.url === record.location)) continue;\n\t\tconst res = await refreshClone(record.location, record.dir);\n\t\tif (res.code !== 0) errors.push(`${record.location}: ${(res.stderr || res.stdout).trim()}`);\n\t\telse {\n\t\t\trecordFetch(agentDir, record.location);\n\t\t\trefreshed.push(record.location);\n\t\t}\n\t}\n\treturn { refreshed, errors };\n}\n\n/**\n * All marketplace records in effect: the bundled default first (curated,\n * trusted), then user-added ones from `.agents/` (falling back to legacy\n * `.hoocode/`). Deduplicated by directory.\n */\nexport function readMarketplaceRecords(cwd: string, agentDir: string = getAgentDir()): MarketplaceRecord[] {\n\tconst records: MarketplaceRecord[] = [];\n\tconst def = defaultMarketplaceRecord();\n\tif (existsSync(def.dir)) records.push(def);\n\n\t// Well-known marketplaces participate once their index is cached locally\n\t// (see ensureWellKnownMarketplaces; SearchPlugins fetches lazily).\n\tfor (const wk of WELL_KNOWN_MARKETPLACES) {\n\t\tconst dir = marketplaceCacheDir(wk.url, agentDir);\n\t\tif (existsSync(dir) && !records.some((x) => x.dir === dir)) {\n\t\t\trecords.push({ location: wk.url, dir });\n\t\t}\n\t}\n\n\t// The registry lives in the agent dir. Project-local ones are a migration\n\t// read-path: merged in, never written back, so an older setup keeps working.\n\tconst user = [\n\t\t...readMarketplaceStore(marketplaceStorePath(agentDir)),\n\t\t...legacyStorePaths(cwd).flatMap((p) => readMarketplaceStore(p)),\n\t];\n\tfor (const r of user) {\n\t\tif (!records.some((x) => x.dir === r.dir)) records.push(r);\n\t}\n\treturn records;\n}\n\n/** A plugin offered by some registered marketplace (not necessarily installed). */\nexport interface AvailablePlugin {\n\tname: string;\n\tdescription?: string;\n\t/** Relative path, git URL, `npm:<spec>`, or structured source object. */\n\tsource: MarketplacePluginSource;\n\t/** Resolved source kind, for display and gating. */\n\tsourceKind: \"local\" | \"git\" | \"git-subdir\" | \"npm\";\n\tmarketplaceName: string;\n\tmarketplaceRoot: string;\n\t/** Platforms this entry targets (per-entry hint, else the marketplace's). */\n\tsupportPlatform: MarketplacePlatform[];\n}\n\n/** Every plugin offered across all registered marketplaces (first marketplace wins on name clash). */\nexport function listAvailablePlugins(cwd: string, agentDir: string = getAgentDir()): AvailablePlugin[] {\n\tconst out: AvailablePlugin[] = [];\n\tconst seen = new Set<string>();\n\tfor (const rec of readMarketplaceRecords(cwd, agentDir)) {\n\t\tconst market = parseMarketplaceDir(rec.dir);\n\t\tif (!market) continue;\n\t\tfor (const entry of market.plugins) {\n\t\t\tif (seen.has(entry.name)) continue;\n\t\t\tseen.add(entry.name);\n\t\t\tout.push({\n\t\t\t\tname: entry.name,\n\t\t\t\tdescription: entry.description,\n\t\t\t\tsource: entry.source,\n\t\t\t\tsourceKind: resolvePluginSource(entry.source, market.root).kind,\n\t\t\t\tmarketplaceName: market.name,\n\t\t\t\tmarketplaceRoot: market.root,\n\t\t\t\tsupportPlatform: entry.supportPlatform ?? market.supportPlatform,\n\t\t\t});\n\t\t}\n\t}\n\treturn out;\n}\n\n/** Find a single available plugin by exact name. */\nexport function findAvailablePlugin(\n\tcwd: string,\n\tname: string,\n\tagentDir: string = getAgentDir(),\n): AvailablePlugin | undefined {\n\treturn listAvailablePlugins(cwd, agentDir).find((p) => p.name === name);\n}\n\n/** All currently installed plugins (project + global plugin dirs). */\nexport function listInstalledPlugins(cwd: string, agentDir: string = getAgentDir()): NormalizedPlugin[] {\n\treturn discoverPlugins(defaultPluginDirs(cwd, agentDir));\n}\n\n/** Whether a plugin with `name` (by id) is already installed. */\nexport function isPluginInstalled(cwd: string, name: string, agentDir: string = getAgentDir()): boolean {\n\treturn listInstalledPlugins(cwd, agentDir).some((p) => p.id === name);\n}\n\nfunction execGit(args: string[]): Promise<{ code: number; stdout: string; stderr: string }> {\n\treturn new Promise((resolve) => {\n\t\tconst child = spawn(\"git\", args);\n\t\tlet stdout = \"\";\n\t\tlet stderr = \"\";\n\t\tchild.stdout?.on(\"data\", (d) => {\n\t\t\tstdout += d.toString();\n\t\t});\n\t\tchild.stderr?.on(\"data\", (d) => {\n\t\t\tstderr += d.toString();\n\t\t});\n\t\tchild.on(\"error\", (e) => resolve({ code: 1, stdout, stderr: stderr || String(e) }));\n\t\tchild.on(\"close\", (code) => resolve({ code: code ?? 1, stdout, stderr }));\n\t});\n}\n\n/**\n * Clone a git repository into `dest`.\n * If `ref` is provided, does a shallow clone of that branch/tag.\n * If only `sha` is provided, does a full clone and checks out the commit.\n * Returns the clone result; on failure `dest` may be partially created.\n */\nasync function cloneGitRepo(\n\turl: string,\n\tdest: string,\n\tref?: string,\n\tsha?: string,\n): Promise<{ code: number; stdout: string; stderr: string }> {\n\tif (ref) {\n\t\treturn execGit([\"clone\", \"--branch\", ref, \"--depth\", \"1\", \"--\", url, dest]);\n\t}\n\tif (sha) {\n\t\tconst cloneRes = await execGit([\"clone\", \"--\", url, dest]);\n\t\tif (cloneRes.code !== 0) return cloneRes;\n\t\treturn execGit([\"-C\", dest, \"checkout\", \"--quiet\", sha]);\n\t}\n\treturn execGit([\"clone\", \"--depth\", \"1\", \"--\", url, dest]);\n}\n\n/**\n * Resolve a git-subdir source: clone the repo, checkout the requested ref/sha,\n * and copy the subdirectory to `dest`. Cleans up the temporary clone on failure.\n */\nasync function installGitSubdir(\n\turl: string,\n\tsubdir: string,\n\tdest: string,\n\tref?: string,\n\tsha?: string,\n): Promise<{ ok: true } | { ok: false; message: string }> {\n\tconst tmpDir = mkdtempSync(path.join(os.tmpdir(), \"hoo-plugin-clone-\"));\n\ttry {\n\t\tconst cloneRes = await cloneGitRepo(url, tmpDir, ref, sha);\n\t\tif (cloneRes.code !== 0) {\n\t\t\treturn { ok: false, message: `git clone failed: ${cloneRes.stderr || cloneRes.stdout}`.trim() };\n\t\t}\n\t\tconst src = path.resolve(tmpDir, subdir);\n\t\tif (!existsSync(src)) {\n\t\t\treturn { ok: false, message: `Plugin subdirectory not found in cloned repo: ${subdir}` };\n\t\t}\n\t\tcpSync(src, dest, { recursive: true });\n\t\treturn { ok: true };\n\t} finally {\n\t\trmSync(tmpDir, { recursive: true, force: true });\n\t}\n}\n\nexport interface InstallOutcome {\n\tinstalled: boolean;\n\t/** Install destination directory (when installed). */\n\tdest?: string;\n\t/** Platforms the installed plugin supports (read back from disk). */\n\tsupportPlatform?: MarketplacePlatform[];\n\t/** Human-readable summary suitable for a tool result or notification. */\n\tmessage: string;\n}\n\n/**\n * Install an available plugin by name into the **consumption home** — the global\n * `~/.agents/plugins/`, not the working tree. A plugin is portable and reusable\n * across projects, so installing into the repo would both dirty `git status` and\n * hide the capability from every other checkout.\n *\n * Copies local sources; clones git sources. Transparent + reversible by\n * construction — the plugin lands in a named directory and\n * {@link uninstallPlugin} removes it. Callers activate the result (live\n * activation via AgentSession.activatePlugin, or a reload).\n */\nexport async function installAvailablePlugin(\n\tcwd: string,\n\tname: string,\n\tagentDir: string = getAgentDir(),\n): Promise<InstallOutcome> {\n\tconst found = findAvailablePlugin(cwd, name, agentDir);\n\tif (!found) return { installed: false, message: `Plugin \"${name}\" not found in any registered marketplace.` };\n\n\tconst resolved = resolvePluginSource(found.source, found.marketplaceRoot);\n\tconst home = consumptionPluginsDir(agentDir);\n\tconst dest = path.join(home, sanitizeForDir(name));\n\trmSync(dest, { recursive: true, force: true });\n\tmkdirSync(home, { recursive: true });\n\n\tif (resolved.kind === \"local\") {\n\t\tif (!existsSync(resolved.path)) {\n\t\t\treturn { installed: false, message: `Plugin source path not found: ${resolved.path}` };\n\t\t}\n\t\tcpSync(resolved.path, dest, { recursive: true });\n\t} else if (resolved.kind === \"git\") {\n\t\tconst res = await cloneGitRepo(resolved.url, dest, resolved.ref, resolved.sha);\n\t\tif (res.code !== 0) {\n\t\t\trmSync(dest, { recursive: true, force: true });\n\t\t\treturn { installed: false, message: `git clone failed: ${res.stderr || res.stdout}`.trim() };\n\t\t}\n\t} else if (resolved.kind === \"git-subdir\") {\n\t\tconst res = await installGitSubdir(resolved.url, resolved.path, dest, resolved.ref, resolved.sha);\n\t\tif (!res.ok) {\n\t\t\trmSync(dest, { recursive: true, force: true });\n\t\t\treturn { installed: false, message: res.message };\n\t\t}\n\t} else {\n\t\treturn { installed: false, message: `npm plugin sources are not supported yet (${resolved.spec}).` };\n\t}\n\n\tlet parsed = parsePluginDir(dest);\n\tif (!hasAnyManifest(dest)) {\n\t\t// Manifest-less plugin dir (some marketplaces index bare capability trees,\n\t\t// e.g. a plugin that is just a `skills/` directory). Such a directory now\n\t\t// *parses* on its own — the vendors make the manifest optional — but the\n\t\t// entry's name and description live only in the marketplace index, and the\n\t\t// derived id would be the sanitized directory name. Synthesize a native\n\t\t// manifest so both survive the install.\n\t\tconst manifestDir = path.join(dest, \".agents-plugin\");\n\t\tmkdirSync(manifestDir, { recursive: true });\n\t\twriteFileSync(\n\t\t\tpath.join(manifestDir, \"plugin.json\"),\n\t\t\t`${JSON.stringify(\n\t\t\t\t{ name: found.name, ...(found.description ? { description: found.description } : {}) },\n\t\t\t\tnull,\n\t\t\t\t2,\n\t\t\t)}\\n`,\n\t\t\t\"utf8\",\n\t\t);\n\t\tparsed = parsePluginDir(dest);\n\t}\n\tif (!parsed) {\n\t\trmSync(dest, { recursive: true, force: true });\n\t\treturn { installed: false, message: `Installed source for \"${name}\" has no recognizable plugin manifest.` };\n\t}\n\treturn {\n\t\tinstalled: true,\n\t\tdest,\n\t\tsupportPlatform: parsed.supportPlatform,\n\t\tmessage:\n\t\t\t`Installed \"${name}\" from marketplace \"${found.marketplaceName}\" ` +\n\t\t\t`(${parsed.supportPlatform.join(\", \")}) to ${dest}. ` +\n\t\t\t`Remove it with UninstallPlugin.`,\n\t};\n}\n\nexport interface UninstallOutcome {\n\tremoved: boolean;\n\tmessage: string;\n}\n\n/**\n * Remove an installed or authored plugin from every location it could occupy:\n * the consumption home, both production homes, and the legacy project-local\n * directories that older versions wrote into.\n */\nexport function uninstallPlugin(cwd: string, name: string, agentDir: string = getAgentDir()): UninstallOutcome {\n\tconst candidates = [\n\t\t...candidatePluginDirs(cwd, name, agentDir),\n\t\tpath.join(cwd, \".hoocode\", \"plugins\", sanitizeForDir(name)),\n\t];\n\tconst present = candidates.filter((p) => existsSync(p));\n\tif (present.length === 0) return { removed: false, message: `Plugin \"${name}\" is not installed.` };\n\tfor (const p of present) rmSync(p, { recursive: true, force: true });\n\treturn { removed: true, message: `Removed \"${name}\".` };\n}\n"]}

package/dist/core/extensions/plugins/install.js

@@ -11,28 +11,24 @@
  * (announce, injection carve-out) lives with the callers.
  */
 import { spawn } from "node:child_process";
-import { cpSync, existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { getAgentDir } from "../../../config.js";
 import { defaultPluginDirs } from "../loader.js";
+import { hasAnyManifest } from "./formats/index.js";
 import { discoverPlugins } from "./index.js";
+import { candidatePluginDirs, consumptionPluginsDir, marketplaceCacheDir, marketplaceCacheMetaPath, marketplaceCacheRoot, marketplaceStorePath, sanitizeForDir, } from "./locations.js";
 import { parsePluginDir } from "./manifest.js";
 import { parseMarketplaceDir, readMarketplaceStore, resolvePluginSource, } from "./marketplace.js";
-/** `.agents/` is the primary, cross-vendor home for installed plugins and the added-marketplace registry. */
-export function installedPluginsDir(cwd) {
-    return path.join(cwd, ".agents", "plugins");
-}
-function marketplaceStorePath(cwd) {
-    return path.join(cwd, ".agents", "marketplaces.json");
-}
-function legacyStorePath(cwd) {
-    return path.join(cwd, ".hoocode", "marketplaces.json");
-}
-/** Filesystem-safe directory name derived from a plugin name (matches the `/plugin` command). */
-export function sanitizeForDir(s) {
-    return s.replace(/[^a-zA-Z0-9._-]+/g, "_").slice(0, 80);
+/**
+ * Marketplace registries older versions wrote into the working tree, newest
+ * convention first. Still read so a user who added a marketplace before the
+ * registry moved to the agent dir does not silently lose it; nothing writes here.
+ */
+function legacyStorePaths(cwd) {
+    return [path.join(cwd, ".agents", "marketplaces.json"), path.join(cwd, ".hoocode", "marketplaces.json")];
 }
 /** Absolute path to the curated default marketplace bundled with hoocode. */
 function defaultMarketplaceDir() {
@@ -47,8 +43,9 @@ export function defaultMarketplaceRecord() {
  * here is a maintainer-level trust decision (the human half of the "adding a
  * marketplace is the human trust boundary" rule) — keep this list short and
  * high-trust. Indices are cloned lazily into the marketplace cache on first
- * search and never auto-updated afterwards (plugin sources inside the official
- * index are sha-pinned).
+ * search and refreshed on a TTL thereafter. Refreshing the *index* only changes
+ * what is discoverable; installed plugins are still never auto-updated, and
+ * plugin sources inside the official index are sha-pinned.
  */
 export const WELL_KNOWN_MARKETPLACES = [
     { name: "claude-plugins-official", url: "https://github.com/anthropics/claude-plugins-official" },
@@ -57,37 +54,139 @@ export const WELL_KNOWN_MARKETPLACES = [
     // supportPlatform ["claude", "github"] — the default `github` source.
     { name: "copilot-plugins", url: "https://github.com/github/copilot-plugins" },
 ];
-/** Local cache directory for a marketplace fetched from `url` (same convention as `/plugin marketplace add`). */
-export function marketplaceCacheDir(cwd, url) {
-    return path.join(cwd, ".agents", "marketplace-cache", sanitizeForDir(url));
+/**
+ * How long a cached marketplace index is considered fresh.
+ *
+ * Refreshing an *index* is safe to automate: it changes what is discoverable,
+ * not what is installed. The rule that an installed plugin is never auto-updated
+ * from a remote is untouched — that is the supply-chain boundary, and this is a
+ * catalog listing.
+ */
+const MARKETPLACE_TTL_MS = 24 * 60 * 60 * 1000;
+function marketplaceTtlMs() {
+    const raw = Number(process.env.HOOCODE_MARKETPLACE_TTL_MS);
+    return Number.isFinite(raw) && raw >= 0 ? raw : MARKETPLACE_TTL_MS;
+}
+function readCacheMeta(agentDir) {
+    const parsed = readJsonFile(marketplaceCacheMetaPath(agentDir));
+    return parsed && typeof parsed === "object" ? parsed : {};
+}
+function recordFetch(agentDir, url) {
+    const meta = readCacheMeta(agentDir);
+    meta[url] = new Date().toISOString();
+    const file = marketplaceCacheMetaPath(agentDir);
+    mkdirSync(path.dirname(file), { recursive: true });
+    writeFileSync(file, `${JSON.stringify(meta, null, 2)}\n`, "utf8");
+}
+function isStale(agentDir, url) {
+    const ttl = marketplaceTtlMs();
+    if (ttl === 0)
+        return true;
+    const at = readCacheMeta(agentDir)[url];
+    if (!at)
+        return true;
+    const age = Date.now() - Date.parse(at);
+    return !Number.isFinite(age) || age > ttl;
+}
+function readJsonFile(file) {
+    try {
+        return JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Bring an existing clone up to date, falling back to a fresh clone when the pull
+ * cannot fast-forward (a force-pushed remote, or a corrupt cache).
+ *
+ * The re-clone goes to a temp directory and is swapped in only on success. An
+ * earlier version deleted the cache first, which meant a refresh attempted while
+ * offline destroyed a perfectly good index — the opposite of the "offline is
+ * non-fatal" property the caller depends on.
+ */
+async function refreshClone(url, dir) {
+    const pulled = await execGit(["-C", dir, "pull", "--ff-only"]);
+    if (pulled.code === 0)
+        return pulled;
+    const staging = mkdtempSync(path.join(os.tmpdir(), "hoo-market-refresh-"));
+    const target = path.join(staging, "clone");
+    const cloned = await cloneGitRepo(url, target);
+    if (cloned.code !== 0) {
+        rmSync(staging, { recursive: true, force: true });
+        return cloned;
+    }
+    rmSync(dir, { recursive: true, force: true });
+    mkdirSync(path.dirname(dir), { recursive: true });
+    try {
+        renameSync(target, dir);
+    }
+    catch {
+        cpSync(target, dir, { recursive: true });
+    }
+    rmSync(staging, { recursive: true, force: true });
+    return cloned;
 }
 /**
- * Clone any well-known marketplace index that is not in the local cache yet.
- * No-op (and no network) when every index is already cached. Returns one error
- * string per marketplace that could not be fetched (offline is non-fatal —
- * search degrades to the marketplaces already available).
+ * Make sure every well-known marketplace index is cached and reasonably fresh.
+ *
+ * Clones what is missing and pulls what has gone stale. Without the TTL the
+ * indices were fetched exactly once and never again, so a plugin added upstream
+ * stayed permanently invisible — the inherit half of the system quietly stopped
+ * inheriting. Offline is non-fatal: each failure is returned and search degrades
+ * to whatever is already on disk.
  */
-export async function ensureWellKnownMarketplaces(cwd) {
+export async function ensureWellKnownMarketplaces(agentDir = getAgentDir(), options = {}) {
     const errors = [];
     for (const wk of WELL_KNOWN_MARKETPLACES) {
-        const dir = marketplaceCacheDir(cwd, wk.url);
-        if (existsSync(dir))
+        const dir = marketplaceCacheDir(wk.url, agentDir);
+        const present = existsSync(dir);
+        if (present && !options.force && !isStale(agentDir, wk.url))
             continue;
         mkdirSync(path.dirname(dir), { recursive: true });
-        const res = await cloneGitRepo(wk.url, dir);
+        const res = present ? await refreshClone(wk.url, dir) : await cloneGitRepo(wk.url, dir);
         if (res.code !== 0) {
-            rmSync(dir, { recursive: true, force: true });
+            // A failed *refresh* keeps the stale copy: an out-of-date index is far
+            // more useful than none, and the network may simply be down.
+            if (!present)
+                rmSync(dir, { recursive: true, force: true });
             errors.push(`${wk.name}: ${(res.stderr || res.stdout).trim()}`);
+            continue;
         }
+        recordFetch(agentDir, wk.url);
     }
     return errors;
 }
+/**
+ * Refresh every cached index — well-known and user-added — ignoring the TTL.
+ * The explicit half of the freshness story, for when a user knows the upstream
+ * changed and does not want to wait out the interval.
+ */
+export async function refreshMarketplaces(cwd, agentDir = getAgentDir()) {
+    const errors = await ensureWellKnownMarketplaces(agentDir, { force: true });
+    const refreshed = WELL_KNOWN_MARKETPLACES.filter((wk) => existsSync(marketplaceCacheDir(wk.url, agentDir))).map((wk) => wk.name);
+    // User-added marketplaces are cached the same way when they came from git; a
+    // local-path marketplace is read in place and has nothing to refresh.
+    for (const record of readMarketplaceRecords(cwd, agentDir)) {
+        const isCachedClone = record.dir.startsWith(marketplaceCacheRoot(agentDir));
+        if (!isCachedClone || WELL_KNOWN_MARKETPLACES.some((wk) => wk.url === record.location))
+            continue;
+        const res = await refreshClone(record.location, record.dir);
+        if (res.code !== 0)
+            errors.push(`${record.location}: ${(res.stderr || res.stdout).trim()}`);
+        else {
+            recordFetch(agentDir, record.location);
+            refreshed.push(record.location);
+        }
+    }
+    return { refreshed, errors };
+}
 /**
  * All marketplace records in effect: the bundled default first (curated,
  * trusted), then user-added ones from `.agents/` (falling back to legacy
  * `.hoocode/`). Deduplicated by directory.
  */
-export function readMarketplaceRecords(cwd) {
+export function readMarketplaceRecords(cwd, agentDir = getAgentDir()) {
     const records = [];
     const def = defaultMarketplaceRecord();
     if (existsSync(def.dir))
@@ -95,15 +194,17 @@ export function readMarketplaceRecords(cwd) {
     // Well-known marketplaces participate once their index is cached locally
     // (see ensureWellKnownMarketplaces; SearchPlugins fetches lazily).
     for (const wk of WELL_KNOWN_MARKETPLACES) {
-        const dir = marketplaceCacheDir(cwd, wk.url);
+        const dir = marketplaceCacheDir(wk.url, agentDir);
         if (existsSync(dir) && !records.some((x) => x.dir === dir)) {
             records.push({ location: wk.url, dir });
         }
     }
-    const primary = readMarketplaceStore(marketplaceStorePath(cwd));
-    const user = primary.length > 0 || existsSync(marketplaceStorePath(cwd))
-        ? primary
-        : readMarketplaceStore(legacyStorePath(cwd));
+    // The registry lives in the agent dir. Project-local ones are a migration
+    // read-path: merged in, never written back, so an older setup keeps working.
+    const user = [
+        ...readMarketplaceStore(marketplaceStorePath(agentDir)),
+        ...legacyStorePaths(cwd).flatMap((p) => readMarketplaceStore(p)),
+    ];
     for (const r of user) {
         if (!records.some((x) => x.dir === r.dir))
             records.push(r);
@@ -111,10 +212,10 @@ export function readMarketplaceRecords(cwd) {
     return records;
 }
 /** Every plugin offered across all registered marketplaces (first marketplace wins on name clash). */
-export function listAvailablePlugins(cwd) {
+export function listAvailablePlugins(cwd, agentDir = getAgentDir()) {
     const out = [];
     const seen = new Set();
-    for (const rec of readMarketplaceRecords(cwd)) {
+    for (const rec of readMarketplaceRecords(cwd, agentDir)) {
         const market = parseMarketplaceDir(rec.dir);
         if (!market)
             continue;
@@ -136,8 +237,8 @@ export function listAvailablePlugins(cwd) {
     return out;
 }
 /** Find a single available plugin by exact name. */
-export function findAvailablePlugin(cwd, name) {
-    return listAvailablePlugins(cwd).find((p) => p.name === name);
+export function findAvailablePlugin(cwd, name, agentDir = getAgentDir()) {
+    return listAvailablePlugins(cwd, agentDir).find((p) => p.name === name);
 }
 /** All currently installed plugins (project + global plugin dirs). */
 export function listInstalledPlugins(cwd, agentDir = getAgentDir()) {
@@ -203,20 +304,25 @@ async function installGitSubdir(url, subdir, dest, ref, sha) {
     }
 }
 /**
- * Install an available plugin by name into `.agents/plugins`. Copies local
- * sources; clones git sources. Transparent + reversible by construction — the
- * plugin lands in a named directory and {@link uninstallPlugin} removes it.
- * Callers activate the result (live activation via AgentSession.activatePlugin,
- * or a reload).
+ * Install an available plugin by name into the **consumption home** — the global
+ * `~/.agents/plugins/`, not the working tree. A plugin is portable and reusable
+ * across projects, so installing into the repo would both dirty `git status` and
+ * hide the capability from every other checkout.
+ *
+ * Copies local sources; clones git sources. Transparent + reversible by
+ * construction — the plugin lands in a named directory and
+ * {@link uninstallPlugin} removes it. Callers activate the result (live
+ * activation via AgentSession.activatePlugin, or a reload).
  */
-export async function installAvailablePlugin(cwd, name) {
-    const found = findAvailablePlugin(cwd, name);
+export async function installAvailablePlugin(cwd, name, agentDir = getAgentDir()) {
+    const found = findAvailablePlugin(cwd, name, agentDir);
     if (!found)
         return { installed: false, message: `Plugin "${name}" not found in any registered marketplace.` };
     const resolved = resolvePluginSource(found.source, found.marketplaceRoot);
-    const dest = path.join(installedPluginsDir(cwd), sanitizeForDir(name));
+    const home = consumptionPluginsDir(agentDir);
+    const dest = path.join(home, sanitizeForDir(name));
     rmSync(dest, { recursive: true, force: true });
-    mkdirSync(installedPluginsDir(cwd), { recursive: true });
+    mkdirSync(home, { recursive: true });
     if (resolved.kind === "local") {
         if (!existsSync(resolved.path)) {
             return { installed: false, message: `Plugin source path not found: ${resolved.path}` };
@@ -241,10 +347,13 @@ export async function installAvailablePlugin(cwd, name) {
         return { installed: false, message: `npm plugin sources are not supported yet (${resolved.spec}).` };
     }
     let parsed = parsePluginDir(dest);
-    if (!parsed) {
+    if (!hasAnyManifest(dest)) {
         // Manifest-less plugin dir (some marketplaces index bare capability trees,
-        // e.g. a plugin that is just a `skills/` directory): synthesize a native
-        // manifest from the marketplace entry so the standard loader can carry it.
+        // e.g. a plugin that is just a `skills/` directory). Such a directory now
+        // *parses* on its own — the vendors make the manifest optional — but the
+        // entry's name and description live only in the marketplace index, and the
+        // derived id would be the sanitized directory name. Synthesize a native
+        // manifest so both survive the install.
         const manifestDir = path.join(dest, ".agents-plugin");
         mkdirSync(manifestDir, { recursive: true });
         writeFileSync(path.join(manifestDir, "plugin.json"), `${JSON.stringify({ name: found.name, ...(found.description ? { description: found.description } : {}) }, null, 2)}\n`, "utf8");
@@ -259,14 +368,18 @@ export async function installAvailablePlugin(cwd, name) {
         dest,
         supportPlatform: parsed.supportPlatform,
         message: `Installed "${name}" from marketplace "${found.marketplaceName}" ` +
-            `(${parsed.supportPlatform.join(", ")}) to ${path.relative(cwd, dest) || dest}. ` +
+            `(${parsed.supportPlatform.join(", ")}) to ${dest}. ` +
             `Remove it with UninstallPlugin.`,
     };
 }
-/** Remove an installed plugin from `.agents/plugins` (and the legacy `.hoocode/plugins`). */
-export function uninstallPlugin(cwd, name) {
+/**
+ * Remove an installed or authored plugin from every location it could occupy:
+ * the consumption home, both production homes, and the legacy project-local
+ * directories that older versions wrote into.
+ */
+export function uninstallPlugin(cwd, name, agentDir = getAgentDir()) {
     const candidates = [
-        path.join(installedPluginsDir(cwd), sanitizeForDir(name)),
+        ...candidatePluginDirs(cwd, name, agentDir),
         path.join(cwd, ".hoocode", "plugins", sanitizeForDir(name)),
     ];
     const present = candidates.filter((p) => existsSync(p));