@nebulr-group/bridge-cli 0.6.0-beta.3 → 0.6.0-beta.4

package/dist/prompts/decisions/roles.md

@@ -0,0 +1,72 @@
+# Roles and permissions — decision guide
+
+Who may do what inside a customer's workspace. A **role** (Owner, Admin, Editor…) is a named bundle of **privileges** (`USER_WRITE`, `INVOICE_APPROVE`…). Every signed-in person has one role per workspace, and their token carries its role key and privileges, so the backend can check them on every request.
+
+> Other decision guides: `bridge guide decision <name>` (MCP: resource `bridge://guides/decisions/<name>`). How the pieces work underneath: `bridge guide mechanisms`.
+
+## Which tool answers which question
+
+Three different questions, three different tools. Keep them apart.
+
+| The question | Answered by | Guide |
+|---|---|---|
+| Who, inside a workspace, may do this? | a **role** and its privileges | this one |
+| Is this feature on for them at all? | a **flag** | feature-control |
+| How much do they get (projects, seats, exports)? | the **plan** | payments |
+
+A role never stands in for a plan ("Pro users are Admins") and a plan never stands in for a role.
+
+## Start from what is there
+
+| Read | MCP | CLI |
+|---|---|---|
+| Roles, their privileges, and which is the default | `list_roles` | `bridge role list` |
+| One role in full | `get_role` | — |
+| Privileges that exist | `list_roles` (the `privileges` map) | `bridge privilege list` |
+
+A new app has two roles: **Owner** (`OWNER`, everything, including permanent deletes) and **Admin** (`ADMIN`, manage people, read workspace settings). **Owner is the default role**, which means anyone invited without a role becomes an Owner.
+
+## Ask the developer
+
+Product questions. Ask, wait, never guess.
+
+1. **What kinds of people use one customer's workspace?** For example: the person who pays, people who manage the team, people who do the work, people who only look.
+2. **For each kind, what may they do that others may not?** Ask in the app's own verbs: approve an invoice, delete a project, invite a colleague, change billing.
+3. **Which role should a newly invited person get?** Owner is rarely the right answer.
+4. **Who may manage the subscription and billing?**
+
+## Decide yourself
+
+- **Name privileges after actions, in capitals: `PROJECT_DELETE`, `INVOICE_APPROVE`.** Reason: they read like the existing ones (`USER_READ`, `TENANT_WRITE`) and say exactly what they allow.
+- **Role keys in capitals too: `EDITOR`, `VIEWER`.** Reason: the token carries the key exactly as written, and a flag rule on `user.role` compares it case for case.
+- **In code, check a privilege, not a role name.** Reason: roles get reshaped as the product grows; the privilege on a handler stays true.
+- **Keep Owner as the one role with everything.** Never strip it: it is the only role that can delete, and every workspace needs someone who can.
+- **Make the lowest sensible role the default** by creating it with the default setting on. Reason: a forgotten role on an invitation then gives too little, not too much.
+- **When changing a role's privileges, send the full list.** Reason: the update replaces the list, and anything left out is revoked.
+- **Enforce on the backend; hide buttons in the frontend only as a courtesy.** Reason: anyone can call the API directly.
+
+## Do it
+
+| Step | MCP | CLI |
+|---|---|---|
+| Add a privilege | — | `bridge privilege create --key PROJECT_DELETE --description …` |
+| Create a role | `create_role` | `bridge role create --key EDITOR --name Editor --privileges PROJECT_READ,PROJECT_WRITE` |
+| Create it as the new default | `create_role` (`isDefault: true`) | `bridge role create --key MEMBER --name Member --privileges … --is-default` |
+| Change a role's privileges | `update_role` (full list) | `bridge role update --key EDITOR --privileges …` (full list) |
+| Give a person a role | `update_user` | `bridge user update --email … --role EDITOR --tenant-id …` |
+| Code for the framework | `get_integration_guide` (topic `team`) | `bridge guide nestjs` (backend checks), `bridge guide svelte team` |
+
+On the NestJS backend the check is a decorator on the handler: `@RequirePrivilege('PROJECT_DELETE')`, or `@RequireRole('ADMIN')` when the developer really means a role.
+
+Setting the default on one role clears it from the previous default.
+
+## Prove it
+
+1. `list_roles` / `bridge role list` shows each role with exactly the privileges agreed, and the default where the developer wanted it.
+2. Call a protected backend route as a user whose role lacks the privilege: it must answer 403. Then with one who has it: it must succeed.
+
+## Where this connects
+
+- **Teams:** the role an invited person gets.
+- **Feature control:** a flag can target `user.role`, but "may this person do it" is still a privilege check on the backend.
+- **Payments:** who may change the plan.

package/dist/prompts/decisions/teams.md

@@ -0,0 +1,56 @@
+# Teams and workspaces — decision guide
+
+How customers are grouped in the developer's app. In Bridge every signed-in person belongs to a **workspace** (the API and the CLI call it a tenant). A workspace is one customer: it holds the people, their roles, and the plan the customer pays for.
+
+> Other decision guides: `bridge guide decision <name>` (MCP: resource `bridge://guides/decisions/<name>`). How the pieces work underneath: `bridge guide mechanisms`.
+
+## Start from what is there
+
+| Read | MCP | CLI |
+|---|---|---|
+| Whether people can create their own workspace (`tenantSelfSignup`) | `get_app` | `bridge app get` |
+| Existing workspaces | `list_tenants` | `bridge tenant list` |
+| The people in one workspace | `list_users` | `bridge user list --tenant-id <id>` |
+| Roles an invited person can get | `list_roles` | `bridge role list` |
+
+## Ask the developer
+
+Product questions. Ask, wait, never guess.
+
+1. **Is the app for single people or for teams?** With teams, a customer invites colleagues into a shared workspace. For single people, each person simply has a workspace of their own and never sees the word.
+2. **How does someone get in the first time?** Either they sign up and get a new workspace of their own, or they can only join by invitation from someone already inside.
+3. **When someone is invited, which role should they get?** See the **roles** guide: on a new app the default role is Owner, so an invitee without a role becomes an Owner.
+4. **Does the number of people per workspace depend on the plan?** ("1 user on Free, 10 on Pro.") If yes, that is a seat limit: see the **payments** guide.
+5. **Can one person belong to several workspaces?** Bridge supports it and shows a workspace picker at sign-in; the question is whether the developer wants to offer it in their product.
+
+## Decide yourself
+
+- **Self-signup on for a product people try on their own; off for invitation-only products.** Take it from the answer to question 2 and set `tenantSelfSignup` to match. Reason: with it off, a stranger who signs up has nowhere to land.
+- **Use Bridge's team panel for inviting and managing people** (`TeamManagementPanel` in SvelteKit) rather than a page of your own. Reason: it already handles invitations, role changes and removal against the right permissions.
+- **Seats are the built-in `users` limit.** Reason: Bridge counts workspace members itself, so there is nothing for the app to count or report.
+- **Never create workspaces from the app's own code for sign-ups.** Reason: Bridge creates one at signup when self-signup is on; creating them elsewhere makes duplicates.
+- **Create workspaces by hand only for setup and support** (an existing customer you are migrating, or a demo).
+
+## Do it
+
+| Step | MCP | CLI |
+|---|---|---|
+| Allow or stop self-signup | `update_app` (`tenantSelfSignup`) | `bridge app update --tenant-self-signup true` |
+| Create a workspace by hand | `create_tenant` | `bridge tenant create --name … --owner-email …` |
+| Invite someone into a workspace | `invite_user` | `bridge user invite --email … --role … --tenant-id …` |
+| Change someone's role | `update_user` | `bridge user update --email … --role … --tenant-id …` |
+| Limit seats per plan | `set_plan_quota` (metric `users`, kind `gauge`) | `bridge plan quota set pro --metric users --limit 10 --policy hard --kind gauge` |
+| Code for the framework | `get_integration_guide` (topic `team`) | `bridge guide svelte team` |
+
+Pass a role key on every invitation you make on the developer's behalf; leaving it out gives the app's default role.
+
+## Prove it
+
+1. Create a test user (`create_test_user` / `bridge test-user create`) and sign in (`verify_login` / `bridge test-user verify`): the response names the workspace.
+2. Invite a second address into that workspace and check it appears in `list_users` / `bridge user list` with the role you meant.
+
+## Where this connects
+
+- **Roles:** what each person in a workspace may do.
+- **Payments:** a plan belongs to the workspace, not to a person; seats are a plan limit.
+- **Login:** whether sign-up is open at all.

package/dist/prompts/mcp-tools.json

@@ -0,0 +1,77 @@
+{
+  "_comment": [
+    "The names of the Bridge MCP server's tools, and nothing else. The bundled guides are tested against this list: a guide that names a tool not in it fails src/__tests__/guide-decisions.test.ts.",
+    "Source: the `bridgeTools` registry in bridge-api, microservices/account/nebulr-api/mcp/tools/register.ts.",
+    "Regenerate from the thebridge-platform root when a tool is added, renamed or removed: grep -hoE \"^ {2,4}name: '[a-z]+(_[a-z]+)+',\" bridge-api/microservices/account/nebulr-api/mcp/tools/*.ts | sed -E \"s/.*'(.*)'.*/\\1/\" | sort -u",
+    "The count must equal the number of entries in `bridgeTools` (66 at the source below). The twin of this check in bridge-api reads the live registry instead of this copy."
+  ],
+  "source": "bridge-api feature/mcp-journey 689899e",
+  "tools": [
+    "add_redirect_uri",
+    "apply_plan",
+    "clear_flag_schedule",
+    "connect_stripe",
+    "create_api_token",
+    "create_app",
+    "create_feature_flag",
+    "create_plan",
+    "create_role",
+    "create_tenant",
+    "create_test_user",
+    "debug_auth_issue",
+    "delete_feature_flag",
+    "delete_tenant",
+    "diagnose_integration",
+    "evaluate_feature_flag",
+    "export_feature_flags",
+    "get_app",
+    "get_auth_config",
+    "get_branding",
+    "get_environment_info",
+    "get_flag",
+    "get_integration_guide",
+    "get_plan",
+    "get_role",
+    "get_server_info",
+    "get_setup_status",
+    "get_stripe_status",
+    "get_tenant",
+    "get_user",
+    "import_feature_flags",
+    "invite_user",
+    "list_api_tokens",
+    "list_apps",
+    "list_events",
+    "list_feature_flags",
+    "list_plan_quotas",
+    "list_plans",
+    "list_redirect_uris",
+    "list_roles",
+    "list_tenants",
+    "list_users",
+    "remove_plan_price",
+    "remove_plan_quota",
+    "remove_redirect_uri",
+    "remove_user",
+    "revoke_api_token",
+    "scaffold_flags_integration",
+    "set_flag_schedule",
+    "set_plan_price",
+    "set_plan_quota",
+    "setup_communication",
+    "setup_payments",
+    "setup_sso",
+    "toggle_feature_flag",
+    "update_app",
+    "update_auth_methods",
+    "update_branding",
+    "update_feature_flag",
+    "update_password_policy",
+    "update_plan",
+    "update_role",
+    "update_tenant",
+    "update_user",
+    "use_app",
+    "verify_login"
+  ]
+}

package/dist/prompts/orientation.md

@@ -0,0 +1,40 @@
+# What Bridge does
+
+Relay this to the developer as it stands, then add one sentence about what their app has today (read it first: `get_app` and `get_setup_status`, or `bridge app get` and `bridge setup status`).
+
+---
+
+Bridge runs everything between signup and invoice for your app, so you don't build it yourself.
+
+- **Login.** People sign up and sign in with a password, a magic link, a passkey, Google, GitHub and other providers, or their company's SSO, with optional two-factor. Bridge serves the pages; your app adds about fifteen lines. *Want to choose how people sign in?*
+- **Teams and workspaces.** Each customer gets a workspace and can invite teammates into it. You decide whether people create their own workspace or join by invitation. *Is your app for single users or for teams?*
+- **Roles and permissions.** Inside a workspace, roles decide who may do what, and your backend checks them on every request. *Who are the different kinds of people in a customer's workspace?*
+- **Payments and plans.** Plans with prices, trials and limits ("3 projects on Free, 50 on Pro"), checkout through your own Stripe account, and an upgrade prompt when someone hits a limit. *Want to set up a free tier and a paid plan?*
+- **Feature control.** Turn any feature on or off for everyone, a percentage of users, one plan or one customer, without a deploy. *Is there a feature you want to roll out carefully or sell on a higher plan?*
+- **Look and feel.** Sign-in and subscription pages in your colours and fonts, inside your own layout, and emails sent in your app's name. *Want the sign-in pages to look like the rest of your app?*
+- **Going live.** A readiness checklist that says exactly what still points at localhost or test keys, and a test sign-in that proves login works end to end. *Ready to check what stands between you and real users?*
+
+---
+
+## Where to go next
+
+Each area has a decision guide: the questions to ask the developer, and the defaults to apply without asking.
+
+| Area | Decision guide | Journey |
+|---|---|---|
+| Login | `bridge guide decision login` | `bridge guide add-login` |
+| Teams and workspaces | `bridge guide decision teams` | `bridge guide add-teams` |
+| Roles and permissions | `bridge guide decision roles` | — |
+| Payments and plans | `bridge guide decision payments` | `bridge guide add-paid-plan` |
+| Feature control | `bridge guide decision feature-control` | `bridge guide add-feature-flag` |
+| Look and feel | `bridge guide decision look-and-feel` | — |
+| Going live | `bridge guide decision going-live` | `bridge guide go-live` |
+
+In an MCP client the same guides are the resources `bridge://guides/decisions/<area>` (areas: `login`, `teams`, `roles`, `payments`, `feature-control`, `look-and-feel`, `going-live`), and the journeys are the server's prompts of the same names.
+
+How limits, upgrade prompts and page customisation actually work, for every area: `bridge guide mechanisms`.
+
+Two rules hold in every guide:
+
+1. **Product questions go to the developer.** What to charge, who may do what, what a plan includes, what users see: ask, and wait for the answer. Never guess them.
+2. **Mechanics you decide.** Where a guide gives a default, apply it and say why in one line. The developer can overrule it.

package/dist/shape.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Tenant metadata keys the platform writes for its own conversion-pixel
+ * bookkeeping (tracking.service.ts, tenant.service.ts). Never app data.
+ */
+export declare const INTERNAL_TENANT_METADATA_KEYS: string[];
+/** A tenant without the platform's pixel bookkeeping in `metadata`. */
+export declare function shapeTenant<T>(tenant: T): T;
+/**
+ * A plan without the payment provider's ids: each quota's `providerRefs`
+ * (Stripe price and meter ids) is dropped. Prices and quotas otherwise stay
+ * whole — `create_plan` and friends still return the full plan.
+ */
+export declare function shapePlan<T>(plan: T): T;
+/**
+ * Roles with each privilege named once. Every role used to carry the full
+ * privilege object (id, key, description) for every privilege it grants, so a
+ * five-role app repeated the same descriptions five times. Now each role lists
+ * privilege KEYS — what code and create_role/update_role take — and the
+ * descriptions appear once, in `privileges`.
+ */
+export declare function shapeRoleList(roles: unknown[]): {
+    roles: Array<Record<string, unknown>>;
+    privileges: Record<string, string>;
+};
+//# sourceMappingURL=shape.d.ts.map

package/dist/shape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shape.d.ts","sourceRoot":"","sources":["../src/shape.ts"],"names":[],"mappings":"AAUA;;;GAGG;AACH,eAAO,MAAM,6BAA6B,UAA+C,CAAC;AAE1F,uEAAuE;AACvE,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAU3C;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,CAYvC;AAOD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG;IAC/C,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACtC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpC,CAkBA"}

package/dist/shape.js

@@ -0,0 +1,74 @@
+/*
+ * TBP-709 (D) — what `bridge … list` shows, minus the platform's internals.
+ *
+ * The REST DTOs these come from also serve the dashboards and the SDKs, so
+ * they are left alone; the trimming happens at the presentation layer.
+ * Port of bridge-api's MCP `shape.ts` (same functions, same tests) so the
+ * CLI lists and the MCP lists cannot drift. Every function is pure and leaves
+ * its input untouched.
+ */
+/**
+ * Tenant metadata keys the platform writes for its own conversion-pixel
+ * bookkeeping (tracking.service.ts, tenant.service.ts). Never app data.
+ */
+export const INTERNAL_TENANT_METADATA_KEYS = ['pendingPixelEvents', 'conversionTracking'];
+/** A tenant without the platform's pixel bookkeeping in `metadata`. */
+export function shapeTenant(tenant) {
+    if (!tenant || typeof tenant !== 'object')
+        return tenant;
+    const metadata = tenant.metadata;
+    if (!metadata || typeof metadata !== 'object')
+        return tenant;
+    const kept = Object.fromEntries(Object.entries(metadata).filter(([k]) => !INTERNAL_TENANT_METADATA_KEYS.includes(k)));
+    return { ...tenant, metadata: kept };
+}
+/**
+ * A plan without the payment provider's ids: each quota's `providerRefs`
+ * (Stripe price and meter ids) is dropped. Prices and quotas otherwise stay
+ * whole — `create_plan` and friends still return the full plan.
+ */
+export function shapePlan(plan) {
+    if (!plan || typeof plan !== 'object')
+        return plan;
+    const quotas = plan.quotas;
+    if (!Array.isArray(quotas))
+        return plan;
+    return {
+        ...plan,
+        quotas: quotas.map((q) => {
+            if (!q || typeof q !== 'object')
+                return q;
+            const { providerRefs: _drop, ...rest } = q;
+            return rest;
+        }),
+    };
+}
+/**
+ * Roles with each privilege named once. Every role used to carry the full
+ * privilege object (id, key, description) for every privilege it grants, so a
+ * five-role app repeated the same descriptions five times. Now each role lists
+ * privilege KEYS — what code and create_role/update_role take — and the
+ * descriptions appear once, in `privileges`.
+ */
+export function shapeRoleList(roles) {
+    const privileges = {};
+    const shaped = (roles ?? []).map((role) => {
+        const r = (role ?? {});
+        const granted = Array.isArray(r.privileges) ? r.privileges : [];
+        const keys = [];
+        for (const p of granted) {
+            if (typeof p === 'string') {
+                keys.push(p);
+                continue;
+            }
+            if (!p || typeof p.key !== 'string')
+                continue;
+            keys.push(p.key);
+            if (!(p.key in privileges))
+                privileges[p.key] = p.description ?? '';
+        }
+        return { ...r, privileges: keys };
+    });
+    return { roles: shaped, privileges };
+}
+//# sourceMappingURL=shape.js.map

package/dist/shape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shape.js","sourceRoot":"","sources":["../src/shape.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAAC,oBAAoB,EAAE,oBAAoB,CAAC,CAAC;AAE1F,uEAAuE;AACvE,MAAM,UAAU,WAAW,CAAI,MAAS;IACtC,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC;IACzD,MAAM,QAAQ,GAAI,MAAiC,CAAC,QAAQ,CAAC;IAC7D,IAAI,CAAC,QAAQ,IAAI,OAAO,QAAQ,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC;IAC7D,MAAM,IAAI,GAAG,MAAM,CAAC,WAAW,CAC7B,MAAM,CAAC,OAAO,CAAC,QAAmC,CAAC,CAAC,MAAM,CACxD,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,6BAA6B,CAAC,QAAQ,CAAC,CAAC,CAAC,CACpD,CACF,CAAC;IACF,OAAO,EAAE,GAAG,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAO,CAAC;AAC5C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAI,IAAO;IAClC,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACnD,MAAM,MAAM,GAAI,IAA6B,CAAC,MAAM,CAAC;IACrD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IACxC,OAAO;QACL,GAAG,IAAI;QACP,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;YACvB,IAAI,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ;gBAAE,OAAO,CAAC,CAAC;YAC1C,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,GAAG,CAA4B,CAAC;YACtE,OAAO,IAAI,CAAC;QACd,CAAC,CAAC;KACE,CAAC;AACT,CAAC;AAOD;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,KAAgB;IAI5C,MAAM,UAAU,GAA2B,EAAE,CAAC;IAC9C,MAAM,MAAM,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACxC,MAAM,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAA4B,CAAC;QAClD,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAE,CAAC,CAAC,UAA4C,CAAC,CAAC,CAAC,EAAE,CAAC;QACnG,MAAM,IAAI,GAAa,EAAE,CAAC;QAC1B,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;YACxB,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;gBAC1B,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;gBACb,SAAS;YACX,CAAC;YACD,IAAI,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,GAAG,KAAK,QAAQ;gBAAE,SAAS;YAC9C,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YACjB,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,UAAU,CAAC;gBAAE,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,WAAW,IAAI,EAAE,CAAC;QACtE,CAAC;QACD,OAAO,EAAE,GAAG,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;IACpC,CAAC,CAAC,CAAC;IACH,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;AACvC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nebulr-group/bridge-cli",
-  "version": "0.6.0-beta.3",
+  "version": "0.6.0-beta.4",
   "description": "Bridge platform CLI for AI coding agents and developers",
   "author": "Nebulr Group",
   "license": "MIT",