@seliseblocks/cli-os 0.1.4 → 0.2.0

package/dist/lib/api.d.ts

@@ -5,8 +5,9 @@ type RequestOptions = {
     body?: unknown;
     impersonatedProjectAuth?: boolean;
     method?: string;
+    preferImpersonatedProjectAuth?: boolean;
     projectTenantId?: string;
-    query?: Record<string, string | number | boolean | undefined>;
+    query?: Record<string, string | number | boolean | string[] | undefined>;
 };
 export declare function blocksRequest<T>(path: string, options?: RequestOptions): Promise<T>;
 export {};

package/dist/lib/api.js

@@ -6,31 +6,75 @@ export async function blocksRequest(path, options = {}) {
     const baseUrl = options.apiUrl ?? profile.apiUrl;
     const url = buildUrl(baseUrl, path);
     for (const [key, value] of Object.entries(options.query ?? {})) {
-        if (value !== undefined)
-            url.searchParams.set(key, String(value));
+        if (value === undefined)
+            continue;
+        if (Array.isArray(value)) {
+            for (const item of value)
+                url.searchParams.append(key, item);
+            continue;
+        }
+        url.searchParams.set(key, String(value));
     }
-    const headers = {
+    const isFormData = options.body instanceof FormData;
+    const baseHeaders = {
         Accept: "application/json"
     };
-    if (options.body !== undefined)
-        headers["Content-Type"] = "application/json";
-    if (options.accountAuth) {
-        const account = await getAccountSession(options.accountName);
-        headers.Authorization = `Bearer ${account.accessToken}`;
-        headers["x-blocks-key"] = account.accountTenant;
+    if (options.body !== undefined && !isFormData)
+        baseHeaders["Content-Type"] = "application/json";
+    const send = async (forceRefresh) => {
+        const headers = { ...baseHeaders };
+        if (options.accountAuth) {
+            const account = await getAccountSession(options.accountName, { forceRefresh });
+            headers.Authorization = `Bearer ${account.accessToken}`;
+            headers["x-blocks-key"] = account.accountTenant;
+        }
+        if (options.impersonatedProjectAuth) {
+            const project = await getImpersonatedProjectSession(options.accountName, options.projectTenantId, { forceRefresh });
+            headers.Authorization = `Bearer ${project.accessToken}`;
+            // The impersonated token is minted and signed by the root tenant's IdP --
+            // its JWKS only exists under the root tenant, so signature validation
+            // needs x-blocks-key pointed at root, not the target project. The actual
+            // tenant-data scoping comes from a claim already inside the validated
+            // token, not from this header.
+            headers["x-blocks-key"] = project.accountTenant;
+        }
+        if (options.preferImpersonatedProjectAuth) {
+            const tenantId = options.projectTenantId ?? config.selectedProject?.tenantId;
+            if (tenantId) {
+                const project = await getImpersonatedProjectSession(options.accountName, tenantId, { forceRefresh });
+                headers.Authorization = `Bearer ${project.accessToken}`;
+                headers["x-blocks-key"] = project.accountTenant;
+            }
+            else {
+                const account = await getAccountSession(options.accountName, { forceRefresh });
+                headers.Authorization = `Bearer ${account.accessToken}`;
+                headers["x-blocks-key"] = account.accountTenant;
+            }
+        }
+        return fetch(url, {
+            body: options.body === undefined ? undefined : isFormData ? options.body : JSON.stringify(options.body),
+            headers,
+            method: options.method ?? (options.body === undefined ? "GET" : "POST")
+        }).catch((error) => {
+            throw new Error(`Blocks API request failed for ${url.origin}${url.pathname}: ${error.message}`);
+        });
+    };
+    const method = options.method ?? (options.body === undefined ? "GET" : "POST");
+    let response = await send(false);
+    if (response.status === 401 && (options.accountAuth || options.impersonatedProjectAuth || options.preferImpersonatedProjectAuth)) {
+        // The locally cached expiry said the token was still good, but the server
+        // rejected it anyway (early revocation, clock skew, forced logout server-side).
+        // Force one refresh-and-retry before giving up -- this is what actually
+        // prevents a spurious 're-run blocks login' when the refresh token is still valid.
+        response = await send(true);
     }
-    if (options.impersonatedProjectAuth) {
-        const project = await getImpersonatedProjectSession(options.accountName, options.projectTenantId);
-        headers.Authorization = `Bearer ${project.accessToken}`;
-        headers["x-blocks-key"] = project.accountTenant;
+    else if (response.status === 500 && method === "GET") {
+        // Some tenant-scoped read endpoints (mfa config, signup-settings) intermittently
+        // 500 with a JWKS/kid lookup failure right after impersonation, then succeed on
+        // an immediate identical retry once the signing-key cache catches up. Safe to
+        // retry blindly here because GET is idempotent.
+        response = await send(false);
     }
-    const response = await fetch(url, {
-        body: options.body === undefined ? undefined : JSON.stringify(options.body),
-        headers,
-        method: options.method ?? (options.body === undefined ? "GET" : "POST")
-    }).catch((error) => {
-        throw new Error(`Blocks API request failed for ${url.origin}${url.pathname}: ${error.message}`);
-    });
     const text = await response.text();
     const data = parseJson(text);
     if (!response.ok) {

package/dist/lib/args.d.ts

@@ -9,3 +9,6 @@ export declare function stringFlag(flags: Record<string, string | boolean>, name
 }): string;
 export declare function integerFlag(flags: Record<string, string | boolean>, name: string, defaultValue: number): number;
 export declare function booleanFlag(flags: Record<string, string | boolean>, name: string): boolean;
+export declare function optionalIntegerFlag(flags: Record<string, string | boolean>, name: string): number | undefined;
+/** Unlike `booleanFlag`, distinguishes "not passed" (undefined) from an explicit `--flag=false`. */
+export declare function optionalBooleanFlag(flags: Record<string, string | boolean>, name: string): boolean | undefined;

package/dist/lib/args.js

@@ -42,3 +42,18 @@ export function integerFlag(flags, name, defaultValue) {
 export function booleanFlag(flags, name) {
     return flags[name] === true || flags[name] === "true";
 }
+export function optionalIntegerFlag(flags, name) {
+    const value = flags[name];
+    if (value === undefined || value === true)
+        return undefined;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed))
+        throw new Error(`--${name} must be an integer`);
+    return parsed;
+}
+/** Unlike `booleanFlag`, distinguishes "not passed" (undefined) from an explicit `--flag=false`. */
+export function optionalBooleanFlag(flags, name) {
+    if (!(name in flags))
+        return undefined;
+    return booleanFlag(flags, name);
+}

package/dist/lib/auth.d.ts

@@ -12,6 +12,9 @@ export type ProjectSession = {
     accountTenant: string;
     tenantId: string;
 };
+export type SessionOptions = {
+    forceRefresh?: boolean;
+};
 export type DeviceAuthorizationResponse = {
     device_code: string;
     expires_in: number;
@@ -25,7 +28,8 @@ export type DevicePollingOptions = {
 };
 export declare function requestDeviceAuthorization(profile: AccountProfile): Promise<DeviceAuthorizationResponse>;
 export declare function pollDeviceToken(profile: AccountProfile, device: DeviceAuthorizationResponse, options?: DevicePollingOptions): Promise<TokenResponse>;
-export declare function getAccountSession(accountOverride?: string): Promise<AccountSession>;
+export declare function getAccountSession(accountOverride?: string, options?: SessionOptions): Promise<AccountSession>;
 export declare function selectProject(tenantId: string): Promise<void>;
-export declare function getImpersonatedProjectSession(accountOverride?: string, tenantOverride?: string): Promise<ProjectSession>;
+export declare function getImpersonatedProjectSession(accountOverride?: string, tenantOverride?: string, options?: SessionOptions): Promise<ProjectSession>;
+export declare function stopProjectImpersonation(accountOverride?: string, tenantOverride?: string): Promise<void>;
 export declare function revokeCurrentSession(accountOverride?: string): Promise<void>;

package/dist/lib/auth.js

@@ -4,7 +4,6 @@ import { readTokenStore, writeTokenStore } from "./token-store.js";
 import { getClientSecret } from "./secret-store.js";
 import { CliActionableError } from "./errors.js";
 const DEVICE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
-const FALLBACK_IMPERSONATION_CLIENT_ID = "57214b67-aa9c-4307-92ab-a25e35180fac";
 const MAX_CONSECUTIVE_TRANSIENT_ERRORS = 3;
 export async function requestDeviceAuthorization(profile) {
     const rootTenantId = await resolveRootTenantForDevice(profile);
@@ -81,33 +80,33 @@ export async function pollDeviceToken(profile, device, options = {}) {
             continue;
         }
         if (response.error === "access_denied") {
-            throw new CliActionableError("Device authorization was denied.", "device_login_denied", "blocks-os login");
+            throw new CliActionableError("Device authorization was denied.", "device_login_denied", "blocks login");
         }
         if (response.error === "expired_token") {
-            throw new CliActionableError("Device login expired before approval.", "device_login_expired", "blocks-os login");
+            throw new CliActionableError("Device login expired before approval.", "device_login_expired", "blocks login");
         }
         if (response.error) {
-            throw new CliActionableError(response.error_description ?? response.error, "device_login_failed", "blocks-os login");
+            throw new CliActionableError(response.error_description ?? response.error, "device_login_failed", "blocks login");
         }
         return response;
     }
-    throw new CliActionableError("Device login expired before approval.", "device_login_expired", "blocks-os login");
+    throw new CliActionableError("Device login expired before approval.", "device_login_expired", "blocks login");
 }
 function throwIfTooManyTransientErrors(count, cause) {
     if (count <= MAX_CONSECUTIVE_TRANSIENT_ERRORS)
         return;
     const detail = cause instanceof Error ? cause.message : String(cause);
-    throw new CliActionableError(`Could not reach the identity provider while waiting for device approval (${detail}).`, "device_login_network_error", "Check your network connection and run 'blocks-os login' again.");
+    throw new CliActionableError(`Could not reach the identity provider while waiting for device approval (${detail}).`, "device_login_network_error", "Check your network connection and run 'blocks login' again.");
 }
-export async function getAccountSession(accountOverride) {
+export async function getAccountSession(accountOverride, options = {}) {
     let config = await readConfig();
     let store = await readTokenStore();
     const { name, profile } = getAccountProfile(config, accountOverride);
     const token = store.accounts[name]?.account;
     if (!token?.accessToken || !token.accountTenant) {
-        throw new Error(`Account '${name}' is not logged in. Run 'blocks-os login' first.`);
+        throw new Error(`Account '${name}' is not logged in. Run 'blocks login' first.`);
     }
-    if (!isExpiring(token.expiresAt)) {
+    if (!options.forceRefresh && !isExpiring(token.expiresAt)) {
         return {
             accessToken: token.accessToken,
             account: name,
@@ -116,7 +115,7 @@ export async function getAccountSession(accountOverride) {
         };
     }
     if (!token.refreshToken) {
-        throw new Error(`Account '${name}' token expired and no refresh token is available. Run 'blocks-os login' again.`);
+        throw new Error(`Account '${name}' token expired and no refresh token is available. Run 'blocks login' again.`);
     }
     const refreshed = await refreshToken(profile.oidcUrl, profile.clientId, token.refreshToken, await getClientSecret(name), profile.rootTenantId ?? token.accountTenant);
     const next = applyAccountToken(config, store, name, profile.clientId, refreshed);
@@ -142,16 +141,16 @@ export async function selectProject(tenantId) {
         }
     });
 }
-export async function getImpersonatedProjectSession(accountOverride, tenantOverride) {
+export async function getImpersonatedProjectSession(accountOverride, tenantOverride, options = {}) {
     let config = await readConfig();
     let store = await readTokenStore();
     const { name, profile } = getAccountProfile(config, accountOverride);
     const tenantId = tenantOverride ?? config.selectedProject?.tenantId;
     if (!tenantId) {
-        throw new Error("No project selected. Run 'blocks-os use <tenantId>' first.");
+        throw new Error("No project selected. Run 'blocks use <tenantId>' first.");
     }
     const projectToken = store.accounts[name]?.projects?.[tenantId];
-    if (projectToken?.accessToken && !isExpiring(projectToken.expiresAt)) {
+    if (!options.forceRefresh && projectToken?.accessToken && !isExpiring(projectToken.expiresAt)) {
         return {
             accessToken: projectToken.accessToken,
             account: name,
@@ -168,12 +167,12 @@ export async function getImpersonatedProjectSession(accountOverride, tenantOverr
         await writeTokenStore(store);
         return projectSessionFromToken(name, tenantId, store.accounts[name].projects[tenantId], store.accounts[name]?.account?.accountTenant ?? profile.rootTenantId);
     }
-    const account = await getAccountSession(name);
+    const account = await getAccountSession(name, options);
     config = await readConfig();
     store = await readTokenStore();
     const rootRefresh = store.accounts[name]?.account?.refreshToken;
     if (!rootRefresh) {
-        throw new Error(`Project impersonation needs a fresh account refresh token. Run 'blocks-os login' again.`);
+        throw new Error(`Project impersonation needs a fresh account refresh token. Run 'blocks login' again.`);
     }
     const data = await impersonateProject({
         accessToken: account.accessToken,
@@ -195,6 +194,57 @@ export async function getImpersonatedProjectSession(accountOverride, tenantOverr
     await writeTokenStore(next.store);
     return projectSessionFromToken(name, tenantId, next.store.accounts[name].projects[tenantId], account.accountTenant);
 }
+// Ends the active project impersonation and restores a fresh, refreshable
+// account-level session. The IAM server revokes the account refresh token the
+// moment it's used to start an impersonation (see impersonateProject) and
+// only ever hands back a project-scoped one in exchange -- calling
+// '/impersonation/stop' is the only way to get a new account-level refresh
+// token back. No-ops if no project is selected or nothing was ever
+// impersonated for it.
+export async function stopProjectImpersonation(accountOverride, tenantOverride) {
+    const config = await readConfig();
+    const { name, profile } = getAccountProfile(config, accountOverride);
+    const tenantId = tenantOverride ?? config.selectedProject?.tenantId;
+    if (!tenantId)
+        return;
+    const store = await readTokenStore();
+    if (!store.accounts[name]?.projects?.[tenantId]?.refreshToken)
+        return;
+    // The stop endpoint requires a currently-valid bearer token to authenticate
+    // the call, so refresh the project session first if it's expiring.
+    const project = await getImpersonatedProjectSession(name, tenantId);
+    const beforeStop = await readTokenStore();
+    const projectToken = beforeStop.accounts[name]?.projects?.[tenantId];
+    if (!projectToken?.refreshToken)
+        return;
+    const refreshed = await postStopImpersonation(profile.apiUrl, project.accessToken, project.accountTenant, projectToken.refreshToken);
+    const latestConfig = await readConfig();
+    const latestStore = await readTokenStore();
+    const next = applyAccountToken(latestConfig, latestStore, name, profile.clientId, refreshed);
+    const { [tenantId]: _removed, ...remainingProjects } = next.store.accounts[name]?.projects ?? {};
+    next.store.accounts[name] = {
+        ...next.store.accounts[name],
+        projects: remainingProjects
+    };
+    await writeConfig(next.config);
+    await writeTokenStore(next.store);
+}
+async function postStopImpersonation(apiUrl, accessToken, accountTenant, refreshToken) {
+    const response = await fetch(new URL("/iam/v4/auth/impersonation/stop", apiUrl), {
+        body: JSON.stringify({ refresh_token: refreshToken }),
+        headers: {
+            Accept: "application/json",
+            Authorization: `Bearer ${accessToken}`,
+            "Content-Type": "application/json",
+            "x-blocks-key": accountTenant
+        },
+        method: "POST"
+    });
+    const data = parseJson(await response.text());
+    if (response.ok && !data.error)
+        return data;
+    throw new Error(data.error_description ?? data.error ?? `Stop impersonation failed with HTTP ${response.status}`);
+}
 export async function revokeCurrentSession(accountOverride) {
     const config = await readConfig();
     const store = await readTokenStore();
@@ -236,7 +286,7 @@ async function refreshToken(oidcUrl, clientId, refreshToken, clientSecret, rootT
             // The OIDC server's exact wording for an expired/revoked refresh token
             // varies (invalid_grant, blank description, etc.) -- don't depend on it.
             // Always surface a clear, consistent next step instead.
-            throw new CliActionableError(`Refresh token was rejected by the identity provider (${error.message}).`, "refresh_token_rejected", "blocks-os login");
+            throw new CliActionableError(`Refresh token was rejected by the identity provider (${error.message}).`, "refresh_token_rejected", "blocks login");
         }
         // fetch() itself failed (DNS, connection refused, TLS, etc.) -- the
         // refresh token may still be valid, so don't tell the user to log in.
@@ -245,22 +295,9 @@ async function refreshToken(oidcUrl, clientId, refreshToken, clientSecret, rootT
     }
 }
 async function impersonateProject(args) {
-    const first = await postImpersonate(args, args.clientId);
-    if (first.ok)
-        return first.data;
-    const message = first.data.error_description ?? first.data.error ?? "";
-    if (args.clientId !== FALLBACK_IMPERSONATION_CLIENT_ID && /invalid_client|client configuration/i.test(message)) {
-        const fallback = await postImpersonate(args, FALLBACK_IMPERSONATION_CLIENT_ID);
-        if (fallback.ok)
-            return fallback.data;
-        throw new Error(fallback.data.error_description ?? fallback.data.error ?? `Impersonation failed with HTTP ${fallback.status}`);
-    }
-    throw new Error(first.data.error_description ?? first.data.error ?? `Impersonation failed with HTTP ${first.status}`);
-}
-async function postImpersonate(args, clientId) {
     const response = await fetch(new URL("/iam/v4/auth/impersonate", args.apiUrl), {
         body: JSON.stringify({
-            client_id: clientId,
+            client_id: args.clientId,
             refresh_token: args.refreshToken,
             targeted_tenant_id: args.tenantId
         }),
@@ -273,11 +310,13 @@ async function postImpersonate(args, clientId) {
         method: "POST"
     });
     const data = parseJson(await response.text());
-    return {
-        data,
-        ok: response.ok && !data.error,
-        status: response.status
-    };
+    if (response.ok && !data.error)
+        return data;
+    const message = data.error_description ?? data.error ?? "";
+    if (/invalid_client|client configuration/i.test(message)) {
+        throw new CliActionableError(`Impersonation failed: the account's OIDC client ('${args.clientId}') is not registered for impersonation (${message}).`, "impersonation_invalid_client", "Check the client_id in 'blocks auth config get', then contact an admin to register it for impersonation.");
+    }
+    throw new Error(message || `Impersonation failed with HTTP ${response.status}`);
 }
 // Thrown only once we have an actual response from the identity provider
 // that rejects the request (bad grant, bad client, etc.) -- as opposed to

package/dist/lib/config.js

@@ -1,11 +1,11 @@
 import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { homedir, platform } from "node:os";
 import { dirname, join } from "node:path";
-const BAD_GATEWAY_OS_URL = "https://api.seliseblocks.com/os/v4";
-const DEFAULT_API_URL = "https://os.seliseblocks.com";
+const BAD_GATEWAY_OS_URL = "https://os.seliseblocks.com";
+const DEFAULT_API_URL = "https://api.seliseblocks.com";
 const DEFAULT_OS_CLIENT_ID = "4a633b13-1108-4fbf-84fd-b196c9dcdee2";
 const DEFAULT_OIDC_URL = "https://iam.seliseblocks.com";
-const DEFAULT_OS_URL = "https://os.seliseblocks.com";
+const DEFAULT_OS_URL = "https://api.seliseblocks.com";
 const DEFAULT_PROFILE_TIMESTAMP = "2026-01-01T00:00:00.000Z";
 const DEFAULT_ROOT_TENANT_ID = "d7e5554c758541db8a18694b64ef423d";
 const DEFAULT_SCOPE = "openid profile offline_access";
@@ -20,16 +20,16 @@ export function defaults() {
     };
 }
 export function configDir() {
-    const override = nonEmptyEnv("BLOCKS_OS_CONFIG_DIR");
+    const override = nonEmptyEnv("BLOCKS_CONFIG_DIR");
     if (override)
         return override;
     if (platform() === "win32") {
-        return join(nonEmptyEnv("APPDATA") ?? join(homedir(), "AppData", "Roaming"), "seliseblocks", "cli-os");
+        return join(nonEmptyEnv("APPDATA") ?? join(homedir(), "AppData", "Roaming"), "seliseblocks", "cli");
     }
     if (platform() === "darwin") {
-        return join(homedir(), "Library", "Application Support", "seliseblocks", "cli-os");
+        return join(homedir(), "Library", "Application Support", "seliseblocks", "cli");
     }
-    return join(nonEmptyEnv("XDG_CONFIG_HOME") ?? join(homedir(), ".config"), "seliseblocks", "cli-os");
+    return join(nonEmptyEnv("XDG_CONFIG_HOME") ?? join(homedir(), ".config"), "seliseblocks", "cli");
 }
 export function configPath() {
     return join(configDir(), "config.json");

package/dist/lib/json-flag.d.ts

@@ -0,0 +1,17 @@
+type Flags = Record<string, string | boolean>;
+/**
+ * Reads a JSON object payload from `--body '<json>'` or `--file <path.json>`.
+ * Rich IAM/MFA/Auth-admin payloads have far more optional fields than are
+ * worth turning into individual flags; this is the escape hatch every
+ * create/update command layers convenience flags on top of.
+ */
+export declare function jsonBodyFlag(flags: Flags, options?: {
+    required?: boolean;
+}): Promise<Record<string, unknown>>;
+/** Splits a comma-separated flag value (e.g. `--roles admin,editor`) into a trimmed string array. */
+export declare function listFlag(flags: Flags, name: string): string[] | undefined;
+/** Parses a single named flag as an arbitrary JSON value (object or array), e.g. `--attachments '["a.pdf"]'`. */
+export declare function jsonFlag(flags: Flags, name: string): unknown;
+/** Drops `undefined` values so unset convenience flags never overwrite a `--body`/`--file` payload's fields. */
+export declare function compact<T extends object>(obj: T): Partial<T>;
+export {};

package/dist/lib/json-flag.js

@@ -0,0 +1,55 @@
+import { readFile } from "node:fs/promises";
+import { stringFlag } from "./args.js";
+/**
+ * Reads a JSON object payload from `--body '<json>'` or `--file <path.json>`.
+ * Rich IAM/MFA/Auth-admin payloads have far more optional fields than are
+ * worth turning into individual flags; this is the escape hatch every
+ * create/update command layers convenience flags on top of.
+ */
+export async function jsonBodyFlag(flags, options = {}) {
+    const inline = stringFlag(flags, "body");
+    if (inline)
+        return parseJsonObject(inline, "--body");
+    const file = stringFlag(flags, "file");
+    if (file)
+        return parseJsonObject(await readFile(file, "utf8"), `--file ${file}`);
+    if (options.required)
+        throw new Error("Provide --body '<json>' or --file <path.json> with the request payload.");
+    return {};
+}
+/** Splits a comma-separated flag value (e.g. `--roles admin,editor`) into a trimmed string array. */
+export function listFlag(flags, name) {
+    const value = flags[name];
+    if (typeof value !== "string" || !value)
+        return undefined;
+    return value.split(",").map((item) => item.trim()).filter(Boolean);
+}
+/** Parses a single named flag as an arbitrary JSON value (object or array), e.g. `--attachments '["a.pdf"]'`. */
+export function jsonFlag(flags, name) {
+    const raw = stringFlag(flags, name);
+    if (!raw)
+        return undefined;
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`Could not parse JSON from --${name}: ${error.message}`);
+    }
+}
+/** Drops `undefined` values so unset convenience flags never overwrite a `--body`/`--file` payload's fields. */
+export function compact(obj) {
+    return Object.fromEntries(Object.entries(obj).filter(([, value]) => value !== undefined));
+}
+function parseJsonObject(text, source) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch (error) {
+        throw new Error(`Could not parse JSON from ${source}: ${error.message}`);
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${source} must be a JSON object.`);
+    }
+    return value;
+}

package/dist/lib/project-info.d.ts

@@ -0,0 +1,33 @@
+export type ProjectRecord = {
+    applications?: Array<{
+        domain?: string;
+    }>;
+    environment?: string;
+    name?: string;
+    tenantId?: string;
+} & Record<string, unknown>;
+export type ProjectGroupRecord = {
+    name?: string;
+    projects?: ProjectRecord[];
+    tenantGroupId?: string;
+} & Record<string, unknown>;
+export type TenantAssetResponse = {
+    assets?: {
+        resources?: Array<{
+            link?: string;
+            name?: string;
+            resourceId?: string;
+        }>;
+    };
+};
+export declare function listProjectGroups(flags: Record<string, string | boolean>): Promise<ProjectGroupRecord[]>;
+export declare function findProjectByTenantId(tenantId: string, flags: Record<string, string | boolean>): Promise<{
+    group: ProjectGroupRecord;
+    project: ProjectRecord;
+}>;
+export declare function resolveSelectedProject(flags: Record<string, string | boolean>): Promise<{
+    group: ProjectGroupRecord;
+    project: ProjectRecord;
+    tenantId: string;
+}>;
+export declare function getProjectAssets(tenantGroupId: string, flags: Record<string, string | boolean>): Promise<TenantAssetResponse>;

package/dist/lib/project-info.js

@@ -0,0 +1,43 @@
+import { blocksRequest } from "./api.js";
+import { requestContext } from "./request-context.js";
+import { selectedProject } from "./workspace.js";
+// Project metadata (Project/Gets, Project/GetAsset) is authorized at the
+// account/tenant-group level, above any single project's own API surface --
+// but the platform's permission check rebuilds to the root tenant while
+// impersonating, and the underlying query filters by user id rather than
+// tenant, so the impersonated project session works here too. Prefer it when
+// a project is selected (avoids an extra account-session refresh mid-project
+// work); fall back to the account token when nothing is selected yet.
+export async function listProjectGroups(flags) {
+    return blocksRequest("/os/v4/Project/Gets", {
+        preferImpersonatedProjectAuth: true,
+        query: { page: 0, pageSize: 100, tenantGroupId: "" },
+        ...requestContext(flags)
+    });
+}
+export async function findProjectByTenantId(tenantId, flags) {
+    const groups = await listProjectGroups(flags);
+    for (const group of groups) {
+        const project = (group.projects ?? []).find((item) => item.tenantId === tenantId);
+        if (project)
+            return { group, project };
+    }
+    throw new Error(`Project '${tenantId}' was not found in Project/Gets.`);
+}
+// Resolves the CLI's currently selected project (blocks.json, --project flag,
+// or 'blocks use') and looks it up via Project/Gets. Throws the same
+// actionable "No project selected" error as selectedProject() when nothing
+// is selected -- callers should not catch that error, letting it surface to
+// the user with the "run blocks use <tenantId>" next step intact.
+export async function resolveSelectedProject(flags) {
+    const tenantId = await selectedProject(flags);
+    const { group, project } = await findProjectByTenantId(tenantId, flags);
+    return { group, project, tenantId };
+}
+export async function getProjectAssets(tenantGroupId, flags) {
+    return blocksRequest("/os/v4/Project/GetAsset", {
+        preferImpersonatedProjectAuth: true,
+        query: { page: 0, pageSize: 100, tenantGroupId },
+        ...requestContext(flags)
+    });
+}

package/dist/lib/prompt.d.ts

@@ -0,0 +1,2 @@
+export declare function promptText(message: string): Promise<string>;
+export declare function selectFromList(message: string, options: string[]): Promise<number>;

package/dist/lib/prompt.js

@@ -0,0 +1,28 @@
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+export async function promptText(message) {
+    const rl = createInterface({ input, output });
+    try {
+        return (await rl.question(message)).trim();
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function selectFromList(message, options) {
+    const rl = createInterface({ input, output });
+    try {
+        console.log(message);
+        options.forEach((option, index) => console.log(`  ${index + 1}) ${option}`));
+        while (true) {
+            const answer = (await rl.question(`Choose 1-${options.length}: `)).trim();
+            const choice = Number(answer);
+            if (Number.isInteger(choice) && choice >= 1 && choice <= options.length)
+                return choice - 1;
+            console.log(`Enter a number between 1 and ${options.length}.`);
+        }
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/lib/scaffold-web/dashboard.js

@@ -55,7 +55,7 @@ export async function writeDashboard(root) {
         "          </li>",
         "          <li>",
         "            <Languages size={18} />",
-        "            <span>Edit <code>blocks/localization/*.en.json</code>, then run <code>blocks-os localization:push</code> to sync copy to Blocks.</span>",
+        "            <span>Edit <code>blocks/localization/*.en.json</code>, then run <code>blocks localization push</code> to sync copy to Blocks.</span>",
         "          </li>",
         "        </ul>",
         "      </div>",

package/dist/lib/scaffold-web/root-files.js

@@ -18,7 +18,7 @@ export async function writeRootFiles(root, options) {
         },
         dependencies: {
             "@radix-ui/react-dropdown-menu": "^2.1.24",
-            "@seliseblocks/client": "^0.1.1",
+            "@seliseblocks/client": "^0.1.3",
             "@tanstack/react-query": "^5.101.4",
             clsx: "^2.1.1",
             "lucide-react": "^1.28.0",
@@ -122,7 +122,7 @@ export async function writeRootFiles(root, options) {
         "- `/login/callback` — completes the hosted IAM callback via `blocksClient.auth.idp.callback()`, then returns to the page you started from.",
         "- `/` and `/profile` — protected; redirect to `/login` when signed out.",
         "- Sidebar + topbar shell matching the `@seliseblocks/blocks-kit` look (icon-only rail on narrow screens, avatar dropdown, notifications menu, active-item accent bar).",
-        "- `blocks/localization/*.en.json` local i18n seed files for AI or human edits. Sync them through `blocks-os localization:validate` and `blocks-os localization:push`; the runtime app reads Localization service data through `blocksClient.localization`.",
+        "- `blocks/localization/*.en.json` local i18n seed files for AI or human edits. Sync them through `blocks localization validate` and `blocks localization push`; the runtime app reads Localization service data through `blocksClient.localization`.",
         "",
         "IAM's hosted login sets the session as a **Secure, httpOnly** cookie by default -- this app never reads, stores, or refreshes a token itself. \"Signed in\" is determined by calling `blocksClient.auth.userInfo()` (`GET /iam/v4/auth/me`), which the browser's cookie authenticates automatically; this is different from `blocksClient.iam.me()`, the full IAM profile call used on the Profile page. Logging out calls `blocksClient.auth.logout()` so IAM ends the session server-side. A cached bearer token (and `blocksClient.auth.oidc.refreshToken()` to refresh it) is only used if a tenant's OIDC config explicitly returns tokens in the response body instead of a cookie.",
         ""