@cubis/foundry 0.3.23 → 0.3.25

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to this project are documented in this file.
 
+## [0.3.25] - 2026-02-26
+
+### Added
+
+- Added `cbx workflows config` command to view and edit `cbx_config.json` from terminal.
+- Added `cbx skills config` alias for compatibility with deprecated `skills` command group.
+- Added docs for showing/updating/clearing Postman `defaultWorkspaceId` after install.
+
+### Changed
+
+- Improved Postman install warnings when workspace selection is not persisted because existing `cbx_config.json` was skipped.
+- Included actionable follow-up command in warnings (`cbx workflows config ...`).
+
 ## [0.3.23] - 2026-02-26
 
 ### Added

package/README.md

@@ -59,6 +59,7 @@ cbx workflows install --platform antigravity --dry-run
 cbx workflows install --platform antigravity --terminal-integration --terminal-verifier codex
 cbx workflows install --platform codex --postman
 cbx workflows install --platform codex --postman --postman-workspace-id null
+cbx workflows install --platform codex --postman --postman-workspace-id "<workspace-id>"
 cbx workflows install --platform codex --postman --postman-api-key "<key>"
 cbx workflows install --platform codex --postman --mcp-scope global
 cbx workflows install --platform copilot --postman --mcp-scope project
@@ -83,10 +84,56 @@ Postman + Antigravity Stitch setup behavior:
 - Env-first auth is supported: when `POSTMAN_API_KEY` is set, generated settings keep `apiKey: null` and MCP config uses `Bearer ${POSTMAN_API_KEY}`.
 - Inline auth is supported with `--postman-api-key <key>`.
 - `--postman-workspace-id null` writes JSON `null` for `defaultWorkspaceId`.
+- If `POSTMAN_API_KEY` is available and install is interactive (no `--yes`) without `--postman-workspace-id`, `cbx` fetches your Postman workspaces and prompts you to pick one as default.
 - Antigravity gets an additional managed file at `.cbx/mcp/antigravity/stitch.json` (or `~/.cbx/mcp/antigravity/stitch.json` in global MCP scope).
 - Stitch key source priority for Antigravity: `--stitch-api-key` then `STITCH_API_KEY`; when unset, generated config keeps placeholder `X-Goog-Api-Key: ur stitch key`.
 - In project MCP scope, `cbx_config.json` and `.cbx/mcp/` are auto-added to `.gitignore` (no duplicate entries).
 
+Codex Postman workspace selection:
+
+```bash
+# Set Postman API key first
+export POSTMAN_API_KEY="<your-postman-api-key>"
+
+# Interactive workspace selector (recommended)
+cbx workflows install --platform codex --bundle agent-environment-setup --postman
+```
+
+- Do not use `--yes` here (it skips prompts).
+- You will get a workspace selector and the selected value is saved as `defaultWorkspaceId`.
+
+Direct/manual workspace ID:
+
+```bash
+cbx workflows install --platform codex --bundle agent-environment-setup --postman --postman-workspace-id "<workspace-id>" --yes
+```
+
+Clear default workspace:
+
+```bash
+cbx workflows install --platform codex --bundle agent-environment-setup --postman --postman-workspace-id null --yes
+```
+
+Important:
+- If `cbx_config.json` already exists and you want to change the saved workspace, use `--overwrite` (or edit config manually), because existing config is preserved by default.
+- If install output shows `Config file: skipped (...)`, your newly selected workspace is not persisted. Use `--overwrite` or edit with the config command below.
+
+View/edit config in terminal:
+
+```bash
+# View config
+cbx workflows config --scope global --show
+
+# Interactive edit (workspace ID)
+cbx workflows config --scope global --edit
+
+# Direct set workspace ID
+cbx workflows config --scope global --workspace-id "<workspace-id>"
+
+# Clear workspace ID
+cbx workflows config --scope global --clear-workspace-id
+```
+
 Platform runtime MCP placement:
 - Codex:
   - Global MCP scope: `~/.codex/config.toml` via `codex mcp add`.

package/bin/cubis.js

@@ -127,11 +127,13 @@ const TERMINAL_VERIFIER_PROVIDERS = ["codex", "gemini"];
 const DEFAULT_TERMINAL_VERIFIER = "codex";
 const POSTMAN_API_KEY_ENV_VAR = "POSTMAN_API_KEY";
 const POSTMAN_MCP_URL = "https://mcp.postman.com/minimal";
+const POSTMAN_API_BASE_URL = "https://api.getpostman.com";
 const POSTMAN_SKILL_ID = "postman";
 const STITCH_MCP_SERVER_ID = "StitchMCP";
 const STITCH_API_KEY_ENV_VAR = "STITCH_API_KEY";
 const STITCH_MCP_URL = "https://stitch.googleapis.com/mcp";
 const STITCH_API_KEY_PLACEHOLDER = "ur stitch key";
+const POSTMAN_WORKSPACE_MANUAL_CHOICE = "__postman_workspace_manual__";
 const CBX_CONFIG_FILENAME = "cbx_config.json";
 const POSTMAN_SETTINGS_FILENAME = "postman_setting.json";
 const POSTMAN_API_KEY_MISSING_WARNING =
@@ -2428,6 +2430,57 @@ function parseStoredPostmanConfig(raw) {
   };
 }
 
+async function fetchPostmanWorkspaces({
+  apiKey,
+  apiBaseUrl = POSTMAN_API_BASE_URL,
+  timeoutMs = 12000
+}) {
+  if (!apiKey) return [];
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  const endpoint = `${apiBaseUrl.replace(/\/$/, "")}/workspaces`;
+
+  try {
+    const response = await fetch(endpoint, {
+      method: "GET",
+      headers: {
+        "X-Api-Key": apiKey,
+        Accept: "application/json"
+      },
+      signal: controller.signal
+    });
+
+    const payload = await response.json().catch(() => null);
+    if (!response.ok) {
+      const message =
+        payload?.error?.message ||
+        payload?.error?.name ||
+        `Postman API request failed (${response.status} ${response.statusText}).`;
+      throw new Error(message);
+    }
+
+    const workspaces = Array.isArray(payload?.workspaces) ? payload.workspaces : [];
+    return workspaces
+      .map((workspace) => {
+        const id = normalizePostmanWorkspaceId(workspace?.id);
+        if (!id) return null;
+        const name = String(workspace?.name || "").trim() || id;
+        const type = String(workspace?.type || "").trim() || null;
+        const visibility = String(workspace?.visibility || "").trim() || null;
+        return { id, name, type, visibility };
+      })
+      .filter(Boolean);
+  } catch (error) {
+    if (error?.name === "AbortError") {
+      throw new Error("Postman workspace lookup timed out.");
+    }
+    throw error;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
 function parseStoredStitchConfig(raw) {
   if (!raw || typeof raw !== "object") return null;
   const source = raw.stitch && typeof raw.stitch === "object" ? raw.stitch : null;
@@ -2739,6 +2792,7 @@ async function resolvePostmanInstallSelection({
   let defaultWorkspaceId = hasWorkspaceOption
     ? normalizePostmanWorkspaceId(options.postmanWorkspaceId)
     : null;
+  let workspaceSelectionSource = hasWorkspaceOption ? "option" : "none";
   const requestedMcpScope = options.mcpScope
     ? normalizeMcpScope(options.mcpScope, normalizeMcpScope(scope, "project"))
     : null;
@@ -2762,11 +2816,60 @@ async function resolvePostmanInstallSelection({
   }
 
   if (canPrompt && !hasWorkspaceOption) {
-    const promptedWorkspaceId = await input({
-      message: "Default Postman workspace ID (optional, leave blank for null):",
-      default: ""
-    });
-    defaultWorkspaceId = normalizePostmanWorkspaceId(promptedWorkspaceId);
+    const selectableApiKey = normalizePostmanApiKey(apiKey || envApiKey);
+    let usedWorkspaceSelector = false;
+    let selectedWorkspaceId = defaultWorkspaceId;
+
+    if (selectableApiKey) {
+      try {
+        const fetchedWorkspaces = await fetchPostmanWorkspaces({
+          apiKey: selectableApiKey
+        });
+        if (fetchedWorkspaces.length > 0) {
+          usedWorkspaceSelector = true;
+          const sortedWorkspaces = [...fetchedWorkspaces].sort((a, b) => a.name.localeCompare(b.name));
+          const workspaceChoice = await select({
+            message: "Choose default Postman workspace for this install:",
+            choices: [
+              { name: "No default workspace (null)", value: null },
+              ...sortedWorkspaces.map((workspace) => {
+                const details = [workspace.type, workspace.visibility].filter(Boolean).join(", ");
+                const suffix = details ? ` - ${details}` : "";
+                return {
+                  name: `${workspace.name} (${workspace.id})${suffix}`,
+                  value: workspace.id
+                };
+              }),
+              { name: "Enter workspace ID manually", value: POSTMAN_WORKSPACE_MANUAL_CHOICE }
+            ],
+            default: null
+          });
+
+          if (workspaceChoice === POSTMAN_WORKSPACE_MANUAL_CHOICE) {
+            const promptedWorkspaceId = await input({
+              message: "Default Postman workspace ID (optional, leave blank for null):",
+              default: ""
+            });
+            selectedWorkspaceId = normalizePostmanWorkspaceId(promptedWorkspaceId);
+          } else {
+            selectedWorkspaceId = normalizePostmanWorkspaceId(workspaceChoice);
+          }
+        }
+      } catch (error) {
+        warnings.push(`Could not load Postman workspaces for selection: ${error.message}`);
+      }
+    }
+
+    if (!usedWorkspaceSelector) {
+      const promptedWorkspaceId = await input({
+        message: "Default Postman workspace ID (optional, leave blank for null):",
+        default: ""
+      });
+      selectedWorkspaceId = normalizePostmanWorkspaceId(promptedWorkspaceId);
+    }
+
+    defaultWorkspaceId = selectedWorkspaceId;
+    workspaceSelectionSource = "interactive";
   }
 
   if (canPrompt && stitchEnabled && !hasStitchApiKeyOption && !stitchApiKey && !envStitchApiKey) {
@@ -2844,6 +2947,7 @@ async function resolvePostmanInstallSelection({
     stitchApiKey,
     stitchApiKeySource,
     defaultWorkspaceId: defaultWorkspaceId ?? null,
+    workspaceSelectionSource,
     mcpScope,
     warnings,
     cbxConfig,
@@ -2912,6 +3016,21 @@ async function configurePostmanInstallArtifacts({
       effectiveStitchApiKey = storedStitchConfig.apiKey;
       effectiveStitchMcpUrl = storedStitchConfig.mcpUrl || STITCH_MCP_URL;
     }
+
+    if (postmanSelection.workspaceSelectionSource && postmanSelection.workspaceSelectionSource !== "none") {
+      const requestedWorkspaceId = postmanSelection.defaultWorkspaceId ?? null;
+      const persistedWorkspaceId = effectiveDefaultWorkspaceId ?? null;
+      if (requestedWorkspaceId !== persistedWorkspaceId) {
+        const configScope = postmanSelection.mcpScope === "global" ? "global" : "project";
+        const configHint =
+          requestedWorkspaceId === null
+            ? `cbx workflows config --scope ${configScope} --clear-workspace-id`
+            : `cbx workflows config --scope ${configScope} --workspace-id \"${requestedWorkspaceId}\"`;
+        warnings.push(
+          `Selected Postman workspace (${requestedWorkspaceId === null ? "null" : requestedWorkspaceId}) was not saved because ${CBX_CONFIG_FILENAME} already exists. Re-run with --overwrite or run '${configHint}'.`
+        );
+      }
+    }
   }
 
   const envApiKey = normalizePostmanApiKey(process.env[POSTMAN_API_KEY_ENV_VAR]);
@@ -4418,6 +4537,105 @@ async function runWorkflowDoctor(platformArg, options) {
   }
 }
 
+async function runWorkflowConfig(options) {
+  try {
+    const cwd = process.cwd();
+    const scope = normalizeMcpScope(options.scope, "global");
+    const dryRun = Boolean(options.dryRun);
+    const hasWorkspaceIdOption = options.workspaceId !== undefined;
+    const wantsClearWorkspaceId = Boolean(options.clearWorkspaceId);
+    const wantsInteractiveEdit = Boolean(options.edit);
+
+    if (hasWorkspaceIdOption && wantsClearWorkspaceId) {
+      throw new Error("Use either --workspace-id or --clear-workspace-id, not both.");
+    }
+
+    const wantsMutation = hasWorkspaceIdOption || wantsClearWorkspaceId || wantsInteractiveEdit;
+    const showOnly = Boolean(options.show) || !wantsMutation;
+    const configPath = resolveCbxConfigPath({ scope, cwd });
+    const existing = await readJsonFileIfExists(configPath);
+    const existingValue =
+      existing.value && typeof existing.value === "object" && !Array.isArray(existing.value) ? existing.value : null;
+
+    if (showOnly) {
+      console.log(`Config file: ${configPath}`);
+      if (!existing.exists) {
+        console.log("Status: missing");
+        return;
+      }
+      if (!existingValue) {
+        throw new Error(`Existing config at ${configPath} is not valid JSON object.`);
+      }
+      console.log(`Status: ${existing.exists ? "exists" : "missing"}`);
+      console.log(JSON.stringify(existingValue, null, 2));
+      return;
+    }
+
+    if (existing.exists && !existingValue) {
+      throw new Error(`Existing config at ${configPath} is not valid JSON object.`);
+    }
+
+    const next = existingValue ? JSON.parse(JSON.stringify(existingValue)) : {};
+    if (!next.schemaVersion || typeof next.schemaVersion !== "number") next.schemaVersion = 1;
+    next.generatedBy = "cbx workflows config";
+    next.generatedAt = new Date().toISOString();
+
+    if (!next.mcp || typeof next.mcp !== "object" || Array.isArray(next.mcp)) next.mcp = {};
+    next.mcp.scope = scope;
+    if (!next.mcp.server) next.mcp.server = POSTMAN_SKILL_ID;
+
+    if (!next.postman || typeof next.postman !== "object" || Array.isArray(next.postman)) next.postman = {};
+    next.postman.apiKey = normalizePostmanApiKey(next.postman.apiKey);
+    next.postman.apiKeyEnvVar = String(next.postman.apiKeyEnvVar || POSTMAN_API_KEY_ENV_VAR).trim() || POSTMAN_API_KEY_ENV_VAR;
+    next.postman.mcpUrl = String(next.postman.mcpUrl || POSTMAN_MCP_URL).trim() || POSTMAN_MCP_URL;
+
+    let workspaceId = normalizePostmanWorkspaceId(next.postman.defaultWorkspaceId);
+
+    if (wantsInteractiveEdit) {
+      const promptedWorkspaceId = await input({
+        message: "Postman default workspace ID (optional, leave blank or 'null' to clear):",
+        default: workspaceId || ""
+      });
+      workspaceId = normalizePostmanWorkspaceId(promptedWorkspaceId);
+    }
+
+    if (hasWorkspaceIdOption) {
+      workspaceId = normalizePostmanWorkspaceId(options.workspaceId);
+    }
+
+    if (wantsClearWorkspaceId) {
+      workspaceId = null;
+    }
+
+    next.postman.defaultWorkspaceId = workspaceId;
+    const envApiKey = normalizePostmanApiKey(process.env[POSTMAN_API_KEY_ENV_VAR]);
+    next.postman.apiKeySource = getPostmanApiKeySource({
+      apiKey: next.postman.apiKey,
+      envApiKey
+    });
+
+    const content = `${JSON.stringify(next, null, 2)}\n`;
+    if (!dryRun) {
+      await mkdir(path.dirname(configPath), { recursive: true });
+      await writeFile(configPath, content, "utf8");
+    }
+
+    console.log(`Config file: ${configPath}`);
+    console.log(`Action: ${dryRun ? (existing.exists ? "would-update" : "would-create") : existing.exists ? "updated" : "created"}`);
+    console.log(`postman.defaultWorkspaceId: ${workspaceId === null ? "null" : workspaceId}`);
+    if (Boolean(options.showAfter)) {
+      console.log(JSON.stringify(next, null, 2));
+    }
+  } catch (error) {
+    if (error?.name === "ExitPromptError") {
+      console.error("\nCancelled.");
+      process.exit(130);
+    }
+    console.error(`\nError: ${error.message}`);
+    process.exit(1);
+  }
+}
+
 function printRulesInitSummary({
   platform,
   scope,
@@ -4649,6 +4867,18 @@ withWorkflowBaseOptions(
     .option("--json", "output JSON")
 ).action(runWorkflowDoctor);
 
+workflowsCommand
+  .command("config")
+  .description("View or edit cbx_config.json from terminal")
+  .option("--scope <scope>", "config scope: project|workspace|global|user", "global")
+  .option("--show", "show current config (default when no edit flags)")
+  .option("--edit", "edit Postman default workspace ID interactively")
+  .option("--workspace-id <id|null>", "set postman.defaultWorkspaceId")
+  .option("--clear-workspace-id", "set postman.defaultWorkspaceId to null")
+  .option("--show-after", "print JSON after update")
+  .option("--dry-run", "preview changes without writing files")
+  .action(runWorkflowConfig);
+
 workflowsCommand.action(() => {
   workflowsCommand.help();
 });
@@ -4708,6 +4938,21 @@ withWorkflowBaseOptions(
   await runWorkflowDoctor(platform, options);
 });
 
+skillsCommand
+  .command("config")
+  .description("Alias for workflows config")
+  .option("--scope <scope>", "config scope: project|workspace|global|user", "global")
+  .option("--show", "show current config (default when no edit flags)")
+  .option("--edit", "edit Postman default workspace ID interactively")
+  .option("--workspace-id <id|null>", "set postman.defaultWorkspaceId")
+  .option("--clear-workspace-id", "set postman.defaultWorkspaceId to null")
+  .option("--show-after", "print JSON after update")
+  .option("--dry-run", "preview changes without writing files")
+  .action(async (options) => {
+    printSkillsDeprecation();
+    await runWorkflowConfig(options);
+  });
+
 skillsCommand.action(() => {
   printSkillsDeprecation();
   skillsCommand.help();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cubis/foundry",
-  "version": "0.3.23",
+  "version": "0.3.25",
   "description": "Cubis Foundry CLI for workflow-first AI agent environments",
   "type": "module",
   "bin": {