Repository navigation
feat: the fluree-companion plugin — plus the cli-contract flip and a customer-facing marketplace - #4
Merged
Merged
Conversation
…ures fluree/db v4.1.5 publishes fluree-cli-manifest.json as a release asset, so the 404-warn-and-skip branch this job carried since #1 has lost its reason to exist. Any fetch failure is now an infrastructure failure and the contract check always runs. cli-facts.json validates clean against the live 4.1.5 manifest (42 commands checked). Closes #2.
…-checked stack contract A second application of the fluree-cli plugin's pattern, aimed at the deployment rather than the binary: probe the stack, don't recall the platform. The skill carries connection choreography, the CLI/Space-MCP/UI division of labor, safety rails, and per-stack version awareness; the playbooks route to stack doc slugs instead of restating procedure that would drift the moment a stack upgrades. The stack's docs MCP tools are treated as probe-then-use throughout — they are still landing solo-side, and a stack older than that release won't have them, so every knowledge path falls back to fetching the public /api/docs index over HTTP. contract/stack-facts.json enumerates every address the choreography can't avoid naming, and check-stack-facts.mjs falsifies it in three directions: router paths resolve against solo's generated endpoint manifest (including their auth posture, since the whole premise of the discovery probe is that it works pre-auth); UI-Lambda paths must NOT resolve there, which is what catches the ownership split moving; and doc slugs check against a live /api/docs index when STACK_ORIGIN is set, asserting public slugs are present AND in-app slugs are absent. The plugin names fluree commands too, so it carries its own cli-facts.json and the CI job now loops every plugin's — a plugin that names a command is on the hook for it existing, whichever plugin it is. The endpoint manifest doesn't exist on solo's main yet (fluree/solo#1041), so that job warns and skips on 404, the same lifecycle the cli-contract check went through before #2 landed.
Whichever plugin a user finds first should point at the rest. The remote rule already owned the connection choreography, so it's the natural place to hand off: stack-shaped work (what can this deployment do, where does its knowledge live) goes to the companion, and the companion routes data and admin operations back here.
The repo self-described as "Internal Claude Code plugins for Fluree demos and tooling" and the README assumed a reader who already worked here. It now leads with the three-plugin mental model — your stack, the CLI that drives it, data to put in it — install paths for all three, and the reason the knowledge lives in the stack and the binary rather than in a plugin. Brand review is separate; this is the factual pass.
aaj3f
changed the title
…oday's stack state Review-pass remediation. Two references made flat claims that go stale the moment solo#1041 merges — 'there is no search endpoint in this path' (that branch ships GET /api/docs/search, and the stack's own index header advertises it) and 'connect-external-mcp-client is not in the public set today' (the allowlist widens to the full corpus). Both were the plugin shipping its own Rule-1 counterexample: a today-shaped assertion about all stacks. Both are now probes — try the search endpoint, fall back to the index on 404; if the public page fetch 404s, route to the signed-in URL — which is correct for every stack version simultaneously and lets the two PRs merge in either order. stack-facts gains /api/docs/search under the inverted UI-path check, and the slug flips to public with a version note, removing the silent hand-flip obligation.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Implements the E1–E4 + F1 + A4 slice of #3 (A4 also closes #2). One PR per the fewest-PRs direction on the program.
The fluree-companion plugin (1.0.0)
A stack-first sibling to
fluree-cli, built on the same doctrine: the plugin carries choreography, not reference — a Fluree AI stack serves its own version-pinned knowledge (/.well-known/fluree.jsonfor capabilities and auth,/api/docs+ the forthcoming stack docs MCP tools for how-to), so the skill teaches probe-don't-recall, the connection order (discovery →remote add→ device-codeauth loginwith the human approving at/activatestated as non-negotiable → optional Space MCP registration), the CLI / Space-MCP / UI division of labor, safety rails, and version awareness (knowledge from one stack doesn't travel)./fluree-companion:connectis the guided end-to-end version, and it refuses to report success without having actually read something from the stack. The stack docs tools are treated as probe-then-use everywhere with an HTTP/api/docsfallback, since stacks older than that release won't have them.The stack contract (
stack-facts.json+check-stack-facts.mjs)Every stack path, doc slug, and tool name the plugin's prose hard-codes is falsifiable, in three directions: router paths resolve against solo's generated endpoint manifest (param-name-insensitive, regex rows evaluated by their own pattern, auth posture asserted — a path documented as unauthenticated must really be
requireAuth: false); UI-Lambda paths (/api/docs,/activate…) are checked inverted — if one ever resolves in the router manifest, the ownership split the prose teaches has moved; doc slugs validate against a live/api/docsindex whenSTACK_ORIGINis set, withpublicslugs required present andin-appslugs required absent. Exit codes mirrorcheck-cli-contract.mjs(1 violation / 2 infra). The CI job warns-and-skips on the manifest 404 until fluree/solo#1041 merges — the same lifecycle the cli-contract check just graduated from. One deliberate flag:how-to/connect-external-mcp-clientis recordedin-appbecause solo withholds it from the public allowlist today; when solo#1041's B4 widening merges, the checker is what reminds us to flip it.The companion also carries its own
cli-facts.json(~13 commands its choreography names) and the cli-contract CI job now loopsplugins/*/contract/cli-facts.json— a plugin that names a command is on the hook for it existing, whichever plugin it is. Both facts files validate clean against the released fluree 4.1.5 manifest (42 + 13 commands).Also here
mainis already active.Validation:
claude plugin validate --stricton all three plugins + the marketplace root (local CLI 2.1.233; CI pins 2.1.220), version-sync green, and the stack-facts checker mutation-tested in five directions (bogus path, flipped auth posture, UI path resolving in the router, bogus prefix, fabricated command) plus a localhost fake-stack run for the docs half — baseline green, promoted-hidden-slug and deleted-public-slug both red.Review-pass remediation (post-open): the two stale-on-merge assertions are now probe-shaped —
stack-knowledge.mdteaches "tryGET /api/docs/search, fall back to reading the index on 404" instead of asserting no search exists, and the withheld-page prose says "if the public fetch 404s, use the signed-in URL" instead of naming today's allowlist — correct for every stack version at once, so this PR and fluree/solo#1041 can merge in either order with nothing going stale.stack-facts.jsongains/api/docs/searchunder the inverted UI-path check and recordsconnect-external-mcp-clientas public with a version note (older stacks 404 it; the prose handles them). Checker re-run: 11 facts OK against solo#1041's manifest; version-sync green.