Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

feat(marketplace): install Agentic QE (agentic-qe-fleet) from the ruflo marketplace (#3950)

Dragan Spiridonov1af3abedd7c1
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index c24d0855be..9bfe1496b4 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -51,6 +51,17 @@
"source": "./plugins/ruflo-testgen",
"description": "Test gap detection, coverage analysis, and automated test generation"
},
+ {
+ "name": "agentic-qe-fleet",
+ "source": {
+ "source": "git-subdir",
+ "url": "https://github.com/proffesor-for-testing/agentic-qe.git",
+ "path": "plugins/agentic-qe-fleet",
+ "ref": "v3.15.10",
+ "sha": "e5814a2f4f3d7995b87ebda9ad30e8a3d92cd555"
+ },
+ "description": "Agentic QE (external: maintained in proffesor-for-testing/agentic-qe, pinned to v3.15.10): a quality-engineering fleet with 11 QE agents, 9 skills, 9 commands, the agentic-qe MCP server pinned to the plugin version, and the aqe-mod guard that refuses destructive operations on AQE learning data"
+ },
{
"name": "ruflo-docs",
"source": "./plugins/ruflo-docs",
diff --git a/.github/workflows/all-plugins-smoke.yml b/.github/workflows/all-plugins-smoke.yml
index 098240a4ab..bb75272445 100644
--- a/.github/workflows/all-plugins-smoke.yml
+++ b/.github/workflows/all-plugins-smoke.yml
@@ -16,7 +16,11 @@ on:
branches: [main]
paths:
- 'plugins/**'
+ - '.claude-plugin/marketplace.json'
- 'scripts/smoke-all-plugins.mjs'
+ - 'scripts/external-plugins.mjs'
+ - 'tests/external-plugins.test.mjs'
+ - '.github/workflows/validate-marketplace.yml'
- 'scripts/audit-plugin-mcp-prefix.mjs'
- 'scripts/audit-skill-mcp-tools.mjs'
- 'verification/skill-mcp-tool-baseline.json'
@@ -33,7 +37,11 @@ on:
pull_request:
paths:
- 'plugins/**'
+ - '.claude-plugin/marketplace.json'
- 'scripts/smoke-all-plugins.mjs'
+ - 'scripts/external-plugins.mjs'
+ - 'tests/external-plugins.test.mjs'
+ - '.github/workflows/validate-marketplace.yml'
- 'scripts/audit-plugin-mcp-prefix.mjs'
- 'scripts/audit-skill-mcp-tools.mjs'
- 'verification/skill-mcp-tool-baseline.json'
@@ -49,12 +57,19 @@ on:
- '.github/workflows/all-plugins-smoke.yml'
workflow_dispatch:
+# The external-plugin smoke runs third-party code (scripts/external-plugins.mjs): the token can only read, and no checkout
+# keeps credentials in the workspace.
+permissions:
+ contents: read
+
jobs:
smoke-all:
runs-on: ubuntu-latest
- timeout-minutes: 10
+ timeout-minutes: 15
steps:
- uses: actions/checkout@v4
+ with:
+ persist-credentials: false
- uses: actions/setup-node@v4
with:
@@ -64,6 +79,9 @@ jobs:
run: |
npm install --prefix "$RUNNER_TEMP/esbuild" --no-audit --no-fund --no-package-lock [email protected] [email protected]
echo "ESBUILD=$RUNNER_TEMP/esbuild/node_modules/.bin/esbuild" >> "$GITHUB_ENV"
+ - name: External plugin checks (github-only source, realpath containment, scrubbed env and cwd)
+ run: node --test tests/external-plugins.test.mjs
+
- name: Discover and run every plugin smoke contract (parallel)
# --timeout 300 caps each individual plugin smoke at 5 minutes.
# iter 119 — bumped from 60s because ruflo-metaharness has grown
diff --git a/.github/workflows/validate-marketplace.yml b/.github/workflows/validate-marketplace.yml
index dc0e3306da..c33e152475 100644
--- a/.github/workflows/validate-marketplace.yml
+++ b/.github/workflows/validate-marketplace.yml
@@ -25,6 +25,20 @@ jobs:
console.log('Marketplace:', catalog.name);
console.log('Plugins:', catalog.plugins.length);
for (const p of catalog.plugins) {
+ // An external plugin (maintained in another repository) is listed by a git source pinned to a commit:
+ // its files are not in this repository, so only the entry itself is checked here; smoke-all-plugins
+ // checks out the pinned commit and runs the plugin's own smoke.
+ if (typeof p.source !== 'string') {
+ const s = p.source || {};
+ // Same rules as scripts/external-plugins.mjs: github.com/<owner>/<repo> only, a relative path of plain names without . or ..
+ const m = typeof s.url === 'string' ? /^https:\/\/github\.com\/([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)$/.exec(s.url) : null;
+ if (s.source !== 'git-subdir' || m === null || [m[1], m[2].replace(/\.git$/, '')].some((x) => x === '' || x === '.' || x === '..')) throw new Error('External plugin ' + p.name + ': source must be a git-subdir with url https://github.com/<owner>/<repo>');
+ if (typeof s.path !== 'string' || !/^[A-Za-z0-9._-]+(\/[A-Za-z0-9._-]+)*$/.test(s.path) || s.path.split('/').some((x) => x === '..' || x === '.')) throw new Error('External plugin ' + p.name + ': path must be a relative folder of plain names without . or ..');
+ if (typeof s.sha !== 'string' || s.sha.length !== 40 || /[^0-9a-f]/.test(s.sha)) throw new Error('External plugin ' + p.name + ': source must pin a full 40-character commit sha');
+ if (!p.description) throw new Error('External plugin ' + p.name + ': missing description');
+ console.log(' OK', p.name, '(external', s.url, s.path + '@' + (s.ref || s.sha) + ')');
+ continue;
+ }
const dir = p.source;
if (!fs.existsSync(dir)) throw new Error('Missing plugin dir: ' + dir);
const manifest = dir + '/.claude-plugin/plugin.json';
diff --git a/README.md b/README.md
index 180cf8868e..b42093667a 100644
--- a/README.md
+++ b/README.md
@@ -240,6 +240,7 @@ This adds slash commands and agent definitions. `ruflo-core` (installed above) d
| [**ruflo-browser**](plugins/ruflo-browser/README.md) | Automate browser testing with Playwright |
| [**ruflo-jujutsu**](plugins/ruflo-jujutsu/README.md) | Analyze git diffs, score risk, suggest reviewers |
| [**ruflo-docs**](plugins/ruflo-docs/README.md) | Generate and maintain documentation automatically |
+| [**agentic-qe-fleet**](https://github.com/proffesor-for-testing/agentic-qe/tree/v3.15.10/plugins/agentic-qe-fleet) | External, maintained by [Agentic QE](https://github.com/proffesor-for-testing/agentic-qe): 11 QE agents, test generation, coverage, chaos and TDD skills, the `agentic-qe` MCP server, and a guard for AQE learning data (`/plugin install agentic-qe-fleet@ruflo`). Install it from one marketplace only, `agentic-qe` or `ruflo`: enabled from both, its mod and commands load twice |
#### Security & Compliance
diff --git a/plugins/README.md b/plugins/README.md
index c9004174b5..0119ae13aa 100644
--- a/plugins/README.md
+++ b/plugins/README.md
@@ -53,6 +53,7 @@ claude $(ls -d plugins/ruflo-*/ | sed 's|^|--plugin-dir |' | tr '\n' ' ')
| [ruflo-protector](ruflo-protector/) | Project Anatole: optional learning watchdog for unattended agents (default off) |
| [ruflo-testgen](ruflo-testgen/) | Test gap detection, TDD London School workflow |
| [ruflo-browser](ruflo-browser/) | Playwright browser automation and testing |
+| [agentic-qe-fleet](https://github.com/proffesor-for-testing/agentic-qe/tree/v3.15.10/plugins/agentic-qe-fleet) | External ([Agentic QE](https://github.com/proffesor-for-testing/agentic-qe), pinned in the marketplace): QE agents, coverage, chaos, TDD skills, `agentic-qe` MCP server. Install with `/plugin install agentic-qe-fleet@ruflo`; not in this folder, so `--plugin-dir` does not load it. Install it from one marketplace only (`agentic-qe` or `ruflo`), not both: enabled from both, its mod and commands load twice |
### Development Tools
diff --git a/plugins/ruflo-console/hooks/data/plugin-catalog.ts b/plugins/ruflo-console/hooks/data/plugin-catalog.ts
index e5c5c78e09..fdc4f5a91b 100644
--- a/plugins/ruflo-console/hooks/data/plugin-catalog.ts
+++ b/plugins/ruflo-console/hooks/data/plugin-catalog.ts
@@ -1,7 +1,9 @@
/**
* The ruflo marketplace as a catalog: every plugin its clone lists, with the skills, agents, commands, MCP config and
- * mod (function hooks) each ships, read from the clone on disk. Read-only, bounded, nothing run: a file over the cap,
- * a name that is not a plain word and a path with `..` are skipped, and every read may be refused.
+ * mod (function hooks) each ships, read from the clone on disk. An external plugin (listed by a git source, maintained in
+ * another repository) has no copy in the clone: it is read from its install path in `installed_plugins.json` when it is
+ * installed. Read-only, bounded, nothing run: a file over the cap, a name that is not a plain word and a path with `..`
+ * are skipped, and every read may be refused.
*/
import type { ReaderFs } from './files'
import { plain } from './parse'
@@ -10,7 +12,7 @@ export type CatalogPlugin = {
name: string
description: string
version: string | null
- /** Folder of the plugin inside the clone (absolute). */
+ /** Folder of the plugin inside the clone, or of the installed copy of an external one (absolute); '' when there is neither. */
dir: string
skills: string[]
agents: string[]
@@ -20,6 +22,8 @@ export type CatalogPlugin = {
options: string[]
/** A `hooks/register.ts` makes it a mod: function hooks run in the engine. */
isMod: boolean
+ /** Set for an external plugin: the repository, folder and ref the marketplace pins it to. */
+ external?: string
}
const NAME = /^[A-Za-z0-9._-]{1,80}$/
@@ -48,15 +52,34 @@ async function namesIn(fs: ReaderFs, dir: string, kind: 'dir' | 'md'): Promise<s
.slice(0, LIST_MAX)
}
+/** An external source (`git-subdir`, `github`, `git`, `url`) as one plain line, or null for anything else. */
+function externalOf(source: unknown): string | null {
+ const record = recordOf(source)
+ const at = (value: unknown) => (typeof value === 'string' ? value : '')
+
+ if (record === null || !['git-subdir', 'github', 'git', 'url'].includes(at(record.source))) return null
+
+ const where = [at(record.url) || at(record.repo), at(record.path)].filter(Boolean).join(' ')
+ const ref = at(record.ref) || at(record.sha).slice(0, 12)
+
+ return where === '' ? null : plain(`${where}${ref === '' ? '' : ` @ ${ref}`}`, 200)
+}
+
const exists = async (fs: ReaderFs, path: string): Promise<boolean> => (await fs.stat(path).catch(() => undefined)) !== undefined
-async function pluginOf(fs: ReaderFs, location: string, entry: Record<string, unknown>): Promise<CatalogPlugin | null> {
+async function pluginOf(fs: ReaderFs, location: string, entry: Record<string, unknown>, installed: ReadonlyMap<string, string>): Promise<CatalogPlugin | null> {
const name = entry.name
const source = safeSource(entry.source)
+ const external = source === null ? externalOf(entry.source) : null
- if (typeof name !== 'string' || !NAME.test(name) || source === null) return null
+ if (typeof name !== 'string' || !NAME.test(name) || (source === null && external === null)) return null
+
+ const dir = source !== null ? `${location}/${source}` : (installed.get(name) ?? '')
+
+ if (dir === '') {
+ return { name, options: [], description: plain(typeof entry.description === 'string' ? entry.description : '', 400), version: null, dir, skills: [], agents: [], commands: [], hasMcp: false, isMod: false, ...(external !== null && { external }) }
+ }
- const dir = `${location}/${source}`
const manifest = await fs.read(`${dir}/.claude-plugin/plugin.json`).then(
text => recordOf(JSON.parse(text)),
() => null,
@@ -66,11 +89,14 @@ async function pluginOf(fs: ReaderFs, location: string, entry: Record<string, un
const options = Object.keys(recordOf(manifest?.userConfig) ?? {}).filter(key => NAME.test(key)).slice(0, 60)
- return { name, options, description: plain(typeof entry.description === 'string' ? entry.description : typeof manifest?.description === 'string' ? manifest.description : '', 400), version, dir, skills, agents, commands, hasMcp, isMod }
+ return { name, options, description: plain(typeof entry.description === 'string' ? entry.description : typeof manifest?.description === 'string' ? manifest.description : '', 400), version, dir, skills, agents, commands, hasMcp, isMod, ...(external !== null && { external }) }
}
-/** Every plugin the marketplace clone at `location` lists, or null when its manifest cannot be read. */
-export async function readCatalog(fs: ReaderFs, location: string): Promise<CatalogPlugin[] | null> {
+/**
+ * Every plugin the marketplace clone at `location` lists, or null when its manifest cannot be read. `installed` maps a plugin name to
+ * its install path (absolute, already checked by the caller): an external plugin is read from there.
+ */
+export async function readCatalog(fs: ReaderFs, location: string, installed: ReadonlyMap<string, string> = new Map()): Promise<CatalogPlugin[] | null> {
if (!location.startsWith('/') || location.split('/').includes('..')) return null
const raw = await fs.read(`${location}/.claude-plugin/marketplace.json`).catch(() => null)
@@ -94,7 +120,7 @@ export async function readCatalog(fs: ReaderFs, location: string): Promise<Catal
list.slice(at, at + 8).map(async entry => {
const record = recordOf(entry)
- return record === null ? null : pluginOf(fs, location, record).catch(() => null)
+ return record === null ? null : pluginOf(fs, location, record, installed).catch(() => null)
}),
)
@@ -106,7 +132,7 @@ export async function readCatalog(fs: ReaderFs, location: string): Promise<Catal
/** A skill, agent or command file's first lines (and its frontmatter description), or null when it cannot be read. */
export async function readDoc(fs: ReaderFs, plugin: CatalogPlugin, kind: 'skill' | 'agent' | 'command', name: string): Promise<{ description: string; lines: string[] } | null> {
- if (!NAME.test(name)) return null
+ if (!NAME.test(name) || plugin.dir === '') return null
const path = kind === 'skill' ? `${plugin.dir}/skills/${name}/SKILL.md` : `${plugin.dir}/${kind === 'agent' ? 'agents' : 'commands'}/${name}.md`
const stat = await fs.stat(path).catch(() => undefined)
diff --git a/plugins/ruflo-console/hooks/plugin-catalog.ts b/plugins/ruflo-console/hooks/plugin-catalog.ts
index 1574624eb4..b7947553f9 100644
--- a/plugins/ruflo-console/hooks/plugin-catalog.ts
+++ b/plugins/ruflo-console/hooks/plugin-catalog.ts
@@ -8,6 +8,7 @@
*/
import type { ActionSpec } from './actions'
import { type CatalogMode, type CatalogPlugin, readCatalog, readDoc, visible } from './data/plugin-catalog'
+import { safeInstallPath } from './data/cost-ledger'
import { plain } from './data/parse'
import { RUFLO_MARKET } from './data/snapshot'
import type { Host } from './host'
@@ -131,7 +132,16 @@ export function loadCatalog(state: State, host: Host): void {
catalog.loading = true
host.invalidate()
- void readCatalog(host.fs, market.location)
+ // Where each installed ruflo plugin lives: an external one (no copy in the clone) is read from there.
+ const installed = new Map(
+ (state.snapshot?.plugins.installed ?? []).flatMap(plugin => {
+ const path = plugin.marketplace === RUFLO_MARKET ? safeInstallPath(plugin.installPath) : undefined
+
+ return path === undefined ? [] : [[plugin.name, path] as const]
+ }),
+ )
+
+ void readCatalog(host.fs, market.location, installed)
.then(plugins => {
catalog.plugins = plugins
catalog.why = plugins === null ? 'the clone’s marketplace.json is not readable' : plugins.length === 0 ? 'the clone lists no plugins' : ''
diff --git a/plugins/ruflo-console/hooks/plugin-map.ts b/plugins/ruflo-console/hooks/plugin-map.ts
index eb23f12158..c10ac9a4ef 100644
--- a/plugins/ruflo-console/hooks/plugin-map.ts
+++ b/plugins/ruflo-console/hooks/plugin-map.ts
@@ -1,8 +1,8 @@
/**
* Which console section owns each ruflo plugin: the section that launches its slash commands (the Launch row) and answers
- * "ask Claude" about it. Every plugin directory under `plugins/` appears here, and a test fails when one is added without a
- * line, so no plugin is ever unreachable from the console. A plugin with no section of its own says why (`catalogOnly`) and is
- * reached from the Plugin Catalog. Pure data.
+ * "ask Claude" about it. Every plugin directory under `plugins/`, and every external plugin the marketplace lists by a git
+ * source, appears here, and a test fails when one is added without a line, so no plugin is ever unreachable from the console.
+ * A plugin with no section of its own says why (`catalogOnly`) and is reached from the Plugin Catalog. Pure data.
*/
import type { ViewId } from './state'
@@ -12,6 +12,7 @@ const home = (view: ViewId): PluginHome => ({ view })
const catalog = (why: string): PluginHome => ({ view: 'market', catalogOnly: why })
export const PLUGIN_MAP: Readonly<Record<string, PluginHome>> = {
+ 'agentic-qe-fleet': home('devtools'),
'ruflo-adr': home('devtools'),
'ruflo-agent': home('swarm'),
'ruflo-agentdb': home('memory'),
diff --git a/plugins/ruflo-console/hooks/views/plugin-catalog.ts b/plugins/ruflo-console/hooks/views/plugin-catalog.ts
index fae6b63669..8d91623027 100644
--- a/plugins/ruflo-console/hooks/views/plugin-catalog.ts
+++ b/plugins/ruflo-console/hooks/views/plugin-catalog.ts
@@ -15,7 +15,7 @@ function verbOf(ctx: Ctx, plugin: CatalogPlugin): { verb: Verb; label: string }
}
function counts(plugin: CatalogPlugin): string {
- return [plugin.skills.length > 0 ? `S${plugin.skills.length}` : '', plugin.agents.length > 0 ? `A${plugin.agents.length}` : '', plugin.commands.length > 0 ? `C${plugin.commands.length}` : '', plugin.hasMcp ? 'MCP' : '', plugin.isMod ? 'MOD' : ''].filter(Boolean).join(' ')
+ return [plugin.skills.length > 0 ? `S${plugin.skills.length}` : '', plugin.agents.length > 0 ? `A${plugin.agents.length}` : '', plugin.commands.length > 0 ? `C${plugin.commands.length}` : '', plugin.hasMcp ? 'MCP' : '', plugin.isMod ? 'MOD' : '', plugin.external !== undefined ? 'EXT' : ''].filter(Boolean).join(' ')
}
/** One plugin row: the whole row selects it, the trailing button changes it. */
@@ -71,6 +71,10 @@ function detailRows(ctx: Ctx, plugin: CatalogPlugin): RenderElement[] {
row(ctx, [text(ctx, ' related ', { dimColor: true }), ...(home === null ? [] : [button(ctx, `cat-home-${plugin.name}`, `→ ${home.label}: its commands (Launch)`, () => ctx.act.view(home.view))]), button(ctx, `cat-health-${plugin.name}`, '→ Plugins: setup health', () => ctx.act.view('plugins'))], `cat-related-${plugin.name}`),
)
+ if (plugin.external !== undefined) {
+ rows.push(text(ctx, ` EXTERNAL: maintained outside ruflo, installed from ${plugin.external}`, { color: THEME.warn }))
+ if (plugin.dir === '') rows.push(text(ctx, ' its skills, agents and commands are listed once it is installed (the ruflo clone holds no copy)', { dimColor: true }))
+ }
if (plugin.isMod) rows.push(text(ctx, ' MOD: function hooks run in the engine once this plugin is loaded (trust it like code you run)', { color: THEME.warn }))
if (plugin.hasMcp) rows.push(text(ctx, ' MCP: ships an .mcp.json: its servers start with the plugin', { dimColor: true }))
diff --git a/plugins/ruflo-console/tests/plugin-catalog.spec.ts b/plugins/ruflo-console/tests/plugin-catalog.spec.ts
index 12f65b37de..c9cff6efba 100644
--- a/plugins/ruflo-console/tests/plugin-catalog.spec.ts
+++ b/plugins/ruflo-console/tests/plugin-catalog.spec.ts
@@ -4,6 +4,8 @@ import { readCatalog, readDoc, visible, type CatalogPlugin } from '../hooks/data
import type { ReaderFs } from '../hooks/data/files'
const ROOT = '/h/.claude/plugins/marketplaces/ruflo'
+const CACHE = '/h/.claude/plugins/cache/ruflo'
+const GIT = { source: 'git-subdir', url: 'https://example.com/qe.git', path: 'plugins/qe', ref: 'v2.0.0', sha: 'a'.repeat(40) }
const files: Record<string, string> = {
[`${ROOT}/.claude-plugin/marketplace.json`]: JSON.stringify({
plugins: [
@@ -11,6 +13,9 @@ const files: Record<string, string> = {
{ name: 'b-mod', source: './plugins/b-mod', description: 'A mod' },
{ name: 'evil', source: './../../etc', description: 'climbs out' },
{ name: 'bad name!', source: './plugins/x', description: 'not a word' },
+ { name: 'ext-installed', source: GIT, description: 'An external plugin, installed' },
+ { name: 'ext-missing', source: { ...GIT, path: 'plugins/other' }, description: 'An external plugin, not installed' },
+ { name: 'ext-odd', source: { source: 'npm', package: 'x' }, description: 'a source kind it does not read' },
],
}),
[`${ROOT}/plugins/a-plugin/.claude-plugin/plugin.json`]: '{"version":"1.2.3"}',
@@ -19,6 +24,10 @@ const files: Record<string, string> = {
[`${ROOT}/plugins/a-plugin/commands/go.md`]: 'x',
[`${ROOT}/plugins/a-plugin/.mcp.json`]: '{}',
[`${ROOT}/plugins/b-mod/hooks/register.ts`]: 'x',
+ [`${CACHE}/ext-installed/2.0.0/.claude-plugin/plugin.json`]: '{"version":"2.0.0","userConfig":{"guardMode":{}}}',
+ [`${CACHE}/ext-installed/2.0.0/commands/qe-go.md`]: '---\ndescription: Go\n---\n',
+ [`${CACHE}/ext-installed/2.0.0/.mcp.json`]: '{}',
+ [`${CACHE}/ext-installed/2.0.0/hooks/register.ts`]: 'x',
}
const fs: ReaderFs = {
@@ -38,14 +47,26 @@ const fs: ReaderFs = {
}
describe('plugin catalog reader', () => {
- it('lists each plugin with what it ships, skipping a climbing source and a non-word name', async () => {
+ it('lists each plugin with what it ships, skipping a climbing source, a non-word name and a source kind it does not read', async () => {
const plugins = (await readCatalog(fs, ROOT)) as CatalogPlugin[]
- expect(plugins.map(plugin => plugin.name)).toEqual(['a-plugin', 'b-mod'])
+ expect(plugins.map(plugin => plugin.name)).toEqual(['a-plugin', 'b-mod', 'ext-installed', 'ext-missing'])
expect(plugins[0]).toMatchObject({ version: '1.2.3', skills: ['alpha'], agents: ['helper'], commands: ['go'], hasMcp: true, isMod: false })
+ expect(plugins[0]?.external).toBeUndefined()
expect(plugins[1]).toMatchObject({ isMod: true, skills: [] })
})
+ it('reads an external plugin from its install path, and lists one that is not installed by its entry alone', async () => {
+ const plugins = (await readCatalog(fs, ROOT, new Map([['ext-installed', `${CACHE}/ext-installed/2.0.0`]]))) as CatalogPlugin[]
+ const installed = plugins.find(plugin => plugin.name === 'ext-installed') as CatalogPlugin
+ const missing = plugins.find(plugin => plugin.name === 'ext-missing') as CatalogPlugin
+
+ expect(installed).toMatchObject({ dir: `${CACHE}/ext-installed/2.0.0`, version: '2.0.0', commands: ['qe-go'], options: ['guardMode'], hasMcp: true, isMod: true, external: 'https://example.com/qe.git plugins/qe @ v2.0.0' })
+ expect((await readDoc(fs, installed, 'command', 'qe-go'))?.description).toBe('Go')
+ expect(missing).toMatchObject({ dir: '', version: null, skills: [], agents: [], commands: [], hasMcp: false, isMod: false, external: 'https://example.com/qe.git plugins/other @ v2.0.0' })
+ expect(await readDoc(fs, missing, 'command', 'qe-go')).toBeNull()
+ })
+
it('refuses a location with .. or a relative one, and a missing manifest', async () => {
expect(await readCatalog(fs, '/h/../etc')).toBeNull()
expect(await readCatalog(fs, 'relative/clone')).toBeNull()
@@ -66,10 +87,59 @@ describe('plugin catalog reader', () => {
const installed = new Set(['a-plugin'])
expect(visible(plugins, installed, 'installed', '').map(plugin => plugin.name)).toEqual(['a-plugin'])
- expect(visible(plugins, installed, 'missing', '').map(plugin => plugin.name)).toEqual(['b-mod'])
+ expect(visible(plugins, installed, 'missing', '').map(plugin => plugin.name)).toEqual(['b-mod', 'ext-installed', 'ext-missing'])
expect(visible(plugins, installed, 'mods', '').map(plugin => plugin.name)).toEqual(['b-mod'])
expect(visible(plugins, installed, 'all', 'alpha').map(plugin => plugin.name)).toEqual(['a-plugin'])
expect(visible(plugins, installed, 'skills', '').map(plugin => plugin.name)).toEqual(['a-plugin'])
expect(visible(plugins, installed, 'all', 'nothing-like-this')).toEqual([])
})
})
+
+describe('plugin catalog reader: hostile text from an external plugin', () => {
+ // ESC/CSI colour, an OSC 8 hyperlink and an OSC title, and the bidi embeddings, overrides and isolates (U+202A–202E, U+2066–2069),
+ // written as \u escapes so no control character sits in this source.
+ const ESC = '\u001b'
+ const BIDI = ['‪', '‫', '‬', '‭', '‮', '⁦', '⁧', '⁨', '⁩']
+ const hostile = `${ESC}[31mred${ESC}[0m ${ESC}]8;;https://evil.example${ESC}\\link${ESC}]8;;${ESC}\\ ${ESC}]0;title\u0007${BIDI.join('')}txt.exe`
+ const dir = `${CACHE}/ext-hostile/1.0.0`
+ const hostileFiles: Record<string, string> = {
+ [`${ROOT}/.claude-plugin/marketplace.json`]: JSON.stringify({ plugins: [{ name: 'ext-hostile', source: { ...GIT, url: `https://github.com/o/r${ESC}[2J` } }] }),
+ [`${dir}/.claude-plugin/plugin.json`]: JSON.stringify({ name: 'ext-hostile', version: `1.0.0${ESC}[2J${BIDI[4]}`, description: hostile }),
+ [`${dir}/commands/go.md`]: `---\ndescription: ${hostile}\n---\n${hostile}\n`,
+ [`${dir}/commands/${ESC}[2Jbad.md`]: 'x',
+ }
+ const hostileFs: ReaderFs = {
+ read: async path => {
+ if (!(path in hostileFiles)) throw new Error('ENOENT')
+
+ return hostileFiles[path] as string
+ },
+ stat: async path => (path in hostileFiles ? { size: (hostileFiles[path] as string).length } : undefined),
+ list: async path => {
+ const below = Object.keys(hostileFiles).filter(file => file.startsWith(`${path}/`)).map(file => file.slice(path.length + 1))
+
+ if (below.length === 0) throw new Error('ENOENT')
+
+ return [...new Set(below.map(name => name.split('/')[0] as string))].map(name => ({ name, kind: below.some(file => file === name) ? 'file' : 'dir' }))
+ },
+ }
+ const clean = (text: string) => {
+ expect(text).not.toMatch(/[\u0000-\u001f\u007f-\u009f]/)
+ for (const mark of BIDI) expect(text.includes(mark), `U+${mark.charCodeAt(0).toString(16)}`).toBe(false)
+ expect(text).not.toMatch(/\]8;;|\[31m|\[2J|\]0;/)
+ }
+
+ it('strips escape sequences and bidi controls from its description, version, source line and docs, and drops a hostile file name', async () => {
+ const [plugin] = (await readCatalog(hostileFs, ROOT, new Map([['ext-hostile', dir]]))) as CatalogPlugin[]
+
+ expect(plugin?.name).toBe('ext-hostile')
+ for (const text of [plugin?.description ?? '', plugin?.version ?? '', plugin?.external ?? '']) clean(text)
+ expect(plugin?.description).toBe('red link txt.exe')
+ expect(plugin?.commands).toEqual(['go'])
+
+ const doc = await readDoc(hostileFs, plugin as CatalogPlugin, 'command', 'go')
+
+ clean(doc?.description ?? 'missing')
+ for (const line of doc?.lines ?? []) clean(line)
+ })
+})
diff --git a/plugins/ruflo-console/tests/plugin-coverage.spec.ts b/plugins/ruflo-console/tests/plugin-coverage.spec.ts
index 1b29427665..2e1bfd6b10 100644
--- a/plugins/ruflo-console/tests/plugin-coverage.spec.ts
+++ b/plugins/ruflo-console/tests/plugin-coverage.spec.ts
@@ -1,8 +1,9 @@
/**
- * Plugin coverage: every ruflo plugin directory has a home section in the console, no entry names a plugin that is gone, every
- * home is a real view, and a plugin that has no surface of its own says why. A new plugin added without a line fails here.
+ * Plugin coverage: every ruflo plugin directory and every external plugin the marketplace lists has a home section in the
+ * console, no entry names a plugin that is gone, every home is a real view, and a plugin that has no surface of its own says
+ * why. A new plugin added without a line fails here.
*/
-import { existsSync, readdirSync } from 'node:fs'
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
import { join } from 'node:path'
import { describe, expect, it } from 'vitest'
@@ -14,6 +15,11 @@ const onDisk = readdirSync(PLUGINS, { withFileTypes: true })
.filter(entry => entry.isDirectory() && existsSync(join(PLUGINS, entry.name, '.claude-plugin', 'plugin.json')))
.map(entry => entry.name)
.sort()
+// An external plugin is listed by a git source (an object, not a `./plugins/...` path): it has no directory here.
+const external = (JSON.parse(readFileSync(join(PLUGINS, '..', '.claude-plugin', 'marketplace.json'), 'utf8')) as { plugins: { name: string; source: unknown }[] }).plugins
+ .filter(plugin => typeof plugin.source !== 'string')
+ .map(plugin => plugin.name)
+const known = [...onDisk, ...external]
describe('plugin coverage', () => {
it('finds the plugin directories (the guard is not checking nothing)', () => {
@@ -22,8 +28,8 @@ describe('plugin coverage', () => {
})
it('every plugin directory has a home section, and no home is for a plugin that is gone', () => {
- expect(onDisk.filter(name => PLUGIN_MAP[name] === undefined), 'unmapped plugins: add a line to hooks/plugin-map.ts').toEqual([])
- expect(Object.keys(PLUGIN_MAP).filter(name => !onDisk.includes(name)), 'stale entries').toEqual([])
+ expect(known.filter(name => PLUGIN_MAP[name] === undefined), 'unmapped plugins: add a line to hooks/plugin-map.ts').toEqual([])
+ expect(Object.keys(PLUGIN_MAP).filter(name => !known.includes(name)), 'stale entries').toEqual([])
})
it('every home is a real section, and a plugin without a surface of its own says why', () => {
@@ -41,6 +47,7 @@ describe('plugin coverage', () => {
it('homeOf reads a plugin name or a slash name; pluginsOfView lists what a section owns', () => {
expect(homeOf('ruflo-cost-tracker')).toBe('cost')
expect(homeOf('ruflo-ruos:deploy')).toBe('swarm')
+ expect(homeOf('agentic-qe-fleet:aqe-generate')).toBe('devtools')
expect(homeOf('not-a-plugin:thing')).toBeNull()
expect(pluginsOfView('secure')).toEqual(['ruflo-aidefence', 'ruflo-protector', 'ruflo-security-audit'])
})
diff --git a/scripts/ci-test-excluded.txt b/scripts/ci-test-excluded.txt
index 8a878b45aa..667a9b032c 100644
--- a/scripts/ci-test-excluded.txt
+++ b/scripts/ci-test-excluded.txt
@@ -84,6 +84,7 @@ scripts/__tests__/mod-capability-matrix.test.mjs
tests/all-plugins-smoke-workflow.test.mjs
tests/check-guard-tool-names.test.mjs
tests/check-status-forwarding.test.mjs
+tests/external-plugins.test.mjs
plugins/ruflo-console/tests/result-display.test.ts
plugins/ruflo-console/tests/toasts.test.ts
plugins/ruflo-console/tests/full-text.test.ts
diff --git a/scripts/external-plugins.mjs b/scripts/external-plugins.mjs
new file mode 100644
index 0000000000..0cc19b4aa9
--- /dev/null
+++ b/scripts/external-plugins.mjs
@@ -0,0 +1,102 @@
+// external-plugins — the checks and the sandboxing smoke-all-plugins applies to an external marketplace entry (ADR-484):
+// a plugin listed by a git-subdir source pinned to a commit, maintained in another repository. Its smoke.sh is third-party
+// code, so it runs with a scrubbed environment, a temporary HOME, and a working directory that holds only its own checkout.
+// This is not a sandbox: the script can still read absolute paths. The workflow therefore also drops the job token's write
+// scopes and keeps no credentials in the workspace (permissions: contents: read, persist-credentials: false).
+//
+// Tested by tests/external-plugins.test.mjs (node --test).
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, sep } from 'node:path';
+
+/** github.com repositories only: owner and repo are plain names; `.` and `..` are not names. */
+const GITHUB_REPO_URL = /^https:\/\/github\.com\/([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)$/;
+
+/** A relative folder of plain names: no leading or trailing slash, no empty segment, no `%`, `\\` or other punctuation. */
+const PLUGIN_PATH = /^[A-Za-z0-9._-]+(\/[A-Za-z0-9._-]+)*$/;
+
+/** True for `https://github.com/<owner>/<repo>` with an optional `.git`, nothing before or after it. */
+export function isAllowedRepoUrl(url) {
+ const match = typeof url === 'string' ? GITHUB_REPO_URL.exec(url) : null;
+ if (match === null) return false;
+ const repo = match[2].replace(/\.git$/, '');
+ return ![match[1], repo].some((part) => part === '' || part === '.' || part === '..');
+}
+
+/** Why an external marketplace source is refused, or null when it is a pinned github git-subdir. */
+export function externalSourceProblem(source) {
+ const s = source ?? {};
+ if (s.source !== 'git-subdir') return 'source is not a git-subdir';
+ if (!isAllowedRepoUrl(s.url)) return 'url is not https://github.com/<owner>/<repo>';
+ if (typeof s.path !== 'string' || !PLUGIN_PATH.test(s.path) || s.path.split('/').some((part) => part === '..' || part === '.')) {
+ return 'path is not a relative folder of plain names without . or ..';
+ }
+ if (typeof s.sha !== 'string' || !/^[0-9a-f]{40}$/.test(s.sha)) return 'source does not pin a full 40-character commit sha';
+ return null;
+}
+
+const SECRET_NAME = /(^GITHUB_TOKEN$|^ACTIONS_|_TOKEN$|_KEY$|SECRET)/i;
+const KEPT = ['PATH', 'LANG', 'TERM', 'CI'];
+
+/** The environment an external smoke runs with: PATH, LANG, TERM and CI from `base`, HOME set to `home`, nothing else. */
+export function scrubbedEnv(home, base = process.env) {
+ const env = { HOME: home };
+ for (const key of KEPT) if (typeof base[key] === 'string' && !SECRET_NAME.test(key)) env[key] = base[key];
+ return env;
+}
+
+/** `inner` resolved through links, when it stays inside `outer` (also resolved); null when it is missing or escapes. */
+export function realpathInside(outer, inner) {
+ let root;
+ let target;
+ try {
+ root = realpathSync(outer);
+ target = realpathSync(inner);
+ } catch {
+ return null;
+ }
+ return target === root || target.startsWith(root + sep) ? target : null;
+}
+
+/** A fresh work area outside the repository: `checkout/` for the plugin's repository and `home/` for its HOME. */
+export function makeWorkArea(parent = tmpdir()) {
+ const dir = mkdtempSync(join(parent, 'smoke-external-'));
+ const checkout = join(dir, 'checkout');
+ const home = join(dir, 'home');
+ mkdirSync(checkout);
+ mkdirSync(home);
+ return { dir, checkout, home };
+}
+
+/** Fetches `sha` of `url` into `checkout` (shallow, blobless) with the scrubbed env; null on success, else why it failed. */
+export function checkoutAt(url, sha, checkout, home, timeoutMs) {
+ const env = { ...scrubbedEnv(home), GIT_TERMINAL_PROMPT: '0', GIT_CONFIG_NOSYSTEM: '1' };
+ for (const args of [['init', '-q'], ['remote', 'add', 'origin', url], ['fetch', '-q', '--depth', '1', '--filter=blob:none', 'origin', sha], ['checkout', '-q', 'FETCH_HEAD']]) {
+ const r = spawnSync('git', ['-C', checkout, ...args], { encoding: 'utf8', timeout: timeoutMs, env });
+ if (r.status !== 0) return `git ${args[0]} failed: ${(r.stderr || r.error?.message || '').trim().slice(0, 200)}`;
+ }
+ return null;
+}
+
+/**
+ * How to run the plugin's smoke inside a checkout: its manifest must carry `name`, the plugin folder and smoke.sh must stay
+ * inside the checkout after links are resolved. Returns { problem } or { smoke: null } (no smoke.sh) or { smoke, cwd, env }, the env
+ * scrubbed from `base` (the caller's environment).
+ */
+export function externalSmokePlan(checkout, home, path, name, base = process.env) {
+ const root = realpathInside(checkout, join(checkout, path));
+ if (root === null) return { problem: `${path} is missing or resolves outside the checkout` };
+ const manifestPath = realpathInside(checkout, join(root, '.claude-plugin', 'plugin.json'));
+ let manifest = null;
+ try {
+ if (manifestPath !== null && statSync(manifestPath).size <= 1_000_000) manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+ } catch { /* reported below */ }
+ if (manifest?.name !== name) return { problem: `plugin.json at ${path} does not name ${name}` };
+ const smokePath = join(root, 'scripts', 'smoke.sh');
+ if (!existsSync(smokePath)) return { smoke: null };
+ const smoke = realpathInside(checkout, smokePath);
+ if (smoke === null) return { problem: 'scripts/smoke.sh resolves outside the checkout' };
+ return { smoke, cwd: realpathSync(checkout), env: scrubbedEnv(home, base) };
+}
diff --git a/scripts/smoke-all-plugins.mjs b/scripts/smoke-all-plugins.mjs
index acdaa02a1c..b6252a2325 100755
--- a/scripts/smoke-all-plugins.mjs
+++ b/scripts/smoke-all-plugins.mjs
@@ -9,6 +9,12 @@
// node scripts/smoke-all-plugins.mjs --only ruflo-agent,ruflo-cost-tracker
// node scripts/smoke-all-plugins.mjs --skip ruflo-iot-cognitum
// node scripts/smoke-all-plugins.mjs --skip-guard-probe # omit the final guard-probe step
+// node scripts/smoke-all-plugins.mjs --skip-external # omit the external plugins (no network)
+//
+// External plugins: a marketplace entry whose source is a git-subdir pinned to a commit on github.com (a plugin maintained in
+// another repository) is checked out at that commit into a temporary folder, its manifest must carry the listed name, and its
+// own scripts/smoke.sh, when it ships one, runs as one more row with a scrubbed env, a temporary HOME and its checkout as cwd
+// (scripts/external-plugins.mjs). This step needs network access to the plugin's repository.
//
// After the per-plugin smokes, `scripts/probe-mod-guards.mjs --fast` runs every hooks/guard.ts through the adversarial corpus. It
// fails only on holes NOT listed in scripts/probe-mod-guards.known-holes.json, so a regression (or a new guard copied from a
@@ -24,10 +30,11 @@
// 2 config error (e.g. invalid CLI args)
// 3 no smoke scripts found (likely repo-layout drift — fail closed)
-import { readdirSync, existsSync, statSync, readFileSync } from 'node:fs';
+import { readdirSync, existsSync, statSync, readFileSync, rmSync } from 'node:fs';
import { spawn, spawnSync } from 'node:child_process';
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';
+import { checkoutAt, externalSmokePlan, externalSourceProblem, makeWorkArea } from './external-plugins.mjs';
const SCRIPTS_DIR = dirname(fileURLToPath(import.meta.url));
const REPO_ROOT = dirname(SCRIPTS_DIR);
@@ -42,6 +49,7 @@ const ARGS = (() => {
timeoutSec: 120, // per-plugin hard cap — prevents a hung smoke from deadlocking the run
failFast: false, // if true, kill remaining smokes on first failure
guardProbe: true, // final step: fast adversarial probe of every hooks/guard.ts
+ external: true, // check out each external plugin at its pinned commit and run its own smoke
};
for (let i = 2; i < process.argv.length; i++) {
const v = process.argv[i];
@@ -50,6 +58,7 @@ const ARGS = (() => {
else if (v === '--timeout') a.timeoutSec = parseFloat(process.argv[++i]);
else if (v === '--fail-fast') a.failFast = true;
else if (v === '--skip-guard-probe') a.guardProbe = false;
+ else if (v === '--skip-external') a.external = false;
else if (v === '--only') {
a.only = new Set((process.argv[++i] || '').split(',').map((s) => s.trim()).filter(Boolean));
} else if (v === '--skip') {
@@ -83,10 +92,42 @@ function discoverPlugins() {
return plugins.sort((a, b) => a.name.localeCompare(b.name));
}
+/** The marketplace's external entries (a git-subdir source), filtered by --only and --skip. */
+function discoverExternal() {
+ let plugins = [];
+ try { plugins = JSON.parse(readFileSync(join(REPO_ROOT, '.claude-plugin', 'marketplace.json'), 'utf8')).plugins ?? []; } catch { return []; }
+ return plugins
+ .filter((p) => p && typeof p.source === 'object' && p.source !== null && typeof p.name === 'string')
+ .filter((p) => (!ARGS.only || ARGS.only.has(p.name)) && !ARGS.skip.has(p.name))
+ .map((p) => ({ name: p.name, source: p.source }));
+}
+
+/** One external plugin as a smoke row: checkout at the pinned commit, manifest name, then its own scripts/smoke.sh, run as
+ * third-party code (scrubbed env, temporary HOME, cwd = its own checkout outside the workspace; see external-plugins.mjs). */
+async function runExternal(entry) {
+ const name = `${entry.name} (external)`;
+ const t0 = Date.now();
+ const fail = (reason) => ({ name, exitCode: 1, ok: false, timedOut: false, aborted: false, terminationReason: reason, passed: null, failed: null, durationMs: Date.now() - t0, failingSteps: [], stderrTail: '' });
+ const problem = externalSourceProblem(entry.source);
+ if (problem !== null) return fail(problem);
+ const { url, path, sha } = entry.source;
+ const area = makeWorkArea();
+ try {
+ const fetched = checkoutAt(url, sha, area.checkout, area.home, ARGS.timeoutSec * 1000);
+ if (fetched !== null) return fail(fetched);
+ const plan = externalSmokePlan(area.checkout, area.home, path, entry.name);
+ if (plan.problem) return fail(plan.problem);
+ if (plan.smoke === null) return { ...fail('no scripts/smoke.sh; manifest checked'), exitCode: 0, ok: true };
+ return { ...(await runSmoke({ name, smoke: plan.smoke, cwd: plan.cwd, env: plan.env })), durationMs: Date.now() - t0 };
+ } finally {
+ rmSync(area.dir, { recursive: true, force: true });
+ }
+}
+
function runSmoke(plugin, abortSignal) {
return new Promise((resolve) => {
const start = Date.now();
- const p = spawn('bash', [plugin.smoke], { stdio: ['ignore', 'pipe', 'pipe'] });
+ const p = spawn('bash', [plugin.smoke], { stdio: ['ignore', 'pipe', 'pipe'], ...(plugin.cwd && { cwd: plugin.cwd }), ...(plugin.env && { env: plugin.env }) });
let stdout = '';
let stderr = '';
let timedOut = false;
@@ -207,7 +248,8 @@ function runChangelogContract() {
async function main() {
const plugins = discoverPlugins();
- if (plugins.length === 0) {
+ const external = ARGS.external ? discoverExternal() : [];
+ if (plugins.length === 0 && external.length === 0) {
console.error('smoke-all-plugins: no plugins/*/scripts/smoke.sh found — repo layout drift?');
process.exit(3);
}
@@ -245,6 +287,9 @@ async function main() {
results = await Promise.all(pending);
}
+ if (ARGS.external && !abortController?.signal.aborted) {
+ for (const entry of external) results.push(await runExternal(entry));
+ }
results.push(runChangelogContract());
if (ARGS.guardProbe && !abortController?.signal.aborted) results.push(runGuardProbe());
diff --git a/tests/external-plugins.test.mjs b/tests/external-plugins.test.mjs
new file mode 100644
index 0000000000..560f33eae6
--- /dev/null
+++ b/tests/external-plugins.test.mjs
@@ -0,0 +1,156 @@
+// node --test tests/external-plugins.test.mjs
+// The external-plugin checks (ADR-484): the github-only source allowlist in scripts/external-plugins.mjs and in
+// validate-marketplace.yml's inline validator, the realpath containment of the plugin folder, and the environment and working
+// directory an external smoke.sh runs with.
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, sep } from 'node:path';
+import { test } from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+import { externalSmokePlan, externalSourceProblem, isAllowedRepoUrl, makeWorkArea, realpathInside, scrubbedEnv } from '../scripts/external-plugins.mjs';
+
+const REPO = fileURLToPath(new URL('..', import.meta.url));
+const SHA = 'e5814a2f4f3d7995b87ebda9ad30e8a3d92cd555';
+const source = (over) => ({ source: 'git-subdir', url: 'https://github.com/proffesor-for-testing/agentic-qe.git', path: 'plugins/agentic-qe-fleet', ref: 'v3.15.10', sha: SHA, ...over });
+
+const REFUSED_URLS = [
+ 'https://github.com.evil.io/owner/repo',
+ 'https://evil.io/github.com/owner/repo',
+ 'https://gitlab.com/owner/repo',
+ 'http://github.com/owner/repo',
+ 'https://[email protected]/owner/repo',
+ 'https://github.com/owner/repo/extra',
+ 'https://github.com/owner',
+ 'https://github.com/../repo',
+ 'https://github.com/owner/..',
+ 'https://github.com/owner/repo?x=1',
+ 'https://github.com/own er/repo',
+ '[email protected]:owner/repo.git',
+ '--upload-pack=x',
+];
+
+// Paths the plugin folder may not take: encoded or backslashed climbs, empty or trailing segments, absolute, . and .. segments.
+const BAD_PATHS = ['%2e%2e', 'plugins/%2e%2e/x', 'a\\..\\b', 'a//b', 'plugins/p/', '/etc', '.', '..', 'a/./b', 'a/../b', '', 'a b', 'a/b?c'];
+
+test('the allowlist takes https://github.com/<owner>/<repo>, with or without .git', () => {
+ assert.equal(isAllowedRepoUrl('https://github.com/proffesor-for-testing/agentic-qe.git'), true);
+ assert.equal(isAllowedRepoUrl('https://github.com/ruvnet/ruflo'), true);
+});
+
+test('the allowlist refuses other hosts, lookalikes and anything around the owner/repo pair', () => {
+ for (const url of REFUSED_URLS) assert.equal(isAllowedRepoUrl(url), false, url);
+});
+
+test('externalSourceProblem refuses a non-github host, a lookalike, a climbing path and a short sha', () => {
+ assert.equal(externalSourceProblem(source()), null);
+ assert.match(externalSourceProblem(source({ url: 'https://gitlab.com/owner/repo.git' })), /github/);
+ assert.match(externalSourceProblem(source({ url: 'https://github.com.evil.io/owner/repo' })), /github/);
+ assert.match(externalSourceProblem(source({ url: 'https://evil.io/github.com/owner/repo' })), /github/);
+ assert.match(externalSourceProblem(source({ path: 'plugins/../..' })), /path/);
+ assert.match(externalSourceProblem(source({ path: '/etc' })), /path/);
+ for (const path of BAD_PATHS) assert.match(externalSourceProblem(source({ path })) ?? 'accepted', /path/, path);
+ assert.equal(externalSourceProblem(source({ path: 'plugins/agentic-qe-fleet' })), null);
+ assert.equal(externalSourceProblem(source({ path: 'a.b/c_d-e' })), null);
+ assert.match(externalSourceProblem(source({ sha: SHA.slice(0, 12) })), /sha/);
+ assert.match(externalSourceProblem(source({ source: 'url' })), /git-subdir/);
+});
+
+/** Runs validate-marketplace.yml's inline validator (the `node -e "..."` block, through bash as CI does) on one entry. */
+function runWorkflowValidator(entrySource) {
+ const yml = readFileSync(join(REPO, '.github', 'workflows', 'validate-marketplace.yml'), 'utf8');
+ const start = yml.indexOf('node -e "');
+ const end = yml.indexOf('\n "', start);
+ assert.ok(start > 0 && end > start, 'found the inline validator');
+ const dir = mkdtempSync(join(tmpdir(), 'validate-marketplace-'));
+ try {
+ mkdirSync(join(dir, '.claude-plugin'));
+ const entry = { name: 'ext', source: entrySource, description: 'an external plugin' };
+ writeFileSync(join(dir, '.claude-plugin', 'marketplace.json'), JSON.stringify({ name: 't', plugins: [entry] }));
+ return spawnSync('bash', ['-c', yml.slice(start, end + 12)], { cwd: dir, encoding: 'utf8' });
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+}
+
+test('validate-marketplace.yml accepts a pinned github git-subdir and refuses other hosts and lookalikes', () => {
+ assert.equal(runWorkflowValidator(source()).status, 0);
+ for (const url of ['https://gitlab.com/owner/repo.git', 'https://github.com.evil.io/owner/repo', 'https://evil.io/github.com/owner/repo', 'https://github.com/../repo']) {
+ const r = runWorkflowValidator(source({ url }));
+ assert.notEqual(r.status, 0, url);
+ assert.match(r.stderr, /github\.com/, url);
+ }
+ for (const path of [...BAD_PATHS, 'plugins/../x']) assert.notEqual(runWorkflowValidator(source({ path })).status, 0, path);
+ assert.equal(runWorkflowValidator(source({ path: 'a.b/c_d-e' })).status, 0);
+ assert.notEqual(runWorkflowValidator(source({ sha: 'abc' })).status, 0);
+});
+
+/** A fake external checkout: plugins/p with a manifest and a smoke.sh that records its env and cwd under $HOME. */
+function fakeCheckout(area) {
+ const plugin = join(area.checkout, 'plugins', 'p');
+ mkdirSync(join(plugin, '.claude-plugin'), { recursive: true });
+ mkdirSync(join(plugin, 'scripts'));
+ writeFileSync(join(plugin, '.claude-plugin', 'plugin.json'), JSON.stringify({ name: 'p' }));
+ writeFileSync(join(plugin, 'scripts', 'smoke.sh'), 'env > "$HOME/env.txt"\npwd -P > "$HOME/cwd.txt"\nls -A > "$HOME/ls.txt"\n');
+ return plugin;
+}
+
+test('an external smoke runs with a scrubbed env (no GITHUB_TOKEN, no *_TOKEN/*_KEY/*SECRET*/ACTIONS_*) and its checkout as cwd, outside the workspace', () => {
+ const area = makeWorkArea();
+ try {
+ fakeCheckout(area);
+ const parent = { PATH: process.env.PATH, LANG: 'C.UTF-8', TERM: 'xterm', CI: 'true', GITHUB_TOKEN: 'ghs_x', ACTIONS_RUNTIME_TOKEN: 'y', NPM_TOKEN: 'z', ANTHROPIC_API_KEY: 'k', MY_SECRET_VALUE: 's', GITHUB_WORKSPACE: REPO, HOME: '/root' };
+ const plan = externalSmokePlan(area.checkout, area.home, 'plugins/p', 'p', parent);
+ assert.ok(plan.smoke, JSON.stringify(plan));
+ // Run it the way smoke-all-plugins' runSmoke does: bash <smoke> with exactly the plan's cwd and env.
+ const r = spawnSync('bash', [plan.smoke], { cwd: plan.cwd, env: plan.env, encoding: 'utf8' });
+ assert.equal(r.status, 0, r.stderr);
+ const seen = readFileSync(join(area.home, 'env.txt'), 'utf8');
+ for (const name of ['GITHUB_TOKEN', 'ACTIONS_RUNTIME_TOKEN', 'NPM_TOKEN', 'ANTHROPIC_API_KEY', 'MY_SECRET_VALUE', 'GITHUB_WORKSPACE']) {
+ assert.doesNotMatch(seen, new RegExp(`^${name}=`, 'm'), name);
+ }
+ assert.match(seen, new RegExp(`^HOME=${area.home.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}$`, 'm'));
+ const cwd = readFileSync(join(area.home, 'cwd.txt'), 'utf8').trim();
+ assert.equal(cwd, plan.cwd);
+ assert.ok(!(cwd + sep).startsWith(REPO), `cwd ${cwd} is outside the workspace ${REPO}`);
+ assert.deepEqual(readFileSync(join(area.home, 'ls.txt'), 'utf8').trim().split('\n'), ['plugins'], 'the cwd holds only the checkout');
+ assert.deepEqual(Object.keys(plan.env).sort(), ['CI', 'HOME', 'LANG', 'PATH', 'TERM']);
+ } finally {
+ rmSync(area.dir, { recursive: true, force: true });
+ }
+});
+
+test('a plugin folder that is a symlink out of the checkout is refused, and so is a smoke.sh that links out', () => {
+ const area = makeWorkArea();
+ const outside = mkdtempSync(join(tmpdir(), 'outside-'));
+ try {
+ mkdirSync(join(outside, '.claude-plugin'));
+ writeFileSync(join(outside, '.claude-plugin', 'plugin.json'), JSON.stringify({ name: 'p' }));
+ mkdirSync(join(area.checkout, 'plugins'));
+ symlinkSync(outside, join(area.checkout, 'plugins', 'p'));
+ assert.equal(realpathInside(area.checkout, join(area.checkout, 'plugins', 'p')), null);
+ assert.match(externalSmokePlan(area.checkout, area.home, 'plugins/p', 'p').problem, /outside the checkout/);
+
+ rmSync(join(area.checkout, 'plugins'), { recursive: true, force: true });
+ const plugin = fakeCheckout(area);
+ rmSync(join(plugin, 'scripts', 'smoke.sh'));
+ writeFileSync(join(outside, 'evil.sh'), 'exit 0\n');
+ symlinkSync(join(outside, 'evil.sh'), join(plugin, 'scripts', 'smoke.sh'));
+ assert.match(externalSmokePlan(area.checkout, area.home, 'plugins/p', 'p').problem, /smoke\.sh resolves outside/);
+ } finally {
+ rmSync(area.dir, { recursive: true, force: true });
+ rmSync(outside, { recursive: true, force: true });
+ }
+});
+
+test('a manifest that does not carry the listed name is refused', () => {
+ const area = makeWorkArea();
+ try {
+ fakeCheckout(area);
+ assert.match(externalSmokePlan(area.checkout, area.home, 'plugins/p', 'other').problem, /does not name other/);
+ } finally {
+ rmSync(area.dir, { recursive: true, force: true });
+ }
+});
diff --git a/v3/docs/adr/ADR-484-external-marketplace-plugins.md b/v3/docs/adr/ADR-484-external-marketplace-plugins.md
new file mode 100644
index 0000000000..c9e81a5e97
--- /dev/null
+++ b/v3/docs/adr/ADR-484-external-marketplace-plugins.md
@@ -0,0 +1,91 @@
+# ADR 484: External plugins in the ruflo marketplace (first: Agentic QE)
+
+Status: Accepted
+
+Date: 2026-10-09
+
+Builds on: ADR-446 (the plugin fleet as mods), ADR-434 (the Plugins page detects the marketplace), ADR-411 (the plugin map)
+
+## 1. Context
+
+Every entry in `.claude-plugin/marketplace.json` has been a local folder, `./plugins/ruflo-*`. Agentic QE (`agentic-qe` on npm) ships a
+Claude Code plugin, `agentic-qe-fleet`, from its own repository and its own marketplace: 11 QE agents, 9 skills, 9 commands, an `.mcp.json`
+that runs `npx -y agentic-qe@<plugin version> mcp`, and an ADR-446-style mod (`aqe-mod`: a status file at `.claude-flow/aqe-mod/status.json`,
+`/aqe-mod`, and a tighten-only `tool.call` guard that refuses destructive operations on `.agentic-qe/*.db` and `*.rvf`). Ruflo users should
+be able to install it from the ruflo marketplace and see it in the console.
+
+Two ways to list it:
+
+1. **An external entry**: the marketplace points at the plugin's folder in its own repository, pinned to a commit.
+2. **A local wrapper**: a `plugins/ruflo-agentic-qe` folder with its own `plugin.json` and a pinned `.mcp.json`.
+
+The wrapper would carry only what it copies: the agents, skills, commands and the mod would either be copied (two sources of truth, drifting
+on every AQE release) or left out (a plugin that is mostly an MCP line).
+
+## 2. Decision
+
+**List external plugins by a `git-subdir` source pinned to a full commit sha**, and teach the ruflo tooling that an entry may have no folder
+here. The first entry:
+
+```json
+{ "name": "agentic-qe-fleet",
+ "source": { "source": "git-subdir", "url": "https://github.com/proffesor-for-testing/agentic-qe.git",
+ "path": "plugins/agentic-qe-fleet", "ref": "v3.15.10", "sha": "e5814a2f4f3d7995b87ebda9ad30e8a3d92cd555" } }
+```
+
+Rules for an external entry:
+
+- **Pinned.** `sha` is the full 40-character commit; `ref` names the release tag for people. Moving to a new release is a reviewed change to
+ this file. `validate-marketplace.yml`, which failed on any non-string source (`Missing plugin dir: [object Object]`), now checks an
+ external entry instead: a `git-subdir` with an https url, a path without `..`, a full sha and a description.
+- **Smoked at the pin.** `scripts/smoke-all-plugins.mjs` checks out each external entry at its sha (shallow, blobless, into a temporary
+ folder), requires its `plugin.json` to carry the listed name, and runs the plugin's own `scripts/smoke.sh` when it ships one. The step needs
+ network access; `--skip-external` turns it off. `all-plugins-smoke.yml` also runs when `marketplace.json` changes.
+- **Third-party code in CI is fenced** (`scripts/external-plugins.mjs`, `tests/external-plugins.test.mjs`). Only
+ `https://github.com/<owner>/<repo>` sources are accepted, in both validators. The plugin folder and its `smoke.sh` must stay inside
+ the checkout after links are resolved. The smoke runs with only PATH, LANG, TERM and CI from the job's environment (no GITHUB_TOKEN,
+ ACTIONS_*, *_TOKEN, *_KEY or *SECRET*), a temporary HOME, and the checkout, in a temporary folder outside the workspace, as its working
+ directory. `all-plugins-smoke.yml` runs with `permissions: contents: read` and checks out with `persist-credentials: false`, so no
+ token sits in the workspace's git config. This is not a sandbox: the script can still read absolute paths and use the network.
+ So every pin bump needs a human review of the pinned commit's `scripts/smoke.sh` (and anything it runs) before merge: a hosted
+ runner cannot contain it, only keep secrets away from it.
+- **Mapped in the console.** `hooks/plugin-map.ts` has a line for it like any plugin (Agentic QE: Dev Tools, beside `ruflo-testgen`), and
+ `tests/plugin-coverage.spec.ts` requires a line for every external marketplace entry as well as every `plugins/` folder.
+- **Read from the installed copy.** The Plugin Catalog reads a local plugin from the marketplace clone; an external one has no copy there, so
+ its skills, agents, commands, `.mcp.json` and `hooks/register.ts` are read from its install path in Claude Code's
+ `installed_plugins.json` (the same checked path the What's new page reads). Not installed, it is listed by its entry alone. Either way
+ the row carries an `EXT` badge and the detail names where it is installed from. Ships in the next ruflo console release (version set at merge).
+
+Nothing else needed a change: the health matrix lists installed plugins by marketplace (`agentic-qe-fleet@ruflo` is a ruflo plugin there),
+the Mods section already reads any `.claude-flow/*-mod/status.json`, and the scripts that walk `plugins/*` (`audit-plugin-*`,
+`check-plugin-manifests`, `mod-capability-matrix`, `probe-mod-guards`, the CLI command inventory) skip a non-string source or never read the
+marketplace. They do not cover the external plugin; its own repository runs its manifest, mod and guard tests.
+
+## 3. Evidence (Claude Code 2.1.295 on 2026-10-09; the install re-run on 2.1.296 at the v3.15.2 pin, 2026-10-10, at the v3.15.3 pin, 2026-10-11, at the v3.15.4 and v3.15.5 pins, 2026-10-12, at the v3.15.6 pin, 2026-10-13, on 2.1.300 at the v3.15.7 pin, 2026-10-15, on 2.1.301 at the v3.15.8 pin, 2026-10-16, on 2.1.302 at the v3.15.9 pin, 2026-10-18, and on 2.1.303 at the v3.15.10 pin, 2026-10-19)
+
+- `claude plugin validate .claude-plugin/marketplace.json` passes with the entry; a `{"source":"bogus"}` source is refused.
+ `claude plugin validate .` at the root fails exactly as it does on `main`, on the legacy root `.claude-plugin/plugin.json`
+ (`repository` must be a string), and reports nothing about the new entry.
+- In a throwaway `CLAUDE_CONFIG_DIR`: `claude plugin marketplace add <marketplace>` then `claude plugin install agentic-qe-fleet@<marketplace>`
+ installs 3.15.10 into `plugins/cache/<marketplace>/agentic-qe-fleet/3.15.10` (`gitCommitSha` e5814a2f in `installed_plugins.json`; d1c33d2b at the v3.15.9 pin, d9ce98f7 at the v3.15.8 pin, 7f2d091d at the v3.15.7 pin, 0fa34d24 at the v3.15.6 pin, d65ede14 at the v3.15.5 pin, bec02b13 at the v3.15.4 pin);
+ `claude mcp list` shows `plugin:agentic-qe-fleet:agentic-qe: npx -y [email protected] mcp - ✔ Connected`; `claude plugin test` on the
+ installed copy: 45 pass, 0 fail across 3 files (the same 45 as at v3.15.2 through v3.15.9; 11 at v3.15.0 and 22 at v3.15.1, as those releases added guard and status-file tests).
+ At the v3.15.2 pin, `claude -p "/aqe-mod status"` answered from the mod, wrote `.claude-flow/aqe-mod/status.json` and reported the mod's
+ version (3.15.2) and its totals across sessions; the v3.15.3 to v3.15.10 re-runs had no logged-in session, so that step was not repeated. From 3.15.2 to
+ 3.15.10 the plugin folder changed only its version (`plugin.json`, the mod's `hooks/version.ts`, CHANGELOG entries) and its MCP pin.
+
+## 4. Consequences
+
+- Ruflo does not review each AQE commit, only each pin. The pinned sha is the trust boundary: an AQE release reaches ruflo users when a PR here
+ moves the pin and the external smoke passes on it.
+- The AQE mod's guard is not in `probe-mod-guards` or the capability matrix, which read `plugins/` only. Covering external guards would mean
+ bundling code from another repository in ruflo CI; left out on purpose.
+- **Older Claude Code cannot read the marketplace at all.** Claude Code before 2.1.69 refuses the whole `marketplace.json` over this one entry
+ (`plugins.N.source: Invalid input`), so `ruflo-*` plugins stop installing there too; found by bisecting `claude plugin marketplace add` across
+ npm releases (2.1.68 refuses, 2.1.69 adds it). On such a client an existing `ruflo` marketplace stops refreshing (`Failed to refresh
+ marketplace 'ruflo': Invalid schema … plugins.9.source`) and its installed plugins report "not found in marketplace". The line was already
+ crossed on `main`: on 2.1.68, 37 of the 46 listed plugins refuse to install (`Unrecognized key: "userConfig"`), and `ruflo-testgen`, one that
+ installs, fails to load (`Hook load failed`). The README requires Claude Code 2.1.287 (2026-10-01) or later; 2.1.69 is from 2026-03-04.
+ A second marketplace file for external entries would avoid this, but the plugin would then be `agentic-qe-fleet@<other name>`, outside the
+ console's `ruflo` health matrix, so it is not done.
+- `--plugin-dir plugins/...` (the plugins README's quick start) does not load an external plugin; it installs from the marketplace only.
diff --git a/v3/docs/adr/INDEX-mod-system.md b/v3/docs/adr/INDEX-mod-system.md
index 0561fbb2b0..8d23b073f1 100644
--- a/v3/docs/adr/INDEX-mod-system.md
+++ b/v3/docs/adr/INDEX-mod-system.md
@@ -69,6 +69,7 @@ Two files carry the number 430 (the menu's accents, and the menu-design amendmen
| 478 | Console What's new page, plugin changelogs | Accepted | 10-07 | 428, 477 | — | — | [ADR-478](ADR-478-console-whats-new.md) | — |
| 480 | Console ADRs page: your project's ADRs, and missions, loops and swarms that follow them | Accepted | 10-07 | 407, 443, 444, 450, 474, 477, 478 | — | this PR | console 0.39.0, swarm 0.3.5, workflows 0.6.4 | `adr.spec`, `adr-write.spec`, `adr-integration.spec`, `adr-page.spec`, `adr-mutation.spec`, `adr-digest.spec` |
| 483 | Console advisor checkpoints for mission loops (plan, repeated failure, before done) | Accepted | 10-08 | 441, 443, 444, 477, 480, 481 | — | this PR | console 0.40.0 | `mission-advisor.spec`, `mission-advisor-mutation.spec` |
+| 484 | External plugins in the ruflo marketplace (first: Agentic QE) | Accepted | 10-09 | 446, 434, 411 | — | this PR | next console release | `plugin-catalog.spec`, `plugin-coverage.spec`, `smoke-all-plugins` external step |
| 486 | Session workspace: attention queue, session browser and preview on the Room (Claude, Codex and Ruflo sessions) | Accepted | 10-09 | 406, 444, 448, 473, 477, 481 | — | this PR | console 0.41.0, mods 0.4.0 | `sessions.spec`, `sessions-safety.spec`, `sessions-real-fs.spec`, `attention.test` |
Other ADRs outside 404-451 that the mod ADRs lean on: 150 (removable integrations), 174 (failures as a learning signal), 322 and 322A/B/C (flywheel, evaluation and promotion, receipts), 324 and 325 (policy engine, claims plane), 103 (witness). The console's Mods section (`hooks/data/mods.ts`, console 0.33.1, PR #3707) reads the status files ADR 446 defines.