@b1-road/integrate
v0.2.0-alpha.9
Published
Drop the Eduzz Plat integration skill into your repo and pre-seed it — go from zero to a verified Plat integration in your AI IDE.
Readme
@b1-road/integrate
Go from zero to a working, verified Eduzz Plat integration in your own repo, driven by the AI assistant you already code with.
npx @b1-road/integrateNew here? Create your developer account first at https://dev-portal.road-sandbox.b1.app — it takes a minute and gives you the platform your app signs in against. You can also run the command above first and let the assistant register the platform for you.
What it does
The command drops an integration skill into your repo at
.claude/skills/road-integration/ — plain Markdown that Claude Code, Cursor and
Windsurf all read. Then you open the repo in your AI IDE and say:
integrate with Road
From there the skill takes over. It:
- Detects your stack — NestJS, Laravel, or a React frontend (including monorepos, where it looks inside the workspace packages).
- Sets up your platform in Eduzz Plat — registers it, defines the
permissions and roles your app checks, issues OIDC credentials, and activates
it. With the Road MCP installed
this runs end to end from your session and the client secret is written
straight into your
.env— never shown in chat, never pasted by hand. Without it, the skill walks you through the Dev Portal instead. - Writes the code you'd otherwise get subtly wrong — the login routes, the server-side session, the API proxy, and a real permission check wired into one of your routes.
- Refuses to say it worked until it watched it work — it runs a real login round-trip against the live sandbox and checks that a proxied call returns your identity. A confident "done" on broken auth code is the failure this whole thing exists to prevent.
You log in once with your own hands. That step is deliberate: it's how you see it work.
Usage
npx @b1-road/integrate # install the skill into this repo
npx @b1-road/integrate plat_7f3a… # install + pre-seed from your platform id
npx @b1-road/integrate plat_7f3a… -y # re-run to refresh the pre-seed (overwrite)| Option | Effect |
| --- | --- |
| plat_… (positional) | Platform id from the Dev Portal. Pre-fills your permission catalog, client id and issuer, so the skill starts knowing your setup. |
| --api <url> | Road API base (default https://api.road-sandbox.b1.app). Scaffolding targets sandbox; production is a go-live step, and the setting that gets you there depends on the stack — ROAD_ENV for Node and the MCP, ROAD_ENVIRONMENT for Laravel, the env prop for React in bearer mode. The skill's references/sources.md has the table. |
| --dir <path> | Target repo root (default: the current directory). |
| -y, --yes | Overwrite an existing install without asking. |
| -v, --version · -h, --help | Bundle version · usage. |
Re-running over an existing install prompts before overwriting; -y refreshes it
non-interactively — useful once you've issued credentials and want the new
clientId picked up. The Dev Portal's install card already includes -y.
It's a dependency-free Node 18+ script, so npx runs it with nothing to install
and you can read every line before you run it. Your client secret is never put
on a command line or into a file this tool commits.
What you need
- Node 18+, and an existing app to integrate into — Plat adds sign-in and permissions to your app; it doesn't scaffold a new one.
- A backend that holds the session: NestJS or Laravel. A React frontend is wired in alongside one of those.
- If your repo already has its own login and roles system, that's a migration, not a first integration — the skill will tell you so rather than bolting a second auth system on top.
After it runs
The skill hands off with what's done, whether it's safe (it can run a security review of your platform's configuration), and how to handle day 2 — rotating a secret, adding a production redirect URI, checking what's still missing.
Help
- Developer community (the official channel): https://discord.gg/WweEC4b8T
- Dev Portal: https://dev-portal.road-sandbox.b1.app
Related packages: @b1-road/mcp
(manage your platform from your AI agent),
@b1-road/nestjs,
@b1-road/react,
@b1-road/types.
License
MIT © B1 Produtos Digitais Ltda
