@firenet-designs/fnd-cli 1.1.1 → 2.0.0

package/README.md

@@ -20,7 +20,7 @@ $ npm install -g @firenet-designs/fnd-cli
 $ fnd-cli COMMAND
 running command...
 $ fnd-cli (--version)
-@firenet-designs/fnd-cli/1.1.1 darwin-x64 node-v24.12.0
+@firenet-designs/fnd-cli/2.0.0 linux-x64 node-v24.12.0
 $ fnd-cli --help [COMMAND]
 USAGE
   $ fnd-cli COMMAND
@@ -31,6 +31,7 @@ USAGE
 <!-- commands -->
 * [`fnd-cli create-app`](#fnd-cli-create-app)
 * [`fnd-cli help [COMMAND]`](#fnd-cli-help-command)
+* [`fnd-cli token`](#fnd-cli-token)
 
 ## `fnd-cli create-app`
 
@@ -51,7 +52,7 @@ EXAMPLES
   $ fnd-cli create-app
 ```
 
-_See code: [src/commands/create-app.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v1.1.1/src/commands/create-app.ts)_
+_See code: [src/commands/create-app.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.0.0/src/commands/create-app.ts)_
 
 ## `fnd-cli help [COMMAND]`
 
@@ -72,4 +73,36 @@ DESCRIPTION
 ```
 
 _See code: [@oclif/plugin-help](https://github.com/oclif/plugin-help/blob/v6.2.37/src/commands/help.ts)_
+
+## `fnd-cli token`
+
+Mint an offline Shopify Admin API access token (shpat_) for a custom app via the OAuth authorization-code grant. Works cross-org, unlike client_credentials.
+
+```
+USAGE
+  $ fnd-cli token [-i <value>] [-c <value>] [--no-open] [-p <value>] [--scopes <value>] [-s <value>] [-w
+    <value>]
+
+FLAGS
+  -c, --client-secret=<value>  app Client secret (shpss_...)
+  -i, --client-id=<value>      app Client ID
+  -p, --port=<value>           [default: 3456] local callback port (must match the app redirect URL)
+  -s, --store=<value>          store domain (mystore or mystore.myshopify.com)
+  -w, --write=<value>          path to an .mcp.json whose 'shopify' server should be rewritten to use the token
+      --no-open                don't auto-open the authorize URL in a browser
+      --scopes=<value>         [default: read_products] comma-separated Admin API scopes to request
+
+DESCRIPTION
+  Mint an offline Shopify Admin API access token (shpat_) for a custom app via the OAuth authorization-code grant. Works
+  cross-org, unlike client_credentials.
+
+EXAMPLES
+  $ fnd-cli token --store trafalgar-store --client-id 0b42... --client-secret shpss_...
+
+  $ fnd-cli token -s mystore -i <id> -c <secret> --scopes read_products,read_orders
+
+  $ fnd-cli token -s mystore -i <id> -c <secret> --write ./.mcp.json
+```
+
+_See code: [src/commands/token.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.0.0/src/commands/token.ts)_
 <!-- commandsstop -->

package/dist/commands/token.d.ts

@@ -0,0 +1,20 @@
+import { Command } from '@oclif/core';
+export default class Token extends Command {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        'client-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'client-secret': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'no-open': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        port: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        scopes: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        store: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        write: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+    private mcpSnippet;
+    /** Minimal readline prompt — keeps the CLI dependency-free. */
+    private prompt;
+    private runOAuthFlow;
+    private writeMcpConfig;
+}

package/dist/commands/token.js

@@ -0,0 +1,174 @@
+import { Command, Flags } from '@oclif/core';
+import chalk from 'chalk';
+import { exec } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { platform, stdin, stdout } from 'node:process';
+import { createInterface } from 'node:readline/promises';
+import ora from 'ora';
+/**
+ * The Shopify `client_credentials` grant only works for apps and stores that
+ * live in the SAME Dev Dashboard org. For a client's paid store in another org
+ * it returns `shop_not_permitted`. This command runs the interactive
+ * authorization-code grant instead, which works cross-org and mints a permanent
+ * OFFLINE access token usable as `--access-token` by Shopify Admin tooling.
+ */
+const DEFAULT_PORT = 3456;
+const DEFAULT_SCOPES = 'read_products';
+/** `mystore` or `https://mystore.myshopify.com/` -> `mystore.myshopify.com`. */
+const normalizeStore = (raw) => {
+    const host = raw.trim().replace(/^https?:\/\//, '').replace(/\/.*$/, '');
+    return host.endsWith('.myshopify.com') ? host : `${host}.myshopify.com`;
+};
+/** Open a URL in the user's default browser (best-effort, never throws). */
+const openBrowser = (url) => {
+    const cmd = platform === 'darwin' ? 'open' : platform === 'win32' ? 'start ""' : 'xdg-open';
+    exec(`${cmd} "${url}"`, () => { });
+};
+export default class Token extends Command {
+    static description = 'Mint an offline Shopify Admin API access token (shpat_) for a custom app via the OAuth authorization-code grant. Works cross-org, unlike client_credentials.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> --store trafalgar-store --client-id 0b42... --client-secret shpss_...',
+        '<%= config.bin %> <%= command.id %> -s mystore -i <id> -c <secret> --scopes read_products,read_orders',
+        '<%= config.bin %> <%= command.id %> -s mystore -i <id> -c <secret> --write ./.mcp.json',
+    ];
+    static flags = {
+        'client-id': Flags.string({ char: 'i', description: 'app Client ID' }),
+        'client-secret': Flags.string({ char: 'c', description: 'app Client secret (shpss_...)' }),
+        'no-open': Flags.boolean({ description: "don't auto-open the authorize URL in a browser" }),
+        port: Flags.integer({ char: 'p', default: DEFAULT_PORT, description: 'local callback port (must match the app redirect URL)' }),
+        scopes: Flags.string({ default: DEFAULT_SCOPES, description: 'comma-separated Admin API scopes to request' }),
+        store: Flags.string({ char: 's', description: 'store domain (mystore or mystore.myshopify.com)' }),
+        write: Flags.string({ char: 'w', description: "path to an .mcp.json whose 'shopify' server should be rewritten to use the token" }),
+    };
+    async run() {
+        const { flags } = await this.parse(Token);
+        const store = normalizeStore(flags.store ?? (await this.prompt('Store domain (e.g. mystore)')));
+        const clientId = flags['client-id'] ?? (await this.prompt('Client ID'));
+        const clientSecret = flags['client-secret'] ?? (await this.prompt('Client secret (shpss_...)'));
+        const { scopes } = flags;
+        const { port } = flags;
+        const redirectUri = `http://localhost:${port}/callback`;
+        this.log('');
+        this.log(chalk.dim('Before continuing, the app must list this exact redirect URL:'));
+        this.log('  ' + chalk.cyan(redirectUri));
+        this.log(chalk.dim('and have these scopes released:') + ' ' + chalk.cyan(scopes));
+        this.log('');
+        const token = await this.runOAuthFlow({ clientId, clientSecret, open: !flags['no-open'], port, redirectUri, scopes, store });
+        this.log('');
+        this.log(chalk.green('✓ Offline access token (never expires until uninstall/secret rotation):'));
+        this.log('  ' + chalk.bold(token));
+        this.log('');
+        this.log(chalk.dim('Drop-in .mcp.json server config:'));
+        this.log(this.mcpSnippet(store, token));
+        if (flags.write) {
+            this.writeMcpConfig(flags.write, store, token);
+            this.log('');
+            this.log(chalk.green(`✓ Updated ${flags.write} (shopify server -> --access-token).`));
+        }
+    }
+    mcpSnippet(store, token) {
+        const config = {
+            mcpServers: {
+                shopify: {
+                    args: ['-y', 'shopify-graphql-admin-mcp', '--store', store, '--access-token', token],
+                    command: 'npx',
+                },
+            },
+        };
+        return chalk.dim(JSON.stringify(config, null, 2));
+    }
+    /** Minimal readline prompt — keeps the CLI dependency-free. */
+    async prompt(label) {
+        const rl = createInterface({ input: stdin, output: stdout });
+        try {
+            const answer = (await rl.question(`${label}: `)).trim();
+            if (!answer)
+                this.error(`${label} is required`, { code: '1' });
+            return answer;
+        }
+        finally {
+            rl.close();
+        }
+    }
+    runOAuthFlow(opts) {
+        const { clientId, clientSecret, open, port, redirectUri, scopes, store } = opts;
+        const state = randomBytes(16).toString('hex');
+        const authorizeUrl = `https://${store}/admin/oauth/authorize` +
+            `?client_id=${encodeURIComponent(clientId)}` +
+            `&scope=${encodeURIComponent(scopes)}` +
+            `&redirect_uri=${encodeURIComponent(redirectUri)}` +
+            `&state=${state}`;
+        const spinner = ora(`Waiting for authorization at ${redirectUri} …`);
+        return new Promise((resolve, reject) => {
+            const server = createServer(async (req, res) => {
+                const url = new URL(req.url ?? '/', `http://localhost:${port}`);
+                if (url.pathname !== '/callback') {
+                    res.writeHead(404).end('not found');
+                    return;
+                }
+                const code = url.searchParams.get('code');
+                const returnedState = url.searchParams.get('state');
+                const fail = (message, httpBody) => {
+                    res.writeHead(400, { 'Content-Type': 'text/html' }).end(httpBody);
+                    spinner.fail(message);
+                    server.close();
+                    reject(new Error(message));
+                };
+                if (returnedState !== state)
+                    return fail('State mismatch (possible CSRF) — aborting.', '<h2>State mismatch. Restart the flow.</h2>');
+                if (!code)
+                    return fail(`Authorization denied: ${url.searchParams.get('error') ?? 'no code returned'}.`, '<h2>No authorization code returned.</h2>');
+                try {
+                    const tokenRes = await fetch(`https://${store}/admin/oauth/access_token`, {
+                        // Shopify's token endpoint requires these exact snake_case keys.
+                        // eslint-disable-next-line camelcase
+                        body: JSON.stringify({ client_id: clientId, client_secret: clientSecret, code }),
+                        headers: { 'Content-Type': 'application/json' },
+                        method: 'POST',
+                    });
+                    const text = await tokenRes.text();
+                    if (!tokenRes.ok)
+                        return fail(`Token exchange failed (${tokenRes.status}): ${text.slice(0, 200)}`, '<h2>Token exchange failed. Check the terminal.</h2>');
+                    const data = JSON.parse(text);
+                    res.writeHead(200, { 'Content-Type': 'text/html' }).end('<h2>✅ Token captured. Return to the terminal.</h2>');
+                    spinner.succeed('Authorization complete.');
+                    server.close();
+                    resolve(data.access_token);
+                }
+                catch (error) {
+                    fail(`Error during token exchange: ${error.message}`, '<h2>Error. Check the terminal.</h2>');
+                }
+            });
+            server.on('error', (error) => {
+                const message = error.code === 'EADDRINUSE'
+                    ? `Port ${port} is already in use. Pass a different --port (and update the app redirect URL).`
+                    : error.message;
+                reject(new Error(message));
+            });
+            server.listen(port, () => {
+                this.log(chalk.dim('Open this URL to authorize (logged into the store admin):'));
+                this.log('  ' + chalk.cyan(authorizeUrl));
+                if (open)
+                    openBrowser(authorizeUrl);
+                spinner.start();
+            });
+        });
+    }
+    writeMcpConfig(path, store, token) {
+        let json;
+        try {
+            json = JSON.parse(readFileSync(path, 'utf8'));
+        }
+        catch (error) {
+            this.error(`Could not read ${path}: ${error.message}`, { code: '1' });
+        }
+        json.mcpServers ??= {};
+        json.mcpServers.shopify = {
+            args: ['-y', 'shopify-graphql-admin-mcp', '--store', store, '--access-token', token],
+            command: 'npx',
+        };
+        writeFileSync(path, JSON.stringify(json, null, 2) + '\n');
+    }
+}

package/oclif.manifest.json

@@ -39,7 +39,88 @@
         "commands",
         "create-app.js"
       ]
+    },
+    "token": {
+      "aliases": [],
+      "args": {},
+      "description": "Mint an offline Shopify Admin API access token (shpat_) for a custom app via the OAuth authorization-code grant. Works cross-org, unlike client_credentials.",
+      "examples": [
+        "<%= config.bin %> <%= command.id %> --store trafalgar-store --client-id 0b42... --client-secret shpss_...",
+        "<%= config.bin %> <%= command.id %> -s mystore -i <id> -c <secret> --scopes read_products,read_orders",
+        "<%= config.bin %> <%= command.id %> -s mystore -i <id> -c <secret> --write ./.mcp.json"
+      ],
+      "flags": {
+        "client-id": {
+          "char": "i",
+          "description": "app Client ID",
+          "name": "client-id",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "client-secret": {
+          "char": "c",
+          "description": "app Client secret (shpss_...)",
+          "name": "client-secret",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "no-open": {
+          "description": "don't auto-open the authorize URL in a browser",
+          "name": "no-open",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "port": {
+          "char": "p",
+          "description": "local callback port (must match the app redirect URL)",
+          "name": "port",
+          "default": 3456,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "scopes": {
+          "description": "comma-separated Admin API scopes to request",
+          "name": "scopes",
+          "default": "read_products",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "store": {
+          "char": "s",
+          "description": "store domain (mystore or mystore.myshopify.com)",
+          "name": "store",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "write": {
+          "char": "w",
+          "description": "path to an .mcp.json whose 'shopify' server should be rewritten to use the token",
+          "name": "write",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "token",
+      "pluginAlias": "@firenet-designs/fnd-cli",
+      "pluginName": "@firenet-designs/fnd-cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "token.js"
+      ]
     }
   },
-  "version": "1.1.1"
+  "version": "2.0.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@firenet-designs/fnd-cli",
   "description": "A new CLI generated with oclif",
-  "version": "1.1.1",
+  "version": "2.0.0",
   "author": "Cole Denslow",
   "bin": {
     "fnd": "bin/run.js"
@@ -21,7 +21,7 @@
     "@oclif/test": "^4",
     "@types/chai": "^4",
     "@types/mocha": "^10",
-    "@types/node": "^18.19.130",
+    "@types/node": "^24.13.1",
     "chai": "^4",
     "eslint": "^9",
     "eslint-config-oclif": "^6",
@@ -33,7 +33,7 @@
     "typescript": "^5"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=24.0.0"
   },
   "files": [
     "./bin",
@@ -46,6 +46,10 @@
   ],
   "license": "MIT",
   "main": "dist/index.js",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
   "type": "module",
   "oclif": {
     "bin": "fnd-cli",