@jacebenson/jsn 4.3.7-dev.13 → 4.3.7-dev.15

package/README.md

@@ -81,6 +81,10 @@ jsn diff record --table incident --sys-id <sys_id> --profile-a dev --profile-b p
 jsn eval "gs.info('Hello World')"
 cat script.js | jsn eval --stdin          # pipe a script in (no shell escaping)
 
+# Now GraphQL (documents may contain mutations; read-only profiles are blocked)
+jsn graphql --query '{ GlideRecord_Query { incident(pagination: {limit: 2}) { _results { number { value } } } } }'
+cat incident.graphql | jsn graphql --stdin --variables '{"limit":2}'
+
 # Saved query snippets (stored locally, run against the active profile)
 jsn snippets save open-inc --table incident --query "active=true"
 jsn snippets run open-inc
@@ -167,6 +171,10 @@ export SERVICENOW_OAUTH_TOKEN="***"
 jsn incidents list
 ```
 
+For the credential identity, auth-method, diagnostics, migration, and concurrency contract, see [`docs/AUTH_LIFECYCLE.md`](docs/AUTH_LIFECYCLE.md).
+
+GraphQL uses ServiceNow's `/api/now/graphql` endpoint and sends `{query, variables}` through the authenticated SDK transport. The command preserves GraphQL `data` and `errors`; introspection and available namespaces depend on the target instance.
+
 ## Local data
 
 JSN stores durable local data under `~/.jsn/`. Documentation lives in

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacebenson/jsn",
-  "version": "4.3.7-dev.13",
+  "version": "4.3.7-dev.15",
   "description": "A command-line interface for ServiceNow that follows the Unix philosophy: simple, composable, and scriptable.",
   "type": "module",
   "bin": {

package/src/auth.js

@@ -41,30 +41,32 @@ function credKey(instance, username) {
 
 // ─── PKCE state persistence (shared with Go version) ───
 
-function pkceStatePath(instance) {
+function pkceStatePath(instance, username) {
   const dir = path.join(globalConfigDir(), 'pkce');
   fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-  const filename = sanitizeKeyPart(instance) + '.json';
+  // A known profile identity gets its own pending-login slot. Keep the bare
+  // instance slot for legacy/no-profile flows, where no identity exists yet.
+  const filename = credKey(instance, username) + '.json';
   return path.join(dir, filename);
 }
 
-function savePKCEState(instance, pkce) {
-  const filePath = pkceStatePath(instance);
+function savePKCEState(instance, pkce, username) {
+  const filePath = pkceStatePath(instance, username);
   fs.writeFileSync(filePath, JSON.stringify(pkce, null, 2), { mode: 0o600 });
 }
 
-function loadPKCEState(instance) {
+function loadPKCEState(instance, username) {
   try {
-    const data = fs.readFileSync(pkceStatePath(instance), 'utf-8');
+    const data = fs.readFileSync(pkceStatePath(instance, username), 'utf-8');
     return JSON.parse(data);
   } catch {
     return null;
   }
 }
 
-function removePKCEState(instance) {
+function removePKCEState(instance, username) {
   try {
-    fs.unlinkSync(pkceStatePath(instance));
+    fs.unlinkSync(pkceStatePath(instance, username));
   } catch {
     // ignore
   }
@@ -746,7 +748,7 @@ export class AuthManager {
     instanceURL = normalizeInstanceURL(instanceURL);
     const clientID = getOAuthClientID();
     const pkce = generatePKCE();
-    savePKCEState(instanceURL, pkce);
+    savePKCEState(instanceURL, pkce, username);
     const url = buildAuthURL(instanceURL, clientID, pkce);
     if (waitFile) {
       console.log(url);
@@ -766,7 +768,7 @@ export class AuthManager {
         const code = fs.readFileSync(filePath, 'utf-8').trim();
         if (code) {
           console.log(`\nAuthorization code found in ${filePath}`);
-          removePKCEState(instanceURL);
+          removePKCEState(instanceURL, username);
           const newCreds = await this.exchangeCode(instanceURL, clientID, code, pkce);
           this.saveCredentials(instanceURL, newCreds, username || newCreds.username);
           console.log('Token exchange successful!\n');
@@ -838,7 +840,7 @@ export class AuthManager {
   async loginWithCode(instanceURL, code, username = this._activeUsername()) {
     instanceURL = normalizeInstanceURL(instanceURL);
     const clientID = getOAuthClientID();
-    const pkce = loadPKCEState(instanceURL);
+    const pkce = loadPKCEState(instanceURL, username);
     if (!pkce) {
       throw errAuth(
         `No pending login session for ${instanceURL}.\n\n` +
@@ -848,7 +850,7 @@ export class AuthManager {
         `  jsn auth login ${instanceURL} --code CODE`
       );
     }
-    removePKCEState(instanceURL);
+    removePKCEState(instanceURL, username);
 
     const newCreds = await this.exchangeCode(instanceURL, clientID, code, pkce);
     this.saveCredentials(instanceURL, newCreds, username || newCreds.username);

package/src/cli.js

@@ -70,6 +70,7 @@ import { atfCmd } from './commands/atf.js';
 import { approvalsCmd } from './commands/approvals.js';
 import { perfCmd } from './commands/perf.js';
 import { diffCmd } from './commands/diff.js';
+import { graphqlCmd } from './commands/graphql.js';
 
 function wrap(handler) {
   return async (argv) => {
@@ -373,6 +374,7 @@ export function buildCLI() {
     .command(approvalsCmd(wrap))
     .command(perfCmd(wrap))
     .command(diffCmd(wrap))
+    .command(graphqlCmd(wrap))
     .command(evalCmd(wrap))
     .command(restCmd(wrap))
     .command(skillCmd(wrap))

package/src/commands/graphql.js

@@ -0,0 +1,95 @@
+import fs from 'node:fs';
+import { declareCapabilities } from '../capabilities.js';
+
+// GraphQL documents may contain mutations. Gate the whole command so normal
+// instance/auth and read-only protections apply without attempting AST parsing.
+declareCapabilities('graphql', { mutationSubcommands: [''] });
+
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (chunk) => { data += chunk; });
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', reject);
+  });
+}
+
+export async function resolveGraphQLInput(argv) {
+  const sources = [
+    argv.document !== undefined,
+    argv.query !== undefined,
+    argv.queryFile !== undefined,
+    argv.stdin === true,
+  ].filter(Boolean).length;
+  if (sources !== 1) {
+    throw new Error('Provide exactly one GraphQL document via positional document, --query, --query-file, or --stdin');
+  }
+
+  let query;
+  if (argv.document !== undefined) query = argv.document;
+  else if (argv.query !== undefined) query = argv.query;
+  else if (argv.queryFile !== undefined) query = fs.readFileSync(argv.queryFile, 'utf-8');
+  else query = await readStdin();
+
+  query = String(query || '').trim();
+  if (!query) throw new Error('GraphQL document must not be empty');
+  return query;
+}
+
+export function parseGraphQLVariables(value) {
+  if (value === undefined) return {};
+  let variables;
+  try {
+    variables = JSON.parse(value);
+  } catch {
+    throw new Error('--variables must be valid JSON');
+  }
+  if (!variables || typeof variables !== 'object' || Array.isArray(variables)) {
+    throw new Error('--variables must be a JSON object');
+  }
+  return variables;
+}
+
+export function graphqlCmd(wrap) {
+  return {
+    command: 'graphql [document]',
+    describe: 'Execute a GraphQL document against ServiceNow Now GraphQL',
+    builder: (yargs) => yargs
+      .positional('document', {
+        describe: 'GraphQL document string',
+        type: 'string',
+      })
+      .option('query', {
+        type: 'string',
+        describe: 'GraphQL document string (alternative to positional)',
+      })
+      .option('query-file', {
+        type: 'string',
+        describe: 'Read the GraphQL document from a file',
+      })
+      .option('variables', {
+        type: 'string',
+        describe: 'GraphQL variables as a JSON object',
+      })
+      .option('stdin', {
+        type: 'boolean',
+        describe: 'Read the GraphQL document from stdin',
+      }),
+    handler: wrap(async (argv, app) => {
+      const query = await resolveGraphQLInput(argv);
+      const variables = parseGraphQLVariables(argv.variables);
+      const endpoint = `${app.getEffectiveInstance()}/api/now/graphql`;
+      const result = await app.sdk.request(endpoint, {
+        method: 'POST',
+        body: JSON.stringify({ query, variables }),
+      });
+      const errorCount = Array.isArray(result?.errors) ? result.errors.length : 0;
+      app.ok(result, {
+        summary: errorCount
+          ? `GraphQL returned ${errorCount} error(s)`
+          : 'GraphQL request succeeded',
+      });
+    }),
+  };
+}