stpr 1.0.4 → 1.0.6

package/README.md

@@ -0,0 +1,159 @@
+# stpr — Stepper Skills CLI
+
+Skill Sets are a Stepper feature that let you bundle integration actions into curated, authenticated toolkits — and expose them to AI agents, CLIs, and any MCP-compatible client.
+
+`stpr` is a command-line interface for interacting with [Stepper](https://stepper.io) Skill Sets. Discover, inspect, and execute integration actions directly from your terminal. This is perfect for OpenClaw or agents that can interact with a CLI, or for developers who want to use skills in their own scripts.
+
+If you prefer, you can directly use the Stepper MCP server at `https://mcp.stepper.io/skill-sets/mcp`instead of the CLI.
+
+## Installation
+
+```bash
+npm install -g stpr
+```
+
+## Authentication
+
+The CLI supports three authentication methods:
+
+### OAuth Login (recommended)
+
+```bash
+stpr login
+```
+
+Opens your browser to authenticate and select a Skill Set. Credentials are saved to `~/.config/stepper-skillsets/config.json` and automatically refreshed when they expire.
+
+### Static Token
+
+Generate a token from [Stepper](https://app.stepper.io/flow/skill-sets) and pass it directly:
+
+```bash
+stpr --token sst_your_token_here list
+```
+
+### Environment Variable
+
+```bash
+export STEPPER_SKILL_TOKEN=sst_your_token_here
+stpr list
+```
+
+## Commands
+
+### Profile Management
+
+```bash
+stpr login                # Authenticate via OAuth (opens browser)
+stpr logout [name]        # Remove a saved profile, or all profiles if no name given
+stpr profiles             # List all saved profiles
+stpr use <name>           # Switch the active profile
+stpr whoami               # Show active profile and server info
+```
+
+### Discovering Skills
+
+```bash
+stpr list                 # List all available skills, grouped by service
+stpr list --verbose       # Include full input schemas
+stpr list <service>       # List skills for a specific service
+stpr <service>            # Shorthand for listing a service's skills
+```
+
+### Inspecting Parameters
+
+Many skills have dynamic parameters — fields that change based on the values of other fields. Calling a skill without `--call` returns its current parameter schema.
+
+```bash
+# See what fields are needed for add_row, given a spreadsheet
+stpr google-sheets add_row -i '{"spreadsheet_id": "abc123"}'
+```
+
+Some parameters have dynamic dropdown options. Fetch them with `--options`:
+
+```bash
+stpr google-sheets add_row --options worksheet_id \
+  -i '{"spreadsheet_id": "abc123"}' \
+  --search "Sheet" \
+  --cursor "next_page"
+```
+
+### Calling Skills
+
+Use the `--call` flag to execute an action:
+
+```bash
+stpr google-sheets create_sheet --call \
+  -i '{"name": "Q1 Report", "columns": "Name, Email, Phone"}'
+```
+
+### Polling Async Results
+
+Component library tools run asynchronously. Poll for results with:
+
+```bash
+stpr status <statusId>
+```
+
+## Input
+
+Pass JSON input via the `-i` / `--input` flag or pipe it through stdin:
+
+```bash
+# Flag
+stpr slack send_message --call -i '{"channel": "#general", "text": "Hello!"}'
+
+# Stdin
+echo '{"channel": "#general", "text": "Hello!"}' | stpr slack send_message --call
+```
+
+## Options Reference
+
+| Flag                 | Description                                                     |
+| -------------------- | --------------------------------------------------------------- |
+| `--token <token>`    | Auth token (overrides saved profiles and `STEPPER_SKILL_TOKEN`) |
+| `--base-url <url>`   | Override MCP server URL (default: `https://mcp.stepper.io`)     |
+| `--skillset <name>`  | Use a specific saved profile instead of the active one          |
+| `--call`             | Execute the skill (default behavior is parameter inspection)    |
+| `--verbose`          | Include full `inputSchema` when listing skills                  |
+| `-i, --input <json>` | JSON input for calls, parameter fetches, or option queries      |
+| `--options <param>`  | Fetch dynamic dropdown options for a parameter                  |
+| `--search <query>`   | Filter dropdown options by search term                          |
+| `--cursor <cursor>`  | Pagination cursor for dropdown options                          |
+| `-h, --help`         | Show help                                                       |
+| `-v, --version`      | Show version                                                    |
+
+## Environment Variables
+
+| Variable              | Description                                                   |
+| --------------------- | ------------------------------------------------------------- |
+| `STEPPER_SKILL_TOKEN` | Auth token (used when no `--token` flag and no saved profile) |
+| `STEPPER_URL`         | Override the MCP server base URL                              |
+
+## Examples
+
+```bash
+# Authenticate
+stpr login
+
+# List everything available
+stpr list
+
+# Explore a service
+stpr google-sheets
+
+# Inspect dynamic parameters step by step
+stpr google-sheets add_row -i '{}'
+stpr google-sheets add_row -i '{"spreadsheet_id": "abc123"}'
+
+# Fetch dropdown options
+stpr google-sheets add_row --options worksheet_id -i '{"spreadsheet_id": "abc123"}'
+
+# Execute
+stpr google-sheets add_row --call -i '{"spreadsheet_id": "abc123", "worksheet_id": "Sheet1", "values": {"Name": "Alice"}}'
+
+# Switch between skill sets
+stpr profiles
+stpr use "Production Tools"
+stpr list
+```

package/dist/cli.js

@@ -138,7 +138,6 @@ var OAUTH_CALLBACK_PORT = 3847;
 var CALLBACK_PATH = "/callback";
 var CONFIG_DIR = path.join(os.homedir(), ".config", "stepper-skillsets");
 var CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
-var LEGACY_CREDENTIALS_FILE = path.join(CONFIG_DIR, "credentials.json");
 function generatePKCE() {
   const codeVerifier = crypto.randomBytes(32).toString("base64url");
   const codeChallenge = crypto.createHash("sha256").update(codeVerifier).digest().toString("base64url");
@@ -158,29 +157,14 @@ function saveConfig(config) {
     mode: 384
   });
 }
-function migrateLegacyCredentials() {
-  try {
-    const data = fs.readFileSync(LEGACY_CREDENTIALS_FILE, "utf-8");
-    const creds = JSON.parse(data);
-    const config = {
-      active: "default",
-      skillsets: { default: creds }
-    };
-    saveConfig(config);
-    fs.unlinkSync(LEGACY_CREDENTIALS_FILE);
-  } catch {
-  }
-}
 function getConfigPathForDisplay() {
   return CONFIG_FILE;
 }
 function getActiveSkillset() {
-  migrateLegacyCredentials();
   const config = loadConfig();
   return config.active;
 }
 function setActiveSkillset(name) {
-  migrateLegacyCredentials();
   const config = loadConfig();
   if (!(name in config.skillsets)) {
     return false;
@@ -190,7 +174,6 @@ function setActiveSkillset(name) {
   return true;
 }
 function listSkillsets() {
-  migrateLegacyCredentials();
   const config = loadConfig();
   return Object.entries(config.skillsets).map(([name, creds]) => ({
     name,
@@ -199,12 +182,10 @@ function listSkillsets() {
   }));
 }
 function getCredentials(name) {
-  migrateLegacyCredentials();
   const config = loadConfig();
   return config.skillsets[name] ?? null;
 }
 function saveCredentials(name, creds) {
-  migrateLegacyCredentials();
   const config = loadConfig();
   config.skillsets[name] = creds;
   if (!config.active || !(config.active in config.skillsets)) {
@@ -213,7 +194,6 @@ function saveCredentials(name, creds) {
   saveConfig(config);
 }
 function deleteSkillset(name) {
-  migrateLegacyCredentials();
   const config = loadConfig();
   if (!(name in config.skillsets)) {
     return false;
@@ -226,7 +206,6 @@ function deleteSkillset(name) {
   return true;
 }
 function deleteAllSkillsets() {
-  migrateLegacyCredentials();
   const config = loadConfig();
   const count = Object.keys(config.skillsets).length;
   config.skillsets = {};
@@ -320,13 +299,30 @@ async function runLoginFlow(baseUrl) {
           res.end("Not found");
           return;
         }
+        const requestHost = req.headers.host ?? `127.0.0.1:${OAUTH_CALLBACK_PORT}`;
+        const callbackUrl = new URL(req.url ?? "/", `http://${requestHost}`);
+        const receivedCallbackUrl = `${callbackUrl.origin}${callbackUrl.pathname}`;
+        if (receivedCallbackUrl !== redirectUri) {
+          res.writeHead(200, { "Content-Type": "text/html" });
+          res.end(
+            "<html><body><h1>Login failed</h1><p>Redirect URI mismatch</p><p>You can close this tab.</p></body></html>"
+          );
+          server.close();
+          reject(new Error("OAuth redirect URI mismatch"));
+          return;
+        }
         const code = url.searchParams.get("code");
         const returnedState = url.searchParams.get("state");
         const error = url.searchParams.get("error");
         if (error) {
+          const escapeHtml = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+          const safeError = escapeHtml(error);
+          const safeDesc = escapeHtml(
+            url.searchParams.get("error_description") ?? "Unknown error"
+          );
           res.writeHead(200, { "Content-Type": "text/html" });
           res.end(
-            `<html><body><h1>Login failed</h1><p>${error}: ${url.searchParams.get("error_description") ?? "Unknown error"}</p><p>You can close this tab.</p></body></html>`
+            `<html><body><h1>Login failed</h1><p>${safeError}: ${safeDesc}</p><p>You can close this tab.</p></body></html>`
           );
           server.close();
           reject(new Error(`OAuth error: ${error}`));
@@ -407,7 +403,6 @@ async function refreshAccessToken(baseUrl, clientId, refreshToken) {
   };
 }
 async function getValidToken(skillsetName, baseUrl) {
-  migrateLegacyCredentials();
   const config = loadConfig();
   const name = skillsetName ?? config.active;
   if (!name || !(name in config.skillsets)) {
@@ -549,9 +544,7 @@ Commands:
   whoami               Show active skillset and server info
   list [<service>]      List available skills (optionally for a service). Use --verbose for inputSchema.
   status <statusId>     Poll the status of a component tool run
-  
   <service>             List available skills for that service. Use --verbose for inputSchema.
- 
   <service> <action> (-i <json> | stdin)
                        Get the current parameters for a skill (default, for dynamic parameters)
   <service> <action> --call (-i <json> | stdin)
@@ -572,24 +565,15 @@ Options:
   -v, --version       Show version
 
 Examples:
-
   Auth (optional, can use STEPPER_SKILL_TOKEN env var, or --token <token> from https://app.stepper.io/flow/skill-sets):
     stpr login
 
-  List available skills:
-    stpr list
-    stpr stripe
-
-
   Load parameters:
     By default, requesting a skill returns the current parameters only; it does
     not call the skill. Use --call to execute the action.
 
     stpr google-sheets add_row -i '{"spreadsheet_id": "abc123"}'
 
-  Call a skill:
-    stpr stripe create_customer --call -i '{"email": "test@example.com"}'
-
   Dynamic dropdown options:
     Some actions have dynamic dropdown options, which change depending on the
     value of other parameters. You can request the current dropdown options for
@@ -597,12 +581,12 @@ Examples:
     options only, it will not call the skill. Dynamic dropdowns are also often
     searchable and paginated via a cursor.
 
-    stpr google-sheets addRow --options worksheet_id -i '{"spreadsheet_id": "abc123"}'
-    stpr google-sheets addRow --options worksheet_id --search "Sheet" --cursor "next_page"
-
-Profiles:
-  Multiple skill sets stored in ~/.config/stepper-skillsets/
-  Precedence: --token > STEPPER_SKILL_TOKEN > --skillset > active skill set`);
+    stpr google-sheets add_row --options worksheet_id -i '{"spreadsheet_id": "abc123"}' --search "Sheet" --cursor "next_page"
+  
+    Call a skill:
+    stpr google-sheets create_sheet --call -i '{"name": "My Sheet", "columns": "Name, Email, Phone"}'
+  
+  `);
 }
 function die(message) {
   process.stderr.write(`\x1B[31m[Error] ${message} \x1B[0m 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stpr",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "CLI for Stepper skill sets",
   "type": "module",
   "files": [
@@ -20,4 +20,4 @@
     "tsup": "^8.0.0",
     "typescript": "^5.4.0"
   }
-}
+}