@seliseblocks/cli-os 0.2.10 → 0.2.12

package/AI_USAGE_GUIDE.md

@@ -82,7 +82,13 @@ List projects:
 blocks projects list --json
 ```
 
-`projects create` is currently disabled in this build (commented out pending a product decision) - do not tell users it's available, and do not try to work around its absence with a raw API call. Projects must already exist (created from the Blocks portal) before selecting one below.
+Create a project when none suitable exists (ask the user first - it accepts the Blocks terms on their behalf):
+
+```bash
+blocks projects create "<project name>" --json      # add --dry-run first to show the payload
+```
+
+It always creates exactly one application in the `dev` environment; environment, domain, cookie domain, and production flag are fixed. Adding further environments (`test`, `stg`, `prod`, ...) to an existing project is still portal-only. The command does not select the new project - run `blocks use <tenantId>` with the `tenantId` it prints.
 
 Select a project:
 
@@ -128,8 +134,7 @@ Then run with explicit flags so no prompt is reached:
 blocks new web <appName> --x-blocks-key <projectTenantId> --app-domain <appDomainOrUrl> --client-id <publicOidcClientId>
 ```
 
-`new web` also accepts `--blocks-api-url <url>` and `--oidc-url <url>`, same as `sdk client`
-below. When `--blocks-api-url` is omitted, the scaffold derives it from the app domain as
+`new web` also accepts `--blocks-api-url <url>` and `--oidc-url <url>`. When `--blocks-api-url` is omitted, the scaffold derives it from the app domain as
 `https://blocksapi.<registrable-domain>`; for example `https://dqrsf.slsblx.com` becomes
 `https://blocksapi.slsblx.com`. Pass `--blocks-api-url` only when targeting a non-default Blocks gateway. `--oidc-url` defaults to `https://iam.seliseblocks.com`.
 
@@ -147,7 +152,7 @@ Do not pass CLI auth state to the scaffolded app. Browser apps must use a public
 
 For local browser login on the real host domain:
 
-1. Add `127.0.0.1 <VITE_BLOCKS_DEV_HOST>` to the hosts file.
+1. Add `127.0.0.1 <VITE_BLOCKS_DEV_HOST>` to the hosts file **yourself** (elevated on Windows, `sudo` elsewhere), then tell the user it was added - never stop and ask the user to edit the hosts file by hand. The blocks-frontend-local-https skill has the idempotent add-and-verify commands for each OS.
 2. Run `npm install`.
 3. Run `npm run cert`.
 4. Run `npm run dev`.
@@ -155,20 +160,6 @@ For local browser login on the real host domain:
 
 The generated cert script uses the `selfsigned` Node dependency, so it works from normal PowerShell after `npm install`; do not tell Windows users to switch to Git Bash just for OpenSSL. If hosted login or secure cookies fail locally, confirm the app is opened with the HTTPS dev URL from `VITE_BLOCKS_DEV_HOST`.
 
-## SDK Client (read-only)
-
-`sdk client` answers "I want to use the Blocks SDK - show me the client." It resolves this project's `@seliseblocks/client` config (same values `new web` scaffolds an app with) and prints a ready-to-paste `createBlocksClient(...)` snippet - **it never writes a file or mutates anything**. To scaffold a full app instead, use `new web` above.
-
-```bash
-blocks sdk client --x-blocks-key <projectTenantId> --app-domain <appDomainOrUrl> --client-id <publicOidcClientId> --blocks-api-url https://api.seliseblocks.com
-```
-
-Unlike `new web`, `sdk client` keeps `--blocks-api-url` defaulted to `https://api.seliseblocks.com`; only pass it explicitly if your project uses a different gateway URL. Passing both `--app-domain` and `--client-id` skips the project lookup entirely, so it needs no CLI login at all - useful for a quick, non-interactive check. Omit either one and it resolves from the selected project instead (auto-picks when there's exactly one match, otherwise lists the options and asks you to pass the flag explicitly - it does not prompt or create anything, since this command is read-only). Use `--json` for the resolved values instead of the snippet.
-
-## Skills
-
-`skill list [--json]` / `skill show <name> [--json]` / `skill add <name> [--dir <path>]` read this package's bundled copy of `blocks-skills/*/SKILL.md` - local-only, no cloud calls. `skill add` copies a skill's **entire directory** (`SKILL.md` plus any supporting files, e.g. `flows/*.md`) into `<dir>/<name>/` (default `./blocks-skills`) in the current directory, for pulling a single skill into a project outside this monorepo. `skill list`'s human-readable output (and the "unknown skill" error from `show`/`add`) both point at the full public skill catalog, in case the locally bundled set is out of date. As with any skill file, verify command names against this guide or `blocks --help` before running them - skills are conversational context, not command ground truth.
-
 ## IAM, MFA, and Auth Admin
 
 `iam me` reads the CLI operator's own account identity (bootstrapping, not a project resource):
@@ -187,8 +178,8 @@ Command families (run `blocks --help` for the full flag reference on each):
 - `iam resources *` - resource groups and feature flags (read-only).
 - `iam organizations *` - list/get/create/update, `my`, and organization config get/save.
 - `iam signup-settings *` - get/save tenant signup policy.
-- `mfa config *`, `mfa totp *`, `mfa generate`/`resend`/`verify`, `mfa method set`, `mfa disable`, `mfa backup-codes *` - tenant MFA policy plus enrollment/verification/backup-code flows.
-- `mfa totp enable --mfa-type <n>` - composed TOTP enrollment: `totp setup` → prints the QR/secret → `totp verify-setup` → `method set` → `backup-codes generate`, one confirmation. Prefer this over running the individual steps. `--mfa-type` is required and not defaulted - the tenant-specific integer meaning "TOTP" isn't documented anywhere in this CLI; don't guess it, ask the user or check `mfa config get`. **Prompts interactively for the verification code unless `--code <c>` is given** - an agent running this non-interactively must supply `--code` (from wherever the user's authenticator app output is captured) or it will hang waiting on stdin. Deliberately excludes `mfa config save` (a separate tenant-wide admin policy, not part of one user's enrollment).
+- `mfa config *`, `mfa totp *`, `mfa generate`/`resend`/`verify`, `mfa method set`, `mfa disable`, `mfa backup-codes *` - tenant MFA policy plus enrollment/verification/backup-code flows. `mfa method set` only switches on `1`/`2`; every other value makes IAM disable the user's MFA. A tenant policy with `enableMfa` but an empty `userMfaType` list never actually requires MFA at login.
+- `mfa totp enable --mfa-type <n>` - composed TOTP enrollment: `totp setup` → prints the QR/secret → `totp verify-setup` → `method set` → `backup-codes generate`, one confirmation. Prefer this over running the individual steps. `--mfa-type` is required and not defaulted - pass `1`, IAM's `UserMfaType` value for TOTP (`0` None, `1` TOTP, `2` Email, `3` Sms and `4` WhatsApp are declared but have no provider). The same enum drives `--auth-type`, `--user-mfa-type`, and a client's `--allowed-mfa-methods`. **Prompts interactively for the verification code unless `--code <c>` is given** - an agent running this non-interactively must supply `--code` (from wherever the user's authenticator app output is captured) or it will hang waiting on stdin. Deliberately excludes `mfa config save` (a separate tenant-wide admin policy, not part of one user's enrollment).
 - `auth idp *` - identity provider (SSO/OIDC) configuration: list/get/create/update/delete/status.
 - `auth config *` - AuthController tenant config (token lifetimes, lockout policy, etc.).
 - `auth client-credentials *` - machine-to-machine client credentials: list/save/delete.

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) SELISE Blocks
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) SELISE Blocks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -58,13 +58,13 @@ Global options available on every command:
 | `blocks logout` | Revoke the current refresh token when possible and remove local session data. |
 | `blocks projects list [--json]` | List accessible Blocks projects via `/os/v4/Project/Gets` using the account token. Read-only. |
 | `blocks projects get [tenantId] [--deployment] [--json]` | Read one project from `Project/Gets`. Uses selected project when `tenantId` is omitted. Pass `--deployment` to also include the environment, tenantGroupId, and linked repo assets that `release deploy` resolves internally. Read-only. |
-| `blocks projects create` | **Currently disabled** (commented out, not deleted) - the dispatch entry, import, and help text were removed pending a product decision. Do not tell users this command is available. |
+| `blocks projects create <name> [--allow-duplicate-name] [--yes] [--dry-run] [--json]` | Create a new project via `/os/v4/Project/Create` with the account token (no project needs to be selected). Always creates **exactly one application, in the `dev` environment** - environment, domain, cookie domain, and production flag are not configurable, and the domain sent is a placeholder the platform replaces with the one it assigns. Confirms first because it accepts the Blocks terms on your behalf. Refuses a name already used by another project unless `--allow-duplicate-name` is passed, then verifies the result against `Project/Gets` and prints the new `tenantId`, `tenantGroupId`, and assigned domain. Does not select the project - run `blocks use <tenantId>` next. |
 | `blocks use <tenantId>` | Save the selected project tenant globally and in `blocks.json` when present. Does not call cloud APIs. |
 | `blocks deselect` | Clear the selected project tenant (globally and in `blocks.json`) and drop its cached impersonation token. Use this to recover when an impersonated project token has expired or failed, then run `blocks use <tenantId>` again to reselect and re-impersonate. |
 | `blocks iam me [--json]` | Read the current user from IAM using the account token (CLI operator identity, not a project resource). |
 | `blocks iam users *`, `iam email available`, `iam roles *`, `iam permissions *`, `iam resources *`, `iam organizations *`, `iam signup-settings *` | Full IAM admin surface for the selected project (users, roles, permissions, resource metadata, organizations and their config, signup settings). Project-scoped: requires a selected project and always uses an impersonated project token, never the account token. Mutating commands support `--dry-run`/`--yes`; rich payloads accept `--body '<json>'`/`--file <path>` on top of common convenience flags. Run `blocks --help` for the full command/flag list. |
 | `blocks mfa config *`, `mfa totp *`, `mfa generate`, `mfa resend`, `mfa verify`, `mfa method set`, `mfa disable`, `mfa backup-codes *` | Project-scoped MFA admin and self-service surface (tenant MFA policy, TOTP enrollment, OTP challenge/verify, method switch, backup codes). Same project-selection and impersonation-only rules as IAM above. |
-| `blocks mfa totp enable --mfa-type <n> [--code <c>]` | Composed TOTP enrollment: `totp setup` → prints the QR/secret → prompts for the code (or `--code` to skip the prompt) → `totp verify-setup` → `method set` → `backup-codes generate`, one confirmation. `--mfa-type` is required and not defaulted - the tenant-specific integer meaning "TOTP" isn't documented anywhere in this CLI. Deliberately excludes `mfa config save` (a separate, tenant-wide admin policy, not part of one user's enrollment). |
+| `blocks mfa totp enable --mfa-type <n> [--code <c>]` | Composed TOTP enrollment: `totp setup` → prints the QR/secret → prompts for the code (or `--code` to skip the prompt) → `totp verify-setup` → `method set` → `backup-codes generate`, one confirmation. `--mfa-type` is required and not defaulted - `1` is TOTP in IAM's `UserMfaType` enum (`0` None, `1` TOTP, `2` Email, `3` Sms, `4` WhatsApp; only 1 and 2 have a provider). Deliberately excludes `mfa config save` (a separate, tenant-wide admin policy, not part of one user's enrollment). |
 | `blocks auth idp *`, `auth config *`, `auth client-credentials *`, `auth oidc-clients *` | Auth admin surface: identity providers, AuthController tenant config, machine-to-machine client credentials, and OIDC client app registrations. Project-scoped, impersonated project token only. `idp delete`, `client-credentials save`/`delete`, and `oidc-clients save`/`delete`/`rotate-secret` return or handle secrets shown only once - treat CLI output as sensitive and never log it. |
 | `blocks mail config *`, `mail template *`, `mail mailbox *` | Project-scoped mail admin surface via `/os/v4/Mail/*`: SMTP/inbound configuration upsert/delete/duplicate, mail template CRUD/clone, and mailbox message reads. Impersonated project token only. `mail config save`'s `--account-password` is redacted in `--dry-run` output only. |
 | `blocks mail send [--to a,b] [--purpose <p>] [--language <c>] ...` / `mail sendtoany [same, plus --is-test-mail]` | Send an email via `/logic/v4/Mail/Send` / `/logic/v4/Mail/SendToAny`. Impersonated project token only; `--project-key` defaults to the selected project. |
@@ -96,8 +96,6 @@ Global options available on every command:
 | `blocks release builds list [repoId] [--repo-id <repoId>] [--json]` | List Release build details for a repository. When `repoId` is omitted, resolves it from the selected project's linked repo assets - auto-picked if there's exactly one, otherwise you're prompted to choose. Read-only. |
 | `blocks release builds get <buildId> [--json]` | Alias for `release status`. Read-only. |
 | `blocks new web <name> [--app-domain <domain>] [--client-id <oidcClientId>] [--x-blocks-key <tenantId>] [--blocks-api-url <url>] [--oidc-url <url>]` | Create a Vite React starter app that talks to Blocks exclusively through `@seliseblocks/client` (a single `createBlocksClient()` instance) using the SDK hosted IdP flow: `blocksClient.auth.idp.redirectToProvider()` on login click and `blocksClient.auth.idp.callback()` on `/login/callback`. Includes route guards, auto-refresh through `auth.oidc.refreshToken()`, live `auth`/`iam`/`data`/`localization` SDK examples, environment config, and safe `.gitignore` defaults. Uses the selected project (see `use`) unless `--x-blocks-key` overrides it. `--app-domain` and `--client-id` are resolved from the project record when omitted: the domain auto-picks if the project has exactly one, otherwise you're prompted to choose; the OIDC client is picked from the project's existing clients, or you can create a minimal one (display name + redirect URI) on the spot, or skip and register one later from the portal or `auth oidc-clients save`. When `--blocks-api-url` is omitted, `new web` derives it from the app domain as `https://blocksapi.<registrable-domain>`; for example `https://dqrsf.slsblx.com` becomes `https://blocksapi.slsblx.com`. Pass a different Data/IAM/Localization/OS gateway URL explicitly only if your project uses a non-default one. `--oidc-url` defaults to `https://iam.seliseblocks.com`. |
-| `blocks skill list [--json]` / `skill show <name> [--json]` / `skill add <name> [--dir <path>]` | Local-only, no cloud calls: list/print the bundled `blocks-skills/*/SKILL.md` agent context docs, or copy a skill's entire directory (`SKILL.md` plus any supporting files) into `<dir>/<name>/` (default `./blocks-skills`) for use in a project outside this monorepo. `list`'s output and `show`/`add`'s "unknown skill" error both point at the full public skill catalog in case the bundled set is out of date. |
-| `blocks sdk client [--app-domain <domain>] [--client-id <oidcClientId>] [--x-blocks-key <tenantId>] [--blocks-api-url <url>] [--oidc-url <url>] [--json]` | Read-only: resolves this project's `@seliseblocks/client` config and prints a ready-to-paste `createBlocksClient(...)` snippet. Unlike `new web`, the API URL defaults to `https://api.seliseblocks.com` unless `--blocks-api-url` is passed. Passing both `--app-domain` and `--client-id` skips the project lookup entirely (no login required). Writes nothing - use `new web` to scaffold a full app. |
 
 Use `--json` on commands when AI or automation needs machine-readable output. Use `--dry-run` before mutations and `--yes` only after approval.
 
@@ -170,4 +168,4 @@ Localization dictionaries are not created by `init` - the default path is `block
 - Localization covers dictionary validate/pull/push plus the full raw `/localization/v4/*` API surface (assistant, config, glossary, key, language, module). Prefer `localization key translate-and-export` over running translate/generate/export by hand.
 - Release covers deploy trigger and build status/read commands only.
 - No direct artifact upload unless Blocks Release adds a confirmed artifact upload API.
-- `projects create` is currently disabled in this build (commented out pending a product decision) - don't reference it as available.
+- `projects create` creates a `dev`-only, single-application project. It cannot add environments to an existing project or create a non-`dev` one - those still go through the Blocks portal.

package/bin/run.js

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-
-await import("../dist/index.js");
+
+await import("../dist/index.js");

package/dist/commands/auth/oidc-clients/save.js

@@ -1,7 +1,9 @@
 import { booleanFlag, optionalBooleanFlag, stringFlag } from "../../../lib/args.js";
 import { blocksRequest } from "../../../lib/api.js";
 import { confirmMutation } from "../../../lib/confirm.js";
+import { defaults } from "../../../lib/config.js";
 import { compact, jsonBodyFlag, listFlag } from "../../../lib/json-flag.js";
+import { withBlocksIdentityProviderDiscovery } from "../../../lib/oidc-discovery.js";
 import { writeOutput } from "../../../lib/output.js";
 import { requestContext } from "../../../lib/request-context.js";
 import { parseCommand, selectedProject } from "../../../lib/workspace.js";
@@ -37,6 +39,7 @@ export async function authOidcClientsSave(argv) {
         })
     };
     const projectKey = await selectedProject(flags);
+    const oidcUrl = stringFlag(flags, "oidc-url", { defaultValue: defaults().oidcUrl });
     const itemId = typeof overrides.itemId === "string" ? overrides.itemId : undefined;
     // Saving an existing client (itemId set) replaces the whole client document
     // rather than merging -- the portal's own Edit dialog always resubmits every
@@ -51,7 +54,7 @@ export async function authOidcClientsSave(argv) {
             projectTenantId: projectKey
         })
         : {};
-    const body = { ...current, ...overrides };
+    const body = withBlocksIdentityProviderDiscovery({ ...current, ...overrides }, oidcUrl, projectKey);
     if (booleanFlag(flags, "dry-run")) {
         writeOutput({ dryRun: true, endpoint: "/iam/v4/oidc-clients", request: redactSecret(body) }, flags);
         return;

package/dist/commands/auth/refresh.js

@@ -2,6 +2,7 @@ import { parseFlags, stringFlag } from "../../lib/args.js";
 import { getAccountSession, getImpersonatedProjectSession } from "../../lib/auth.js";
 import { readConfig } from "../../lib/config.js";
 import { readTokenStore } from "../../lib/token-store.js";
+import { writeOutput } from "../../lib/output.js";
 export async function authRefresh(argv) {
     const { flags } = parseFlags(argv);
     const accountName = stringFlag(flags, "account");
@@ -9,9 +10,17 @@ export async function authRefresh(argv) {
     const config = await readConfig();
     const store = await readTokenStore();
     const account = await getAccountSession(accountName);
-    console.log(`Account '${account.account}' session ready for tenant ${account.accountTenant}`);
-    if (!project)
+    if (!project) {
+        // --json has to produce JSON on success too, not just on the error path, or an
+        // agent that asked for machine-readable output gets a prose line to parse.
+        if (flags.json) {
+            writeOutput({ account: account.account, accountTenant: account.accountTenant, refreshed: "account" }, flags);
+        }
+        else {
+            console.log(`Account '${account.account}' session ready for tenant ${account.accountTenant}`);
+        }
         return;
+    }
     if (!config.selectedProject?.tenantId) {
         throw new Error("No project selected. Run `blocks use <tenantId>` first.");
     }
@@ -20,5 +29,15 @@ export async function authRefresh(argv) {
         throw new Error("No project session exists yet. A service command must create impersonation first.");
     }
     const projectSession = await getImpersonatedProjectSession(account.account);
+    if (flags.json) {
+        writeOutput({
+            account: account.account,
+            accountTenant: account.accountTenant,
+            projectTenantId: projectSession.tenantId,
+            refreshed: "account+project"
+        }, flags);
+        return;
+    }
+    console.log(`Account '${account.account}' session ready for tenant ${account.accountTenant}`);
     console.log(`Project session ready for tenant ${projectSession.tenantId}`);
 }

package/dist/commands/mfa/generate.js

@@ -1,13 +1,16 @@
-import { integerFlag, stringFlag } from "../../lib/args.js";
+import { optionalIntegerFlag, stringFlag } from "../../lib/args.js";
 import { blocksRequest } from "../../lib/api.js";
 import { writeOutput } from "../../lib/output.js";
 import { requestContext } from "../../lib/request-context.js";
 import { parseCommand, selectedProject } from "../../lib/workspace.js";
 export async function mfaGenerate(argv) {
     const { args, flags } = parseCommand(argv);
-    const mfaType = integerFlag(flags, "mfa-type", NaN) || Number(args[0]);
-    if (!Number.isInteger(mfaType))
-        throw new Error("Provide --mfa-type <n> (or a positional integer).");
+    // optionalIntegerFlag, not `integerFlag(...) || Number(args[0])`: mfaType 0 (None) is a
+    // valid enum value, and `0 || ...` silently fell through to the missing positional.
+    const mfaType = optionalIntegerFlag(flags, "mfa-type") ?? Number(args[0]);
+    if (!Number.isInteger(mfaType)) {
+        throw new Error("Provide --mfa-type <n> (or a positional integer). Only 1 (TOTP) and 2 (Email) have an OTP provider; IAM rejects the rest.");
+    }
     const projectKey = await selectedProject(flags);
     const result = await blocksRequest("/iam/v4/mfa/generate", {
         body: {

package/dist/commands/mfa/method-set.js

@@ -1,13 +1,22 @@
-import { integerFlag } from "../../lib/args.js";
+import { optionalIntegerFlag } from "../../lib/args.js";
 import { blocksRequest } from "../../lib/api.js";
 import { writeOutput } from "../../lib/output.js";
 import { requestContext } from "../../lib/request-context.js";
 import { parseCommand, selectedProject } from "../../lib/workspace.js";
 export async function mfaMethodSet(argv) {
     const { args, flags } = parseCommand(argv);
-    const mfaType = integerFlag(flags, "mfa-type", NaN) || Number(args[0]);
-    if (!Number.isInteger(mfaType))
-        throw new Error("Provide --mfa-type <n> (or a positional integer).");
+    // optionalIntegerFlag, not `integerFlag(...) || Number(args[0])`: mfaType 0 (None) is a
+    // valid enum value, and `0 || ...` silently fell through to the missing positional.
+    const mfaType = optionalIntegerFlag(flags, "mfa-type") ?? Number(args[0]);
+    if (!Number.isInteger(mfaType)) {
+        throw new Error("Provide --mfa-type <n> (or a positional integer). IAM's UserMfaType: 0 None, 1 TOTP, 2 Email, 3 Sms, 4 WhatsApp.");
+    }
+    // IAM's PUT /mfa/method only branches on TOTP and Email; every other value falls
+    // through to its disable path and turns the user's MFA off. Say so rather than
+    // letting "switch to SMS" silently unenroll them.
+    if (mfaType !== 1 && mfaType !== 2) {
+        console.warn(`Warning: IAM only switches to 1 (TOTP) or 2 (Email). --mfa-type ${mfaType} disables MFA for this user instead -- use 'blocks mfa disable' if that is what you meant.`);
+    }
     const projectKey = await selectedProject(flags);
     const result = await blocksRequest("/iam/v4/mfa/method", {
         body: { mfaType },

package/dist/commands/mfa/totp-enable.d.ts

@@ -3,8 +3,8 @@
  * method to TOTP -> generate backup codes. This is one real enrollment sitting, not four
  * independent tasks -- nobody enables TOTP setup and comes back next week to verify it.
  *
- * --mfa-type is still required, not defaulted: the numeric MFA-method value that means
- * "TOTP" for a given tenant isn't documented anywhere in this CLI (mfa:method:set/mfa:generate
- * take the same raw, tenant-defined integer), so it's not safe to guess one here.
+ * --mfa-type is still required, not defaulted: it is IAM's UserMfaType value to make active
+ * after enrollment (1 = TOTP), the same integer mfa:method:set and mfa:generate take. Keeping
+ * it explicit means the caller states which method they are enrolling, not this command.
  */
 export declare function mfaTotpEnable(argv: string[]): Promise<void>;

package/dist/commands/mfa/totp-enable.js

@@ -12,15 +12,15 @@ import { mfaTotpVerifySetup } from "./totp-verify-setup.js";
  * method to TOTP -> generate backup codes. This is one real enrollment sitting, not four
  * independent tasks -- nobody enables TOTP setup and comes back next week to verify it.
  *
- * --mfa-type is still required, not defaulted: the numeric MFA-method value that means
- * "TOTP" for a given tenant isn't documented anywhere in this CLI (mfa:method:set/mfa:generate
- * take the same raw, tenant-defined integer), so it's not safe to guess one here.
+ * --mfa-type is still required, not defaulted: it is IAM's UserMfaType value to make active
+ * after enrollment (1 = TOTP), the same integer mfa:method:set and mfa:generate take. Keeping
+ * it explicit means the caller states which method they are enrolling, not this command.
  */
 export async function mfaTotpEnable(argv) {
     const { flags } = parseCommand(argv);
     const mfaType = integerFlag(flags, "mfa-type", NaN);
     if (!Number.isInteger(mfaType)) {
-        throw new Error("Provide --mfa-type <n> -- the numeric MFA method value your tenant uses for TOTP (the same value 'mfa:method:set' expects).");
+        throw new Error("Provide --mfa-type <n> -- the UserMfaType value to make active after enrollment (1 is TOTP, the same value 'mfa:method:set' expects).");
     }
     if (booleanFlag(flags, "dry-run")) {
         writeOutput({

package/dist/commands/mfa/verify.js

@@ -8,8 +8,10 @@ export async function mfaVerify(argv) {
     const mfaId = args[0] || stringFlag(flags, "mfa-id", { required: true });
     const verificationCode = args[1] || stringFlag(flags, "code", { required: true });
     const authType = integerFlag(flags, "auth-type", NaN);
-    if (!Number.isInteger(authType))
-        throw new Error("Provide --auth-type <n>.");
+    if (!Number.isInteger(authType)) {
+        // Same UserMfaType enum as --mfa-type -- IAM types this field as UserMfaType too.
+        throw new Error("Provide --auth-type <n> -- the method that issued the challenge: 1 TOTP, 2 Email.");
+    }
     const projectKey = await selectedProject(flags);
     const result = await blocksRequest("/iam/v4/mfa/verify", {
         body: {

package/dist/commands/new/web.js

@@ -4,6 +4,7 @@ import { confirmMutation } from "../../lib/confirm.js";
 import { defaults, readConfig, writeConfig } from "../../lib/config.js";
 import { apiUrlFromAppDomain } from "../../lib/domains.js";
 import { CliActionableError } from "../../lib/errors.js";
+import { withBlocksIdentityProviderDiscovery } from "../../lib/oidc-discovery.js";
 import { findProjectByTenantId } from "../../lib/project-info.js";
 import { promptText, selectFromList } from "../../lib/prompt.js";
 import { requestContext } from "../../lib/request-context.js";
@@ -187,7 +188,7 @@ async function createOidcClientInteractively(tenantId, appDomain, appName, flags
     // straight to the provider via window.location.assign -- without this flag IAM
     // shows an interstitial "continue" click on the hosted login page instead of
     // redirecting immediately, which is dead weight for a flow the SPA already drives.
-    const body = {
+    const body = withBlocksIdentityProviderDiscovery({
         clientDisplayName: displayName,
         clientType: "public",
         isActive: true,
@@ -196,7 +197,7 @@ async function createOidcClientInteractively(tenantId, appDomain, appName, flags
         registerAsIdentityProvider: true,
         requirePkce: true,
         scope: "openid profile"
-    };
+    }, stringFlag(flags, "oidc-url", { defaultValue: defaults().oidcUrl }), tenantId);
     await confirmMutation(flags, `Create OIDC client '${displayName}' for this project. The response's client secret (if any) is shown once.`);
     const result = await blocksRequest("/iam/v4/oidc-clients", {
         body,

package/dist/commands/projects/create.js

@@ -1,42 +1,136 @@
+import { randomBytes } from "node:crypto";
 import { booleanFlag, stringFlag } from "../../lib/args.js";
 import { blocksRequest } from "../../lib/api.js";
 import { confirmMutation } from "../../lib/confirm.js";
+import { CliActionableError } from "../../lib/errors.js";
+import { isRecord } from "../../lib/data-response.js";
 import { writeOutput } from "../../lib/output.js";
-import { parseCommand } from "../../lib/workspace.js";
+import { listProjectGroups } from "../../lib/project-info.js";
 import { requestContext } from "../../lib/request-context.js";
+import { parseCommand } from "../../lib/workspace.js";
+const CREATE_ENDPOINT = "/os/v4/Project/Create";
+// This command creates exactly one application, always in 'dev'. More
+// environments are added later from the portal (or by a future command that
+// passes tenantGroupId); nothing here may widen that.
+const ENVIRONMENT = "dev";
+// Project/Gets builds each tenantId as the environment letter prefixed onto
+// the tenant group id -- 'd' for dev, uppercased.
+const ENVIRONMENT_LETTER = "d";
+const ENVIRONMENT_TENANT_PREFIX = ENVIRONMENT_LETTER.toUpperCase();
+// Only ever a placeholder: the server validates that the domain parses as an
+// absolute http(s) URL and then discards it, assigning its own domain during
+// provisioning (environment letter + tenant slug, e.g.
+// https://dboafe.slsblx.com). Mirror that shape so a dry-run payload looks
+// like what the platform actually hands back.
+const PLACEHOLDER_BASE_DOMAIN = "slsblx.com";
+const PLACEHOLDER_COOKIE_DOMAIN = "slsblx.com";
+const NAME_MIN_LENGTH = 3;
+const NAME_MAX_LENGTH = 100;
+const VERIFY_ATTEMPTS = 5;
+const VERIFY_INTERVAL_MS = 2000;
 export async function createProject(argv) {
     const { args, flags } = parseCommand(argv);
-    const name = args[0] || stringFlag(flags, "name", { required: true });
-    const env = stringFlag(flags, "env", { defaultValue: "dev" });
-    const domain = stringFlag(flags, "domain", { defaultValue: `https://${slug(name)}-${env}.seliseblocks.com` });
-    const cookieDomain = stringFlag(flags, "cookie-domain", { defaultValue: "seliseblocks.com" });
-    const production = booleanFlag(flags, "production");
+    const name = (args[0] || stringFlag(flags, "name")).trim();
+    if (!name) {
+        throw new CliActionableError("Missing project name.", "missing_project_name", 'blocks projects create "<name>"');
+    }
+    if (name.length < NAME_MIN_LENGTH || name.length > NAME_MAX_LENGTH) {
+        throw new CliActionableError(`Project name must be between ${NAME_MIN_LENGTH} and ${NAME_MAX_LENGTH} characters.`, "invalid_project_name", `blocks projects create "<${NAME_MIN_LENGTH}-${NAME_MAX_LENGTH} character name>"`);
+    }
     const body = {
         name,
         isAcceptBlocksTerms: true,
         isUseBlocksExclusively: true,
-        isProduction: production,
+        isProduction: false,
         resources: [],
         applicationContexts: [
             {
-                cookieDomain,
-                domain,
-                environment: env
+                cookieDomain: PLACEHOLDER_COOKIE_DOMAIN,
+                domain: placeholderDomain(),
+                environment: ENVIRONMENT
             }
         ]
     };
     if (booleanFlag(flags, "dry-run")) {
-        writeOutput({ dryRun: true, request: body }, flags);
+        writeOutput({ dryRun: true, endpoint: CREATE_ENDPOINT, request: body }, flags);
         return;
     }
-    await confirmMutation(flags, `Create Blocks project '${name}' with '${env}' environment.`);
-    const result = await blocksRequest("/os/v4/Project/Create", {
+    if (!booleanFlag(flags, "allow-duplicate-name")) {
+        await assertNameIsFree(name, flags);
+    }
+    await confirmMutation(flags, `Create Blocks project '${name}' with a single '${ENVIRONMENT}' environment. This accepts the Blocks terms (isAcceptBlocksTerms, isUseBlocksExclusively) on your behalf.`);
+    // No tenantGroupId in the body: omitting it is what makes this a new
+    // project. Sending one would instead add an environment to an existing
+    // project, which this command deliberately cannot do.
+    const result = await blocksRequest(CREATE_ENDPOINT, {
         accountAuth: true,
         ...requestContext(flags),
         body
     });
-    writeOutput(result, flags);
+    // Project/Create answers validation failures with HTTP 200 and
+    // { isSuccess: false, errors: { property: message } }, so the status code
+    // alone never proves the project was created.
+    if (!result?.isSuccess || !result.tenantGroupId) {
+        throw new CliActionableError(`Project/Create rejected '${name}': ${formatErrors(result?.errors)}`, "project_create_failed", "blocks projects list --json");
+    }
+    const tenantGroupId = result.tenantGroupId;
+    const created = await findCreatedProject(tenantGroupId, flags);
+    const tenantId = created?.tenantId ?? `${ENVIRONMENT_TENANT_PREFIX}${tenantGroupId}`;
+    writeOutput({
+        domain: created?.applications?.[0]?.domain ?? "",
+        environment: created?.environment ?? ENVIRONMENT,
+        name: created?.name ?? name,
+        tenantGroupId,
+        tenantId,
+        verified: Boolean(created)
+    }, flags);
+    if (!flags.json) {
+        if (!created) {
+            console.log(`Project/Gets has not listed '${tenantId}' yet. Re-run 'blocks projects list' to confirm before using it.`);
+        }
+        console.log(`Next: blocks use ${tenantId}`);
+    }
+}
+async function assertNameIsFree(name, flags) {
+    const groups = await listProjectGroups(flags);
+    const target = name.toLowerCase();
+    const clash = groups.some((group) => (group.name ?? "").trim().toLowerCase() === target ||
+        (group.projects ?? []).some((project) => (project.name ?? "").trim().toLowerCase() === target));
+    if (!clash)
+        return;
+    // A retried create makes a second tenant group with the same name rather
+    // than failing, so an accidental duplicate is only preventable here.
+    throw new CliActionableError(`A project named '${name}' already exists on this account.`, "project_name_taken", "blocks projects list --json, or re-run with --allow-duplicate-name to create a second project with this name");
+}
+// Provisioning is asynchronous (Project/Create hands the tenant to a
+// consumer queue) but fast, so poll Project/Gets briefly instead of
+// reporting a tenantId the platform has not published yet.
+async function findCreatedProject(tenantGroupId, flags) {
+    const expectedTenantId = `${ENVIRONMENT_TENANT_PREFIX}${tenantGroupId}`;
+    for (let attempt = 0; attempt < VERIFY_ATTEMPTS; attempt += 1) {
+        if (attempt > 0)
+            await delay(VERIFY_INTERVAL_MS);
+        const groups = await listProjectGroups(flags).catch(() => []);
+        const group = groups.find((item) => item.tenantGroupId === tenantGroupId);
+        const project = (group?.projects ?? []).find((item) => item.tenantId === expectedTenantId || item.environment === ENVIRONMENT);
+        if (project)
+            return project;
+    }
+    return undefined;
+}
+function placeholderDomain() {
+    return `https://${ENVIRONMENT_LETTER}${randomSlug(5)}.${PLACEHOLDER_BASE_DOMAIN}`;
+}
+function randomSlug(length) {
+    const letters = "abcdefghijklmnopqrstuvwxyz";
+    return Array.from(randomBytes(length), (byte) => letters[byte % letters.length]).join("");
+}
+function formatErrors(errors) {
+    if (!isRecord(errors))
+        return "no error detail returned.";
+    const entries = Object.entries(errors).map(([key, value]) => `${key}: ${String(value)}`);
+    return entries.length > 0 ? entries.join("; ") : "no error detail returned.";
 }
-function slug(value) {
-    return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 40) || "blocks-app";
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
 }