@topolo/cli 0.12.31 → 0.12.33

package/README.md

@@ -25,6 +25,23 @@ npx @topolo/cli whoami
 
 ## Configure
 
+### Use it from your terminal
+
+Every command starts with `topolo`. Running `topolo` prints help and returns to
+your shell; it does not open an interactive prompt. Copy a complete command:
+
+```bash
+topolo auth login       # sign in with your browser
+topolo whoami           # see who you are signed in as
+topolo apps --no-json   # list your apps as a readable table
+topolo auth --help      # see sign-in commands
+topolo help apps        # see app commands and options
+```
+
+In help output, `[brackets]` mean an argument is optional and `<angle brackets>`
+mark a value to replace. Do not type the brackets. For example, `help [command]`
+means you can run `topolo help` or `topolo help apps`.
+
 Credentials come from (in priority order):
 
 1. Environment-specific credential variables

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { Command } from "commander";
+import { Command, Help } from "commander";
 
 // src/commands/auth.ts
 import { spawn } from "child_process";
@@ -9,7 +9,7 @@ import { platform as platform2 } from "os";
 import { createInterface } from "readline/promises";
 import { stdin as input } from "process";
 
-// node_modules/.pnpm/@topolo+sdk@0.23.16/node_modules/@topolo/sdk/dist/index.js
+// node_modules/.pnpm/@topolo+sdk@0.23.17/node_modules/@topolo/sdk/dist/index.js
 function record(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
@@ -3610,7 +3610,7 @@ async function pollUntilApproved(params) {
   throw new Error("Device code expired. Run `topolo auth login` again.");
 }
 
-// node_modules/.pnpm/@topolo+sdk@0.23.16/node_modules/@topolo/sdk/dist/node/credential-store.js
+// node_modules/.pnpm/@topolo+sdk@0.23.17/node_modules/@topolo/sdk/dist/node/credential-store.js
 import { mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2, chmod as chmod2, rm as rm2, stat } from "fs/promises";
 import { existsSync as existsSync2 } from "fs";
 import { homedir as homedir2, platform } from "os";
@@ -4507,7 +4507,9 @@ async function refreshCredentialIfNeeded(environment = selectedEnvironment(), op
   if (process.env[`${prefix}_API_KEY`] || process.env[`${prefix}_ACCESS_TOKEN`] || environment === "production" && process.env.TOPOLO_API_KEY || environment === "production" && process.env.TOPOLO_ACCESS_TOKEN) {
     return resolveCredential(environment);
   }
-  const observed = profileForEnvironment(await readConfig(), environment).credential;
+  const observedProfile = profileForEnvironment(await readConfig(), environment);
+  const observed = observedProfile.credential;
+  if (!observed || observed.kind !== "access_token" || !observed.refreshToken || !observedProfile.oauthClientId || !options.force && observed.expiresAt && observed.expiresAt - REFRESH_SKEW_SECONDS > Math.floor(Date.now() / 1e3)) return observed ?? null;
   return withConfigWriteLock(async () => {
     const config = await readConfig();
     const profile = profileForEnvironment(config, environment);
@@ -4561,6 +4563,10 @@ async function refreshCredentialIfNeeded(environment = selectedEnvironment(), op
   });
 }
 async function refreshContextCredentialIfNeeded(environment, key, options = {}) {
+  const observedProfile = profileForEnvironment(await readConfig(), environment);
+  const observedContext = observedProfile.contexts?.[key];
+  const observed = observedContext?.credential;
+  if (!observed || observed.kind !== "access_token" || !observed.refreshToken || !(observedContext.oauthClientId ?? observedProfile.oauthClientId) || !options.force && observed.expiresAt && observed.expiresAt - REFRESH_SKEW_SECONDS > Math.floor(Date.now() / 1e3)) return observed ?? null;
   return withConfigWriteLock(async () => {
     const config = await readConfig();
     const profile = profileForEnvironment(config, environment);
@@ -7688,8 +7694,8 @@ try {
 }
 var environmentWasStated = Boolean(inheritedEnvironment) || environmentArgSeen;
 program.name("topolo").description(
-  "Public Topolo CLI for customer identity, organization context, applications, resources, and actions."
-).version(CLI_VERSION).option("--env <environment>", "Topolo environment: production, staging, development, or local");
+  "Use Topolo from your terminal: sign in, find your apps, and run actions.\n\nQuick start (copy a command, then press Enter):\n  topolo auth login       # Sign in with your browser\n  topolo whoami           # See who you are signed in as\n  topolo apps --no-json   # List your apps as a readable table\n  topolo auth --help      # See sign-in commands\n  topolo help apps        # See app commands and options"
+).version(CLI_VERSION).option("--env <environment>", "Topolo environment: production, staging, development, or local").addHelpText("beforeAll", '\nEvery command starts with "topolo". Running "topolo" alone prints help; it does not open an interactive prompt.\n').addHelpText("afterAll", "\nHelp notation: [brackets] mean optional; <angle brackets> mark a value to replace. Do not type the brackets.");
 program.hook("preAction", async (thisCommand, actionCommand) => {
   const opts = thisCommand.opts();
   if (opts.env) process.env.TOPOLO_ENV = normalizeEnvironment(opts.env);
@@ -7727,11 +7733,28 @@ registerContextCommand(program);
 registerResourcesCommand(program);
 registerWorkspacesCommand(program);
 registerInstallationsCommand(program);
-program.parseAsync(argv).catch((err) => {
-  process.stderr.write(`Unexpected error: ${err instanceof Error ? err.message : String(err)}
+var helpCommands = [program];
+for (const command of helpCommands) {
+  command.configureHelp({
+    subcommandTerm(subcommand) {
+      const parents = [];
+      for (let parent = subcommand.parent ?? command; parent; parent = parent.parent) {
+        parents.unshift(parent.name());
+      }
+      return [...parents, new Help().subcommandTerm(subcommand)].join(" ");
+    }
+  });
+  helpCommands.push(...command.commands);
+}
+if (argv.length === 2) {
+  program.outputHelp();
+} else {
+  program.parseAsync(argv).catch((err) => {
+    process.stderr.write(`Unexpected error: ${err instanceof Error ? err.message : String(err)}
 `);
-  process.exit(1);
-});
+    process.exit(1);
+  });
+}
 function consumeEnvironmentArg(argv2) {
   const next = argv2.slice(0, 2);
   for (let i = 2; i < argv2.length; i += 1) {

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@topolo/cli",
   "packageManager": "pnpm@10.17.1",
-  "version": "0.12.31",
-  "topoloPublishedVersion": "0.12.31",
+  "version": "0.12.33",
+  "topoloPublishedVersion": "0.12.33",
   "description": "Public command-line interface for Topolo customer organizations, developers, and agents.",
   "license": "UNLICENSED",
   "author": "Topolo",
@@ -28,8 +28,8 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "@topolo/mcp": "0.14.21",
-    "@topolo/sdk": "0.23.16",
+    "@topolo/mcp": "0.14.22",
+    "@topolo/sdk": "0.23.17",
     "commander": "^12.1.0",
     "undici": "6.29.0"
   },