@jacebenson/jsn 3.0.6 → 3.1.0

package/README.md

@@ -1,270 +1,113 @@
-# JSN - ServiceNow CLI
+# JSN — ServiceNow CLI
 
-A command-line interface for ServiceNow that follows the Unix philosophy: simple, composable, and scriptable.
+A command-line interface for ServiceNow. Type `jsn` and start working — no web UI needed.
 
-## Installation
+Works standalone or with AI agents (Claude Code, OpenCode, Hermes, Cursor, Copilot).
 
-### npm (recommended — cross-platform)
+## Install
 
 ```bash
 npm install -g @jacebenson/jsn
 ```
 
-No compilation needed. Works on macOS, Linux, and Windows with Node.js 18+.
+Node.js 18+. macOS, Linux, Windows.
 
-> **Note:** As of v0.1.0, the `latest` dist-tag points to the Node.js implementation. This is the version you get with `npm install -g @jacebenson/jsn`.
+The install also copies an AI agent skill file to `~/.agents/skills/servicenow/SKILL.md`.
 
-### Quick Start
+## Quick Start
 
 ```bash
-# Interactive setup
-jsn setup
-
-# Check auth status
-jsn auth status
+jsn setup                                    # Interactive first-time setup
+jsn auth login https://dev12345.service-now.com
+jsn incidents list --query "priority=1"      # Critical incidents
+```
 
-# List incidents
-jsn incidents
+## What It Does
 
-# Check for updates
-jsn version --check
-```
+jsn talks to the ServiceNow REST API. Read, create, update, delete — tickets, users, groups, records on any table. Inspect flows and business rules. Export update sets. Run background scripts.
 
-## What's New in v0.1.0
-
-Full feature parity — 128 tests, lint clean:
-
-| Feature | Status |
-|---------|--------|
-| Incident management (CRUD) | ✅ |
-| Change request management (CRUD) | ✅ |
-| Service catalog requests (with attachments + variables) | ✅ |
-| Catalog tasks, generic tickets | ✅ |
-| User management (CRUD) | ✅ |
-| Group management (CRUD) | ✅ |
-| Group memberships and roles | ✅ |
-| Generic Table API (`jsn records`) | ✅ |
-| OAuth PKCE with keychain (shared auth store) | ✅ |
-| Bot/CI/CD auth flags (`--code`, `--print-url`) | ✅ |
-| Dev commands: flows, actions, includes, rules, ACLs, etc. | ✅ |
-| Script execution (`jsn dev eval`) via OAuth session flow | ✅ |
-| Interactive search-as-you-type pickers | ✅ |
-| Output formats: JSON, styled, markdown, quiet | ✅ |
-| Enriched `requests show` with attachments + variables | ✅ |
-| Categorized help system (CORE, DATA, DEV, CONFIG) | ✅ |
-
-### New Commands
-
-- **`jsn version --check`** — Check npm registry for newer versions
-- **`jsn skill`** — Manage the jsn AI agent skill file (for Hermes, Claude Code, etc.)
-  - `jsn skill show` — Display the bundled skill
-  - `jsn skill fetch` — Download latest skill from GitHub
-  - `jsn skill path` — Show skill file locations
-  - `jsn skill install` — Download + save to Hermes skills directory
-
-## Configuration
-
-JSN uses a layered configuration system:
-
-| Source | Priority | Description |
-|--------|----------|-------------|
-| Flags | Highest | `--instance`, `--profile`, `--format` |
-| Environment | High | `SERVICENOW_INSTANCE_URL`, `SERVICENOW_FORMAT` |
-| Local config | Medium | `./.servicenow/config.json` |
-| Global config | Low | `~/.config/servicenow/config.json` |
-| Defaults | Lowest | Built-in defaults |
-
-### Profiles
+Everything outputs JSON when piped, styled tables in a terminal.
 
 ```bash
-# Login to a new instance
-jsn auth login https://dev12345.service-now.com
+# Core ticket work
+jsn incidents list --query "active=true^priority=1"
+jsn incidents INC0010001
+jsn incidents create --description "Server down" --priority 1
 
-# List all profiles
-jsn profiles list
+# Admin tasks
+jsn flows list                                # Interactive picker with pagination
+jsn flows show "Assign Task"                  # Full flow detail
+jsn rules list --query "collection=incident"
+jsn updatesets set "My Feature"
 
-# Switch to a different profile
-jsn profiles use dev12345
+# Generic table access
+jsn records list --table incident --limit 50 --json | jq '.[].number'
+jsn records create --table incident --data '{"short_description":"test"}'
 
-# Show current profile
-jsn profiles show
+# Script execution
+jsn eval "gs.info('Hello World')"
 ```
 
 ## Commands
 
-### CORE
-
-| Command | Aliases | Description |
-|---------|---------|-------------|
-| `incidents` | `incident`, `inc` | Manage IT incidents |
-| `changes` | `change`, `chg` | Manage change requests |
-| `requests` | `request`, `req`, `ritm` | Manage service catalog requests |
-| `tasks` | `task`, `sctask` | Manage service catalog tasks |
-| `tickets` | `ticket` | Query generic tickets |
-
-### DATA & ADMIN
-
-| Command | Aliases | Description |
-|---------|---------|-------------|
-| `records` | - | Generic Table API for any table |
-| `users` | `user` | Manage users |
-| `groups` | `group` | Manage user groups |
-| `groupmembers` | `gm` | Manage group memberships |
-| `grouproles` | `gr` | Manage group roles |
-
-### DEVELOPMENT
-
-| Command | Description |
-|---------|-------------|
-| `dev flows` | Manage Flow Designer flows |
-| `dev actions` | Manage action definitions |
-| `dev includes` | Manage script includes |
-| `dev rules` | Manage business rules |
-| `dev clientscripts` | Manage client scripts |
-| `dev uiactions` | Manage UI actions |
-| `dev uipolicies` | Manage UI policies |
-| `dev tables` | View table definitions |
-| `dev columns` | Manage column definitions |
-| `dev import` | Manage import sets |
-| `dev acls` | Manage access controls |
-| `dev roles` | Manage roles |
-| `dev updatesets` | Manage update sets |
-| `dev scopes` | Manage application scopes |
-| `dev properties` | Manage system properties |
-| `dev logs` | Query system logs |
-| `dev rest` | Raw REST API calls |
-| `dev eval` | Execute background scripts |
-
-### CONFIGURATION
-
-| Command | Description |
-|---------|-------------|
-| `setup` | Interactive first-time setup |
-| `auth` | Manage OAuth authentication |
-| `profiles` | Manage instance profiles |
-
-### UTILITY
-
-| Command | Description |
-|---------|-------------|
-| `version` | Show version (use `--check` for update check) |
-| `skill` | Manage the jsn AI agent skill file |
-
-## Usage Examples
-
-### Incidents
+Run `jsn` for the full grouped list. Commands are organized by ServiceNow domain:
 
-```bash
-jsn incidents                              # List all
-jsn incidents list --query "priority=1"    # Critical only
-jsn incidents INC0010001                   # Show specific
-jsn incidents create --description "Server down" --priority 1
-jsn incidents update INC0010001 --data '{"state": "6"}'
-```
+**Core** — `incidents`, `changes`, `requests`, `tasks`, `tickets`
 
-### Requests (with enriched details)
+**Automation** — `flows`, `actions`, `rules`, `scrapi`, `updatesets`, `eval`, `rest`
 
-```bash
-jsn requests show RITM0010001
-# Output includes attachments + catalog variables:
-# ─ Attachments ─
-#   onboarding_form.pdf  (by John Smith, 2026-05-15 14:23:10)
-# ─ Catalog Variables ─
-#   Department:  Engineering
-#   Urgency:  High
-```
+**Access** — `acls`, `roles`, `scopes`, `properties`, `privileges`
 
-### Development
+**User Experience** — `forms`, `lists`, `clientscripts`, `uipolicies`, `uiactions`
 
-```bash
-jsn dev flows                              # List flows
-jsn dev includes MyScriptInclude           # Show a script include
-jsn dev rules                              # List business rules
-jsn dev updatesets set "My Update Set"     # Set current updateset
-jsn dev eval "gs.info('Hello World')"      # Run background script
-```
+**Data** — `records`, `tables`, `columns`, `includes`, `import`, `logs`, `users`, `groups`
 
-### Generic Table API
+Every command supports `--json`, `--query`, and `--help`.
+
+## Profiles
+
+Switch between instances without re-authenticating.
 
 ```bash
-jsn records list --table incident --limit 10
-jsn records list --table incident --query "priority=1^active=true"
-jsn records get --table incident --sys-id abc123
-jsn records create --table incident --data '{"short_description": "Test"}'
+jsn auth login https://dev12345.service-now.com
+jsn profiles list
+jsn profiles use dev12345
+jsn profiles show
 ```
 
 ## Output Formats
 
-| Format | Flag | Description |
-|--------|------|-------------|
-| Auto (default) | `--format=auto` | JSON for pipes, styled for TTY |
-| JSON | `--json` or `--format=json` | Machine-readable JSON |
-| Styled | `--styled` | ANSI-styled tables |
-| Markdown | `--markdown` | Markdown tables |
-| Quiet | `--quiet` or `-q` | Data only, no envelope |
-
-```bash
-jsn incidents --json | jq '.[].number'
-jsn incidents --styled
-jsn incidents -q | jq '.[].number'
-```
+| Flag | When to use |
+|------|-------------|
+| (default) | Terminal — styled tables |
+| `--json` | Pipelines, scripts |
+| `--markdown` | Documentation |
+| `--quiet` / `-q` | Data only, no envelope |
 
 ## Authentication
 
-OAuth 2.0 with PKCE. Credentials stored in `~/.config/servicenow/credentials/`.
+OAuth 2.0 with PKCE. Credentials in `~/.config/servicenow/credentials/`.
 
 ```bash
 jsn auth login https://dev12345.service-now.com
-
-# Bot-friendly: print auth URL instead of opening a browser
-jsn auth login https://dev12345.service-now.com --print-url
-
-# Paste code from browser
-jsn auth login https://dev12345.service-now.com --code ABC123
 ```
 
-### CI/CD Integration
+For CI/CD, set environment variables:
 
 ```bash
 export SERVICENOW_INSTANCE_URL="https://dev12345.service-now.com"
 export SERVICENOW_OAUTH_TOKEN="***"
-jsn incidents list   # No interactive auth needed
+jsn incidents list
 ```
 
-## AI Agent Integration
+## AI Agents
 
-JSN includes a built-in skill file for AI agents:
+jsn ships with a skill file that tells AI agents how to use it. Installed automatically to `~/.agents/skills/servicenow/SKILL.md`.
 
 ```bash
-# View the skill file
-jsn skill show
-
-# Download the latest skill from GitHub
-jsn skill fetch | head -30
-
-# Install to Hermes skills directory
-jsn skill install
-
-# Install to a custom location
-jsn skill install /path/to/skills/
-```
-
-## Environment Variables
-
-| Variable | Description |
-|----------|-------------|
-| `SERVICENOW_INSTANCE_URL` | Default instance URL |
-| `SERVICENOW_FORMAT` | Default output format |
-| `SERVICENOW_OAUTH_TOKEN` | OAuth token (for CI/CD) |
-| `JSN_NO_HEADER` | Suppress context header |
-
-## Getting Help
-
-```bash
-jsn                          # Categorized help with command groups
-jsn incidents --help         # Command details
-jsn version                  # Show version
-jsn version --check          # Check for npm updates
+jsn skill show                  # View the skill
+jsn skill install               # Install to Hermes
+jsn skill install --target all  # All supported agents
 ```
 
 ## Development
@@ -272,80 +115,12 @@ jsn version --check          # Check for npm updates
 ```bash
 git clone https://github.com/jacebenson/jsn.git
 cd jsn
-git checkout nodejs
 npm install
-npm test           # 128+ tests
-npm run lint       # ESLint
-npm run start      # Run CLI locally
-```
-
-### Project Structure
-
-```
-├── src/
-│   ├── cli.js              # Root CLI (yargs setup)
-│   ├── app.js              # App context
-│   ├── auth.js             # OAuth PKCE manager
-│   ├── sdk.js              # ServiceNow REST API client
-│   ├── output.js           # Output formatting
-│   ├── config.js           # Configuration loader
-│   ├── context.js          # Runtime context
-│   ├── errors.js           # Structured error types
-│   ├── helpers.js          # Shared utilities
-│   ├── help.js             # Custom grouped help renderer
-│   └── commands/           # CLI command modules
-├── skills/
-│   └── servicenow/
-│       └── SKILL.md        # AI agent skill file
-├── test/                   # Test suite
-└── package.json
-```
-
-### Releasing
-
-```bash
-npm run release -- patch    # or minor, major
-# Creates node-v* tag, pushes to GitHub, publishes to npm
-```
-
-## Troubleshooting
-
-### Not authenticated
-
-```
-⚠️  Not authenticated to https://dev12345.service-now.com
-
-To get started, run:
-  jsn setup
-  jsn auth login
-```
-
-### Instance URL required
-
-```
-Error (usage): Instance URL required. Set via --instance flag,
-               SERVICENOW_INSTANCE_URL env, or config file.
+npm test
 ```
 
-### Outdated version
-
-```bash
-jsn version --check
-# → jsn 0.0.10 — newer version 0.1.0 available
-npm install -g @jacebenson/jsn
-```
+Releases: `npm run release -- patch` (or `minor`, `major`). Tags, pushes, and publishes to npm via GitHub Actions.
 
 ## License
 
-MIT License — see LICENSE file for details
-
-## Acknowledgments
-
-This project follows architectural patterns from [basecamp-cli](https://github.com/basecamp/basecamp-cli).
-
-| Project | What we learned |
-|---------|----------------|
-| [Abey's `sn` CLI](https://github.com/tehubersheezy/servicenow-cli) (Rust) | Table API patterns, aggregate stats, raw REST passthrough |
-| [ServiceNow `now-sdk`](https://www.npmjs.com/package/@servicenow/sdk) | OAuth session flow for UI pages |
-| [ServiceNow VS Code Extension](https://marketplace.visualstudio.com/items?itemName=ServiceNow.now-vscode) | `sys.scripts.do` CSRF extraction |
-| [Getting Real](https://basecamp.com/gettingreal) by Basecamp | Build less, start with no, embrace constraints |
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacebenson/jsn",
-  "version": "3.0.6",
+  "version": "3.1.0",
   "description": "A command-line interface for ServiceNow that follows the Unix philosophy: simple, composable, and scriptable.",
   "type": "module",
   "bin": {
@@ -10,6 +10,7 @@
   "scripts": {
     "test": "node --test $(find test -name '*.test.js')",
     "lint": "npx eslint src/ bin/ test/",
+    "postinstall": "node scripts/postinstall.mjs",
     "start": "node bin/jsn.js",
     "tag-reminder": "node scripts/tag-reminder.js",
     "release": "node scripts/release.js"
@@ -40,6 +41,7 @@
     "bin/jsn.js",
     "src/",
     "skills/",
+    "scripts/",
     "README.md",
     "LICENSE"
   ]

package/scripts/postinstall.mjs

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+/**
+ * postinstall.mjs — Copies the bundled ServiceNow SKILL.md to agent skill directories
+ * on npm global install. Mirrors what `basecamp`'s installer does for their skill.
+ *
+ * Only runs when `npm install -g @jacebenson/jsn`.
+ * On `npm install` (local dependency), it's a no-op.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SKILL_SOURCE = path.resolve(__dirname, '..', 'skills', 'servicenow', 'SKILL.md');
+const AGENTS_DIR = path.join(os.homedir(), '.agents', 'skills', 'servicenow');
+const AGENTS_SKILL = path.join(AGENTS_DIR, 'SKILL.md');
+const CLAUDE_SKILL_DIR = path.join(os.homedir(), '.claude', 'skills');
+const CLAUDE_SYMLINK = path.join(CLAUDE_SKILL_DIR, 'servicenow');
+
+function isGlobalInstall() {
+  return (
+    process.env.npm_config_global === 'true' ||
+    process.env.npm_lifecycle_event === 'postinstall'
+  );
+}
+
+function installSkill() {
+  // Check if running in a non-interactive/CI environment where .agents
+  // doesn't make sense. Skip silently.
+  if (!AGENTS_DIR.startsWith(os.homedir())) {
+    return;
+  }
+
+  if (!fs.existsSync(SKILL_SOURCE)) {
+    console.warn('  ⚠ jsn: ServiceNow SKILL.md not found at', SKILL_SOURCE);
+    return;
+  }
+
+  // Create ~/.agents/skills/servicenow/
+  try {
+    fs.mkdirSync(AGENTS_DIR, { recursive: true });
+  } catch {
+    // user's home might not be writable in container/CI
+    return;
+  }
+
+  // Copy the bundled skill file
+  try {
+    fs.copyFileSync(SKILL_SOURCE, AGENTS_SKILL);
+    console.log('  ✓ jsn: ServiceNow skill installed to ' + AGENTS_SKILL);
+  } catch (err) {
+    console.warn('  ⚠ jsn: Could not copy skill to ' + AGENTS_SKILL, err.message);
+    return;
+  }
+
+  // Create symlink at ~/.claude/skills/servicenow → ../../.agents/skills/servicenow
+  // This is the same pattern basecamp's installer uses: ~/.claude/skills/basecamp → ../../.agents/skills/basecamp
+  try {
+    fs.mkdirSync(CLAUDE_SKILL_DIR, { recursive: true });
+
+    // Remove stale symlink or directory if it exists
+    try {
+      fs.unlinkSync(CLAUDE_SYMLINK);
+    } catch {
+      // doesn't exist — fine
+    }
+
+    // Relative symlink so it survives user home dir moves
+    const relativeTarget = path.relative(CLAUDE_SKILL_DIR, AGENTS_DIR);
+    fs.symlinkSync(relativeTarget, CLAUDE_SYMLINK, 'dir');
+    console.log('  ✓ jsn: Claude Code skill link at ' + CLAUDE_SYMLINK);
+  } catch (err) {
+    // Claude Code skill dir might not be expected — non-fatal
+    console.warn('  ⚠ jsn: Could not create Claude Code symlink:', err.message);
+  }
+}
+
+installSkill();

package/scripts/pre-commit-check.sh

@@ -0,0 +1,61 @@
+#!/bin/bash
+# pre-commit-check.sh - Run this before committing to check architecture compliance
+
+echo "🔍 Checking architecture patterns..."
+
+# Check for forbidden SDK patterns
+FORBIDDEN_PATTERNS=(
+    "func.*Client.*ListForm"
+    "func.*Client.*ListList"
+    "func.*Client.*GetSP"
+    "func.*Client.*ListSP"
+)
+
+ERRORS=0
+
+for pattern in "${FORBIDDEN_PATTERNS[@]}"; do
+    matches=$(grep -r "$pattern" internal/sdk/*.go 2>/dev/null | grep -v "_test.go" | grep -v "^Binary")
+    if [ ! -z "$matches" ]; then
+        echo "❌ Found forbidden SDK pattern: $pattern"
+        echo "$matches"
+        ERRORS=$((ERRORS + 1))
+    fi
+done
+
+# Check that commands don't import old SDK types
+BAD_IMPORTS=(
+    "sdk.FormSection"
+    "sdk.FormElement"
+    "sdk.ListLayout"
+    "sdk.ListElement"
+    "sdk.SPPage"
+    "sdk.SPWidgetInstance"
+)
+
+for pattern in "${BAD_IMPORTS[@]}"; do
+    matches=$(grep -r "$pattern" internal/commands/**/*.go 2>/dev/null)
+    if [ ! -z "$matches" ]; then
+        echo "❌ Command using SDK type instead of local type: $pattern"
+        echo "$matches"
+        ERRORS=$((ERRORS + 1))
+    fi
+done
+
+# Run architecture tests
+echo "🧪 Running architecture tests..."
+if ! go test ./internal/sdk -run TestNoSDKHelperMethods -run TestCommandsUseDirectSDKList > /dev/null 2>&1; then
+    echo "❌ Architecture tests failed"
+    go test ./internal/sdk -v -run "TestNoSDKHelperMethods|TestCommandsUseDirectSDKList"
+    ERRORS=$((ERRORS + 1))
+fi
+
+if [ $ERRORS -eq 0 ]; then
+    echo "✅ All architecture checks passed!"
+    exit 0
+else
+    echo ""
+    echo "⚠️  Architecture violations found!"
+    echo "   Remember: Commands should call app.SDK.List() directly with local types."
+    echo "   See internal/commands/dev/forms.go for the correct pattern."
+    exit 1
+fi

package/scripts/release.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+import { execSync } from 'child_process';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+
+const type = process.argv[2];
+if (!type || !['patch', 'minor', 'major'].includes(type)) {
+  console.error('Usage: npm run release -- <patch|minor|major>');
+  process.exit(1);
+}
+
+let branch;
+try {
+  branch = execSync('git rev-parse --abbrev-ref HEAD', { encoding: 'utf8' }).trim();
+} catch {
+  console.error('Error: Not in a git repository');
+  process.exit(1);
+}
+
+if (branch !== 'main') {
+  console.error(`Error: Releases can only be made from 'main' branch (currently on '${branch}')`);
+  process.exit(1);
+}
+
+const prefix = 'v';
+
+console.log('');
+console.log(`🚀 Releasing from '${branch}'`);
+console.log(`   Bump: ${type}`);
+console.log('');
+
+// Run tests
+console.log('⏳ Running tests...');
+try {
+  execSync('npm test', { stdio: 'inherit' });
+} catch {
+  console.error('');
+  console.error('❌ Tests failed. Release aborted.');
+  process.exit(1);
+}
+
+// Bump version with correct tag prefix
+console.log('');
+console.log(`⏳ Bumping version (${type})...`);
+execSync(`npm version ${type} --tag-version-prefix=${prefix}`, { stdio: 'inherit' });
+
+// Push commits and tags
+console.log('');
+console.log('⏳ Pushing to origin...');
+execSync('git push && git push --tags', { stdio: 'inherit' });
+
+// Show final state
+const newPkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+console.log('');
+console.log('✅ Release complete!');
+console.log(`   Version: ${newPkg.version}`);
+console.log(`   Tag:     ${prefix}${newPkg.version}`);
+console.log('');

package/scripts/tag-reminder.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import { execSync } from 'child_process';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+
+let branch;
+try {
+  branch = execSync('git rev-parse --abbrev-ref HEAD', { encoding: 'utf8' }).trim();
+} catch {
+  branch = 'unknown';
+}
+
+const version = pkg.version;
+const prefix = 'v';
+
+console.log('');
+console.log('📦 Release Reminder');
+console.log('');
+console.log(`   Current version: ${version}`);
+console.log(`   Current branch:  ${branch}`);
+console.log('');
+console.log('   To create a release tag, run:');
+console.log('');
+console.log(`     git tag ${prefix}${version}`);
+console.log('     git push origin --tags');
+console.log('');