restructure: ship only plugin/ via git-subdir — keep build artifacts out of the distributed plugin (#29)

[mattwillems-exabeam]

Closes #29.

What this does

Moves socxen's distributable payload into plugin/ so the community-marketplace install stops shipping build-time artifacts to every user. Today the marketplace installs with source: url over the whole repo, so each user's plugin cache gets tests/, evals/, security/ (including our red-team attack payloads), scripts/, and .github/. Claude Code has no exclude/ignore mechanism; the only supported fix is a git-subdir source pointing at a subdirectory.

Moved into plugin/ (the only thing that ships): .claude-plugin/plugin.json · .mcp.json · skills/ · connector/ · docs/ · install.sh · README.md · LICENSE · NOTICE
Stays at repo root (never ships): tests/ evals/ security/ scripts/ .github/ + community-health docs.

All build tooling repointed to plugin/ (tests, evals/run.py, gen_aibom.py + regenerated BOM, ci.yml py_compile, bump_version.py, plugin-smoke.sh, doc cross-links). Clean git renames — history preserved. install.sh is move-safe (resolves SCRIPT_DIR via BASH_SOURCE; connector/ stays its sibling). A thin root README is added so the public GitHub landing isn't bare (it doesn't ship — git-subdir takes only plugin/; drop it if you'd rather).

⚠️ Paired change — do NOT promote to main alone

This restructure and a one-time edit to the open-agent-ai-security/plugins marketplace must reach socxen main together. That marketplace tracks socxen main; if the restructure hits main while the marketplace still uses source:url (or the marketplace flips first), Claude Code can't find the manifest at the repo root and installs break. Safe to merge to dev — nothing users touch changes until promotion.

@virtualsteve-exa — the companion edit is yours (Matt lacks write on the plugins repo). Apply this to plugins/.claude-plugin/marketplace.json in the same window you promote this to main:

       "name": "socxen",
       "source": {
-        "source": "url",
+        "source": "git-subdir",
         "url": "https://github.com/open-agent-ai-security/socxen.git",
+        "path": "plugin",
         "ref": "main"
       },

Verification

• CI green locally: pytest 237 passed / 1 skipped · evals/run.py 1/1 · py_compile ok · AI BOM --check current — all on the rebased tree (0.6.7).
• Isolated git-subdir install smoke (throwaway CLAUDE_CONFIG_DIR, real claude plugin install of this branch): cache contained only plugin/ contents; tests/ evals/ security/ scripts/ .github/ all excluded; plugin.json/.mcp.json/SKILL.md/bridge/LICENSE all present; version 0.6.7.
• Rebased onto current dev (0.6.7 + the merged Fixtures use real routable IPs as attacker indicators — remap to RFC 5737 documentation ranges before going public #46 remap); moved fixtures carry the new RFC 5737 IPs, zero old IPs.

Acceptance criteria (#29)

• Fresh marketplace install caches only plugin/ — no security/ tests/ evals/ scripts/ .github/
• Install + connect smoke passes end-to-end (real claude plugin install against a scratch config)
• CI green (invariants, evals, AI BOM freshness, red-team corpus) with new paths
• Docs/README/bump_version.py/gen_aibom.py updated for the new layout

[virtualsteve-exa]

Thorough review with independent verification — the restructure itself is excellent (clean 100% renames, ${CLAUDE_PLUGIN_ROOT} wiring correct, bump_version/invariants/CI all repointed, no two-README pill drift, shipped README's clone line updated). I reproduced the core claim myself: a real install from this branch via a ./plugin marketplace source caches only plugin/ contents — no tests/ evals/ security/ scripts/. Requesting changes on three items, one of which turned out to be a P0 hiding in your verification section.

1. Your "1 skipped" was a masked live breakage — now fixed on dev; rebase required

The skip wasn't env noise: mcp 2.0.0 removed streamablehttp_client, and the bridge's unbounded mcp>=1.0 pin meant every fresh uv resolve got 2.0.0 and crashed at import. Your path move busts the env cache key, which is why the fresh resolve happened (on both our machines) — and the smoke test's env-failure guard downgraded the crash to a skip. Details in #67; pinned mcp>=1.0,<2 in #68 and released as 0.6.8 (fresh installs on main were broken for everyone, independent of this PR — promoting this PR unpinned would have extended that to every updating user at once).
Action: rebase onto dev (0.6.8). After rebase the suite must report 238 passed, 0 skipped — treat any remaining skip as a failure.

2. plugin-smoke.sh breaks on its first post-promotion run (blocking, in-PR)

The upgrade leg can't handle a pre-restructure prior ref — which is exactly what prior will be (0.6.8, old layout) on the first run after promotion:

• version_at() reads $1/plugin/.claude-plugin/plugin.json → FileNotFoundError under set -e when the prior worktree has it at the root.
• fabricate_marketplace hardcodes "source": "./plugin" → the prior install has no plugin/ to install from.

Both need an existence fallback, e.g. in version_at: try plugin/.claude-plugin/plugin.json then .claude-plugin/plugin.json; in fabricate_marketplace: [ -d "$1/plugin" ] && src="./plugin" || src="./". (Same boundary class 0.6.6 fixed once with checkout -f — this is its two remaining instances.)

3. Harden the skip guard that masked #67 (strongly recommended, small)

In test_check_without_creds_exits_clean: a bridge traceback is never an environment problem. Before the skip at the returncode != 0 guard, add: if "Traceback" in proc.stderr → pytest.fail, only then fall through to skip for genuine uv-provisioning failures. That one line would have caught #67 on both our machines instead of hiding it.

Minor

• evals/README.md:8,87 still say skills/soc-investigate/reference/examples/ — now plugin/skills/….

Sequencing addendum for the ⚠️ paired change (@virtualsteve-exa)

The window has three coordinated edits, not two: (1) this PR's promotion to socxen main, (2) the plugins index source flip to git-subdir+path: plugin, and (3) praxen's legacy mirror (praxen/.claude-plugin/marketplace.json) — #211 gave it a socxen entry with a url+ref: main source, which breaks identically if not flipped in the same window. Praxen's check_marketplace_mirror.py cron will flag drift after the fact, but the edit itself must be paired.

Everything else checked out: fixtures carry the RFC 5737 remap, install.sh is genuinely move-safe, root README correctly doesn't ship. Happy to re-review immediately after the rebase + smoke fix.

[virtualsteve-exa]

Correction to my review's sequencing addendum, after a sanity check from Steve: socxen currently has no installed user base beyond the two maintainers, both on the canonical marketplace — so the population that could hit a stale praxen-mirror socxen entry during the window is empty.

Revised sequencing: two hard-paired edits — (1) this PR's promotion to socxen main and (2) the plugins index flip to git-subdir + path: plugin — and the praxen legacy-mirror update is a trailing edit that can safely lag (praxen's check_marketplace_mirror.py cron will flag the drift; a one-line follow-up closes it whenever). No scrub of the mirror's socxen entry — it's praxen's deliberate catalog design and useful socxen distribution besides.

Review verdict otherwise unchanged: rebase onto 0.6.8 (expect 238/0-skip), the plugin-smoke.sh prior-worktree fallbacks, and the skip-guard hardening.

[virtualsteve-exa]

Sequencing update #2 (final): per Steve, the praxen legacy mirror's socxen entry shouldn't be updated — it should be removed: with zero legacy socxen installs, its only effect is acquiring new users onto a deprecated channel (dead-end onboarding). Filed as praxen#235. Once that lands, this PR's promotion window is exactly two paired edits — socxen main + the plugins index flip — with no trailing praxen obligation at all.

[virtualsteve-exa]

Praxen-side prep is done: open-agent-ai-security/praxen#236 (fast-tracked to praxen main, awaiting merge) removes the socxen entry from praxen's legacy mirror and teaches the drift check that the omission is deliberate — so this restructure's canonical-index flip will no longer trip praxen's weekly cron, and praxen never has to track socxen's layout again (#235).

⚠️ One blocker on the plan above, though: the companion git-subdir edit will bounce off the plugins repo's own CI as written. scripts/validate_catalog.py there enforces ALLOWED_SOURCE_KEYS = {source, url, ref} — the path key is rejected, and validate.yml runs main's validator against PR manifests, fail-closed. So the real sequence is: (1) plugins repo: teach the validator the git-subdir shape first (with path hardened — relative, no traversal), land on main; (2) then the marketplace.json flip in the same window this promotes. The validator update is praxen-maintainer work (same write-access constraint as the flip itself) — flagging so the 'this week' target accounts for it.

[virtualsteve-exa]

Blocker cleared: the catalog validator now accepts git-subdir sources (open-agent-ai-security/plugins#4, merged to main as 8582ca3). The exact flip in this issue's diff (path: plugin) validates green; the path field is hardened (strictly relative, traversal-free, no ./../absolute/backslash/whitespace forms) and per-type key allow-lists keep unreviewed fields an error. The promotion window is back to the two paired edits as planned — stage the index PR whenever Matt's push lands and it will pass CI.

[mattwillems-exabeam]

All three review items addressed, plus the minor — e506f33. Rebased onto dev (21e2a0b), so this now sits on 0.6.8 and #74's containment fix; the moved snippet carries the 68-rule deny tier intact ({allow: 18, ask: 4, deny: 68}).

1. Rebase → 238 passed, 0 skipped. Confirmed the skip is genuinely gone, not merely absent: tests/test_bridge_static.py reports 6 passed / 0 skipped, so the no-creds bridge test actually ran. That was the point of the number.

2. plugin-smoke.sh — both instances fixed.

• version_at() now probes plugin/.claude-plugin/plugin.json, then the root. A genuinely missing manifest still hard-errors instead of returning an empty version — an empty one would pass the current-vs-prior equality check and smoke-test nothing.
• fabricate_marketplace() resolves the source per call (./plugin when the ref has a plugin/ dir, else ./) rather than once, because the upgrade leg fabricates twice against the same worktree — straddling the checkout that crosses the restructure boundary.

Verified against fabricated old- and new-layout worktrees rather than by inspection: 0.6.8 read from the root layout, 0.7.0 from plugin/, sources ./ and ./plugin respectively, set -e never tripped (used if blocks, not && chains, so the false branch can't return non-zero), and a manifest-less directory exits 1.

3. Skip guard un-masked. A traceback now pytest.fails; only genuine provisioning failures still skip. Worth noting the assertions below that guard already rejected tracebacks — they simply never ran, which is precisely how #67 stayed invisible on two machines.

Minor: evals/README.md:8,87 repointed, and test_bridge_wiring.py's module docstring had the same stale connector/ path.

I left security/redteam/HISTORY.md and security/design/*.md alone — they reference connector/… as a historical/design record rather than as live paths, and rewriting a history file to match a later layout seemed worse than the staleness. Say the word if you'd rather they track.

[virtualsteve-exa]

Re-review of e506f33 — all three items plus the minor verified fixed, independently. APPROVING on content. One more (mechanical but consequential) rebase is needed before merge; checklist below.

Verified on the branch

• Suite: 238 passed / 0 skipped — and test_bridge_static.py genuinely runs 6/6 now. The skip-guard fix is exactly right: traceback → pytest.fail with the #67 story memorialized in the comment, provisioning failures still skip. That guard will never hide an import crash again.
• plugin-smoke.sh fallbacks: version_at() probes plugin/ then root and still hard-errors on a genuinely missing manifest (good catch keeping that fatal — an empty version would pass the equality check and smoke nothing); fabricate_marketplace() resolves ./ vs ./plugin per call, which is the detail that matters since the upgrade leg fabricates twice across the boundary checkout.
• Moved snippet intact: plugin/skills/soc-investigate/settings.snippet.json = {allow: 18, ask: 4, deny: 68} — #74's containment fix survived the move.
• evals/README + wiring docstring paths fixed.

Required in the final rebase (dev moved under you again — sorry, busy day: 0.6.9, #77, #78)

1. Version/CHANGELOG: rebase brings the 0.6.9 entry; plugin/.claude-plugin/plugin.json + the README pill must read 0.6.9 (branch currently says 0.6.8).
2. #78 (observra 1.1 + dep lock) touched two files you're moving: take #78's side of exabeam-mcp-bridge.py (bounded PEP 723 line: observra>=1.1,<2, httpx<1, certifi>=2024,<2027, typing_extensions>=4.7,<5) and observra_logging.py (public emit() migration) into their plugin/connector/ homes.
3. Move the lockfile too: #78 added connector/exabeam-mcp-bridge.py.lock (hash-pinned resolve; uv run picks it up by adjacency). It must land at plugin/connector/exabeam-mcp-bridge.py.lock — if the rebase drops it at root connector/, fresh installs silently lose the pin we just added.
4. #77 (security/praxen/): stays at root with the rest of security/ — should be conflict-free, just confirm the invariant-test edits merge (it touched the SPDX exemption in test_repo_invariants.py).
5. Regenerate the AI BOM after the rebase (sources moved + #78 changed the recorded bounds; CI gates BOM currency on any source change — it caught me on #74 too).
6. Re-run the suite (expect 238/0) and your old/new-layout smoke-helper spot check once more on the final tree.

Sequencing note (your call, but flagging)

Your #73 edits root install.sh; this PR moves it to plugin/install.sh. Whichever lands second rebases over the other — my suggestion is this one first (it's the release-window PR and the bigger rebase), then #73 relocates its wiring into plugin/install.sh + plugin/skills/soc-investigate/merge_permissions.py.

The promotion window itself is unchanged and fully staged: this PR's release to main pairs with the plugins index flip to git-subdir/path: plugin (validator already accepts it), and you have write there to author it.

[mattwillems-exabeam]

Rebased onto dev @ a413686 — d17fa41. All six checklist items done; notes on two where what I found differed from the expectation.

#	Item	Result
1	Version/CHANGELOG → 0.6.9	plugin/.claude-plugin/plugin.json = 0.6.9, README pill = v0.6.9 (both arrived with the rebase; the invariant test enforces the pair)
2	#78's side of the bridge + observra_logging.py	in plugin/connector/: PEP 723 reads mcp>=1.0,<2, httpx>=0.27,<1, certifi>=2024,<2027, observra>=1.1,<2, typing_extensions>=4.7,<5; observra.emit bound as public-since-1.1
3	Lockfile moves too	plugin/connector/exabeam-mcp-bridge.py.lock, byte-identical to #78's, and zero files remain under root connector/
4	#77 security/praxen/	at root as intended; test_repo_invariants.py merged clean
5	Regenerate the AI BOM	see below
6	Suite + smoke spot-check	238 passed, 0 skipped; helpers re-verified on the final tree

On item 3 — git got this right, but only just. The rebase surfaced it as an explicit CONFLICT (file location): the lockfile was added on dev inside a directory this PR renames. Git proposed plugin/connector/ and I confirmed it against dev's copy. Worth knowing it announced itself rather than silently landing at the root, which is the failure you were guarding against.

On item 5 — the BOM was already current, so I committed nothing. gen_aibom.py --check passes on the rebased tree. I forced a regen anyway to be sure, and the only delta was the timestamp field — content already matched, because this branch's generator reads plugin/connector/… and #78's bounds came through the rebase intact. Since CI gates on --check (which ignores the timestamp), committing a timestamp-only churn would add a conflict surface for no verification value. Reverted it. Say the word if you'd rather the release carry a fresh stamp.

Item 6 spot-check, re-run on the final tree (not carried over from the last round): old-layout worktree → 0.6.9 + source ./; new-layout → 0.7.0 + source ./plugin; manifest-less dir → exit 1; set -e never tripped.

Ready for the promotion window whenever you are.